# Overview

> 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.

Subsidia is an AI engine for organisations that cannot let their data leave the building, accounting and legal firms first. The API gives your software the same engine the Subsidia app runs on, in two ways.

- The **Gateway** speaks the OpenAI and Anthropic wire protocols. You change a base URL, and every call your existing client makes is masked, routed, metered and signed.
- The **platform APIs** under `/v1` expose the engine's parts directly: the knowledge base (Cortex), agents, the Vérificateur, the Registre, webhooks.

Both are authenticated by the same developer API key, and both aim at the same outcome: something you can show an auditor, not only something you have to believe.

## The mental model

**The path of a Gateway call. The certificate is stored before the response completes, so the proof id returned with the answer can always be fetched.**

Flow: Your application -> API key + scope check -> PII shield -> Routing (Synapse) -> Model, local or external -> Restore + sign -> Answer + proof id

| Layer | What it is | Use it when |
| --- | --- | --- |
| **Gateway** (`/v1/chat/completions`, `/v1/messages`, `/v1/models`) | Drop-in OpenAI and Anthropic endpoints. The `model` field is an [address](https://dev.subsidia.protypa.fr/docs/model-addressing.md) that can reach your agents and your knowledge base. | You already have code, a framework or a tool (Claude Code, Cursor, n8n, LangChain) that talks to a model. |
| **Knowledge** (`/v1/knowledge-sources`, `/v1/knowledge/*`) | Cortex: ingestion, hybrid retrieval, extracted facts, contradictions and health of your documents. | You want answers grounded in the client's own documents, or you want to build your own retrieval on top. |
| **Agents and conversations** (`/v1/agents`, `/v1/tools`, `/v1/conversations`) | Persona agents with memory, documents and tools, one-to-one chat and multi-agent debates. | You want a persistent assistant rather than a stateless completion. |
| **Proof** (`/v1/proofs`, `/v1/verify`, `/v1/registre`) | Signed, hash-chained certificates for every Gateway call, a deterministic claim checker, and the AI-usage register. | You must demonstrate what the AI read, said and was checked against. |
| **Platform** (`/v1/webhooks`, `/v1/postes/:key/run`, Reflex, partner) | Events pushed to you, job-description agents, automations, and the integrator space. | You integrate Subsidia into a product or resell it to your own clients. |

> **INFO: Capabilities are opt-in**
> With no Subsidia prefix or flag in the `model` field, the Gateway is a faithful passthrough: masking, routing and a certificate, nothing else. Knowledge grounding, agents and local-only processing are things you ask for through the address, never things the Gateway imposes.

## Base URLs

| Purpose | URL |
| --- | --- |
| API (Gateway and platform) | `https://api.subsidia.protypa.fr` |
| OpenAI-style clients | `https://api.subsidia.protypa.fr/v1` (the SDK appends `/chat/completions`) |
| Anthropic-style clients | `https://api.subsidia.protypa.fr` (the SDK appends `/v1/messages`) |
| Create an API key | `https://subsidia.protypa.fr/console/gateway` |
| These docs, for people and machines | `https://dev.subsidia.protypa.fr/docs`, plus `/llms.txt`. See [Use these docs with an AI agent](https://dev.subsidia.protypa.fr/docs/llm-ready.md). |

> **INFO: On-premise installations**
> A Subsidia desktop or Box installation serves the same routes on its own host. Replace the base URL with that machine's address; paths, headers and error shapes are the same.

## Conventions

| Topic | Convention |
| --- | --- |
| Format | Requests and responses are JSON (`Content-Type: application/json`). The exceptions are file upload (`multipart/form-data`) and streaming (Server-Sent Events). |
| Authentication | A developer key `sk_live_...`, as `Authorization: Bearer` or `x-api-key`. See [Authentication](https://dev.subsidia.protypa.fr/docs/authentication.md). |
| Workspace scoping | A key belongs to exactly one workspace and every read and write is scoped to it. There is no header that switches workspace for a key. Another workspace's object is indistinguishable from a missing one (404). |
| Ids | Opaque strings. Gateway certificates are `pf_` followed by 32 hex characters. Treat ids as opaque and never parse them. |
| Dates | ISO 8601 in UTC, for example `2026-10-09T08:30:00.000Z`. A key's monthly question ceiling resets on the first day of the calendar month, UTC. |
| Errors | A non-2xx status with a JSON body. Native routes carry a human `error` message and, for anything you should branch on, a machine `code`. The OpenAI and Anthropic routes use each vendor's envelope. See [Errors](https://dev.subsidia.protypa.fr/docs/errors.md). |
| Pagination | There is no global scheme. Routes that paginate say so: `GET /v1/verify` takes `page` and `pageSize` (default 20, maximum 100) and returns `total`; `GET /v1/ai/extracted-data` takes `limit` (default 100, maximum 500). Other lists return everything for the workspace. |
| Unknown fields | The OpenAI and Anthropic routes accept and ignore unknown fields so SDK upgrades do not break. Do not rely on this for platform routes. |
| Quotas | Customers buy **questions**. See [Rate limits and quotas](https://dev.subsidia.protypa.fr/docs/rate-limits.md). |

## Where to go next

- **[Quickstart](https://dev.subsidia.protypa.fr/docs/quickstart.md)**: From an empty account to a signed answer and a knowledge query.
- **[Gateway](https://dev.subsidia.protypa.fr/docs/gateway.md)**: OpenAI and Anthropic compatible endpoints, Claude Code, streaming.
- **[Model addressing](https://dev.subsidia.protypa.fr/docs/model-addressing.md)**: Reach agents and Cortex through the model name: agent:slug, +cortex, +sensitive.
- **[Proof certificates](https://dev.subsidia.protypa.fr/docs/proofs.md)**: What a certificate commits to and how to verify it offline.
- **[Synapse](https://dev.subsidia.protypa.fr/docs/synapse.md)**: Routing, PII shielding and metering behind every call.
- **[Knowledge (Cortex)](https://dev.subsidia.protypa.fr/docs/knowledge-sources.md)**: Upload documents, query them, inspect facts and contradictions.
- **[Agents](https://dev.subsidia.protypa.fr/docs/agents.md)**: Persona agents with memory, documents and tools.
- **[Le Vérificateur](https://dev.subsidia.protypa.fr/docs/verify.md)**: Give every claim of a text a verdict against your pieces. Zero model calls.
- **[Le Registre](https://dev.subsidia.protypa.fr/docs/registre.md)**: The AI usage register, signed, exportable for an audit.
- **[Webhooks](https://dev.subsidia.protypa.fr/docs/webhooks.md)**: Be told when an ingestion ends or a contradiction appears.
- **[Reflex](https://dev.subsidia.protypa.fr/docs/reflex.md)**: Automations that run on their own, with approval before anything goes out.
- **[Integrators](https://dev.subsidia.protypa.fr/docs/integrators.md)**: Resell Subsidia: client workspaces, keys with ceilings, monthly statements.
- **[Authentication](https://dev.subsidia.protypa.fr/docs/authentication.md)**: Key formats, scopes, read-only keys, ceilings and rotation.
- **[Errors](https://dev.subsidia.protypa.fr/docs/errors.md)**: Every status and code, and what to do about it.
- **[SDKs](https://dev.subsidia.protypa.fr/docs/sdk.md)**: The TypeScript SDK, and the official OpenAI and Anthropic SDKs.
- **[Docs for AI agents](https://dev.subsidia.protypa.fr/docs/llm-ready.md)**: llms.txt, Markdown pages and a system prompt to paste into your agent.

## Frequently asked

**Do I need to rewrite my application?**

No. If it uses an OpenAI or Anthropic SDK, set the base URL and the key. Everything beyond that (agents, grounding, proof retrieval) is added by choice.

**Where does my data go?**

To the provider that serves the call, after masking when that provider is external. With `pulse-sensitive` or the `+sensitive` flag the call stays on a local model and nothing leaves the machine. Each certificate records the provider that answered.

**Why do some identifiers still say pulse?**

The product was renamed Subsidia, but wire-level identifiers such as `pulse-auto`, the `x-pulse-proof` header and the `X-PulseLabs-*` webhook headers are kept so that existing integrations keep working.