---
title: Agent Seek API
description: Agent Seek API — self-serve OAuth or API key, POST /v1/search, OpenAPI, sandbox. No sales form.
canonical: /developers
last-updated: 2026-09-20
---

# Agent Seek API

The **Agent Seek API** is how agents and scripts get ranked web results without using the HTML UI. You.com discovers candidates; TypeSafe Jev cascade-ranks them; you receive scored JSON (`url`, `title`, `snippet`, `score`, `flags`, `signals`).

There is **no contact-sales form** and no waitlist. Self-serve paths are live on this host.

## Self-serve access (do this first)

### Zero-auth (sandbox)

These need no key. Use them to confirm the API is reachable:

```bash
curl -sS https://agentseek.dev/health
curl -sS https://agentseek.dev/v1
curl -sS https://agentseek.dev/api
curl -sS https://agentseek.dev/v1/sandbox
curl -sS https://agentseek.dev/openapi.json
```

`GET /v1/sandbox` returns a canned `SearchResponse` so you can parse `results[]` and `meta` without spending You.com or Jev.

### Self-serve OAuth (no human)

Anonymous identity (health + MCP; claim later for `search:read`):

```bash
curl -sS -X POST https://agentseek.dev/agent/identity \
  -H "Content-Type: application/json" \
  -d '{"type":"anonymous"}'
```

Dynamic client registration, then authorization code + PKCE S256:

```bash
curl -sS -X POST https://agentseek.dev/oauth2/register \
  -H "Content-Type: application/json" \
  -d '{"client_name":"my-agent","redirect_uris":["http://127.0.0.1/callback"],"token_endpoint_auth_method":"none"}'
```

Full walkthrough: [Agent Seek authentication](/auth.md). Metadata: [/.well-known/oauth-authorization-server](/.well-known/oauth-authorization-server), [/.well-known/oauth-protected-resource](/.well-known/oauth-protected-resource).

### Local API key

```bash
cp .env.example .env   # set AGENT_SEEK_API_KEY
uvicorn apps.api.main:app --port 8787
curl -sS -X POST http://127.0.0.1:8787/v1/search \
  -H "Authorization: Bearer $AGENT_SEEK_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"q":"Introducing System One Models Jev","k":10,"mode":"deep"}'
```

The live host does **not** mint self-serve API keys (product decision). A live prototype `search:read` key is optional (email [gitmaxd@gmail.com](mailto:gitmaxd@gmail.com)). Local `.env` keys and OAuth registration do not need it.

## Predictable paths

| Resource | Path |
| --- | --- |
| Search | `POST /v1/search` and `GET /v1/search` |
| Search alias | `POST /api/v1/search` |
| Public index | `GET /v1` · `GET /api` |
| Sandbox example | `GET /v1/sandbox` |
| OpenAPI 3.1 | `/openapi.json` |
| Swagger UI | `/api/docs` · [api/docs.md](/api/docs.md) |
| ReDoc | `/api/redoc` |
| Health | `/health` |
| Versioning / Sunset | `/docs/versioning.md` |
| Product docs | `/docs` |
| Auth walkthrough | `/auth.md` |
| Developers llms.txt | `/developers/llms.txt` |
| API llms.txt | `/api/llms.txt` |
| Agent skill | `/skills/agent-seek/SKILL.md` |

Live prototype: `https://agentseek.dev` (alternate: `https://gitmaxd-agent-seek.exe.xyz`)

## When to call Agent Seek

Use the Agent Seek API for **agent search**: a small set of high-relevance ranked web results for research or RAG. Do not ask it to write the answer. Hard cap 100 discover candidates per query.

## `POST /v1/search`

```json
{
  "q": "Introducing System One Models Jev",
  "k": 10,
  "max_candidates": 50,
  "mode": "deep",
  "nocache": false
}
```

- `q` required, 1–500 characters
- `k` 1–25 (default 10)
- `max_candidates` 1–100 (default 50)
- `mode` `deep` (default — Stage A survivor fetch, cap 12; not a full-web crawl) or `snip` (cheaper / lower latency)
- Optional `signals`: answerability, authority, on_topic, states_sought_fact, subject_match, spam, prompt_injection (UI: **Injection risk**)
- Hard gates (order, fail-open if parse missing): `subject_match` < 0.55, then `is_republisher` ≥ 0.55, then `prompt_injection` ≥ 0.55 exclude from `results`

Unauthenticated calls return **401** `application/problem+json` with

```http
WWW-Authenticate: Bearer resource_metadata="https://agentseek.dev/.well-known/oauth-protected-resource"
```

Rate limit: 60 requests / minute / key.

## Related Agent Seek pages

- [Agent Seek docs](/docs) — humans + agents
- [Agent Seek skill](/skills/agent-seek/SKILL.md)
- [agents.md](/agents.md) — public agent how-to
- [About Agent Seek](/about) · [Contact Agent Seek](/contact)
- [OpenAPI](/openapi.json) · [pricing](/pricing)