{"openapi":"3.1.0","info":{"title":"Agent Seek OpenAPI","description":"Agent Seek ranks web results for humans and agents: You.com discovers candidates,\nTypeSafe Jev cascade-ranks them, and `POST /v1/search` returns a small scored list.\n\n**Auth:** OAuth 2.0 (authorization code + PKCE S256, plus anonymous/service_auth\nagent registration) **or** `Authorization: Bearer $AGENT_SEEK_API_KEY` /\n`X-API-Key`. Scopes: `search:read`, `mcp:invoke`, `health:read`.\nWalkthrough: `/auth.md`. Metadata: `/.well-known/oauth-authorization-server`\nand `/.well-known/oauth-protected-resource`.\n\n**Versioning:** URL versioning on `/v1`. `info.version` and `meta.agent_seek_version`\nidentify the prototype build. Additive JSON fields are non-breaking. Breaking\nchanges ship as a new path (`/v2`) and are announced with RFC 8594 `Deprecation`\nand `Sunset` headers plus `/docs/versioning.md`. `/v1` has no sunset date.\nUnsupported versions (for example `GET /v2` today) return\n`application/problem+json` with `code=UNSUPPORTED_VERSION`.\n\n**Rate limits:** 60 requests / minute / client key (in-memory). `/v1/*`, `/mcp`,\nand `/health` include RFC `RateLimit` + `RateLimit-Policy`. `429` includes\n`Retry-After`.\n\n**Errors:** RFC 9457 `application/problem+json` on every API 4xx/5xx\n(`type`, `title`, `status`, `detail`, `instance`, plus `code` / `message` /\n`hint` and nested `error`). See `/docs/versioning.md` and the ProblemDetails\nschema on each operation.\n\n**MCP:** Streamable HTTP at `/mcp` and `/.well-known/mcp`. Server card:\n`/.well-known/mcp/server-card.json`.\n\n**Modes:** default `mode=deep` (Stage A survivor fetch, cap 12; not a full-web crawl). Pass `mode=snip` for cheaper title/URL/snippet ranking.\n\n**Signals:** answerability, authority, on_topic, states_sought_fact, subject_match, spam, prompt_injection (UI label: Injection risk).\n\n**Hard gates (order):** subject_match → is_republisher → prompt_injection (fail-open if parse missing; 0.55 thresholds as in code).\n\n**Caps:** `max_candidates` ≤ 100; default 50 in, `k` default 10 (1–25).\nDo not ask Agent Seek to write answers.","version":"0.1.39","x-api-versioning":{"strategy":"url","current":"v1","policy":"/docs/versioning.md","deprecation":"RFC 8594 Deprecation + Sunset headers at least 90 days before removal","sunset":"Unsupported versions return application/problem+json with code=UNSUPPORTED_VERSION"}},"paths":{"/health":{"get":{"tags":["meta"],"summary":"Liveness + version","description":"Return process liveness and `agent_seek_version` (same value as OpenAPI info.version). Zero-auth. Typed HealthResponse: ok + version.","operationId":"healthCheck","responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HealthResponse"}}},"headers":{"RateLimit":{"$ref":"#/components/headers/RateLimit"},"RateLimit-Policy":{"description":"Policy token, e.g. 60;w=60","schema":{"type":"string"}}}},"400":{"description":"Bad request (RFC 9457 problem+json)","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/ProblemDetails"},"example":{"type":"https://agentseek.dev/errors/unauthorized","title":"Unauthorized","status":401,"detail":"Unauthorized","instance":"/v1/search","code":"UNAUTHORIZED","message":"Unauthorized","hint":"Use OAuth (see /auth.md) or Authorization: Bearer $AGENT_SEEK_API_KEY.","error":{"code":"UNAUTHORIZED","message":"Unauthorized","hint":"Use OAuth (see /auth.md) or Authorization: Bearer $AGENT_SEEK_API_KEY."}}},"application/json":{"schema":{"$ref":"#/components/schemas/ProblemDetails"},"example":{"type":"https://agentseek.dev/errors/unauthorized","title":"Unauthorized","status":401,"detail":"Unauthorized","instance":"/v1/search","code":"UNAUTHORIZED","message":"Unauthorized","hint":"Use OAuth (see /auth.md) or Authorization: Bearer $AGENT_SEEK_API_KEY.","error":{"code":"UNAUTHORIZED","message":"Unauthorized","hint":"Use OAuth (see /auth.md) or Authorization: Bearer $AGENT_SEEK_API_KEY."}}}}},"401":{"description":"Missing or invalid credential. WWW-Authenticate: Bearer resource_metadata=…","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/ProblemDetails"},"example":{"type":"https://agentseek.dev/errors/unauthorized","title":"Unauthorized","status":401,"detail":"Unauthorized","instance":"/v1/search","code":"UNAUTHORIZED","message":"Unauthorized","hint":"Use OAuth (see /auth.md) or Authorization: Bearer $AGENT_SEEK_API_KEY.","error":{"code":"UNAUTHORIZED","message":"Unauthorized","hint":"Use OAuth (see /auth.md) or Authorization: Bearer $AGENT_SEEK_API_KEY."}}},"application/json":{"schema":{"$ref":"#/components/schemas/ProblemDetails"},"example":{"type":"https://agentseek.dev/errors/unauthorized","title":"Unauthorized","status":401,"detail":"Unauthorized","instance":"/v1/search","code":"UNAUTHORIZED","message":"Unauthorized","hint":"Use OAuth (see /auth.md) or Authorization: Bearer $AGENT_SEEK_API_KEY.","error":{"code":"UNAUTHORIZED","message":"Unauthorized","hint":"Use OAuth (see /auth.md) or Authorization: Bearer $AGENT_SEEK_API_KEY."}}}},"headers":{"WWW-Authenticate":{"$ref":"#/components/headers/WWWAuthenticate"}}},"403":{"description":"Valid token missing required scope","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/ProblemDetails"},"example":{"type":"https://agentseek.dev/errors/unauthorized","title":"Unauthorized","status":401,"detail":"Unauthorized","instance":"/v1/search","code":"UNAUTHORIZED","message":"Unauthorized","hint":"Use OAuth (see /auth.md) or Authorization: Bearer $AGENT_SEEK_API_KEY.","error":{"code":"UNAUTHORIZED","message":"Unauthorized","hint":"Use OAuth (see /auth.md) or Authorization: Bearer $AGENT_SEEK_API_KEY."}}},"application/json":{"schema":{"$ref":"#/components/schemas/ProblemDetails"},"example":{"type":"https://agentseek.dev/errors/unauthorized","title":"Unauthorized","status":401,"detail":"Unauthorized","instance":"/v1/search","code":"UNAUTHORIZED","message":"Unauthorized","hint":"Use OAuth (see /auth.md) or Authorization: Bearer $AGENT_SEEK_API_KEY.","error":{"code":"UNAUTHORIZED","message":"Unauthorized","hint":"Use OAuth (see /auth.md) or Authorization: Bearer $AGENT_SEEK_API_KEY."}}}}},"422":{"description":"Validation error (RFC 9457 problem+json)","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/ProblemDetails"},"example":{"type":"https://agentseek.dev/errors/unauthorized","title":"Unauthorized","status":401,"detail":"Unauthorized","instance":"/v1/search","code":"UNAUTHORIZED","message":"Unauthorized","hint":"Use OAuth (see /auth.md) or Authorization: Bearer $AGENT_SEEK_API_KEY.","error":{"code":"UNAUTHORIZED","message":"Unauthorized","hint":"Use OAuth (see /auth.md) or Authorization: Bearer $AGENT_SEEK_API_KEY."}}},"application/json":{"schema":{"$ref":"#/components/schemas/ProblemDetails"},"example":{"type":"https://agentseek.dev/errors/unauthorized","title":"Unauthorized","status":401,"detail":"Unauthorized","instance":"/v1/search","code":"UNAUTHORIZED","message":"Unauthorized","hint":"Use OAuth (see /auth.md) or Authorization: Bearer $AGENT_SEEK_API_KEY.","error":{"code":"UNAUTHORIZED","message":"Unauthorized","hint":"Use OAuth (see /auth.md) or Authorization: Bearer $AGENT_SEEK_API_KEY."}}}}},"429":{"description":"Rate limited (60/min). Retry-After + RateLimit headers.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/ProblemDetails"},"example":{"type":"https://agentseek.dev/errors/unauthorized","title":"Unauthorized","status":401,"detail":"Unauthorized","instance":"/v1/search","code":"UNAUTHORIZED","message":"Unauthorized","hint":"Use OAuth (see /auth.md) or Authorization: Bearer $AGENT_SEEK_API_KEY.","error":{"code":"UNAUTHORIZED","message":"Unauthorized","hint":"Use OAuth (see /auth.md) or Authorization: Bearer $AGENT_SEEK_API_KEY."}}},"application/json":{"schema":{"$ref":"#/components/schemas/ProblemDetails"},"example":{"type":"https://agentseek.dev/errors/unauthorized","title":"Unauthorized","status":401,"detail":"Unauthorized","instance":"/v1/search","code":"UNAUTHORIZED","message":"Unauthorized","hint":"Use OAuth (see /auth.md) or Authorization: Bearer $AGENT_SEEK_API_KEY.","error":{"code":"UNAUTHORIZED","message":"Unauthorized","hint":"Use OAuth (see /auth.md) or Authorization: Bearer $AGENT_SEEK_API_KEY."}}}},"headers":{"Retry-After":{"$ref":"#/components/headers/RetryAfter"},"RateLimit":{"$ref":"#/components/headers/RateLimit"}}},"502":{"description":"Upstream discover failed","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/ProblemDetails"},"example":{"type":"https://agentseek.dev/errors/unauthorized","title":"Unauthorized","status":401,"detail":"Unauthorized","instance":"/v1/search","code":"UNAUTHORIZED","message":"Unauthorized","hint":"Use OAuth (see /auth.md) or Authorization: Bearer $AGENT_SEEK_API_KEY.","error":{"code":"UNAUTHORIZED","message":"Unauthorized","hint":"Use OAuth (see /auth.md) or Authorization: Bearer $AGENT_SEEK_API_KEY."}}},"application/json":{"schema":{"$ref":"#/components/schemas/ProblemDetails"},"example":{"type":"https://agentseek.dev/errors/unauthorized","title":"Unauthorized","status":401,"detail":"Unauthorized","instance":"/v1/search","code":"UNAUTHORIZED","message":"Unauthorized","hint":"Use OAuth (see /auth.md) or Authorization: Bearer $AGENT_SEEK_API_KEY.","error":{"code":"UNAUTHORIZED","message":"Unauthorized","hint":"Use OAuth (see /auth.md) or Authorization: Bearer $AGENT_SEEK_API_KEY."}}}}},"503":{"description":"Server missing YDC_API_KEY","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/ProblemDetails"},"example":{"type":"https://agentseek.dev/errors/unauthorized","title":"Unauthorized","status":401,"detail":"Unauthorized","instance":"/v1/search","code":"UNAUTHORIZED","message":"Unauthorized","hint":"Use OAuth (see /auth.md) or Authorization: Bearer $AGENT_SEEK_API_KEY.","error":{"code":"UNAUTHORIZED","message":"Unauthorized","hint":"Use OAuth (see /auth.md) or Authorization: Bearer $AGENT_SEEK_API_KEY."}}},"application/json":{"schema":{"$ref":"#/components/schemas/ProblemDetails"},"example":{"type":"https://agentseek.dev/errors/unauthorized","title":"Unauthorized","status":401,"detail":"Unauthorized","instance":"/v1/search","code":"UNAUTHORIZED","message":"Unauthorized","hint":"Use OAuth (see /auth.md) or Authorization: Bearer $AGENT_SEEK_API_KEY.","error":{"code":"UNAUTHORIZED","message":"Unauthorized","hint":"Use OAuth (see /auth.md) or Authorization: Bearer $AGENT_SEEK_API_KEY."}}}}},"504":{"description":"Upstream timeout","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/ProblemDetails"},"example":{"type":"https://agentseek.dev/errors/unauthorized","title":"Unauthorized","status":401,"detail":"Unauthorized","instance":"/v1/search","code":"UNAUTHORIZED","message":"Unauthorized","hint":"Use OAuth (see /auth.md) or Authorization: Bearer $AGENT_SEEK_API_KEY.","error":{"code":"UNAUTHORIZED","message":"Unauthorized","hint":"Use OAuth (see /auth.md) or Authorization: Bearer $AGENT_SEEK_API_KEY."}}},"application/json":{"schema":{"$ref":"#/components/schemas/ProblemDetails"},"example":{"type":"https://agentseek.dev/errors/unauthorized","title":"Unauthorized","status":401,"detail":"Unauthorized","instance":"/v1/search","code":"UNAUTHORIZED","message":"Unauthorized","hint":"Use OAuth (see /auth.md) or Authorization: Bearer $AGENT_SEEK_API_KEY.","error":{"code":"UNAUTHORIZED","message":"Unauthorized","hint":"Use OAuth (see /auth.md) or Authorization: Bearer $AGENT_SEEK_API_KEY."}}}}}}}},"/v1/search":{"post":{"tags":["search"],"summary":"Ranked web search","description":"Discover up to `max_candidates` (≤100) via You.com, cascade-rank with Jev, return top `k` scored results. Default `mode=deep` (Stage A survivor fetch, cap 12; not a full-web crawl). Signals include `prompt_injection`. OAuth scope `search:read` or Bearer AGENT_SEEK_API_KEY. Rate limit: 60/min (RateLimit + Retry-After headers). Errors use RFC 9457 application/problem+json (`type`, `title`, `status`, `detail`, `code`, `message`, `hint`).","operationId":"searchPost","requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/SearchRequest"}}},"description":"Discover up to `max_candidates` (≤100) via You.com, cascade-rank with Jev, return top `k` scored results. Default `mode=deep` (Stage A survivor fetch, cap 12; not a full-web crawl). Signals include `prompt_injection`. OAuth scope `search:read` or Bearer AGENT_SEEK_API_KEY. Rate limit: 60/min (RateLimit + Retry-After headers). Errors use RFC 9457 application/problem+json (`type`, `title`, `status`, `detail`, `code`, `message`, `hint`)."},"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/SearchResponse"}}},"headers":{"RateLimit":{"$ref":"#/components/headers/RateLimit"},"RateLimit-Policy":{"description":"Policy token, e.g. 60;w=60","schema":{"type":"string"}}}},"401":{"description":"Missing or invalid credential. WWW-Authenticate: Bearer resource_metadata=…","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/ProblemDetails"},"example":{"type":"https://agentseek.dev/errors/unauthorized","title":"Unauthorized","status":401,"detail":"Unauthorized","instance":"/v1/search","code":"UNAUTHORIZED","message":"Unauthorized","hint":"Use OAuth (see /auth.md) or Authorization: Bearer $AGENT_SEEK_API_KEY.","error":{"code":"UNAUTHORIZED","message":"Unauthorized","hint":"Use OAuth (see /auth.md) or Authorization: Bearer $AGENT_SEEK_API_KEY."}}},"application/json":{"schema":{"$ref":"#/components/schemas/ProblemDetails"},"example":{"type":"https://agentseek.dev/errors/unauthorized","title":"Unauthorized","status":401,"detail":"Unauthorized","instance":"/v1/search","code":"UNAUTHORIZED","message":"Unauthorized","hint":"Use OAuth (see /auth.md) or Authorization: Bearer $AGENT_SEEK_API_KEY.","error":{"code":"UNAUTHORIZED","message":"Unauthorized","hint":"Use OAuth (see /auth.md) or Authorization: Bearer $AGENT_SEEK_API_KEY."}}}},"headers":{"WWW-Authenticate":{"$ref":"#/components/headers/WWWAuthenticate"}}},"429":{"description":"Rate limited (60/min). Retry-After + RateLimit headers.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/ProblemDetails"},"example":{"type":"https://agentseek.dev/errors/unauthorized","title":"Unauthorized","status":401,"detail":"Unauthorized","instance":"/v1/search","code":"UNAUTHORIZED","message":"Unauthorized","hint":"Use OAuth (see /auth.md) or Authorization: Bearer $AGENT_SEEK_API_KEY.","error":{"code":"UNAUTHORIZED","message":"Unauthorized","hint":"Use OAuth (see /auth.md) or Authorization: Bearer $AGENT_SEEK_API_KEY."}}},"application/json":{"schema":{"$ref":"#/components/schemas/ProblemDetails"},"example":{"type":"https://agentseek.dev/errors/unauthorized","title":"Unauthorized","status":401,"detail":"Unauthorized","instance":"/v1/search","code":"UNAUTHORIZED","message":"Unauthorized","hint":"Use OAuth (see /auth.md) or Authorization: Bearer $AGENT_SEEK_API_KEY.","error":{"code":"UNAUTHORIZED","message":"Unauthorized","hint":"Use OAuth (see /auth.md) or Authorization: Bearer $AGENT_SEEK_API_KEY."}}}},"headers":{"Retry-After":{"$ref":"#/components/headers/RetryAfter"},"RateLimit":{"$ref":"#/components/headers/RateLimit"}}},"422":{"description":"Validation error (RFC 9457 problem+json)","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/ProblemDetails"},"example":{"type":"https://agentseek.dev/errors/unauthorized","title":"Unauthorized","status":401,"detail":"Unauthorized","instance":"/v1/search","code":"UNAUTHORIZED","message":"Unauthorized","hint":"Use OAuth (see /auth.md) or Authorization: Bearer $AGENT_SEEK_API_KEY.","error":{"code":"UNAUTHORIZED","message":"Unauthorized","hint":"Use OAuth (see /auth.md) or Authorization: Bearer $AGENT_SEEK_API_KEY."}}},"application/json":{"schema":{"$ref":"#/components/schemas/ProblemDetails"},"example":{"type":"https://agentseek.dev/errors/unauthorized","title":"Unauthorized","status":401,"detail":"Unauthorized","instance":"/v1/search","code":"UNAUTHORIZED","message":"Unauthorized","hint":"Use OAuth (see /auth.md) or Authorization: Bearer $AGENT_SEEK_API_KEY.","error":{"code":"UNAUTHORIZED","message":"Unauthorized","hint":"Use OAuth (see /auth.md) or Authorization: Bearer $AGENT_SEEK_API_KEY."}}}}},"400":{"description":"Bad request (RFC 9457 problem+json)","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/ProblemDetails"},"example":{"type":"https://agentseek.dev/errors/unauthorized","title":"Unauthorized","status":401,"detail":"Unauthorized","instance":"/v1/search","code":"UNAUTHORIZED","message":"Unauthorized","hint":"Use OAuth (see /auth.md) or Authorization: Bearer $AGENT_SEEK_API_KEY.","error":{"code":"UNAUTHORIZED","message":"Unauthorized","hint":"Use OAuth (see /auth.md) or Authorization: Bearer $AGENT_SEEK_API_KEY."}}},"application/json":{"schema":{"$ref":"#/components/schemas/ProblemDetails"},"example":{"type":"https://agentseek.dev/errors/unauthorized","title":"Unauthorized","status":401,"detail":"Unauthorized","instance":"/v1/search","code":"UNAUTHORIZED","message":"Unauthorized","hint":"Use OAuth (see /auth.md) or Authorization: Bearer $AGENT_SEEK_API_KEY.","error":{"code":"UNAUTHORIZED","message":"Unauthorized","hint":"Use OAuth (see /auth.md) or Authorization: Bearer $AGENT_SEEK_API_KEY."}}}}},"403":{"description":"Valid token missing required scope","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/ProblemDetails"},"example":{"type":"https://agentseek.dev/errors/unauthorized","title":"Unauthorized","status":401,"detail":"Unauthorized","instance":"/v1/search","code":"UNAUTHORIZED","message":"Unauthorized","hint":"Use OAuth (see /auth.md) or Authorization: Bearer $AGENT_SEEK_API_KEY.","error":{"code":"UNAUTHORIZED","message":"Unauthorized","hint":"Use OAuth (see /auth.md) or Authorization: Bearer $AGENT_SEEK_API_KEY."}}},"application/json":{"schema":{"$ref":"#/components/schemas/ProblemDetails"},"example":{"type":"https://agentseek.dev/errors/unauthorized","title":"Unauthorized","status":401,"detail":"Unauthorized","instance":"/v1/search","code":"UNAUTHORIZED","message":"Unauthorized","hint":"Use OAuth (see /auth.md) or Authorization: Bearer $AGENT_SEEK_API_KEY.","error":{"code":"UNAUTHORIZED","message":"Unauthorized","hint":"Use OAuth (see /auth.md) or Authorization: Bearer $AGENT_SEEK_API_KEY."}}}}},"502":{"description":"Upstream discover failed","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/ProblemDetails"},"example":{"type":"https://agentseek.dev/errors/unauthorized","title":"Unauthorized","status":401,"detail":"Unauthorized","instance":"/v1/search","code":"UNAUTHORIZED","message":"Unauthorized","hint":"Use OAuth (see /auth.md) or Authorization: Bearer $AGENT_SEEK_API_KEY.","error":{"code":"UNAUTHORIZED","message":"Unauthorized","hint":"Use OAuth (see /auth.md) or Authorization: Bearer $AGENT_SEEK_API_KEY."}}},"application/json":{"schema":{"$ref":"#/components/schemas/ProblemDetails"},"example":{"type":"https://agentseek.dev/errors/unauthorized","title":"Unauthorized","status":401,"detail":"Unauthorized","instance":"/v1/search","code":"UNAUTHORIZED","message":"Unauthorized","hint":"Use OAuth (see /auth.md) or Authorization: Bearer $AGENT_SEEK_API_KEY.","error":{"code":"UNAUTHORIZED","message":"Unauthorized","hint":"Use OAuth (see /auth.md) or Authorization: Bearer $AGENT_SEEK_API_KEY."}}}}},"503":{"description":"Server missing YDC_API_KEY","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/ProblemDetails"},"example":{"type":"https://agentseek.dev/errors/unauthorized","title":"Unauthorized","status":401,"detail":"Unauthorized","instance":"/v1/search","code":"UNAUTHORIZED","message":"Unauthorized","hint":"Use OAuth (see /auth.md) or Authorization: Bearer $AGENT_SEEK_API_KEY.","error":{"code":"UNAUTHORIZED","message":"Unauthorized","hint":"Use OAuth (see /auth.md) or Authorization: Bearer $AGENT_SEEK_API_KEY."}}},"application/json":{"schema":{"$ref":"#/components/schemas/ProblemDetails"},"example":{"type":"https://agentseek.dev/errors/unauthorized","title":"Unauthorized","status":401,"detail":"Unauthorized","instance":"/v1/search","code":"UNAUTHORIZED","message":"Unauthorized","hint":"Use OAuth (see /auth.md) or Authorization: Bearer $AGENT_SEEK_API_KEY.","error":{"code":"UNAUTHORIZED","message":"Unauthorized","hint":"Use OAuth (see /auth.md) or Authorization: Bearer $AGENT_SEEK_API_KEY."}}}}},"504":{"description":"Upstream timeout","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/ProblemDetails"},"example":{"type":"https://agentseek.dev/errors/unauthorized","title":"Unauthorized","status":401,"detail":"Unauthorized","instance":"/v1/search","code":"UNAUTHORIZED","message":"Unauthorized","hint":"Use OAuth (see /auth.md) or Authorization: Bearer $AGENT_SEEK_API_KEY.","error":{"code":"UNAUTHORIZED","message":"Unauthorized","hint":"Use OAuth (see /auth.md) or Authorization: Bearer $AGENT_SEEK_API_KEY."}}},"application/json":{"schema":{"$ref":"#/components/schemas/ProblemDetails"},"example":{"type":"https://agentseek.dev/errors/unauthorized","title":"Unauthorized","status":401,"detail":"Unauthorized","instance":"/v1/search","code":"UNAUTHORIZED","message":"Unauthorized","hint":"Use OAuth (see /auth.md) or Authorization: Bearer $AGENT_SEEK_API_KEY.","error":{"code":"UNAUTHORIZED","message":"Unauthorized","hint":"Use OAuth (see /auth.md) or Authorization: Bearer $AGENT_SEEK_API_KEY."}}}}}},"security":[{"OAuth2":["search:read"]},{"AgentSeekApiKey":[]}]},"get":{"tags":["search"],"summary":"Ranked web search (GET)","description":"Same contract as POST /v1/search with query-string parameters. Default `mode=deep` (Stage A survivor fetch, cap 12). OAuth scope `search:read` or Bearer AGENT_SEEK_API_KEY.","operationId":"searchGet","parameters":[{"name":"q","in":"query","required":true,"schema":{"type":"string","minLength":1,"maxLength":500,"description":"Search query (1–500 characters)","title":"Q"},"description":"Search query (1–500 characters)"},{"name":"k","in":"query","required":false,"schema":{"type":"integer","maximum":25,"minimum":1,"description":"Number of ranked results to return","default":10,"title":"K"},"description":"Number of ranked results to return"},{"name":"max_candidates","in":"query","required":false,"schema":{"type":"integer","maximum":100,"minimum":1,"description":"Discover cap (hard max 100)","default":50,"title":"Max Candidates"},"description":"Discover cap (hard max 100)"},{"name":"mode","in":"query","required":false,"schema":{"type":"string","description":"deep (default; Stage A survivor fetch, cap 12) or snip","default":"deep","title":"Mode"},"description":"deep (default; Stage A survivor fetch, cap 12) or snip"},{"name":"rank","in":"query","required":false,"schema":{"type":"string","description":"on | off","default":"on","title":"Rank"},"description":"on | off"},{"name":"nocache","in":"query","required":false,"schema":{"type":"boolean","description":"Force discover cache miss","default":false,"title":"Nocache"},"description":"Force discover cache miss"}],"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/SearchResponse"}}},"headers":{"RateLimit":{"$ref":"#/components/headers/RateLimit"},"RateLimit-Policy":{"description":"Policy token, e.g. 60;w=60","schema":{"type":"string"}}}},"422":{"description":"Validation error (RFC 9457 problem+json)","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/ProblemDetails"},"example":{"type":"https://agentseek.dev/errors/unauthorized","title":"Unauthorized","status":401,"detail":"Unauthorized","instance":"/v1/search","code":"UNAUTHORIZED","message":"Unauthorized","hint":"Use OAuth (see /auth.md) or Authorization: Bearer $AGENT_SEEK_API_KEY.","error":{"code":"UNAUTHORIZED","message":"Unauthorized","hint":"Use OAuth (see /auth.md) or Authorization: Bearer $AGENT_SEEK_API_KEY."}}},"application/json":{"schema":{"$ref":"#/components/schemas/ProblemDetails"},"example":{"type":"https://agentseek.dev/errors/unauthorized","title":"Unauthorized","status":401,"detail":"Unauthorized","instance":"/v1/search","code":"UNAUTHORIZED","message":"Unauthorized","hint":"Use OAuth (see /auth.md) or Authorization: Bearer $AGENT_SEEK_API_KEY.","error":{"code":"UNAUTHORIZED","message":"Unauthorized","hint":"Use OAuth (see /auth.md) or Authorization: Bearer $AGENT_SEEK_API_KEY."}}}}},"400":{"description":"Bad request (RFC 9457 problem+json)","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/ProblemDetails"},"example":{"type":"https://agentseek.dev/errors/unauthorized","title":"Unauthorized","status":401,"detail":"Unauthorized","instance":"/v1/search","code":"UNAUTHORIZED","message":"Unauthorized","hint":"Use OAuth (see /auth.md) or Authorization: Bearer $AGENT_SEEK_API_KEY.","error":{"code":"UNAUTHORIZED","message":"Unauthorized","hint":"Use OAuth (see /auth.md) or Authorization: Bearer $AGENT_SEEK_API_KEY."}}},"application/json":{"schema":{"$ref":"#/components/schemas/ProblemDetails"},"example":{"type":"https://agentseek.dev/errors/unauthorized","title":"Unauthorized","status":401,"detail":"Unauthorized","instance":"/v1/search","code":"UNAUTHORIZED","message":"Unauthorized","hint":"Use OAuth (see /auth.md) or Authorization: Bearer $AGENT_SEEK_API_KEY.","error":{"code":"UNAUTHORIZED","message":"Unauthorized","hint":"Use OAuth (see /auth.md) or Authorization: Bearer $AGENT_SEEK_API_KEY."}}}}},"401":{"description":"Missing or invalid credential. WWW-Authenticate: Bearer resource_metadata=…","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/ProblemDetails"},"example":{"type":"https://agentseek.dev/errors/unauthorized","title":"Unauthorized","status":401,"detail":"Unauthorized","instance":"/v1/search","code":"UNAUTHORIZED","message":"Unauthorized","hint":"Use OAuth (see /auth.md) or Authorization: Bearer $AGENT_SEEK_API_KEY.","error":{"code":"UNAUTHORIZED","message":"Unauthorized","hint":"Use OAuth (see /auth.md) or Authorization: Bearer $AGENT_SEEK_API_KEY."}}},"application/json":{"schema":{"$ref":"#/components/schemas/ProblemDetails"},"example":{"type":"https://agentseek.dev/errors/unauthorized","title":"Unauthorized","status":401,"detail":"Unauthorized","instance":"/v1/search","code":"UNAUTHORIZED","message":"Unauthorized","hint":"Use OAuth (see /auth.md) or Authorization: Bearer $AGENT_SEEK_API_KEY.","error":{"code":"UNAUTHORIZED","message":"Unauthorized","hint":"Use OAuth (see /auth.md) or Authorization: Bearer $AGENT_SEEK_API_KEY."}}}},"headers":{"WWW-Authenticate":{"$ref":"#/components/headers/WWWAuthenticate"}}},"403":{"description":"Valid token missing required scope","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/ProblemDetails"},"example":{"type":"https://agentseek.dev/errors/unauthorized","title":"Unauthorized","status":401,"detail":"Unauthorized","instance":"/v1/search","code":"UNAUTHORIZED","message":"Unauthorized","hint":"Use OAuth (see /auth.md) or Authorization: Bearer $AGENT_SEEK_API_KEY.","error":{"code":"UNAUTHORIZED","message":"Unauthorized","hint":"Use OAuth (see /auth.md) or Authorization: Bearer $AGENT_SEEK_API_KEY."}}},"application/json":{"schema":{"$ref":"#/components/schemas/ProblemDetails"},"example":{"type":"https://agentseek.dev/errors/unauthorized","title":"Unauthorized","status":401,"detail":"Unauthorized","instance":"/v1/search","code":"UNAUTHORIZED","message":"Unauthorized","hint":"Use OAuth (see /auth.md) or Authorization: Bearer $AGENT_SEEK_API_KEY.","error":{"code":"UNAUTHORIZED","message":"Unauthorized","hint":"Use OAuth (see /auth.md) or Authorization: Bearer $AGENT_SEEK_API_KEY."}}}}},"429":{"description":"Rate limited (60/min). Retry-After + RateLimit headers.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/ProblemDetails"},"example":{"type":"https://agentseek.dev/errors/unauthorized","title":"Unauthorized","status":401,"detail":"Unauthorized","instance":"/v1/search","code":"UNAUTHORIZED","message":"Unauthorized","hint":"Use OAuth (see /auth.md) or Authorization: Bearer $AGENT_SEEK_API_KEY.","error":{"code":"UNAUTHORIZED","message":"Unauthorized","hint":"Use OAuth (see /auth.md) or Authorization: Bearer $AGENT_SEEK_API_KEY."}}},"application/json":{"schema":{"$ref":"#/components/schemas/ProblemDetails"},"example":{"type":"https://agentseek.dev/errors/unauthorized","title":"Unauthorized","status":401,"detail":"Unauthorized","instance":"/v1/search","code":"UNAUTHORIZED","message":"Unauthorized","hint":"Use OAuth (see /auth.md) or Authorization: Bearer $AGENT_SEEK_API_KEY.","error":{"code":"UNAUTHORIZED","message":"Unauthorized","hint":"Use OAuth (see /auth.md) or Authorization: Bearer $AGENT_SEEK_API_KEY."}}}},"headers":{"Retry-After":{"$ref":"#/components/headers/RetryAfter"},"RateLimit":{"$ref":"#/components/headers/RateLimit"}}},"502":{"description":"Upstream discover failed","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/ProblemDetails"},"example":{"type":"https://agentseek.dev/errors/unauthorized","title":"Unauthorized","status":401,"detail":"Unauthorized","instance":"/v1/search","code":"UNAUTHORIZED","message":"Unauthorized","hint":"Use OAuth (see /auth.md) or Authorization: Bearer $AGENT_SEEK_API_KEY.","error":{"code":"UNAUTHORIZED","message":"Unauthorized","hint":"Use OAuth (see /auth.md) or Authorization: Bearer $AGENT_SEEK_API_KEY."}}},"application/json":{"schema":{"$ref":"#/components/schemas/ProblemDetails"},"example":{"type":"https://agentseek.dev/errors/unauthorized","title":"Unauthorized","status":401,"detail":"Unauthorized","instance":"/v1/search","code":"UNAUTHORIZED","message":"Unauthorized","hint":"Use OAuth (see /auth.md) or Authorization: Bearer $AGENT_SEEK_API_KEY.","error":{"code":"UNAUTHORIZED","message":"Unauthorized","hint":"Use OAuth (see /auth.md) or Authorization: Bearer $AGENT_SEEK_API_KEY."}}}}},"503":{"description":"Server missing YDC_API_KEY","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/ProblemDetails"},"example":{"type":"https://agentseek.dev/errors/unauthorized","title":"Unauthorized","status":401,"detail":"Unauthorized","instance":"/v1/search","code":"UNAUTHORIZED","message":"Unauthorized","hint":"Use OAuth (see /auth.md) or Authorization: Bearer $AGENT_SEEK_API_KEY.","error":{"code":"UNAUTHORIZED","message":"Unauthorized","hint":"Use OAuth (see /auth.md) or Authorization: Bearer $AGENT_SEEK_API_KEY."}}},"application/json":{"schema":{"$ref":"#/components/schemas/ProblemDetails"},"example":{"type":"https://agentseek.dev/errors/unauthorized","title":"Unauthorized","status":401,"detail":"Unauthorized","instance":"/v1/search","code":"UNAUTHORIZED","message":"Unauthorized","hint":"Use OAuth (see /auth.md) or Authorization: Bearer $AGENT_SEEK_API_KEY.","error":{"code":"UNAUTHORIZED","message":"Unauthorized","hint":"Use OAuth (see /auth.md) or Authorization: Bearer $AGENT_SEEK_API_KEY."}}}}},"504":{"description":"Upstream timeout","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/ProblemDetails"},"example":{"type":"https://agentseek.dev/errors/unauthorized","title":"Unauthorized","status":401,"detail":"Unauthorized","instance":"/v1/search","code":"UNAUTHORIZED","message":"Unauthorized","hint":"Use OAuth (see /auth.md) or Authorization: Bearer $AGENT_SEEK_API_KEY.","error":{"code":"UNAUTHORIZED","message":"Unauthorized","hint":"Use OAuth (see /auth.md) or Authorization: Bearer $AGENT_SEEK_API_KEY."}}},"application/json":{"schema":{"$ref":"#/components/schemas/ProblemDetails"},"example":{"type":"https://agentseek.dev/errors/unauthorized","title":"Unauthorized","status":401,"detail":"Unauthorized","instance":"/v1/search","code":"UNAUTHORIZED","message":"Unauthorized","hint":"Use OAuth (see /auth.md) or Authorization: Bearer $AGENT_SEEK_API_KEY.","error":{"code":"UNAUTHORIZED","message":"Unauthorized","hint":"Use OAuth (see /auth.md) or Authorization: Bearer $AGENT_SEEK_API_KEY."}}}}}},"security":[{"OAuth2":["search:read"]},{"AgentSeekApiKey":[]}]}},"/v1":{"get":{"tags":["meta"],"summary":"Public API index","description":"Unauthenticated machine-readable index of the Agent Seek HTTP API (typed ApiDiscoveryResponse).","operationId":"apiIndex","responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiDiscoveryResponse"}}},"headers":{"RateLimit":{"$ref":"#/components/headers/RateLimit"},"RateLimit-Policy":{"description":"Policy token, e.g. 60;w=60","schema":{"type":"string"}}}},"400":{"description":"Bad request (RFC 9457 problem+json)","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/ProblemDetails"},"example":{"type":"https://agentseek.dev/errors/unauthorized","title":"Unauthorized","status":401,"detail":"Unauthorized","instance":"/v1/search","code":"UNAUTHORIZED","message":"Unauthorized","hint":"Use OAuth (see /auth.md) or Authorization: Bearer $AGENT_SEEK_API_KEY.","error":{"code":"UNAUTHORIZED","message":"Unauthorized","hint":"Use OAuth (see /auth.md) or Authorization: Bearer $AGENT_SEEK_API_KEY."}}},"application/json":{"schema":{"$ref":"#/components/schemas/ProblemDetails"},"example":{"type":"https://agentseek.dev/errors/unauthorized","title":"Unauthorized","status":401,"detail":"Unauthorized","instance":"/v1/search","code":"UNAUTHORIZED","message":"Unauthorized","hint":"Use OAuth (see /auth.md) or Authorization: Bearer $AGENT_SEEK_API_KEY.","error":{"code":"UNAUTHORIZED","message":"Unauthorized","hint":"Use OAuth (see /auth.md) or Authorization: Bearer $AGENT_SEEK_API_KEY."}}}}},"401":{"description":"Missing or invalid credential. WWW-Authenticate: Bearer resource_metadata=…","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/ProblemDetails"},"example":{"type":"https://agentseek.dev/errors/unauthorized","title":"Unauthorized","status":401,"detail":"Unauthorized","instance":"/v1/search","code":"UNAUTHORIZED","message":"Unauthorized","hint":"Use OAuth (see /auth.md) or Authorization: Bearer $AGENT_SEEK_API_KEY.","error":{"code":"UNAUTHORIZED","message":"Unauthorized","hint":"Use OAuth (see /auth.md) or Authorization: Bearer $AGENT_SEEK_API_KEY."}}},"application/json":{"schema":{"$ref":"#/components/schemas/ProblemDetails"},"example":{"type":"https://agentseek.dev/errors/unauthorized","title":"Unauthorized","status":401,"detail":"Unauthorized","instance":"/v1/search","code":"UNAUTHORIZED","message":"Unauthorized","hint":"Use OAuth (see /auth.md) or Authorization: Bearer $AGENT_SEEK_API_KEY.","error":{"code":"UNAUTHORIZED","message":"Unauthorized","hint":"Use OAuth (see /auth.md) or Authorization: Bearer $AGENT_SEEK_API_KEY."}}}},"headers":{"WWW-Authenticate":{"$ref":"#/components/headers/WWWAuthenticate"}}},"403":{"description":"Valid token missing required scope","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/ProblemDetails"},"example":{"type":"https://agentseek.dev/errors/unauthorized","title":"Unauthorized","status":401,"detail":"Unauthorized","instance":"/v1/search","code":"UNAUTHORIZED","message":"Unauthorized","hint":"Use OAuth (see /auth.md) or Authorization: Bearer $AGENT_SEEK_API_KEY.","error":{"code":"UNAUTHORIZED","message":"Unauthorized","hint":"Use OAuth (see /auth.md) or Authorization: Bearer $AGENT_SEEK_API_KEY."}}},"application/json":{"schema":{"$ref":"#/components/schemas/ProblemDetails"},"example":{"type":"https://agentseek.dev/errors/unauthorized","title":"Unauthorized","status":401,"detail":"Unauthorized","instance":"/v1/search","code":"UNAUTHORIZED","message":"Unauthorized","hint":"Use OAuth (see /auth.md) or Authorization: Bearer $AGENT_SEEK_API_KEY.","error":{"code":"UNAUTHORIZED","message":"Unauthorized","hint":"Use OAuth (see /auth.md) or Authorization: Bearer $AGENT_SEEK_API_KEY."}}}}},"422":{"description":"Validation error (RFC 9457 problem+json)","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/ProblemDetails"},"example":{"type":"https://agentseek.dev/errors/unauthorized","title":"Unauthorized","status":401,"detail":"Unauthorized","instance":"/v1/search","code":"UNAUTHORIZED","message":"Unauthorized","hint":"Use OAuth (see /auth.md) or Authorization: Bearer $AGENT_SEEK_API_KEY.","error":{"code":"UNAUTHORIZED","message":"Unauthorized","hint":"Use OAuth (see /auth.md) or Authorization: Bearer $AGENT_SEEK_API_KEY."}}},"application/json":{"schema":{"$ref":"#/components/schemas/ProblemDetails"},"example":{"type":"https://agentseek.dev/errors/unauthorized","title":"Unauthorized","status":401,"detail":"Unauthorized","instance":"/v1/search","code":"UNAUTHORIZED","message":"Unauthorized","hint":"Use OAuth (see /auth.md) or Authorization: Bearer $AGENT_SEEK_API_KEY.","error":{"code":"UNAUTHORIZED","message":"Unauthorized","hint":"Use OAuth (see /auth.md) or Authorization: Bearer $AGENT_SEEK_API_KEY."}}}}},"429":{"description":"Rate limited (60/min). Retry-After + RateLimit headers.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/ProblemDetails"},"example":{"type":"https://agentseek.dev/errors/unauthorized","title":"Unauthorized","status":401,"detail":"Unauthorized","instance":"/v1/search","code":"UNAUTHORIZED","message":"Unauthorized","hint":"Use OAuth (see /auth.md) or Authorization: Bearer $AGENT_SEEK_API_KEY.","error":{"code":"UNAUTHORIZED","message":"Unauthorized","hint":"Use OAuth (see /auth.md) or Authorization: Bearer $AGENT_SEEK_API_KEY."}}},"application/json":{"schema":{"$ref":"#/components/schemas/ProblemDetails"},"example":{"type":"https://agentseek.dev/errors/unauthorized","title":"Unauthorized","status":401,"detail":"Unauthorized","instance":"/v1/search","code":"UNAUTHORIZED","message":"Unauthorized","hint":"Use OAuth (see /auth.md) or Authorization: Bearer $AGENT_SEEK_API_KEY.","error":{"code":"UNAUTHORIZED","message":"Unauthorized","hint":"Use OAuth (see /auth.md) or Authorization: Bearer $AGENT_SEEK_API_KEY."}}}},"headers":{"Retry-After":{"$ref":"#/components/headers/RetryAfter"},"RateLimit":{"$ref":"#/components/headers/RateLimit"}}},"502":{"description":"Upstream discover failed","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/ProblemDetails"},"example":{"type":"https://agentseek.dev/errors/unauthorized","title":"Unauthorized","status":401,"detail":"Unauthorized","instance":"/v1/search","code":"UNAUTHORIZED","message":"Unauthorized","hint":"Use OAuth (see /auth.md) or Authorization: Bearer $AGENT_SEEK_API_KEY.","error":{"code":"UNAUTHORIZED","message":"Unauthorized","hint":"Use OAuth (see /auth.md) or Authorization: Bearer $AGENT_SEEK_API_KEY."}}},"application/json":{"schema":{"$ref":"#/components/schemas/ProblemDetails"},"example":{"type":"https://agentseek.dev/errors/unauthorized","title":"Unauthorized","status":401,"detail":"Unauthorized","instance":"/v1/search","code":"UNAUTHORIZED","message":"Unauthorized","hint":"Use OAuth (see /auth.md) or Authorization: Bearer $AGENT_SEEK_API_KEY.","error":{"code":"UNAUTHORIZED","message":"Unauthorized","hint":"Use OAuth (see /auth.md) or Authorization: Bearer $AGENT_SEEK_API_KEY."}}}}},"503":{"description":"Server missing YDC_API_KEY","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/ProblemDetails"},"example":{"type":"https://agentseek.dev/errors/unauthorized","title":"Unauthorized","status":401,"detail":"Unauthorized","instance":"/v1/search","code":"UNAUTHORIZED","message":"Unauthorized","hint":"Use OAuth (see /auth.md) or Authorization: Bearer $AGENT_SEEK_API_KEY.","error":{"code":"UNAUTHORIZED","message":"Unauthorized","hint":"Use OAuth (see /auth.md) or Authorization: Bearer $AGENT_SEEK_API_KEY."}}},"application/json":{"schema":{"$ref":"#/components/schemas/ProblemDetails"},"example":{"type":"https://agentseek.dev/errors/unauthorized","title":"Unauthorized","status":401,"detail":"Unauthorized","instance":"/v1/search","code":"UNAUTHORIZED","message":"Unauthorized","hint":"Use OAuth (see /auth.md) or Authorization: Bearer $AGENT_SEEK_API_KEY.","error":{"code":"UNAUTHORIZED","message":"Unauthorized","hint":"Use OAuth (see /auth.md) or Authorization: Bearer $AGENT_SEEK_API_KEY."}}}}},"504":{"description":"Upstream timeout","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/ProblemDetails"},"example":{"type":"https://agentseek.dev/errors/unauthorized","title":"Unauthorized","status":401,"detail":"Unauthorized","instance":"/v1/search","code":"UNAUTHORIZED","message":"Unauthorized","hint":"Use OAuth (see /auth.md) or Authorization: Bearer $AGENT_SEEK_API_KEY.","error":{"code":"UNAUTHORIZED","message":"Unauthorized","hint":"Use OAuth (see /auth.md) or Authorization: Bearer $AGENT_SEEK_API_KEY."}}},"application/json":{"schema":{"$ref":"#/components/schemas/ProblemDetails"},"example":{"type":"https://agentseek.dev/errors/unauthorized","title":"Unauthorized","status":401,"detail":"Unauthorized","instance":"/v1/search","code":"UNAUTHORIZED","message":"Unauthorized","hint":"Use OAuth (see /auth.md) or Authorization: Bearer $AGENT_SEEK_API_KEY.","error":{"code":"UNAUTHORIZED","message":"Unauthorized","hint":"Use OAuth (see /auth.md) or Authorization: Bearer $AGENT_SEEK_API_KEY."}}}}}}}},"/api":{"get":{"tags":["meta"],"summary":"Public API discovery (/api)","description":"Same typed public discovery document as GET /v1, at the conventional /api prefix.","operationId":"listPublicApi","responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiDiscoveryResponse"}}},"headers":{"RateLimit":{"$ref":"#/components/headers/RateLimit"},"RateLimit-Policy":{"description":"Policy token, e.g. 60;w=60","schema":{"type":"string"}}}},"400":{"description":"Bad request (RFC 9457 problem+json)","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/ProblemDetails"},"example":{"type":"https://agentseek.dev/errors/unauthorized","title":"Unauthorized","status":401,"detail":"Unauthorized","instance":"/v1/search","code":"UNAUTHORIZED","message":"Unauthorized","hint":"Use OAuth (see /auth.md) or Authorization: Bearer $AGENT_SEEK_API_KEY.","error":{"code":"UNAUTHORIZED","message":"Unauthorized","hint":"Use OAuth (see /auth.md) or Authorization: Bearer $AGENT_SEEK_API_KEY."}}},"application/json":{"schema":{"$ref":"#/components/schemas/ProblemDetails"},"example":{"type":"https://agentseek.dev/errors/unauthorized","title":"Unauthorized","status":401,"detail":"Unauthorized","instance":"/v1/search","code":"UNAUTHORIZED","message":"Unauthorized","hint":"Use OAuth (see /auth.md) or Authorization: Bearer $AGENT_SEEK_API_KEY.","error":{"code":"UNAUTHORIZED","message":"Unauthorized","hint":"Use OAuth (see /auth.md) or Authorization: Bearer $AGENT_SEEK_API_KEY."}}}}},"401":{"description":"Missing or invalid credential. WWW-Authenticate: Bearer resource_metadata=…","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/ProblemDetails"},"example":{"type":"https://agentseek.dev/errors/unauthorized","title":"Unauthorized","status":401,"detail":"Unauthorized","instance":"/v1/search","code":"UNAUTHORIZED","message":"Unauthorized","hint":"Use OAuth (see /auth.md) or Authorization: Bearer $AGENT_SEEK_API_KEY.","error":{"code":"UNAUTHORIZED","message":"Unauthorized","hint":"Use OAuth (see /auth.md) or Authorization: Bearer $AGENT_SEEK_API_KEY."}}},"application/json":{"schema":{"$ref":"#/components/schemas/ProblemDetails"},"example":{"type":"https://agentseek.dev/errors/unauthorized","title":"Unauthorized","status":401,"detail":"Unauthorized","instance":"/v1/search","code":"UNAUTHORIZED","message":"Unauthorized","hint":"Use OAuth (see /auth.md) or Authorization: Bearer $AGENT_SEEK_API_KEY.","error":{"code":"UNAUTHORIZED","message":"Unauthorized","hint":"Use OAuth (see /auth.md) or Authorization: Bearer $AGENT_SEEK_API_KEY."}}}},"headers":{"WWW-Authenticate":{"$ref":"#/components/headers/WWWAuthenticate"}}},"403":{"description":"Valid token missing required scope","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/ProblemDetails"},"example":{"type":"https://agentseek.dev/errors/unauthorized","title":"Unauthorized","status":401,"detail":"Unauthorized","instance":"/v1/search","code":"UNAUTHORIZED","message":"Unauthorized","hint":"Use OAuth (see /auth.md) or Authorization: Bearer $AGENT_SEEK_API_KEY.","error":{"code":"UNAUTHORIZED","message":"Unauthorized","hint":"Use OAuth (see /auth.md) or Authorization: Bearer $AGENT_SEEK_API_KEY."}}},"application/json":{"schema":{"$ref":"#/components/schemas/ProblemDetails"},"example":{"type":"https://agentseek.dev/errors/unauthorized","title":"Unauthorized","status":401,"detail":"Unauthorized","instance":"/v1/search","code":"UNAUTHORIZED","message":"Unauthorized","hint":"Use OAuth (see /auth.md) or Authorization: Bearer $AGENT_SEEK_API_KEY.","error":{"code":"UNAUTHORIZED","message":"Unauthorized","hint":"Use OAuth (see /auth.md) or Authorization: Bearer $AGENT_SEEK_API_KEY."}}}}},"422":{"description":"Validation error (RFC 9457 problem+json)","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/ProblemDetails"},"example":{"type":"https://agentseek.dev/errors/unauthorized","title":"Unauthorized","status":401,"detail":"Unauthorized","instance":"/v1/search","code":"UNAUTHORIZED","message":"Unauthorized","hint":"Use OAuth (see /auth.md) or Authorization: Bearer $AGENT_SEEK_API_KEY.","error":{"code":"UNAUTHORIZED","message":"Unauthorized","hint":"Use OAuth (see /auth.md) or Authorization: Bearer $AGENT_SEEK_API_KEY."}}},"application/json":{"schema":{"$ref":"#/components/schemas/ProblemDetails"},"example":{"type":"https://agentseek.dev/errors/unauthorized","title":"Unauthorized","status":401,"detail":"Unauthorized","instance":"/v1/search","code":"UNAUTHORIZED","message":"Unauthorized","hint":"Use OAuth (see /auth.md) or Authorization: Bearer $AGENT_SEEK_API_KEY.","error":{"code":"UNAUTHORIZED","message":"Unauthorized","hint":"Use OAuth (see /auth.md) or Authorization: Bearer $AGENT_SEEK_API_KEY."}}}}},"429":{"description":"Rate limited (60/min). Retry-After + RateLimit headers.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/ProblemDetails"},"example":{"type":"https://agentseek.dev/errors/unauthorized","title":"Unauthorized","status":401,"detail":"Unauthorized","instance":"/v1/search","code":"UNAUTHORIZED","message":"Unauthorized","hint":"Use OAuth (see /auth.md) or Authorization: Bearer $AGENT_SEEK_API_KEY.","error":{"code":"UNAUTHORIZED","message":"Unauthorized","hint":"Use OAuth (see /auth.md) or Authorization: Bearer $AGENT_SEEK_API_KEY."}}},"application/json":{"schema":{"$ref":"#/components/schemas/ProblemDetails"},"example":{"type":"https://agentseek.dev/errors/unauthorized","title":"Unauthorized","status":401,"detail":"Unauthorized","instance":"/v1/search","code":"UNAUTHORIZED","message":"Unauthorized","hint":"Use OAuth (see /auth.md) or Authorization: Bearer $AGENT_SEEK_API_KEY.","error":{"code":"UNAUTHORIZED","message":"Unauthorized","hint":"Use OAuth (see /auth.md) or Authorization: Bearer $AGENT_SEEK_API_KEY."}}}},"headers":{"Retry-After":{"$ref":"#/components/headers/RetryAfter"},"RateLimit":{"$ref":"#/components/headers/RateLimit"}}},"502":{"description":"Upstream discover failed","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/ProblemDetails"},"example":{"type":"https://agentseek.dev/errors/unauthorized","title":"Unauthorized","status":401,"detail":"Unauthorized","instance":"/v1/search","code":"UNAUTHORIZED","message":"Unauthorized","hint":"Use OAuth (see /auth.md) or Authorization: Bearer $AGENT_SEEK_API_KEY.","error":{"code":"UNAUTHORIZED","message":"Unauthorized","hint":"Use OAuth (see /auth.md) or Authorization: Bearer $AGENT_SEEK_API_KEY."}}},"application/json":{"schema":{"$ref":"#/components/schemas/ProblemDetails"},"example":{"type":"https://agentseek.dev/errors/unauthorized","title":"Unauthorized","status":401,"detail":"Unauthorized","instance":"/v1/search","code":"UNAUTHORIZED","message":"Unauthorized","hint":"Use OAuth (see /auth.md) or Authorization: Bearer $AGENT_SEEK_API_KEY.","error":{"code":"UNAUTHORIZED","message":"Unauthorized","hint":"Use OAuth (see /auth.md) or Authorization: Bearer $AGENT_SEEK_API_KEY."}}}}},"503":{"description":"Server missing YDC_API_KEY","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/ProblemDetails"},"example":{"type":"https://agentseek.dev/errors/unauthorized","title":"Unauthorized","status":401,"detail":"Unauthorized","instance":"/v1/search","code":"UNAUTHORIZED","message":"Unauthorized","hint":"Use OAuth (see /auth.md) or Authorization: Bearer $AGENT_SEEK_API_KEY.","error":{"code":"UNAUTHORIZED","message":"Unauthorized","hint":"Use OAuth (see /auth.md) or Authorization: Bearer $AGENT_SEEK_API_KEY."}}},"application/json":{"schema":{"$ref":"#/components/schemas/ProblemDetails"},"example":{"type":"https://agentseek.dev/errors/unauthorized","title":"Unauthorized","status":401,"detail":"Unauthorized","instance":"/v1/search","code":"UNAUTHORIZED","message":"Unauthorized","hint":"Use OAuth (see /auth.md) or Authorization: Bearer $AGENT_SEEK_API_KEY.","error":{"code":"UNAUTHORIZED","message":"Unauthorized","hint":"Use OAuth (see /auth.md) or Authorization: Bearer $AGENT_SEEK_API_KEY."}}}}},"504":{"description":"Upstream timeout","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/ProblemDetails"},"example":{"type":"https://agentseek.dev/errors/unauthorized","title":"Unauthorized","status":401,"detail":"Unauthorized","instance":"/v1/search","code":"UNAUTHORIZED","message":"Unauthorized","hint":"Use OAuth (see /auth.md) or Authorization: Bearer $AGENT_SEEK_API_KEY.","error":{"code":"UNAUTHORIZED","message":"Unauthorized","hint":"Use OAuth (see /auth.md) or Authorization: Bearer $AGENT_SEEK_API_KEY."}}},"application/json":{"schema":{"$ref":"#/components/schemas/ProblemDetails"},"example":{"type":"https://agentseek.dev/errors/unauthorized","title":"Unauthorized","status":401,"detail":"Unauthorized","instance":"/v1/search","code":"UNAUTHORIZED","message":"Unauthorized","hint":"Use OAuth (see /auth.md) or Authorization: Bearer $AGENT_SEEK_API_KEY.","error":{"code":"UNAUTHORIZED","message":"Unauthorized","hint":"Use OAuth (see /auth.md) or Authorization: Bearer $AGENT_SEEK_API_KEY."}}}}}}}},"/v1/sandbox":{"get":{"tags":["search"],"summary":"Zero-auth sandbox example","description":"Canned SearchResponse for onboarding. Does not call You.com or Jev and does not require a key. Use this to inspect the result shape before calling POST /v1/search.","operationId":"sandboxSearchExample","responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/SearchResponse"}}},"headers":{"RateLimit":{"$ref":"#/components/headers/RateLimit"},"RateLimit-Policy":{"description":"Policy token, e.g. 60;w=60","schema":{"type":"string"}}}},"400":{"description":"Bad request (RFC 9457 problem+json)","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/ProblemDetails"},"example":{"type":"https://agentseek.dev/errors/unauthorized","title":"Unauthorized","status":401,"detail":"Unauthorized","instance":"/v1/search","code":"UNAUTHORIZED","message":"Unauthorized","hint":"Use OAuth (see /auth.md) or Authorization: Bearer $AGENT_SEEK_API_KEY.","error":{"code":"UNAUTHORIZED","message":"Unauthorized","hint":"Use OAuth (see /auth.md) or Authorization: Bearer $AGENT_SEEK_API_KEY."}}},"application/json":{"schema":{"$ref":"#/components/schemas/ProblemDetails"},"example":{"type":"https://agentseek.dev/errors/unauthorized","title":"Unauthorized","status":401,"detail":"Unauthorized","instance":"/v1/search","code":"UNAUTHORIZED","message":"Unauthorized","hint":"Use OAuth (see /auth.md) or Authorization: Bearer $AGENT_SEEK_API_KEY.","error":{"code":"UNAUTHORIZED","message":"Unauthorized","hint":"Use OAuth (see /auth.md) or Authorization: Bearer $AGENT_SEEK_API_KEY."}}}}},"401":{"description":"Missing or invalid credential. WWW-Authenticate: Bearer resource_metadata=…","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/ProblemDetails"},"example":{"type":"https://agentseek.dev/errors/unauthorized","title":"Unauthorized","status":401,"detail":"Unauthorized","instance":"/v1/search","code":"UNAUTHORIZED","message":"Unauthorized","hint":"Use OAuth (see /auth.md) or Authorization: Bearer $AGENT_SEEK_API_KEY.","error":{"code":"UNAUTHORIZED","message":"Unauthorized","hint":"Use OAuth (see /auth.md) or Authorization: Bearer $AGENT_SEEK_API_KEY."}}},"application/json":{"schema":{"$ref":"#/components/schemas/ProblemDetails"},"example":{"type":"https://agentseek.dev/errors/unauthorized","title":"Unauthorized","status":401,"detail":"Unauthorized","instance":"/v1/search","code":"UNAUTHORIZED","message":"Unauthorized","hint":"Use OAuth (see /auth.md) or Authorization: Bearer $AGENT_SEEK_API_KEY.","error":{"code":"UNAUTHORIZED","message":"Unauthorized","hint":"Use OAuth (see /auth.md) or Authorization: Bearer $AGENT_SEEK_API_KEY."}}}},"headers":{"WWW-Authenticate":{"$ref":"#/components/headers/WWWAuthenticate"}}},"403":{"description":"Valid token missing required scope","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/ProblemDetails"},"example":{"type":"https://agentseek.dev/errors/unauthorized","title":"Unauthorized","status":401,"detail":"Unauthorized","instance":"/v1/search","code":"UNAUTHORIZED","message":"Unauthorized","hint":"Use OAuth (see /auth.md) or Authorization: Bearer $AGENT_SEEK_API_KEY.","error":{"code":"UNAUTHORIZED","message":"Unauthorized","hint":"Use OAuth (see /auth.md) or Authorization: Bearer $AGENT_SEEK_API_KEY."}}},"application/json":{"schema":{"$ref":"#/components/schemas/ProblemDetails"},"example":{"type":"https://agentseek.dev/errors/unauthorized","title":"Unauthorized","status":401,"detail":"Unauthorized","instance":"/v1/search","code":"UNAUTHORIZED","message":"Unauthorized","hint":"Use OAuth (see /auth.md) or Authorization: Bearer $AGENT_SEEK_API_KEY.","error":{"code":"UNAUTHORIZED","message":"Unauthorized","hint":"Use OAuth (see /auth.md) or Authorization: Bearer $AGENT_SEEK_API_KEY."}}}}},"422":{"description":"Validation error (RFC 9457 problem+json)","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/ProblemDetails"},"example":{"type":"https://agentseek.dev/errors/unauthorized","title":"Unauthorized","status":401,"detail":"Unauthorized","instance":"/v1/search","code":"UNAUTHORIZED","message":"Unauthorized","hint":"Use OAuth (see /auth.md) or Authorization: Bearer $AGENT_SEEK_API_KEY.","error":{"code":"UNAUTHORIZED","message":"Unauthorized","hint":"Use OAuth (see /auth.md) or Authorization: Bearer $AGENT_SEEK_API_KEY."}}},"application/json":{"schema":{"$ref":"#/components/schemas/ProblemDetails"},"example":{"type":"https://agentseek.dev/errors/unauthorized","title":"Unauthorized","status":401,"detail":"Unauthorized","instance":"/v1/search","code":"UNAUTHORIZED","message":"Unauthorized","hint":"Use OAuth (see /auth.md) or Authorization: Bearer $AGENT_SEEK_API_KEY.","error":{"code":"UNAUTHORIZED","message":"Unauthorized","hint":"Use OAuth (see /auth.md) or Authorization: Bearer $AGENT_SEEK_API_KEY."}}}}},"429":{"description":"Rate limited (60/min). Retry-After + RateLimit headers.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/ProblemDetails"},"example":{"type":"https://agentseek.dev/errors/unauthorized","title":"Unauthorized","status":401,"detail":"Unauthorized","instance":"/v1/search","code":"UNAUTHORIZED","message":"Unauthorized","hint":"Use OAuth (see /auth.md) or Authorization: Bearer $AGENT_SEEK_API_KEY.","error":{"code":"UNAUTHORIZED","message":"Unauthorized","hint":"Use OAuth (see /auth.md) or Authorization: Bearer $AGENT_SEEK_API_KEY."}}},"application/json":{"schema":{"$ref":"#/components/schemas/ProblemDetails"},"example":{"type":"https://agentseek.dev/errors/unauthorized","title":"Unauthorized","status":401,"detail":"Unauthorized","instance":"/v1/search","code":"UNAUTHORIZED","message":"Unauthorized","hint":"Use OAuth (see /auth.md) or Authorization: Bearer $AGENT_SEEK_API_KEY.","error":{"code":"UNAUTHORIZED","message":"Unauthorized","hint":"Use OAuth (see /auth.md) or Authorization: Bearer $AGENT_SEEK_API_KEY."}}}},"headers":{"Retry-After":{"$ref":"#/components/headers/RetryAfter"},"RateLimit":{"$ref":"#/components/headers/RateLimit"}}},"502":{"description":"Upstream discover failed","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/ProblemDetails"},"example":{"type":"https://agentseek.dev/errors/unauthorized","title":"Unauthorized","status":401,"detail":"Unauthorized","instance":"/v1/search","code":"UNAUTHORIZED","message":"Unauthorized","hint":"Use OAuth (see /auth.md) or Authorization: Bearer $AGENT_SEEK_API_KEY.","error":{"code":"UNAUTHORIZED","message":"Unauthorized","hint":"Use OAuth (see /auth.md) or Authorization: Bearer $AGENT_SEEK_API_KEY."}}},"application/json":{"schema":{"$ref":"#/components/schemas/ProblemDetails"},"example":{"type":"https://agentseek.dev/errors/unauthorized","title":"Unauthorized","status":401,"detail":"Unauthorized","instance":"/v1/search","code":"UNAUTHORIZED","message":"Unauthorized","hint":"Use OAuth (see /auth.md) or Authorization: Bearer $AGENT_SEEK_API_KEY.","error":{"code":"UNAUTHORIZED","message":"Unauthorized","hint":"Use OAuth (see /auth.md) or Authorization: Bearer $AGENT_SEEK_API_KEY."}}}}},"503":{"description":"Server missing YDC_API_KEY","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/ProblemDetails"},"example":{"type":"https://agentseek.dev/errors/unauthorized","title":"Unauthorized","status":401,"detail":"Unauthorized","instance":"/v1/search","code":"UNAUTHORIZED","message":"Unauthorized","hint":"Use OAuth (see /auth.md) or Authorization: Bearer $AGENT_SEEK_API_KEY.","error":{"code":"UNAUTHORIZED","message":"Unauthorized","hint":"Use OAuth (see /auth.md) or Authorization: Bearer $AGENT_SEEK_API_KEY."}}},"application/json":{"schema":{"$ref":"#/components/schemas/ProblemDetails"},"example":{"type":"https://agentseek.dev/errors/unauthorized","title":"Unauthorized","status":401,"detail":"Unauthorized","instance":"/v1/search","code":"UNAUTHORIZED","message":"Unauthorized","hint":"Use OAuth (see /auth.md) or Authorization: Bearer $AGENT_SEEK_API_KEY.","error":{"code":"UNAUTHORIZED","message":"Unauthorized","hint":"Use OAuth (see /auth.md) or Authorization: Bearer $AGENT_SEEK_API_KEY."}}}}},"504":{"description":"Upstream timeout","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/ProblemDetails"},"example":{"type":"https://agentseek.dev/errors/unauthorized","title":"Unauthorized","status":401,"detail":"Unauthorized","instance":"/v1/search","code":"UNAUTHORIZED","message":"Unauthorized","hint":"Use OAuth (see /auth.md) or Authorization: Bearer $AGENT_SEEK_API_KEY.","error":{"code":"UNAUTHORIZED","message":"Unauthorized","hint":"Use OAuth (see /auth.md) or Authorization: Bearer $AGENT_SEEK_API_KEY."}}},"application/json":{"schema":{"$ref":"#/components/schemas/ProblemDetails"},"example":{"type":"https://agentseek.dev/errors/unauthorized","title":"Unauthorized","status":401,"detail":"Unauthorized","instance":"/v1/search","code":"UNAUTHORIZED","message":"Unauthorized","hint":"Use OAuth (see /auth.md) or Authorization: Bearer $AGENT_SEEK_API_KEY.","error":{"code":"UNAUTHORIZED","message":"Unauthorized","hint":"Use OAuth (see /auth.md) or Authorization: Bearer $AGENT_SEEK_API_KEY."}}}}}}}}},"components":{"schemas":{"ApiDiscoveryResponse":{"properties":{"name":{"description":"Public API display name (Agent Seek API)","title":"Name","type":"string"},"version":{"description":"Prototype build version","title":"Version","type":"string"},"description":{"description":"One-line description of the ranked search API","title":"Description","type":"string"},"openapi":{"description":"Absolute URL of Agent Seek OpenAPI (/openapi.json)","title":"Openapi","type":"string"},"docs":{"description":"Absolute URL of Agent Seek docs (/docs)","title":"Docs","type":"string"},"developers":{"description":"Absolute URL of Agent Seek API portal (/developers)","title":"Developers","type":"string"},"auth":{"description":"Absolute URL of Agent Seek authentication (/auth.md)","title":"Auth","type":"string"},"health":{"description":"Absolute URL of GET /health","title":"Health","type":"string"},"search":{"description":"Absolute URL of POST /v1/search","title":"Search","type":"string"},"search_get":{"description":"Absolute URL of GET /v1/search","title":"Search Get","type":"string"},"mcp":{"description":"Absolute URL of Agent Seek MCP (/mcp)","title":"Mcp","type":"string"},"sandbox":{"description":"Absolute URL of zero-auth GET /v1/sandbox","title":"Sandbox","type":"string"},"versioning":{"description":"Absolute URL of /docs/versioning.md","title":"Versioning","type":"string"},"oauth_authorization_server":{"description":"RFC 8414 authorization-server metadata URL","title":"Oauth Authorization Server","type":"string"},"oauth_protected_resource":{"description":"RFC 9728 protected-resource metadata URL","title":"Oauth Protected Resource","type":"string"},"scopes":{"additionalProperties":{"type":"string"},"description":"OAuth scope name → description","title":"Scopes","type":"object"},"auth_methods":{"description":"Accepted auth methods (oauth2, api_key)","items":{"type":"string"},"title":"Auth Methods","type":"array"},"errors":{"description":"Error format (RFC 9457 application/problem+json)","title":"Errors","type":"string"},"deprecation_policy":{"description":"URL versioning and Sunset policy summary","title":"Deprecation Policy","type":"string"}},"required":["name","version","description","openapi","docs","developers","auth","health","search","search_get","mcp","sandbox","versioning","oauth_authorization_server","oauth_protected_resource","scopes","auth_methods","errors","deprecation_policy"],"title":"ApiDiscoveryResponse","type":"object"},"HTTPValidationError":{"properties":{"detail":{"items":{"$ref":"#/components/schemas/ValidationError"},"type":"array","title":"Detail"}},"type":"object","title":"HTTPValidationError"},"HealthResponse":{"properties":{"ok":{"description":"Process liveness","title":"Ok","type":"boolean"},"version":{"description":"Prototype version (same as OpenAPI info.version)","title":"Version","type":"string"}},"required":["ok","version"],"title":"HealthResponse","type":"object"},"RankedResult":{"properties":{"rank":{"description":"1-based Agent Seek rank after Jev cascade","minimum":1,"title":"Rank","type":"integer"},"url":{"description":"Result URL","title":"Url","type":"string"},"title":{"description":"Result title","title":"Title","type":"string"},"snippet":{"description":"Short excerpt used for ranking and display","title":"Snippet","type":"string"},"score":{"description":"Jev relevance score in 0–1","title":"Score","type":"number"},"flags":{"description":"Keep/skip chips such as on_topic","items":{"type":"string"},"title":"Flags","type":"array"},"raw_rank":{"description":"Original You.com discover rank","minimum":1,"title":"Raw Rank","type":"integer"},"provider":{"default":"you.com","description":"Discover provider id (you.com or sandbox)","title":"Provider","type":"string"},"signals":{"anyOf":[{"additionalProperties":{"type":"number"},"type":"object"},{"type":"null"}],"default":null,"description":"Optional Jev noul map (answerability, authority, on_topic, states_sought_fact, subject_match, spam, prompt_injection)","title":"Signals"}},"required":["rank","url","title","snippet","score","raw_rank"],"title":"RankedResult","type":"object"},"SearchMeta":{"properties":{"q":{"description":"Echo of the search query","title":"Q","type":"string"},"candidates_in":{"description":"Discover candidates considered","minimum":0,"title":"Candidates In","type":"integer"},"kept":{"description":"Results returned after ranking and gates","minimum":0,"title":"Kept","type":"integer"},"latency_ms":{"description":"End-to-end latency in milliseconds","minimum":0,"title":"Latency Ms","type":"integer"},"mode":{"default":"deep","description":"deep (default) or snip","title":"Mode","type":"string"},"provider":{"default":"you.com","description":"Discover provider id","title":"Provider","type":"string"},"agent_seek_version":{"default":"0.1.39","description":"Prototype build version","title":"Agent Seek Version","type":"string"},"ranking":{"default":"jev","description":"Ranking path: jev | raw | raw_fallback | sandbox","title":"Ranking","type":"string"},"discover_ms":{"anyOf":[{"type":"integer"},{"type":"null"}],"default":null,"description":"Discover-stage latency ms","title":"Discover Ms"},"rank_ms":{"anyOf":[{"type":"integer"},{"type":"null"}],"default":null,"description":"Rank-stage latency ms","title":"Rank Ms"},"fetch_ms":{"anyOf":[{"type":"integer"},{"type":"null"}],"default":null,"description":"Deep page-fetch wall time ms","title":"Fetch Ms"},"cache_hit":{"anyOf":[{"type":"boolean"},{"type":"null"}],"default":null,"description":"True when discover cache hit","title":"Cache Hit"},"cache_scope":{"anyOf":[{"type":"string"},{"type":"null"}],"default":null,"description":"Cache scope, e.g. discover","title":"Cache Scope"}},"required":["q","candidates_in","kept","latency_ms"],"title":"SearchMeta","type":"object"},"SearchRequest":{"properties":{"q":{"description":"Search query (1–500 characters)","maxLength":500,"minLength":1,"title":"Q","type":"string"},"k":{"default":10,"description":"Number of ranked results to return","maximum":25,"minimum":1,"title":"K","type":"integer"},"max_candidates":{"default":50,"description":"Discover cap (hard max 100)","maximum":100,"minimum":1,"title":"Max Candidates","type":"integer"},"mode":{"default":"deep","description":"deep (default; Stage A survivor fetch, cap 12) or snip","title":"Mode","type":"string"},"rank":{"default":"on","description":"on | off","title":"Rank","type":"string"},"nocache":{"default":false,"description":"Force discover cache miss","title":"Nocache","type":"boolean"}},"required":["q"],"title":"SearchRequest","type":"object"},"SearchResponse":{"properties":{"results":{"description":"Top-k ranked results in Agent Seek order","items":{"$ref":"#/components/schemas/RankedResult"},"title":"Results","type":"array"},"meta":{"$ref":"#/components/schemas/SearchMeta","description":"Query accounting and ranking path"},"raw_results":{"anyOf":[{"items":{"$ref":"#/components/schemas/RankedResult"},"type":"array"},{"type":"null"}],"default":null,"description":"Same candidate set in original discover order (UI toggle)","title":"Raw Results"}},"required":["results","meta"],"title":"SearchResponse","type":"object"},"ValidationError":{"properties":{"loc":{"items":{"anyOf":[{"type":"string"},{"type":"integer"}]},"type":"array","title":"Location"},"msg":{"type":"string","title":"Message"},"type":{"type":"string","title":"Error Type"},"input":{"title":"Input"},"ctx":{"type":"object","title":"Context"}},"type":"object","required":["loc","msg","type"],"title":"ValidationError"},"ErrorBody":{"type":"object","required":["code","message","hint"],"properties":{"code":{"type":"string","description":"Machine-readable error code"},"message":{"type":"string","description":"Human-readable message"},"hint":{"type":"string","description":"How an agent should recover"}}},"ProblemDetails":{"type":"object","required":["type","title","status","detail","code","message","hint","error"],"properties":{"type":{"type":"string","format":"uri","description":"RFC 9457 problem type URI"},"title":{"type":"string","description":"Short, stable problem title"},"status":{"type":"integer","description":"HTTP status copy"},"detail":{"type":"string","description":"Occurrence-specific explanation"},"instance":{"type":"string","description":"Request path that failed"},"code":{"type":"string","description":"Machine-readable error code"},"message":{"type":"string","description":"Human-readable message"},"hint":{"type":"string","description":"How an agent should recover"},"error":{"$ref":"#/components/schemas/ErrorBody"},"errors":{"description":"Optional validation issue list"}}},"ErrorResponse":{"$ref":"#/components/schemas/ProblemDetails"}},"securitySchemes":{"AgentSeekApiKey":{"type":"http","scheme":"bearer","bearerFormat":"API key","description":"Shared AGENT_SEEK_API_KEY. Alternate to OAuth 2.0. See /auth.md."},"OAuth2":{"type":"oauth2","description":"OAuth 2.0 authorization code + PKCE (S256). See /auth.md.","flows":{"authorizationCode":{"authorizationUrl":"/oauth2/authorize","tokenUrl":"/oauth2/token","refreshUrl":"/oauth2/token","scopes":{"search:read":"Call ranked web search (POST /v1/search and search_web MCP tool).","mcp:invoke":"Call Agent Seek MCP tools over Streamable HTTP.","health:read":"Read health, docs, and capability metadata."}}}}},"headers":{"RateLimit":{"description":"RFC RateLimit header: limit, remaining, reset.","schema":{"type":"string"}},"RetryAfter":{"description":"Seconds to wait after 429.","schema":{"type":"string"}},"WWWAuthenticate":{"description":"WorkOS/RFC 9728: Bearer resource_metadata=\"<PRM URL>\" (no realm).","schema":{"type":"string"}},"Deprecation":{"description":"RFC 8594 Deprecation header when a version or field is retiring.","schema":{"type":"string"}},"Sunset":{"description":"HTTP Sunset date (IMF-fixdate) for a retiring version.","schema":{"type":"string"}}}},"tags":[{"name":"search","description":"Ranked web search. OAuth scope search:read or Bearer AGENT_SEEK_API_KEY."},{"name":"meta","description":"Liveness and service identity."}],"servers":[{"url":"https://agentseek.dev","description":"Live Agent Seek prototype (agentseek.dev)"},{"url":"/","description":"This Agent Seek host"}]}