Agent Seek API

How agents and scripts get ranked sources without the HTML UI. Less SEO. More signal. You.com discovers candidates; TypeSafe Jev cascade-ranks them; you receive scored JSON (url, title, snippet, score, flags, signals). The caller writes the answer. Web results are scored for prompt injection before the agent reads them (signals.prompt_injection; UI: Injection risk).

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

Self-serve access

Zero-auth (sandbox)

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

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

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

Live demo (public Bearer)

Copy the public demo key (not a secret — same value as /config.js):

Authorization: Bearer AS_LXxYWY1wQcEwliYnkfAXRA-c0sPlsRtVz4j_ZvJRlnI

curl -sS -X POST https://agentseek.dev/v1/search \
  -H "Authorization: Bearer AS_LXxYWY1wQcEwliYnkfAXRA-c0sPlsRtVz4j_ZvJRlnI" \
  -H "Content-Type: application/json" \
  -d '{"q":"Introducing System One Models Jev","k":10}'

This is the main live path for POST /v1/search and MCP search_web on https://agentseek.dev. It burns operator You.com / TypeSafe quota and the per-IP demo limit. It does not unlock upstream secrets. The live host does not mint self-serve API keys.

Local / self-host API key

cp .env.example .env   # set AGENT_SEEK_API_KEY (and your own YDC / TypeSafe keys)
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}'

Local AGENT_SEEK_API_KEY is separate from the live AS_… demo key.

Optional / advanced: OAuth DCR

Prefer Dynamic Client Registration or PKCE instead of the public demo key? See auth.md. Brief entry points: POST /agent/identity with {"type":"anonymous"}, or POST /oauth2/register. Metadata: OAuth AS, protected resource. You do not need OAuth to try the live demo.

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
ReDoc	`/api/redoc`
Health	`/health`
Versioning / Sunset	`/docs/versioning.md`
Product docs	`/docs`
Auth walkthrough	`/auth.md`
Agent skill	`/.well-known/agent-skills/agent-seek/SKILL.md`

Live prototype: https://dev.agentseek.dev

When to call

Use the API for a small set of high-relevance ranked web results for research or RAG. Agent Seek returns ranked sources; you write the answer. Hard cap: 100 discover candidates per query. Prefer the top 1–2 ranked sources before expanding. One good keeper beats a context window full of searches. Do not dump all k results into context by default.

`POST /v1/search`

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

q required, 1–500 characters
k 1–25 (default 10)
max_candidates 1–100 (default 50)
mode snip (default: title/URL/snippet, cheaper/faster) or deep (Stage A survivor fetch, cap 12; not a full-web crawl). Website UI is fixed snip.
Optional signals: answerability, authority, on_topic, states_sought_fact, subject_match, spam, prompt_injection (UI: Injection risk)
Hard gates (order, 0.55): subject_match < 0.55, then is_republisher ≥ 0.55, then prompt_injection ≥ 0.55 or missing parse drop from results. subject_match and is_republisher fail-open if parse missing; prompt_injection is fail-flagged. If hard gates empty the scored list, pre-gate ranking is restored (scores unchanged) and each restored row has gates_relaxed: true. Treat that as a relaxed-safety response. gates_relaxed is a per-result boolean, not a SearchMeta field.

Unauthenticated calls return 401 application/problem+json with

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

Burst rate limit: optional Upstash sliding window, 60 requests / minute / client IP on search and MCP search_web when enabled. That 429 is code=RATE_LIMITED and may include Retry-After.

Website demo quota: when AGENT_SEEK_DEMO_MODE=enabled (code default disabled; the live host sets enabled), REST /v1/search, /api/v1/search, and MCP search_web share a lifetime per-IP allowance (default 5, Upstash INCR, no TTL). Exhausted → 429 application/problem+json with code=DEMO_EXHAUSTED and no Retry-After. See pricing.