> For clean Markdown of any page, append .md to the page URL.
> For a complete documentation index, see https://infonite.dev/llms.txt.
> For AI client integration (Claude Code, Cursor, etc.), connect to the MCP server at https://infonite.dev/_mcp/server.

# Using the API

The pages in this section are **generated from the running services**, so what you read here is what the API does, not what someone remembered to write down. Each one carries the exact request and response schemas and an explorer you can send a call from.

They are built for **looking things up**. If you are still deciding how to integrate, start with [what a flow is](/flows/overview) — this section will make far more sense afterwards.

Everything below is true of every endpoint, so it is stated once here rather than repeated on each page.

---

## Authenticating

Server-to-server calls carry your **application secret** in a header:

```http
X-APP-SECRET: <your application secret>
```

**The secret belongs on your server and nowhere else.** It authorises creating sessions and reading extracted records for every customer of that application. It must never reach a browser, a mobile binary, or anything a user can open — the widget is the part that faces the end user, and it authenticates with its own short-lived session token instead.

Secrets are issued per application in the console, and can be revoked without affecting the application itself — useful for rotation. A call answers `401` when the secret is unknown or has been revoked, and `403` while the application is still pending approval.

**Each application is either `sandbox` or `production`**, and its secret only works for its own. A sandbox application returns realistic, fabricated records: build and test the whole journey end to end, with no real person and no real institution involved, before anything goes live.

---

## Base URLs

| Environment     | Base URL                                      |
| :-------------- | :-------------------------------------------- |
| **Production**  | `https://widgets.infonite.tech/api/flows`     |
| **Development** | `https://widgets-dev.infonite.tech/api/flows` |

The explorer on each endpoint page lets you pick between them, so you can try a call without leaving the documentation.

---

## Errors

Every error answers with the same shape — an HTTP status, and a body with one field:

```json
{ "detail": "app_secret_revoked" }
```

`detail` is a **stable code, not a sentence**: branch on it in your integration and show your own message to your own user. It is deliberately terse, and deliberately identical in cases that must not be distinguishable from outside.

The one exception is `422`, which carries a validation body naming the field that was rejected — the shape is documented on each endpoint that can return it.

---

## Rate limits

Limits are applied **per application** and vary by endpoint: the calls that create and read sessions are cheap, the one that returns full extracted results is deliberately tighter, since a result set is a large object that should be fetched once and stored.

**Read your budget from the response, do not hardcode it.** Every response carries the current limit, what is left of it, and when it resets. A client that watches those headers keeps working when a limit is tuned; one built around numbers copied from a document does not.

Exceeding a limit answers `429` with a `detail` that names which limit you hit — for example `manager_session_results_rate_limit_exceeded` — so a retry can back off against the right one.

---

## Every response carries

| Header                  | What it is for                                                                                                                           |
| :---------------------- | :--------------------------------------------------------------------------------------------------------------------------------------- |
| `x-request-id`          | The identifier of that exact call. **Log it.** Quote it to support and we can find the request without asking you to reproduce anything. |
| `x-process-time`        | Seconds we spent processing, excluding the network. Useful for telling *"they are slow"* apart from *"the link is slow"*.                |
| `x-ratelimit-limit`     | The ceiling in force for that endpoint.                                                                                                  |
| `x-ratelimit-remaining` | What is left of it right now.                                                                                                            |
| `x-ratelimit-reset`     | When the window resets, as a Unix timestamp.                                                                                             |

---

## The webhook pages

A section here is titled **Webhooks**, and its pages describe calls that go the other way: **we** send them to **your** server. They are documented as endpoints because the payload contract is identical in kind — the schema on the page is exactly what will arrive.

#### [Webhooks guide](/flows/spain-public-administration/webhooks)

How to receive them: subscribing, authenticating the call, what travels with and without an encryption key, and the rules a destination URL has to satisfy.