# Use these docs with an AI agent

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

More and more integrations are written with an AI coding agent beside the developer. An agent is only as good as the context it is given, and a rendered web page is a poor context: navigation, scripts and layout around a few kilobytes of useful text. Every page of this site therefore has a plain Markdown twin, and the whole site is available as one file, so you can give an agent exactly the documentation it needs and nothing else.

The Markdown is generated from the same source as the pages you read, so it is never out of date with them, and it carries the same information: tables, parameters, examples and error codes are all present as text.

## The machine-readable entry points

| URL | What it is | Use it when |
| --- | --- | --- |
| `https://dev.subsidia.protypa.fr/llms.txt` | An index following the llms.txt convention: the base URL, how to authenticate, where to create a key, then every page with a one-line summary and a link to its Markdown. | The agent should find the right page itself and fetch only that. |
| `https://dev.subsidia.protypa.fr/llms-full.txt` | The complete documentation in one Markdown file, pages separated by rules and each preceded by its source URL. | You can afford the context, or want the agent to reason across pages (for example errors, scopes and quotas together). |
| `https://dev.subsidia.protypa.fr/docs/<slug>.md` | One page as Markdown, for example `/docs/gateway.md`. The overview is `/docs.md`. | You are working on one feature. |
| `https://dev.subsidia.protypa.fr/openapi.json` | A generated OpenAPI snapshot of the routes. | You want to generate a client or a tool schema. It lists routes and shapes, not behaviour: the pages remain the reference for errors and quotas. |
| `https://dev.subsidia.protypa.fr/sitemap.xml` | The sitemap. | A crawler. |

All of these are public and answer with permissive CORS, so an agent, a browser extension or a script can read them without an account. Responses are cached for a few minutes.

**Fetching docs from a terminal**

_curl_

```bash
# the index
curl -s https://dev.subsidia.protypa.fr/llms.txt

# one page
curl -s https://dev.subsidia.protypa.fr/docs/gateway.md

# everything, saved for reuse
curl -s https://dev.subsidia.protypa.fr/llms-full.txt -o subsidia-docs.md
```

_PowerShell_

```powershell
Invoke-WebRequest https://dev.subsidia.protypa.fr/docs/gateway.md -OutFile gateway.md
Invoke-WebRequest https://dev.subsidia.protypa.fr/llms-full.txt -OutFile subsidia-docs.md
```

## The buttons on every page

At the top of each documentation page:

- **Copy page** copies the page as Markdown to your clipboard. Paste it into any chat or into your agent's context.
- The arrow next to it opens a menu with **View as Markdown** (the `.md` twin), **Open in Claude** and **Open in ChatGPT**. The last two open a new conversation with a prompt that asks the assistant to read that page's Markdown URL and help you with it.

The assistants fetch the URL themselves, so use them with a page you are reading right now. For a longer session in your own tools, prefer the next section.

## Claude Code, Cursor and other coding agents

Give the agent the index and tell it to fetch pages on demand. This keeps the context small and the answers current.

- **Claude Code.** Put the system prompt below in your project's `CLAUDE.md`, or paste a page URL in the conversation and ask it to read it. You can also save `llms-full.txt` in the repository (for example `docs/subsidia.md`) and reference it from `CLAUDE.md`.
- **Cursor and similar editors.** Add `https://dev.subsidia.protypa.fr/llms-full.txt` (or a single `.md` page) as a documentation source in the editor's docs or context settings, or reference the file you saved.
- **Any agent with web access.** Give it `https://dev.subsidia.protypa.fr/llms.txt` as its starting point.

