# Subsidia API

> Subsidia API documentation. One base URL change: every AI call is masked, routed, metered and signed with a hash-chained proof certificate. OpenAI and Anthropic compatible Gateway, Cortex knowledge, Vérificateur, Registre, agents, webhooks.

- Base URL: https://api.subsidia.protypa.fr (OpenAI-compatible routes live under /v1; Anthropic-compatible clients use the same host)
- Authentication: developer API key `sk_live_...`, sent as `Authorization: Bearer <key>` or `x-api-key: <key>`
- Create a key: https://subsidia.protypa.fr/console/gateway
- Full documentation in one file: https://dev.subsidia.protypa.fr/llms-full.txt
- Any page as Markdown: append .md to its URL (https://dev.subsidia.protypa.fr/docs/gateway.md)
- OpenAPI snapshot: https://dev.subsidia.protypa.fr/openapi.json

## Get started

- [Overview](https://dev.subsidia.protypa.fr/docs.md): What the Subsidia API is: a Gateway compatible with OpenAI and Anthropic, plus platform APIs for knowledge, agents and proof, all behind one API key.
- [Quickstart](https://dev.subsidia.protypa.fr/docs/quickstart.md): Create a key, make your first attested Gateway call, upload a document, query it, and read the proof certificate.
- [Authentication](https://dev.subsidia.protypa.fr/docs/authentication.md): Developer API keys: formats, the Bearer and x-api-key headers, scopes per route family, read-only keys, ceilings, rotation and hygiene.
- [Errors](https://dev.subsidia.protypa.fr/docs/errors.md): The error body shapes of the native, OpenAI and Anthropic routes, every status and code, and what to do about each one.
- [Rate limits and quotas](https://dev.subsidia.protypa.fr/docs/rate-limits.md): Request limits per key and per route, how questions are counted and which plans include how many, controls counted apart, and the 402 codes.
- [SDKs](https://dev.subsidia.protypa.fr/docs/sdk.md): The subsidia-sdk TypeScript client for the platform APIs, and how to use the official OpenAI and Anthropic SDKs, or plain fetch, for everything else.
- [Changelog](https://dev.subsidia.protypa.fr/docs/changelog.md): Dated changes to the public API: new routes, scopes, error codes and behaviour, newest first.
- [Use these docs with an AI agent](https://dev.subsidia.protypa.fr/docs/llm-ready.md): llms.txt, llms-full.txt, a Markdown twin of every page, copy and open-in-Claude buttons, and a system prompt to paste into an agent that integrates Subsidia.

## Gateway

- [Gateway](https://dev.subsidia.protypa.fr/docs/gateway.md): OpenAI and Anthropic compatible endpoints: change one base URL and every call is masked, routed, metered and signed with a proof certificate.
- [Model addressing](https://dev.subsidia.protypa.fr/docs/model-addressing.md): The model field is an address: prefixes pick who answers (Synapse, a full model, a local model, one of your agents) and +flags add or remove capabilities.
- [Proof certificates](https://dev.subsidia.protypa.fr/docs/proofs.md): Every call returns an Ed25519-signed, hash-chained certificate that commits to the request, what left toward the model and the response, without containing any content.
- [Synapse](https://dev.subsidia.protypa.fr/docs/synapse.md): Synapse is the engine behind every call: it masks personal data, picks the model by task, meters usage in questions and spreads work over machines.
- [Completions and data extraction](https://dev.subsidia.protypa.fr/docs/completions.md): POST /v1/ai/complete runs a masked, routed, metered completion with optional context blocks, JSON mode and automatic fact extraction.

## Knowledge (Cortex)

- [Knowledge sources](https://dev.subsidia.protypa.fr/docs/knowledge-sources.md): Ingest text, URLs and files (PDF, Office, email, images) into Cortex, track ingestion, and attach sources to agents.
- [Querying the knowledge base](https://dev.subsidia.protypa.fr/docs/knowledge-query.md): POST /v1/knowledge/query runs hybrid retrieval with reranking and returns cited passages plus a trace of why they matched.
- [Facts, contradictions and health](https://dev.subsidia.protypa.fr/docs/knowledge-insights.md): Read the atomic facts Cortex extracted, review conflicts between documents, and track a health score for the knowledge base.
- [Light](https://dev.subsidia.protypa.fr/docs/light.md): Ask a question and get an answer strictly from your documents, with numbered citations or an honest refusal; web search only as an explicit second step.

## Agents

- [Agents](https://dev.subsidia.protypa.fr/docs/agents.md): Create, read, update and delete the agents (personas) of a workspace through the API.
- [Agent memory](https://dev.subsidia.protypa.fr/docs/agent-memory.md): What an agent remembers across conversations: how memories are written, ranked, deduplicated and labelled by provenance, and how to read, seed and delete them.
- [Agent chat](https://dev.subsidia.protypa.fr/docs/agent-chat.md): Talk to one agent, or let Subsidia pick the best-fit agent: multi-turn sessions, knowledge citations, tool calls, structured JSON and a server-sent event stream.
- [Sessions](https://dev.subsidia.protypa.fr/docs/sessions.md): Chat sessions keep the history of a conversation with an agent: create one, continue it, list and replay it.
- [Tools](https://dev.subsidia.protypa.fr/docs/tools.md): Register an HTTP endpoint of yours as a tool an agent can call during a chat, with a signed request, a JSON schema for its arguments and a JSON answer.
- [Conversations](https://dev.subsidia.protypa.fr/docs/conversations.md): Multi-agent debates: put a question to all the agents of a workspace, let them argue for several rounds, and get a structured synthesis.
- [Postes](https://dev.subsidia.protypa.fr/docs/postes.md): Run a poste (a job-role agent such as the Auditeur de pièces) on one dossier and get a structured verdict, RAS or a list of findings, each tied to a piece.

## Proof & compliance

- [Le Vérificateur](https://dev.subsidia.protypa.fr/docs/verify.md): Check every claim of a text against passages you send or documents in Cortex, with zero model calls, and get a report signed in the Subsidia proof chain.
- [Le Registre](https://dev.subsidia.protypa.fr/docs/registre.md): The register of AI usage in your workspace (model, data, date, reviewer, human change), listable through the API and exportable as a signed zip whose attestation commits to the filters.

## Platform

- [Webhooks](https://dev.subsidia.protypa.fr/docs/webhooks.md): Receive signed HTTP callbacks when a document is ingested, a flow finishes or an approval is waiting, and manage endpoints, deliveries and replays through the API.
- [Reflex](https://dev.subsidia.protypa.fr/docs/reflex.md): Flows that run on their own: triggers, a catalogue of steps, a human approval before anything leaves the building, and an API to build, start and follow them.
- [Partner API](https://dev.subsidia.protypa.fr/docs/partner.md): For approved integrators: create client workspaces, issue each client a restricted API key, and read the usage and statements you re-invoice from, all over the API.
- [Building on Subsidia for your clients](https://dev.subsidia.protypa.fr/docs/integrators.md): A guide for integrators who put Subsidia behind their own software for several client organisations: architecture, one workspace and one key per client, billing, and what to tell a client legal team.