# Agent Seek API

Scoped index for the HTTP API and MCP transport. Full site index: [/llms.txt](/llms.txt).

Install the skill first: [/.well-known/agent-skills/agent-seek/SKILL.md](/.well-known/agent-skills/agent-seek/SKILL.md) — then [Install the skill](/llms.txt#install-the-skill) → [/auth.md](/auth.md) → MCP or `POST /v1/search`.

## Public discovery (zero-auth)

- [GET /api](/api) — machine-readable API index
- [GET /v1](/v1) — same index at the versioned root
- [GET /health](/health) — liveness + version
- [Agent Seek sandbox](/v1/sandbox) — canned SearchResponse, no key, no upstream calls
- [Agent Seek OpenAPI](/openapi.json)
- [Swagger](/api/docs) · [api/docs.md](/api/docs.md) · [ReDoc](/api/redoc)

## Authenticated search

- `POST /v1/search` and `GET /v1/search` — canonical
- `POST /api/v1/search` — alias
- `GET /api/v1` — 401 + `WWW-Authenticate: Bearer resource_metadata="…"` unless you send a Bearer token

Default `mode=deep` (Stage A survivor fetch, cap 12; not a full-web crawl). Pass `mode=snip` for cheaper title/URL/snippet ranking. `k` default 10 (1–25); `max_candidates` default 50 (≤100).

Signals: answerability, authority, on_topic, states_sought_fact, subject_match, spam, prompt_injection (UI: **Injection risk**). Hard gates (order): subject_match → is_republisher → prompt_injection (fail-open if parse missing; 0.55 thresholds).

Auth: OAuth 2.0 `search:read` or `Authorization: Bearer $AGENT_SEEK_API_KEY`. Walkthrough: [/auth.md](/auth.md).

## Errors and versioning

API 4xx/5xx use RFC 9457 `application/problem+json` (`type`, `title`, `status`, `detail`, `code`, `message`, `hint`). Versioning and Sunset policy: [/docs/versioning.md](/docs/versioning.md). `/v1` is current; `/v2` is not published.

## MCP

- Agent Seek MCP Streamable HTTP: [/mcp](/mcp) · [/.well-known/mcp](/.well-known/mcp)
- Agent Seek MCP server card: [/.well-known/mcp/server-card.json](/.well-known/mcp/server-card.json)
- A2A card: [/.well-known/agent-card.json](/.well-known/agent-card.json)

Tools: `search_web`, `get_service_health`, `get_api_docs`, `list_search_capabilities`.