# API and agent documentation

Use these interfaces to research, shortlist and compare AI visibility tools. The catalog contains five profiles with source links and research dates. All directory operations are read-only; the REST API does not require an account or key.

## Search and retrieve
- `GET /api/platforms` lists the catalog.
- `GET /api/platforms?q=content&focus=content` filters by text and focus.
- `GET /api/platforms/nur-ai` returns a complete profile.
- `GET /api/compare?ids=nur-ai,peec-ai` returns a comparison of two to five unique platform IDs.
- [OpenAPI schema](/openapi.json) describes inputs, outputs and errors.

## Read as Markdown
Send `Accept: text/markdown` to a page URL, append `.md` to a profile path, or fetch `/index.md`. The homepage also supports `?mode=agent` for a JSON capability summary. HTML and Markdown variants contain equivalent published information. Unknown paths return a real 404, with a Markdown explanation when requested.

## Browser tools
Browsers with WebMCP support discover `find_platforms`, `get_platform` and `compare_platforms` on this site. Tool calls validate input and use the same public catalog as the website. Ordinary browsing works when WebMCP is not available.

## MCP connection
POST JSON-RPC to `/api/mcp` for public, read-only MCP access with no API key. The `/mcp` endpoint also supports the Sites-managed connection. Supported operations include `server/discover`, `initialize`, `tools/list`, `tools/call`, `resources/list`, `resources/read`, `prompts/list` and `prompts/get`. Available tools mirror the REST API. Resources expose the agent instructions and the five Markdown profiles. The evaluate_platforms prompt prepares a research workflow. The live lists are authoritative.

## Versioning, pagination and retries
Use `/api/v1/platforms`, `/api/v1/platforms/{slug}` and `/api/v1/compare` for the stable v1 contract. Unversioned endpoints remain compatible aliases. Breaking changes will use a new major path. If v1 is deprecated, these docs will announce retirement at least 90 days ahead of time.

List responses accept `limit` (1–5) and `offset` (zero or greater), and include `total` and `next_offset`. A null next_offset means there are no more records. Invalid input and unknown API routes return typed `application/problem+json` errors with type, title, status, detail and instance.

All operations are read-only and safe to retry. There are no asynchronous jobs, mutations or idempotency-key requirements. No application-level request quota is currently configured; hosting protections may still return 429. Honor Retry-After if present, otherwise retry transient 429 or 5xx responses with exponential backoff and jitter. Do not retry validation errors without correcting input.

## Evidence and errors
Responses include canonical profile URLs, original source links and the research date. Invalid queries return 400; unknown records return 404. There are no write operations, purchases or account records, so the public catalog can be used for testing without changing production data. It is not a live pricing feed or a product performance benchmark.

## More guidance
- [When-to-use instructions](/agents.md)
- [Authentication and access](/auth.md)
- [Discovery catalog](/.well-known/ard.json)
- [Agent skills index](/.well-known/agent-skills/index.json)