{"openapi":"3.1.0","info":{"title":"Agent Seek OpenAPI","description":"Less SEO. More signal. Agent Seek returns ranked sources; the caller writes the answer.\nYou.com discovers candidates, TypeSafe Jev cascade-ranks them, and `POST /v1/search`\nreturns 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:** optional Upstash Redis REST sliding window, **per client IP**\n(default 60/min via `AGENT_SEEK_RATE_LIMIT_PER_MIN`). Disabled when\n`UPSTASH_REDIS_REST_URL` or `UPSTASH_REDIS_REST_TOKEN` is empty. Applied to\nsearch and MCP `search_web` only. `/v1/*`, `/mcp`, and `/health` include RFC\n`RateLimit` + `RateLimit-Policy`. Burst `429` includes `Retry-After`. Redis\nerrors while enabled fail closed with `503`.\n\n**Website demo quota:** off unless `AGENT_SEEK_DEMO_MODE=enabled` (code\ndefault `disabled`). When enabled, REST `/v1/search`, `/api/v1/search`, and\nMCP `search_web` share a lifetime per-IP allowance (default 5 via\n`AGENT_SEEK_DEMO_SEARCH_LIMIT`; no time reset). Exhausted calls return `429`\n`application/problem+json` with `code=DEMO_EXHAUSTED` and no `Retry-After`.\nUnauthenticated MCP helper tools do not consume this quota.\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=snip` (title/URL/snippet; cheaper/faster). Pass `mode=deep` for Stage A survivor fetch (cap 12; not a full-web crawl). Website UI is fixed `snip`.\n\n**Injection:** Web results are scored for prompt injection before the agent reads them (signal `prompt_injection`; UI: Injection risk).\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 (0.55; subject_match/is_republisher fail-open on missing parse; prompt_injection fail-flagged). If hard gates empty the scored list, pre-gate ranking is restored and each restored row has gates_relaxed true (relaxed-safety response; not a SearchMeta field).\n\n**Caps:** `max_candidates` ≤ 100; default 50 in, `k` default 10 (1–25).\nDo not ask Agent Seek to write answers.\nPrefer the top 1–2 ranked sources before expanding. One good keeper beats a context window full of searches.","version":"0.3.0","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://dev.agentseek.dev/errors/bad-request","title":"Bad Request","status":400,"detail":"mode must be 'snip' or 'deep'","instance":"/v1/search","code":"BAD_REQUEST","message":"mode must be 'snip' or 'deep'","hint":"Check request fields against /openapi.json. mode must be 'snip' or 'deep'.","error":{"code":"BAD_REQUEST","message":"mode must be 'snip' or 'deep'","hint":"Check request fields against /openapi.json. mode must be 'snip' or 'deep'."}}},"application/json":{"schema":{"$ref":"#/components/schemas/ProblemDetails"},"example":{"type":"https://dev.agentseek.dev/errors/bad-request","title":"Bad Request","status":400,"detail":"mode must be 'snip' or 'deep'","instance":"/v1/search","code":"BAD_REQUEST","message":"mode must be 'snip' or 'deep'","hint":"Check request fields against /openapi.json. mode must be 'snip' or 'deep'.","error":{"code":"BAD_REQUEST","message":"mode must be 'snip' or 'deep'","hint":"Check request fields against /openapi.json. mode must be 'snip' or 'deep'."}}}}},"401":{"description":"Missing or invalid credential. WWW-Authenticate: Bearer resource_metadata=…","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/ProblemDetails"},"example":{"type":"https://dev.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://dev.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://dev.agentseek.dev/errors/forbidden","title":"Forbidden","status":403,"detail":"Insufficient scope","instance":"/v1/search","code":"FORBIDDEN","message":"Insufficient scope","hint":"Token is valid but missing the required OAuth scope. See /auth.md.","error":{"code":"FORBIDDEN","message":"Insufficient scope","hint":"Token is valid but missing the required OAuth scope. See /auth.md."}}},"application/json":{"schema":{"$ref":"#/components/schemas/ProblemDetails"},"example":{"type":"https://dev.agentseek.dev/errors/forbidden","title":"Forbidden","status":403,"detail":"Insufficient scope","instance":"/v1/search","code":"FORBIDDEN","message":"Insufficient scope","hint":"Token is valid but missing the required OAuth scope. See /auth.md.","error":{"code":"FORBIDDEN","message":"Insufficient scope","hint":"Token is valid but missing the required OAuth scope. See /auth.md."}}}}},"422":{"description":"Validation error (RFC 9457 problem+json)","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/ProblemDetails"},"example":{"type":"https://dev.agentseek.dev/errors/validation-error","title":"Validation Error","status":422,"detail":"Request validation failed","instance":"/v1/search","code":"VALIDATION_ERROR","message":"Request validation failed","hint":"q is required (1–500 chars); k 1–25; max_candidates 1–100. See /openapi.json.","error":{"code":"VALIDATION_ERROR","message":"Request validation failed","hint":"q is required (1–500 chars); k 1–25; max_candidates 1–100. See /openapi.json."}}},"application/json":{"schema":{"$ref":"#/components/schemas/ProblemDetails"},"example":{"type":"https://dev.agentseek.dev/errors/validation-error","title":"Validation Error","status":422,"detail":"Request validation failed","instance":"/v1/search","code":"VALIDATION_ERROR","message":"Request validation failed","hint":"q is required (1–500 chars); k 1–25; max_candidates 1–100. See /openapi.json.","error":{"code":"VALIDATION_ERROR","message":"Request validation failed","hint":"q is required (1–500 chars); k 1–25; max_candidates 1–100. See /openapi.json."}}}}},"429":{"description":"Rate limited (per client IP when Upstash is enabled; default 60/min burst, Retry-After + RateLimit) or website demo quota exhausted (REST and MCP search_web share the per-IP allowance; code DEMO_EXHAUSTED; no Retry-After).","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/ProblemDetails"},"example":{"type":"https://dev.agentseek.dev/errors/rate-limited","title":"Rate Limited","status":429,"detail":"Rate limit exceeded","instance":"/v1/search","code":"RATE_LIMITED","message":"Rate limit exceeded","hint":"Wait Retry-After seconds, then retry. When Upstash is enabled, the live burst limit is per client IP (default 60 requests/minute).","error":{"code":"RATE_LIMITED","message":"Rate limit exceeded","hint":"Wait Retry-After seconds, then retry. When Upstash is enabled, the live burst limit is per client IP (default 60 requests/minute)."}}},"application/json":{"schema":{"$ref":"#/components/schemas/ProblemDetails"},"example":{"type":"https://dev.agentseek.dev/errors/rate-limited","title":"Rate Limited","status":429,"detail":"Rate limit exceeded","instance":"/v1/search","code":"RATE_LIMITED","message":"Rate limit exceeded","hint":"Wait Retry-After seconds, then retry. When Upstash is enabled, the live burst limit is per client IP (default 60 requests/minute).","error":{"code":"RATE_LIMITED","message":"Rate limit exceeded","hint":"Wait Retry-After seconds, then retry. When Upstash is enabled, the live burst limit is per client IP (default 60 requests/minute)."}}}},"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://dev.agentseek.dev/errors/upstream-error","title":"Upstream Error","status":502,"detail":"Upstream discover failed","instance":"/v1/search","code":"UPSTREAM_ERROR","message":"Upstream discover failed","hint":"Discover provider failed. Retry with backoff.","error":{"code":"UPSTREAM_ERROR","message":"Upstream discover failed","hint":"Discover provider failed. Retry with backoff."}}},"application/json":{"schema":{"$ref":"#/components/schemas/ProblemDetails"},"example":{"type":"https://dev.agentseek.dev/errors/upstream-error","title":"Upstream Error","status":502,"detail":"Upstream discover failed","instance":"/v1/search","code":"UPSTREAM_ERROR","message":"Upstream discover failed","hint":"Discover provider failed. Retry with backoff.","error":{"code":"UPSTREAM_ERROR","message":"Upstream discover failed","hint":"Discover provider failed. Retry with backoff."}}}}},"503":{"description":"Server missing YDC_API_KEY","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/ProblemDetails"},"example":{"type":"https://dev.agentseek.dev/errors/service-unavailable","title":"Service Unavailable","status":503,"detail":"YDC_API_KEY not configured","instance":"/v1/search","code":"SERVICE_UNAVAILABLE","message":"YDC_API_KEY not configured","hint":"Server is missing upstream configuration (YDC_API_KEY), or the rate limiter is unavailable. Retry with backoff.","error":{"code":"SERVICE_UNAVAILABLE","message":"YDC_API_KEY not configured","hint":"Server is missing upstream configuration (YDC_API_KEY), or the rate limiter is unavailable. Retry with backoff."}}},"application/json":{"schema":{"$ref":"#/components/schemas/ProblemDetails"},"example":{"type":"https://dev.agentseek.dev/errors/service-unavailable","title":"Service Unavailable","status":503,"detail":"YDC_API_KEY not configured","instance":"/v1/search","code":"SERVICE_UNAVAILABLE","message":"YDC_API_KEY not configured","hint":"Server is missing upstream configuration (YDC_API_KEY), or the rate limiter is unavailable. Retry with backoff.","error":{"code":"SERVICE_UNAVAILABLE","message":"YDC_API_KEY not configured","hint":"Server is missing upstream configuration (YDC_API_KEY), or the rate limiter is unavailable. Retry with backoff."}}}}},"504":{"description":"Upstream timeout","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/ProblemDetails"},"example":{"type":"https://dev.agentseek.dev/errors/upstream-timeout","title":"Upstream Timeout","status":504,"detail":"Upstream timeout","instance":"/v1/search","code":"UPSTREAM_TIMEOUT","message":"Upstream timeout","hint":"Upstream timed out. Retry with backoff or a smaller max_candidates.","error":{"code":"UPSTREAM_TIMEOUT","message":"Upstream timeout","hint":"Upstream timed out. Retry with backoff or a smaller max_candidates."}}},"application/json":{"schema":{"$ref":"#/components/schemas/ProblemDetails"},"example":{"type":"https://dev.agentseek.dev/errors/upstream-timeout","title":"Upstream Timeout","status":504,"detail":"Upstream timeout","instance":"/v1/search","code":"UPSTREAM_TIMEOUT","message":"Upstream timeout","hint":"Upstream timed out. Retry with backoff or a smaller max_candidates.","error":{"code":"UPSTREAM_TIMEOUT","message":"Upstream timeout","hint":"Upstream timed out. Retry with backoff or a smaller max_candidates."}}}}}}}},"/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=snip` (title/URL/snippet; cheaper/faster). Pass `mode=deep` for Stage A survivor fetch (cap 12; not a full-web crawl). Website UI is fixed `snip`. Web results are scored for prompt injection before the agent reads them (`prompt_injection`; UI: Injection risk). If hard gates empty the scored list, pre-gate ranking is restored and each restored row has gates_relaxed true (relaxed-safety response; not a SearchMeta field). OAuth scope `search:read` or Bearer AGENT_SEEK_API_KEY. Burst rate limit: optional Upstash per client IP, default 60/min (RateLimit + Retry-After). When AGENT_SEEK_DEMO_MODE=enabled, REST /v1/search, /api/v1/search, and MCP search_web share a lifetime per-IP demo quota (default 5; 429 code DEMO_EXHAUSTED; no Retry-After). 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=snip` (title/URL/snippet; cheaper/faster). Pass `mode=deep` for Stage A survivor fetch (cap 12; not a full-web crawl). Website UI is fixed `snip`. Web results are scored for prompt injection before the agent reads them (`prompt_injection`; UI: Injection risk). If hard gates empty the scored list, pre-gate ranking is restored and each restored row has gates_relaxed true (relaxed-safety response; not a SearchMeta field). OAuth scope `search:read` or Bearer AGENT_SEEK_API_KEY. Burst rate limit: optional Upstash per client IP, default 60/min (RateLimit + Retry-After). When AGENT_SEEK_DEMO_MODE=enabled, REST /v1/search, /api/v1/search, and MCP search_web share a lifetime per-IP demo quota (default 5; 429 code DEMO_EXHAUSTED; no Retry-After). 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://dev.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://dev.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 (per client IP when Upstash is enabled; default 60/min burst, Retry-After + RateLimit) or website demo quota exhausted (REST and MCP search_web share the per-IP allowance; code DEMO_EXHAUSTED; no Retry-After).","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/ProblemDetails"},"example":{"type":"https://dev.agentseek.dev/errors/rate-limited","title":"Rate Limited","status":429,"detail":"Rate limit exceeded","instance":"/v1/search","code":"RATE_LIMITED","message":"Rate limit exceeded","hint":"Wait Retry-After seconds, then retry. When Upstash is enabled, the live burst limit is per client IP (default 60 requests/minute).","error":{"code":"RATE_LIMITED","message":"Rate limit exceeded","hint":"Wait Retry-After seconds, then retry. When Upstash is enabled, the live burst limit is per client IP (default 60 requests/minute)."}}},"application/json":{"schema":{"$ref":"#/components/schemas/ProblemDetails"},"example":{"type":"https://dev.agentseek.dev/errors/rate-limited","title":"Rate Limited","status":429,"detail":"Rate limit exceeded","instance":"/v1/search","code":"RATE_LIMITED","message":"Rate limit exceeded","hint":"Wait Retry-After seconds, then retry. When Upstash is enabled, the live burst limit is per client IP (default 60 requests/minute).","error":{"code":"RATE_LIMITED","message":"Rate limit exceeded","hint":"Wait Retry-After seconds, then retry. When Upstash is enabled, the live burst limit is per client IP (default 60 requests/minute)."}}}},"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://dev.agentseek.dev/errors/validation-error","title":"Validation Error","status":422,"detail":"Request validation failed","instance":"/v1/search","code":"VALIDATION_ERROR","message":"Request validation failed","hint":"q is required (1–500 chars); k 1–25; max_candidates 1–100. See /openapi.json.","error":{"code":"VALIDATION_ERROR","message":"Request validation failed","hint":"q is required (1–500 chars); k 1–25; max_candidates 1–100. See /openapi.json."}}},"application/json":{"schema":{"$ref":"#/components/schemas/ProblemDetails"},"example":{"type":"https://dev.agentseek.dev/errors/validation-error","title":"Validation Error","status":422,"detail":"Request validation failed","instance":"/v1/search","code":"VALIDATION_ERROR","message":"Request validation failed","hint":"q is required (1–500 chars); k 1–25; max_candidates 1–100. See /openapi.json.","error":{"code":"VALIDATION_ERROR","message":"Request validation failed","hint":"q is required (1–500 chars); k 1–25; max_candidates 1–100. See /openapi.json."}}}}},"400":{"description":"Bad request (RFC 9457 problem+json)","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/ProblemDetails"},"example":{"type":"https://dev.agentseek.dev/errors/bad-request","title":"Bad Request","status":400,"detail":"mode must be 'snip' or 'deep'","instance":"/v1/search","code":"BAD_REQUEST","message":"mode must be 'snip' or 'deep'","hint":"Check request fields against /openapi.json. mode must be 'snip' or 'deep'.","error":{"code":"BAD_REQUEST","message":"mode must be 'snip' or 'deep'","hint":"Check request fields against /openapi.json. mode must be 'snip' or 'deep'."}}},"application/json":{"schema":{"$ref":"#/components/schemas/ProblemDetails"},"example":{"type":"https://dev.agentseek.dev/errors/bad-request","title":"Bad Request","status":400,"detail":"mode must be 'snip' or 'deep'","instance":"/v1/search","code":"BAD_REQUEST","message":"mode must be 'snip' or 'deep'","hint":"Check request fields against /openapi.json. mode must be 'snip' or 'deep'.","error":{"code":"BAD_REQUEST","message":"mode must be 'snip' or 'deep'","hint":"Check request fields against /openapi.json. mode must be 'snip' or 'deep'."}}}}},"403":{"description":"Valid token missing required scope","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/ProblemDetails"},"example":{"type":"https://dev.agentseek.dev/errors/forbidden","title":"Forbidden","status":403,"detail":"Insufficient scope","instance":"/v1/search","code":"FORBIDDEN","message":"Insufficient scope","hint":"Token is valid but missing the required OAuth scope. See /auth.md.","error":{"code":"FORBIDDEN","message":"Insufficient scope","hint":"Token is valid but missing the required OAuth scope. See /auth.md."}}},"application/json":{"schema":{"$ref":"#/components/schemas/ProblemDetails"},"example":{"type":"https://dev.agentseek.dev/errors/forbidden","title":"Forbidden","status":403,"detail":"Insufficient scope","instance":"/v1/search","code":"FORBIDDEN","message":"Insufficient scope","hint":"Token is valid but missing the required OAuth scope. See /auth.md.","error":{"code":"FORBIDDEN","message":"Insufficient scope","hint":"Token is valid but missing the required OAuth scope. See /auth.md."}}}}},"502":{"description":"Upstream discover failed","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/ProblemDetails"},"example":{"type":"https://dev.agentseek.dev/errors/upstream-error","title":"Upstream Error","status":502,"detail":"Upstream discover failed","instance":"/v1/search","code":"UPSTREAM_ERROR","message":"Upstream discover failed","hint":"Discover provider failed. Retry with backoff.","error":{"code":"UPSTREAM_ERROR","message":"Upstream discover failed","hint":"Discover provider failed. Retry with backoff."}}},"application/json":{"schema":{"$ref":"#/components/schemas/ProblemDetails"},"example":{"type":"https://dev.agentseek.dev/errors/upstream-error","title":"Upstream Error","status":502,"detail":"Upstream discover failed","instance":"/v1/search","code":"UPSTREAM_ERROR","message":"Upstream discover failed","hint":"Discover provider failed. Retry with backoff.","error":{"code":"UPSTREAM_ERROR","message":"Upstream discover failed","hint":"Discover provider failed. Retry with backoff."}}}}},"503":{"description":"Server missing YDC_API_KEY","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/ProblemDetails"},"example":{"type":"https://dev.agentseek.dev/errors/service-unavailable","title":"Service Unavailable","status":503,"detail":"YDC_API_KEY not configured","instance":"/v1/search","code":"SERVICE_UNAVAILABLE","message":"YDC_API_KEY not configured","hint":"Server is missing upstream configuration (YDC_API_KEY), or the rate limiter is unavailable. Retry with backoff.","error":{"code":"SERVICE_UNAVAILABLE","message":"YDC_API_KEY not configured","hint":"Server is missing upstream configuration (YDC_API_KEY), or the rate limiter is unavailable. Retry with backoff."}}},"application/json":{"schema":{"$ref":"#/components/schemas/ProblemDetails"},"example":{"type":"https://dev.agentseek.dev/errors/service-unavailable","title":"Service Unavailable","status":503,"detail":"YDC_API_KEY not configured","instance":"/v1/search","code":"SERVICE_UNAVAILABLE","message":"YDC_API_KEY not configured","hint":"Server is missing upstream configuration (YDC_API_KEY), or the rate limiter is unavailable. Retry with backoff.","error":{"code":"SERVICE_UNAVAILABLE","message":"YDC_API_KEY not configured","hint":"Server is missing upstream configuration (YDC_API_KEY), or the rate limiter is unavailable. Retry with backoff."}}}}},"504":{"description":"Upstream timeout","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/ProblemDetails"},"example":{"type":"https://dev.agentseek.dev/errors/upstream-timeout","title":"Upstream Timeout","status":504,"detail":"Upstream timeout","instance":"/v1/search","code":"UPSTREAM_TIMEOUT","message":"Upstream timeout","hint":"Upstream timed out. Retry with backoff or a smaller max_candidates.","error":{"code":"UPSTREAM_TIMEOUT","message":"Upstream timeout","hint":"Upstream timed out. Retry with backoff or a smaller max_candidates."}}},"application/json":{"schema":{"$ref":"#/components/schemas/ProblemDetails"},"example":{"type":"https://dev.agentseek.dev/errors/upstream-timeout","title":"Upstream Timeout","status":504,"detail":"Upstream timeout","instance":"/v1/search","code":"UPSTREAM_TIMEOUT","message":"Upstream timeout","hint":"Upstream timed out. Retry with backoff or a smaller max_candidates.","error":{"code":"UPSTREAM_TIMEOUT","message":"Upstream timeout","hint":"Upstream timed out. Retry with backoff or a smaller max_candidates."}}}}}},"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=snip` (title/URL/snippet; cheaper/faster). Pass `mode=deep` for Stage A survivor fetch (cap 12). If hard gates empty the scored list, restored rows set gates_relaxed true. 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":"snip (default; title/URL/snippet, cheaper/faster) or deep (Stage A survivor fetch, cap 12)","default":"snip","title":"Mode"},"description":"snip (default; title/URL/snippet, cheaper/faster) or deep (Stage A survivor fetch, cap 12)"},{"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://dev.agentseek.dev/errors/validation-error","title":"Validation Error","status":422,"detail":"Request validation failed","instance":"/v1/search","code":"VALIDATION_ERROR","message":"Request validation failed","hint":"q is required (1–500 chars); k 1–25; max_candidates 1–100. See /openapi.json.","error":{"code":"VALIDATION_ERROR","message":"Request validation failed","hint":"q is required (1–500 chars); k 1–25; max_candidates 1–100. See /openapi.json."}}},"application/json":{"schema":{"$ref":"#/components/schemas/ProblemDetails"},"example":{"type":"https://dev.agentseek.dev/errors/validation-error","title":"Validation Error","status":422,"detail":"Request validation failed","instance":"/v1/search","code":"VALIDATION_ERROR","message":"Request validation failed","hint":"q is required (1–500 chars); k 1–25; max_candidates 1–100. See /openapi.json.","error":{"code":"VALIDATION_ERROR","message":"Request validation failed","hint":"q is required (1–500 chars); k 1–25; max_candidates 1–100. See /openapi.json."}}}}},"400":{"description":"Bad request (RFC 9457 problem+json)","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/ProblemDetails"},"example":{"type":"https://dev.agentseek.dev/errors/bad-request","title":"Bad Request","status":400,"detail":"mode must be 'snip' or 'deep'","instance":"/v1/search","code":"BAD_REQUEST","message":"mode must be 'snip' or 'deep'","hint":"Check request fields against /openapi.json. mode must be 'snip' or 'deep'.","error":{"code":"BAD_REQUEST","message":"mode must be 'snip' or 'deep'","hint":"Check request fields against /openapi.json. mode must be 'snip' or 'deep'."}}},"application/json":{"schema":{"$ref":"#/components/schemas/ProblemDetails"},"example":{"type":"https://dev.agentseek.dev/errors/bad-request","title":"Bad Request","status":400,"detail":"mode must be 'snip' or 'deep'","instance":"/v1/search","code":"BAD_REQUEST","message":"mode must be 'snip' or 'deep'","hint":"Check request fields against /openapi.json. mode must be 'snip' or 'deep'.","error":{"code":"BAD_REQUEST","message":"mode must be 'snip' or 'deep'","hint":"Check request fields against /openapi.json. mode must be 'snip' or 'deep'."}}}}},"401":{"description":"Missing or invalid credential. WWW-Authenticate: Bearer resource_metadata=…","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/ProblemDetails"},"example":{"type":"https://dev.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://dev.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://dev.agentseek.dev/errors/forbidden","title":"Forbidden","status":403,"detail":"Insufficient scope","instance":"/v1/search","code":"FORBIDDEN","message":"Insufficient scope","hint":"Token is valid but missing the required OAuth scope. See /auth.md.","error":{"code":"FORBIDDEN","message":"Insufficient scope","hint":"Token is valid but missing the required OAuth scope. See /auth.md."}}},"application/json":{"schema":{"$ref":"#/components/schemas/ProblemDetails"},"example":{"type":"https://dev.agentseek.dev/errors/forbidden","title":"Forbidden","status":403,"detail":"Insufficient scope","instance":"/v1/search","code":"FORBIDDEN","message":"Insufficient scope","hint":"Token is valid but missing the required OAuth scope. See /auth.md.","error":{"code":"FORBIDDEN","message":"Insufficient scope","hint":"Token is valid but missing the required OAuth scope. See /auth.md."}}}}},"429":{"description":"Rate limited (per client IP when Upstash is enabled; default 60/min burst, Retry-After + RateLimit) or website demo quota exhausted (REST and MCP search_web share the per-IP allowance; code DEMO_EXHAUSTED; no Retry-After).","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/ProblemDetails"},"example":{"type":"https://dev.agentseek.dev/errors/rate-limited","title":"Rate Limited","status":429,"detail":"Rate limit exceeded","instance":"/v1/search","code":"RATE_LIMITED","message":"Rate limit exceeded","hint":"Wait Retry-After seconds, then retry. When Upstash is enabled, the live burst limit is per client IP (default 60 requests/minute).","error":{"code":"RATE_LIMITED","message":"Rate limit exceeded","hint":"Wait Retry-After seconds, then retry. When Upstash is enabled, the live burst limit is per client IP (default 60 requests/minute)."}}},"application/json":{"schema":{"$ref":"#/components/schemas/ProblemDetails"},"example":{"type":"https://dev.agentseek.dev/errors/rate-limited","title":"Rate Limited","status":429,"detail":"Rate limit exceeded","instance":"/v1/search","code":"RATE_LIMITED","message":"Rate limit exceeded","hint":"Wait Retry-After seconds, then retry. When Upstash is enabled, the live burst limit is per client IP (default 60 requests/minute).","error":{"code":"RATE_LIMITED","message":"Rate limit exceeded","hint":"Wait Retry-After seconds, then retry. When Upstash is enabled, the live burst limit is per client IP (default 60 requests/minute)."}}}},"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://dev.agentseek.dev/errors/upstream-error","title":"Upstream Error","status":502,"detail":"Upstream discover failed","instance":"/v1/search","code":"UPSTREAM_ERROR","message":"Upstream discover failed","hint":"Discover provider failed. Retry with backoff.","error":{"code":"UPSTREAM_ERROR","message":"Upstream discover failed","hint":"Discover provider failed. Retry with backoff."}}},"application/json":{"schema":{"$ref":"#/components/schemas/ProblemDetails"},"example":{"type":"https://dev.agentseek.dev/errors/upstream-error","title":"Upstream Error","status":502,"detail":"Upstream discover failed","instance":"/v1/search","code":"UPSTREAM_ERROR","message":"Upstream discover failed","hint":"Discover provider failed. Retry with backoff.","error":{"code":"UPSTREAM_ERROR","message":"Upstream discover failed","hint":"Discover provider failed. Retry with backoff."}}}}},"503":{"description":"Server missing YDC_API_KEY","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/ProblemDetails"},"example":{"type":"https://dev.agentseek.dev/errors/service-unavailable","title":"Service Unavailable","status":503,"detail":"YDC_API_KEY not configured","instance":"/v1/search","code":"SERVICE_UNAVAILABLE","message":"YDC_API_KEY not configured","hint":"Server is missing upstream configuration (YDC_API_KEY), or the rate limiter is unavailable. Retry with backoff.","error":{"code":"SERVICE_UNAVAILABLE","message":"YDC_API_KEY not configured","hint":"Server is missing upstream configuration (YDC_API_KEY), or the rate limiter is unavailable. Retry with backoff."}}},"application/json":{"schema":{"$ref":"#/components/schemas/ProblemDetails"},"example":{"type":"https://dev.agentseek.dev/errors/service-unavailable","title":"Service Unavailable","status":503,"detail":"YDC_API_KEY not configured","instance":"/v1/search","code":"SERVICE_UNAVAILABLE","message":"YDC_API_KEY not configured","hint":"Server is missing upstream configuration (YDC_API_KEY), or the rate limiter is unavailable. Retry with backoff.","error":{"code":"SERVICE_UNAVAILABLE","message":"YDC_API_KEY not configured","hint":"Server is missing upstream configuration (YDC_API_KEY), or the rate limiter is unavailable. Retry with backoff."}}}}},"504":{"description":"Upstream timeout","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/ProblemDetails"},"example":{"type":"https://dev.agentseek.dev/errors/upstream-timeout","title":"Upstream Timeout","status":504,"detail":"Upstream timeout","instance":"/v1/search","code":"UPSTREAM_TIMEOUT","message":"Upstream timeout","hint":"Upstream timed out. Retry with backoff or a smaller max_candidates.","error":{"code":"UPSTREAM_TIMEOUT","message":"Upstream timeout","hint":"Upstream timed out. Retry with backoff or a smaller max_candidates."}}},"application/json":{"schema":{"$ref":"#/components/schemas/ProblemDetails"},"example":{"type":"https://dev.agentseek.dev/errors/upstream-timeout","title":"Upstream Timeout","status":504,"detail":"Upstream timeout","instance":"/v1/search","code":"UPSTREAM_TIMEOUT","message":"Upstream timeout","hint":"Upstream timed out. Retry with backoff or a smaller max_candidates.","error":{"code":"UPSTREAM_TIMEOUT","message":"Upstream timeout","hint":"Upstream timed out. Retry with backoff or a smaller max_candidates."}}}}}},"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://dev.agentseek.dev/errors/bad-request","title":"Bad Request","status":400,"detail":"mode must be 'snip' or 'deep'","instance":"/v1/search","code":"BAD_REQUEST","message":"mode must be 'snip' or 'deep'","hint":"Check request fields against /openapi.json. mode must be 'snip' or 'deep'.","error":{"code":"BAD_REQUEST","message":"mode must be 'snip' or 'deep'","hint":"Check request fields against /openapi.json. mode must be 'snip' or 'deep'."}}},"application/json":{"schema":{"$ref":"#/components/schemas/ProblemDetails"},"example":{"type":"https://dev.agentseek.dev/errors/bad-request","title":"Bad Request","status":400,"detail":"mode must be 'snip' or 'deep'","instance":"/v1/search","code":"BAD_REQUEST","message":"mode must be 'snip' or 'deep'","hint":"Check request fields against /openapi.json. mode must be 'snip' or 'deep'.","error":{"code":"BAD_REQUEST","message":"mode must be 'snip' or 'deep'","hint":"Check request fields against /openapi.json. mode must be 'snip' or 'deep'."}}}}},"401":{"description":"Missing or invalid credential. WWW-Authenticate: Bearer resource_metadata=…","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/ProblemDetails"},"example":{"type":"https://dev.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://dev.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://dev.agentseek.dev/errors/forbidden","title":"Forbidden","status":403,"detail":"Insufficient scope","instance":"/v1/search","code":"FORBIDDEN","message":"Insufficient scope","hint":"Token is valid but missing the required OAuth scope. See /auth.md.","error":{"code":"FORBIDDEN","message":"Insufficient scope","hint":"Token is valid but missing the required OAuth scope. See /auth.md."}}},"application/json":{"schema":{"$ref":"#/components/schemas/ProblemDetails"},"example":{"type":"https://dev.agentseek.dev/errors/forbidden","title":"Forbidden","status":403,"detail":"Insufficient scope","instance":"/v1/search","code":"FORBIDDEN","message":"Insufficient scope","hint":"Token is valid but missing the required OAuth scope. See /auth.md.","error":{"code":"FORBIDDEN","message":"Insufficient scope","hint":"Token is valid but missing the required OAuth scope. See /auth.md."}}}}},"422":{"description":"Validation error (RFC 9457 problem+json)","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/ProblemDetails"},"example":{"type":"https://dev.agentseek.dev/errors/validation-error","title":"Validation Error","status":422,"detail":"Request validation failed","instance":"/v1/search","code":"VALIDATION_ERROR","message":"Request validation failed","hint":"q is required (1–500 chars); k 1–25; max_candidates 1–100. See /openapi.json.","error":{"code":"VALIDATION_ERROR","message":"Request validation failed","hint":"q is required (1–500 chars); k 1–25; max_candidates 1–100. See /openapi.json."}}},"application/json":{"schema":{"$ref":"#/components/schemas/ProblemDetails"},"example":{"type":"https://dev.agentseek.dev/errors/validation-error","title":"Validation Error","status":422,"detail":"Request validation failed","instance":"/v1/search","code":"VALIDATION_ERROR","message":"Request validation failed","hint":"q is required (1–500 chars); k 1–25; max_candidates 1–100. See /openapi.json.","error":{"code":"VALIDATION_ERROR","message":"Request validation failed","hint":"q is required (1–500 chars); k 1–25; max_candidates 1–100. See /openapi.json."}}}}},"429":{"description":"Rate limited (per client IP when Upstash is enabled; default 60/min burst, Retry-After + RateLimit) or website demo quota exhausted (REST and MCP search_web share the per-IP allowance; code DEMO_EXHAUSTED; no Retry-After).","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/ProblemDetails"},"example":{"type":"https://dev.agentseek.dev/errors/rate-limited","title":"Rate Limited","status":429,"detail":"Rate limit exceeded","instance":"/v1/search","code":"RATE_LIMITED","message":"Rate limit exceeded","hint":"Wait Retry-After seconds, then retry. When Upstash is enabled, the live burst limit is per client IP (default 60 requests/minute).","error":{"code":"RATE_LIMITED","message":"Rate limit exceeded","hint":"Wait Retry-After seconds, then retry. When Upstash is enabled, the live burst limit is per client IP (default 60 requests/minute)."}}},"application/json":{"schema":{"$ref":"#/components/schemas/ProblemDetails"},"example":{"type":"https://dev.agentseek.dev/errors/rate-limited","title":"Rate Limited","status":429,"detail":"Rate limit exceeded","instance":"/v1/search","code":"RATE_LIMITED","message":"Rate limit exceeded","hint":"Wait Retry-After seconds, then retry. When Upstash is enabled, the live burst limit is per client IP (default 60 requests/minute).","error":{"code":"RATE_LIMITED","message":"Rate limit exceeded","hint":"Wait Retry-After seconds, then retry. When Upstash is enabled, the live burst limit is per client IP (default 60 requests/minute)."}}}},"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://dev.agentseek.dev/errors/upstream-error","title":"Upstream Error","status":502,"detail":"Upstream discover failed","instance":"/v1/search","code":"UPSTREAM_ERROR","message":"Upstream discover failed","hint":"Discover provider failed. Retry with backoff.","error":{"code":"UPSTREAM_ERROR","message":"Upstream discover failed","hint":"Discover provider failed. Retry with backoff."}}},"application/json":{"schema":{"$ref":"#/components/schemas/ProblemDetails"},"example":{"type":"https://dev.agentseek.dev/errors/upstream-error","title":"Upstream Error","status":502,"detail":"Upstream discover failed","instance":"/v1/search","code":"UPSTREAM_ERROR","message":"Upstream discover failed","hint":"Discover provider failed. Retry with backoff.","error":{"code":"UPSTREAM_ERROR","message":"Upstream discover failed","hint":"Discover provider failed. Retry with backoff."}}}}},"503":{"description":"Server missing YDC_API_KEY","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/ProblemDetails"},"example":{"type":"https://dev.agentseek.dev/errors/service-unavailable","title":"Service Unavailable","status":503,"detail":"YDC_API_KEY not configured","instance":"/v1/search","code":"SERVICE_UNAVAILABLE","message":"YDC_API_KEY not configured","hint":"Server is missing upstream configuration (YDC_API_KEY), or the rate limiter is unavailable. Retry with backoff.","error":{"code":"SERVICE_UNAVAILABLE","message":"YDC_API_KEY not configured","hint":"Server is missing upstream configuration (YDC_API_KEY), or the rate limiter is unavailable. Retry with backoff."}}},"application/json":{"schema":{"$ref":"#/components/schemas/ProblemDetails"},"example":{"type":"https://dev.agentseek.dev/errors/service-unavailable","title":"Service Unavailable","status":503,"detail":"YDC_API_KEY not configured","instance":"/v1/search","code":"SERVICE_UNAVAILABLE","message":"YDC_API_KEY not configured","hint":"Server is missing upstream configuration (YDC_API_KEY), or the rate limiter is unavailable. Retry with backoff.","error":{"code":"SERVICE_UNAVAILABLE","message":"YDC_API_KEY not configured","hint":"Server is missing upstream configuration (YDC_API_KEY), or the rate limiter is unavailable. Retry with backoff."}}}}},"504":{"description":"Upstream timeout","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/ProblemDetails"},"example":{"type":"https://dev.agentseek.dev/errors/upstream-timeout","title":"Upstream Timeout","status":504,"detail":"Upstream timeout","instance":"/v1/search","code":"UPSTREAM_TIMEOUT","message":"Upstream timeout","hint":"Upstream timed out. Retry with backoff or a smaller max_candidates.","error":{"code":"UPSTREAM_TIMEOUT","message":"Upstream timeout","hint":"Upstream timed out. Retry with backoff or a smaller max_candidates."}}},"application/json":{"schema":{"$ref":"#/components/schemas/ProblemDetails"},"example":{"type":"https://dev.agentseek.dev/errors/upstream-timeout","title":"Upstream Timeout","status":504,"detail":"Upstream timeout","instance":"/v1/search","code":"UPSTREAM_TIMEOUT","message":"Upstream timeout","hint":"Upstream timed out. Retry with backoff or a smaller max_candidates.","error":{"code":"UPSTREAM_TIMEOUT","message":"Upstream timeout","hint":"Upstream timed out. Retry with backoff or a smaller max_candidates."}}}}}}}},"/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://dev.agentseek.dev/errors/bad-request","title":"Bad Request","status":400,"detail":"mode must be 'snip' or 'deep'","instance":"/v1/search","code":"BAD_REQUEST","message":"mode must be 'snip' or 'deep'","hint":"Check request fields against /openapi.json. mode must be 'snip' or 'deep'.","error":{"code":"BAD_REQUEST","message":"mode must be 'snip' or 'deep'","hint":"Check request fields against /openapi.json. mode must be 'snip' or 'deep'."}}},"application/json":{"schema":{"$ref":"#/components/schemas/ProblemDetails"},"example":{"type":"https://dev.agentseek.dev/errors/bad-request","title":"Bad Request","status":400,"detail":"mode must be 'snip' or 'deep'","instance":"/v1/search","code":"BAD_REQUEST","message":"mode must be 'snip' or 'deep'","hint":"Check request fields against /openapi.json. mode must be 'snip' or 'deep'.","error":{"code":"BAD_REQUEST","message":"mode must be 'snip' or 'deep'","hint":"Check request fields against /openapi.json. mode must be 'snip' or 'deep'."}}}}},"401":{"description":"Missing or invalid credential. WWW-Authenticate: Bearer resource_metadata=…","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/ProblemDetails"},"example":{"type":"https://dev.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://dev.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://dev.agentseek.dev/errors/forbidden","title":"Forbidden","status":403,"detail":"Insufficient scope","instance":"/v1/search","code":"FORBIDDEN","message":"Insufficient scope","hint":"Token is valid but missing the required OAuth scope. See /auth.md.","error":{"code":"FORBIDDEN","message":"Insufficient scope","hint":"Token is valid but missing the required OAuth scope. See /auth.md."}}},"application/json":{"schema":{"$ref":"#/components/schemas/ProblemDetails"},"example":{"type":"https://dev.agentseek.dev/errors/forbidden","title":"Forbidden","status":403,"detail":"Insufficient scope","instance":"/v1/search","code":"FORBIDDEN","message":"Insufficient scope","hint":"Token is valid but missing the required OAuth scope. See /auth.md.","error":{"code":"FORBIDDEN","message":"Insufficient scope","hint":"Token is valid but missing the required OAuth scope. See /auth.md."}}}}},"422":{"description":"Validation error (RFC 9457 problem+json)","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/ProblemDetails"},"example":{"type":"https://dev.agentseek.dev/errors/validation-error","title":"Validation Error","status":422,"detail":"Request validation failed","instance":"/v1/search","code":"VALIDATION_ERROR","message":"Request validation failed","hint":"q is required (1–500 chars); k 1–25; max_candidates 1–100. See /openapi.json.","error":{"code":"VALIDATION_ERROR","message":"Request validation failed","hint":"q is required (1–500 chars); k 1–25; max_candidates 1–100. See /openapi.json."}}},"application/json":{"schema":{"$ref":"#/components/schemas/ProblemDetails"},"example":{"type":"https://dev.agentseek.dev/errors/validation-error","title":"Validation Error","status":422,"detail":"Request validation failed","instance":"/v1/search","code":"VALIDATION_ERROR","message":"Request validation failed","hint":"q is required (1–500 chars); k 1–25; max_candidates 1–100. See /openapi.json.","error":{"code":"VALIDATION_ERROR","message":"Request validation failed","hint":"q is required (1–500 chars); k 1–25; max_candidates 1–100. See /openapi.json."}}}}},"429":{"description":"Rate limited (per client IP when Upstash is enabled; default 60/min burst, Retry-After + RateLimit) or website demo quota exhausted (REST and MCP search_web share the per-IP allowance; code DEMO_EXHAUSTED; no Retry-After).","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/ProblemDetails"},"example":{"type":"https://dev.agentseek.dev/errors/rate-limited","title":"Rate Limited","status":429,"detail":"Rate limit exceeded","instance":"/v1/search","code":"RATE_LIMITED","message":"Rate limit exceeded","hint":"Wait Retry-After seconds, then retry. When Upstash is enabled, the live burst limit is per client IP (default 60 requests/minute).","error":{"code":"RATE_LIMITED","message":"Rate limit exceeded","hint":"Wait Retry-After seconds, then retry. When Upstash is enabled, the live burst limit is per client IP (default 60 requests/minute)."}}},"application/json":{"schema":{"$ref":"#/components/schemas/ProblemDetails"},"example":{"type":"https://dev.agentseek.dev/errors/rate-limited","title":"Rate Limited","status":429,"detail":"Rate limit exceeded","instance":"/v1/search","code":"RATE_LIMITED","message":"Rate limit exceeded","hint":"Wait Retry-After seconds, then retry. When Upstash is enabled, the live burst limit is per client IP (default 60 requests/minute).","error":{"code":"RATE_LIMITED","message":"Rate limit exceeded","hint":"Wait Retry-After seconds, then retry. When Upstash is enabled, the live burst limit is per client IP (default 60 requests/minute)."}}}},"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://dev.agentseek.dev/errors/upstream-error","title":"Upstream Error","status":502,"detail":"Upstream discover failed","instance":"/v1/search","code":"UPSTREAM_ERROR","message":"Upstream discover failed","hint":"Discover provider failed. Retry with backoff.","error":{"code":"UPSTREAM_ERROR","message":"Upstream discover failed","hint":"Discover provider failed. Retry with backoff."}}},"application/json":{"schema":{"$ref":"#/components/schemas/ProblemDetails"},"example":{"type":"https://dev.agentseek.dev/errors/upstream-error","title":"Upstream Error","status":502,"detail":"Upstream discover failed","instance":"/v1/search","code":"UPSTREAM_ERROR","message":"Upstream discover failed","hint":"Discover provider failed. Retry with backoff.","error":{"code":"UPSTREAM_ERROR","message":"Upstream discover failed","hint":"Discover provider failed. Retry with backoff."}}}}},"503":{"description":"Server missing YDC_API_KEY","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/ProblemDetails"},"example":{"type":"https://dev.agentseek.dev/errors/service-unavailable","title":"Service Unavailable","status":503,"detail":"YDC_API_KEY not configured","instance":"/v1/search","code":"SERVICE_UNAVAILABLE","message":"YDC_API_KEY not configured","hint":"Server is missing upstream configuration (YDC_API_KEY), or the rate limiter is unavailable. Retry with backoff.","error":{"code":"SERVICE_UNAVAILABLE","message":"YDC_API_KEY not configured","hint":"Server is missing upstream configuration (YDC_API_KEY), or the rate limiter is unavailable. Retry with backoff."}}},"application/json":{"schema":{"$ref":"#/components/schemas/ProblemDetails"},"example":{"type":"https://dev.agentseek.dev/errors/service-unavailable","title":"Service Unavailable","status":503,"detail":"YDC_API_KEY not configured","instance":"/v1/search","code":"SERVICE_UNAVAILABLE","message":"YDC_API_KEY not configured","hint":"Server is missing upstream configuration (YDC_API_KEY), or the rate limiter is unavailable. Retry with backoff.","error":{"code":"SERVICE_UNAVAILABLE","message":"YDC_API_KEY not configured","hint":"Server is missing upstream configuration (YDC_API_KEY), or the rate limiter is unavailable. Retry with backoff."}}}}},"504":{"description":"Upstream timeout","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/ProblemDetails"},"example":{"type":"https://dev.agentseek.dev/errors/upstream-timeout","title":"Upstream Timeout","status":504,"detail":"Upstream timeout","instance":"/v1/search","code":"UPSTREAM_TIMEOUT","message":"Upstream timeout","hint":"Upstream timed out. Retry with backoff or a smaller max_candidates.","error":{"code":"UPSTREAM_TIMEOUT","message":"Upstream timeout","hint":"Upstream timed out. Retry with backoff or a smaller max_candidates."}}},"application/json":{"schema":{"$ref":"#/components/schemas/ProblemDetails"},"example":{"type":"https://dev.agentseek.dev/errors/upstream-timeout","title":"Upstream Timeout","status":504,"detail":"Upstream timeout","instance":"/v1/search","code":"UPSTREAM_TIMEOUT","message":"Upstream timeout","hint":"Upstream timed out. Retry with backoff or a smaller max_candidates.","error":{"code":"UPSTREAM_TIMEOUT","message":"Upstream timeout","hint":"Upstream timed out. Retry with backoff or a smaller max_candidates."}}}}}}}},"/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://dev.agentseek.dev/errors/bad-request","title":"Bad Request","status":400,"detail":"mode must be 'snip' or 'deep'","instance":"/v1/search","code":"BAD_REQUEST","message":"mode must be 'snip' or 'deep'","hint":"Check request fields against /openapi.json. mode must be 'snip' or 'deep'.","error":{"code":"BAD_REQUEST","message":"mode must be 'snip' or 'deep'","hint":"Check request fields against /openapi.json. mode must be 'snip' or 'deep'."}}},"application/json":{"schema":{"$ref":"#/components/schemas/ProblemDetails"},"example":{"type":"https://dev.agentseek.dev/errors/bad-request","title":"Bad Request","status":400,"detail":"mode must be 'snip' or 'deep'","instance":"/v1/search","code":"BAD_REQUEST","message":"mode must be 'snip' or 'deep'","hint":"Check request fields against /openapi.json. mode must be 'snip' or 'deep'.","error":{"code":"BAD_REQUEST","message":"mode must be 'snip' or 'deep'","hint":"Check request fields against /openapi.json. mode must be 'snip' or 'deep'."}}}}},"401":{"description":"Missing or invalid credential. WWW-Authenticate: Bearer resource_metadata=…","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/ProblemDetails"},"example":{"type":"https://dev.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://dev.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://dev.agentseek.dev/errors/forbidden","title":"Forbidden","status":403,"detail":"Insufficient scope","instance":"/v1/search","code":"FORBIDDEN","message":"Insufficient scope","hint":"Token is valid but missing the required OAuth scope. See /auth.md.","error":{"code":"FORBIDDEN","message":"Insufficient scope","hint":"Token is valid but missing the required OAuth scope. See /auth.md."}}},"application/json":{"schema":{"$ref":"#/components/schemas/ProblemDetails"},"example":{"type":"https://dev.agentseek.dev/errors/forbidden","title":"Forbidden","status":403,"detail":"Insufficient scope","instance":"/v1/search","code":"FORBIDDEN","message":"Insufficient scope","hint":"Token is valid but missing the required OAuth scope. See /auth.md.","error":{"code":"FORBIDDEN","message":"Insufficient scope","hint":"Token is valid but missing the required OAuth scope. See /auth.md."}}}}},"422":{"description":"Validation error (RFC 9457 problem+json)","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/ProblemDetails"},"example":{"type":"https://dev.agentseek.dev/errors/validation-error","title":"Validation Error","status":422,"detail":"Request validation failed","instance":"/v1/search","code":"VALIDATION_ERROR","message":"Request validation failed","hint":"q is required (1–500 chars); k 1–25; max_candidates 1–100. See /openapi.json.","error":{"code":"VALIDATION_ERROR","message":"Request validation failed","hint":"q is required (1–500 chars); k 1–25; max_candidates 1–100. See /openapi.json."}}},"application/json":{"schema":{"$ref":"#/components/schemas/ProblemDetails"},"example":{"type":"https://dev.agentseek.dev/errors/validation-error","title":"Validation Error","status":422,"detail":"Request validation failed","instance":"/v1/search","code":"VALIDATION_ERROR","message":"Request validation failed","hint":"q is required (1–500 chars); k 1–25; max_candidates 1–100. See /openapi.json.","error":{"code":"VALIDATION_ERROR","message":"Request validation failed","hint":"q is required (1–500 chars); k 1–25; max_candidates 1–100. See /openapi.json."}}}}},"429":{"description":"Rate limited (per client IP when Upstash is enabled; default 60/min burst, Retry-After + RateLimit) or website demo quota exhausted (REST and MCP search_web share the per-IP allowance; code DEMO_EXHAUSTED; no Retry-After).","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/ProblemDetails"},"example":{"type":"https://dev.agentseek.dev/errors/rate-limited","title":"Rate Limited","status":429,"detail":"Rate limit exceeded","instance":"/v1/search","code":"RATE_LIMITED","message":"Rate limit exceeded","hint":"Wait Retry-After seconds, then retry. When Upstash is enabled, the live burst limit is per client IP (default 60 requests/minute).","error":{"code":"RATE_LIMITED","message":"Rate limit exceeded","hint":"Wait Retry-After seconds, then retry. When Upstash is enabled, the live burst limit is per client IP (default 60 requests/minute)."}}},"application/json":{"schema":{"$ref":"#/components/schemas/ProblemDetails"},"example":{"type":"https://dev.agentseek.dev/errors/rate-limited","title":"Rate Limited","status":429,"detail":"Rate limit exceeded","instance":"/v1/search","code":"RATE_LIMITED","message":"Rate limit exceeded","hint":"Wait Retry-After seconds, then retry. When Upstash is enabled, the live burst limit is per client IP (default 60 requests/minute).","error":{"code":"RATE_LIMITED","message":"Rate limit exceeded","hint":"Wait Retry-After seconds, then retry. When Upstash is enabled, the live burst limit is per client IP (default 60 requests/minute)."}}}},"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://dev.agentseek.dev/errors/upstream-error","title":"Upstream Error","status":502,"detail":"Upstream discover failed","instance":"/v1/search","code":"UPSTREAM_ERROR","message":"Upstream discover failed","hint":"Discover provider failed. Retry with backoff.","error":{"code":"UPSTREAM_ERROR","message":"Upstream discover failed","hint":"Discover provider failed. Retry with backoff."}}},"application/json":{"schema":{"$ref":"#/components/schemas/ProblemDetails"},"example":{"type":"https://dev.agentseek.dev/errors/upstream-error","title":"Upstream Error","status":502,"detail":"Upstream discover failed","instance":"/v1/search","code":"UPSTREAM_ERROR","message":"Upstream discover failed","hint":"Discover provider failed. Retry with backoff.","error":{"code":"UPSTREAM_ERROR","message":"Upstream discover failed","hint":"Discover provider failed. Retry with backoff."}}}}},"503":{"description":"Server missing YDC_API_KEY","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/ProblemDetails"},"example":{"type":"https://dev.agentseek.dev/errors/service-unavailable","title":"Service Unavailable","status":503,"detail":"YDC_API_KEY not configured","instance":"/v1/search","code":"SERVICE_UNAVAILABLE","message":"YDC_API_KEY not configured","hint":"Server is missing upstream configuration (YDC_API_KEY), or the rate limiter is unavailable. Retry with backoff.","error":{"code":"SERVICE_UNAVAILABLE","message":"YDC_API_KEY not configured","hint":"Server is missing upstream configuration (YDC_API_KEY), or the rate limiter is unavailable. Retry with backoff."}}},"application/json":{"schema":{"$ref":"#/components/schemas/ProblemDetails"},"example":{"type":"https://dev.agentseek.dev/errors/service-unavailable","title":"Service Unavailable","status":503,"detail":"YDC_API_KEY not configured","instance":"/v1/search","code":"SERVICE_UNAVAILABLE","message":"YDC_API_KEY not configured","hint":"Server is missing upstream configuration (YDC_API_KEY), or the rate limiter is unavailable. Retry with backoff.","error":{"code":"SERVICE_UNAVAILABLE","message":"YDC_API_KEY not configured","hint":"Server is missing upstream configuration (YDC_API_KEY), or the rate limiter is unavailable. Retry with backoff."}}}}},"504":{"description":"Upstream timeout","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/ProblemDetails"},"example":{"type":"https://dev.agentseek.dev/errors/upstream-timeout","title":"Upstream Timeout","status":504,"detail":"Upstream timeout","instance":"/v1/search","code":"UPSTREAM_TIMEOUT","message":"Upstream timeout","hint":"Upstream timed out. Retry with backoff or a smaller max_candidates.","error":{"code":"UPSTREAM_TIMEOUT","message":"Upstream timeout","hint":"Upstream timed out. Retry with backoff or a smaller max_candidates."}}},"application/json":{"schema":{"$ref":"#/components/schemas/ProblemDetails"},"example":{"type":"https://dev.agentseek.dev/errors/upstream-timeout","title":"Upstream Timeout","status":504,"detail":"Upstream timeout","instance":"/v1/search","code":"UPSTREAM_TIMEOUT","message":"Upstream timeout","hint":"Upstream timed out. Retry with backoff or a smaller max_candidates.","error":{"code":"UPSTREAM_TIMEOUT","message":"Upstream timeout","hint":"Upstream timed out. Retry with backoff or a smaller max_candidates."}}}}}}}}},"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"},"gates_relaxed":{"default":false,"description":"gates_relaxed is true when hard gates emptied the scored list and this row was restored from the pre-gate ranking. Treat true as a relaxed-safety response (including prompt injection). Not a SearchMeta field.","title":"Gates Relaxed","type":"boolean"}},"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":"snip","description":"snip (default) or deep","title":"Mode","type":"string"},"provider":{"default":"you.com","description":"Discover provider id","title":"Provider","type":"string"},"agent_seek_version":{"default":"0.3.0","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":"snip","description":"snip (default; title/URL/snippet, cheaper/faster) or deep (Stage A survivor fetch, cap 12)","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://dev.agentseek.dev","description":"Live Agent Seek prototype (dev.agentseek.dev)"},{"url":"/","description":"This Agent Seek host"}]}