# AI integration

> The documentation is built to be read by coding assistants and agents as well as people. Here is how to point them at it, and what they must not get wrong.

- **HTML:** https://offendersearch.app/docs/ai
- **Base URL (live):** https://api.offendersearch.app — live keys (`os_live_…`)
- **Base URL (sandbox):** https://sandbox.offendersearch.app — test keys (`os_test_…`), never billed
- **Authentication:** `X-API-Key` request header
- **OpenAPI:** https://offendersearch.app/openapi.json · https://offendersearch.app/openapi.yaml
- **Docs index for agents:** https://offendersearch.app/llms.txt

## How AI reads these docs

- **Every page has a Markdown twin** at the same URL plus `.md` — `/docs/criminal/search.md`, `/docs/platform/authentication.md` — complete, with code blocks, parameter tables and enums, and no navigation. Whole products: `/docs/all.md`, `/docs/criminal/all.md`, `/docs/monitoring/all.md`, `/docs/fcra/all.md`, `/docs/map/all.md`.
- **[/llms.txt](/llms.txt)** is the index an agent reads first: products, quickstarts, references, OpenAPI, guides, what is coming soon.
- **[/openapi.json](/openapi.json)** and **[/openapi.yaml](/openapi.yaml)** are the contract: operation ids, parameters, schemas, enums, errors, examples. Generate a typed client from them.
- Pages are one purpose each, with descriptive titles, stable anchors and tables for structured data, so a retrieval step can land on the endpoint page it needs.

## In this section

- [Coding assistants (Claude, Cursor, ChatGPT-compatible tools)](https://offendersearch.app/docs/ai/coding-assistants): the prompt and the context to give an assistant so it generates correct code
- [MCP server](https://offendersearch.app/docs/ai/mcp): the OffenderSearch Model Context Protocol server: tools, configuration, billing, access
- [Agents & tool calling](https://offendersearch.app/docs/ai/agents): tool definitions, structured results, async jobs inside an agent loop, interpretation rules
- [Recipes](https://offendersearch.app/docs/ai/recipes): complete, runnable integrations for the common tasks

## Interpretation rules every integration must keep

- A possible match is not a confirmed identity. Records carry `matchConfidence` and a labelled basis; a person decides.
- An arrest or a booking is not a conviction. Read `disposition` and `currentStatus`; see [arrests vs. charges vs. convictions](/docs/guides/criminal/arrests-charges-convictions).
- Missing records do not prove a clean history. An empty `records[]` is an answer only when `status` is `complete`.
- Coverage is incomplete by nature and said so in the catalogs; partial results (`status: "partial"`, `sourceStatus[]`) need handling, not hiding.
- Regulated screening (employment, housing, credit, insurance) needs the FCRA Partner API and the partner's own compliance workflow. The self-service APIs refuse it on every response (`legal.notice`).
- No real personal data or live credentials in prompts, examples or logs. Use the sandbox and its fixed test names.