Running Claude Code *through* Subsidia, rather than only reading its docs, is a separate topic: see [Gateway](https://dev.subsidia.protypa.fr/docs/gateway.md#use-it-with-claude-code).

> **TIP: Give the agent a sandbox key, not your production key**
> An agent that integrates Subsidia will run the code it writes. Create a key for it with only the scopes the task needs, a small `monthlyQuestionLimit` and an `expiresAt` a few days away. If it leaks into a log or a commit, the damage is bounded. See [Authentication](https://dev.subsidia.protypa.fr/docs/authentication.md).

## A system prompt to paste

This prompt gives an agent the facts it most often gets wrong, and tells it where to look for the rest. Replace nothing; it points at the public documentation. Keep it short on purpose: the agent should read pages, not memorise them.

**System prompt for an agent integrating Subsidia**

_Prompt_

```markdown
You are helping integrate software with the Subsidia API.

Documentation (read it before writing code, do not guess):
- Index: https://dev.subsidia.protypa.fr/llms.txt
- Any page as Markdown: https://dev.subsidia.protypa.fr/docs/<slug>.md (for example gateway, authentication, errors, rate-limits, knowledge-query, verify)
- Everything in one file: https://dev.subsidia.protypa.fr/llms-full.txt

Facts you must respect:
- Base URL: https://api.subsidia.protypa.fr . OpenAI-style clients use https://api.subsidia.protypa.fr/v1 as base URL; Anthropic-style clients use the host without /v1.
- Authenticate with a developer key sk_live_... read from the SUBSIDIA_API_KEY environment variable, as "Authorization: Bearer <key>" or "x-api-key: <key>". Never hard-code or print a key.
- The Gateway is OpenAI and Anthropic compatible. Prefer the official OpenAI or Anthropic SDK with the base URL changed over hand-written HTTP. The model field is an address: use "pulse-auto" unless told otherwise; "agent:<slug>" calls a workspace agent; the flags +cortex (ground in the knowledge base) and +sensitive (local processing only) can be appended. Do not invent other model names or flags.
- Every Gateway response carries an x-pulse-proof header: the id of a signed proof certificate. Keep it with the business record the answer feeds. Fetch it with GET /v1/proofs/{id}.
- A key may be restricted by scope (engine, knowledge, proof, agents, conversations, webhooks, reflex, light, partner, readonly). A 403 scope_denied means the key lacks the scope named in the message; do not retry, report it.
- Errors: branch on the HTTP status, then on the "code" field. 401 and 403 and 4xx: do not retry. 402 means a quota or plan limit: stop and tell the user, never loop. 429 with a retry-after header: wait that many seconds and retry. 5xx: retry at most three times with backoff. The body is {"error": string, "code"?: string} on native routes, {"error": {"message","type","code"}} on /v1/chat/completions, and {"type":"error","error":{"type","message"}} on /v1/messages. In streams, errors arrive as an event after the 200 status.
- Customers buy questions, not tokens. Do not describe limits to end users in tokens.
- File upload is multipart/form-data to POST /v1/knowledge-sources/upload (field "file", 25 MB max); ingestion is asynchronous, poll GET /v1/knowledge-sources/{id} until status is "ready".
- POST /v1/verify checks a text against passages and calls no model; it is counted as a control, not as questions.
- Only document and use endpoints that appear in the documentation. If the documentation does not mention a route, field or error code, say so instead of inventing it.

When unsure, fetch the relevant page and quote the line you relied on.
```

## For documentation tooling

- Pages are plain Markdown with GitHub-style tables and fenced code blocks, headings for sections, and absolute links back to the site.
- Each endpoint is rendered as a section with method and path, authentication and scopes, parameters, examples, responses and errors, so an agent can lift it directly.
- The Ctrl+K search on the site uses the same content as these files.
- If you build a retrieval index over `llms-full.txt`, split on the horizontal rules and keep the source URL comment that precedes each page as the citation.

**Is there an MCP server for these docs?**

No. The Markdown endpoints are the supported way to give an agent the documentation. Any agent that can fetch a URL can use them.

**How fresh is the Markdown?**

It is generated from the same source as the web pages on every request and cached for a few minutes, so it matches the site. For behaviour changes see the [Changelog](https://dev.subsidia.protypa.fr/docs/changelog.md).

**Can an agent call the API on its own to explore it?**

Yes, with a key. `GET /v1/models` lists the model addresses available to the key, including your agents. Prefer a restricted, short-lived key for this, as described above.