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

# Overview

Saturn's external API for firms integrating their own systems.

## Authentication

Every request needs your API key:

Authorization: Api-Key \<your key>

The key identifies your firm. All data returned is your firm's data, and only your firm's data — there is no parameter to select an organisation, and any attempt to supply one is ignored.

Keys are shown once at creation and cannot be recovered. If a key is lost or exposed, ask Saturn to revoke it and issue a new one.

## Identifying records

Every record has a `saturn_ref_id` — a UUID that is stable for the life of the record. Store it when you first see a record and use it for every later request.

You do not tell Saturn which CRM you use, and there are no CRM-specific identifiers or endpoints. If you have no CRM integration at all, this API still works exactly the same way.

## Response shape

Successful responses:

\{ "success": true, "data": \{ ... }, "error": null }

List responses add pagination:

\{ "success": true, "data": \[ ... ],
"meta": \{ "pagination": \{ "count": 120, "limit": 10, "offset": 0 } } }

Optional fields are `null` when unset, never an empty string, so you can distinguish "not recorded" from "empty".

## Status codes

| Code | Meaning                                                                                                   |
| ---- | --------------------------------------------------------------------------------------------------------- |
| 200  | Success                                                                                                   |
| 400  | Invalid request — malformed id or bad parameter                                                           |
| 401  | Missing, invalid, revoked or expired API key                                                              |
| 403  | Your key lacks the scope for this operation                                                               |
| 404  | Not found. Also returned for a record belonging to another firm — the two are indistinguishable by design |
| 429  | Rate limit exceeded. Check `Retry-After`                                                                  |
| 502  | A Saturn upstream service is unavailable. Retry; this does not mean the data is missing                   |

A 404 for another firm's record is deliberate: a 403 would confirm the record exists, which would let anyone probe for valid ids.

## Rate limits

Limits are per key. `X-RateLimit-Limit` and `X-RateLimit-Remaining` are returned on every response. If you are backfilling and need a higher ceiling, ask before you start rather than discovering the limit mid-run.