> For the complete documentation index, see [llms.txt](https://shinkalabs.gitbook.io/hub/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://shinkalabs.gitbook.io/hub/andromeda/api-reference/overview.md).

# Overview & conventions

The REST API is served from `https://api.andromedainfra.pro`. The canonical schema is the [OpenAPI 3.1 document](https://api.andromedainfra.pro/openapi.json); when this documentation and the spec disagree, the spec wins.

## Base URL and versioning

* Base URL: `https://api.andromedainfra.pro`
* All product routes are under `/v1/`.
* Public, no-auth routes: `GET /capabilities`, `GET /openapi.json`, `GET /v1/pricing`, `GET /health`, `GET /health/ready`.
* Routes scheduled for removal carry RFC 8594 `Deprecation` and `Sunset` response headers before they go.

## Authentication

Send `X-Api-Key: <key>` on every authenticated request. The key's scope (`read`, `write`, `admin`, or wildcard) must cover the route. See [Authentication](/hub/andromeda/getting-started/auth.md).

## Request shape

* JSON request bodies; `Content-Type: application/json`.
* Mutating endpoints accept an `Idempotency-Key` header. See [Idempotency keys](/hub/andromeda/guides/idempotency.md).
* Request bodies are capped (large enough for the heaviest engine payloads); oversize bodies fail with `413`.
* Two common patterns for writes:
  * `.../prepare` returns an unsigned transaction (`unsignedTx`, base64); you sign and submit it.
  * `.../challenge` returns a 32-byte challenge plus `expectedNonce`; the user signs it; you submit the signature.

## Response shape

Responses are JSON. Successful responses return the resource or result for the operation; the exact fields are in the OpenAPI spec per endpoint. Errors follow a consistent envelope; see [Error codes](/hub/andromeda/api-reference/errors.md).

## Rate limits and quotas

* Calls are throttled per API key in two buckets: `read` (GETs and read-only POSTs) and `tx` (signing, prepares, submits, recovery, future-sign, identity). Exceeding a bucket returns `429` with `Retry-After`.
* Each call charges the key's quota by the operation's cost. Exhausting quota returns `402`. See [Quotas & rate limits](/hub/andromeda/pricing/quotas.md).

## Timeouts

Heavy MPC operations (DKG, sign, presign, future-sign completion, quorum finalize) have longer server-side timeouts than typical calls. Set generous client timeouts for those, and always pair them with an `Idempotency-Key`.

## Caching

`GET /v1/pricing` is cacheable at the edge (`Cache-Control: public, max-age=60`). Treat other responses as non-cacheable unless a header says otherwise.

## Endpoint groups

| Group                  | What it covers                                                                                                     |
| ---------------------- | ------------------------------------------------------------------------------------------------------------------ |
| dWallets & signing     | DKG, presign, sign, future-sign, imported keys, share management                                                   |
| Recovery               | discovery, recovery policy config, primary recovery, quorum sessions                                               |
| Identity               | email magic link (OAuth and passkey flows run server-side and are not exposed via the gateway)                     |
| Policies               | the eight policy templates: preview, deploy, read, and challenge-based admin actions (change, and `revoke`)        |
| Webhooks               | endpoint registration and management                                                                               |
| Future-Sign            | triggers and completion                                                                                            |
| Audit log              | query and verification data                                                                                        |
| Encrypt FHE            | ciphertexts, graphs, DSL, decrypt, NEK, authorities, fees, ownership, events, private transactions, wallet balance |
| Capabilities & pricing | introspection and cost planning                                                                                    |
| SDK metadata           | per-policy typed client artifacts                                                                                  |

Use the [OpenAPI explorer](/hub/andromeda/api-reference/openapi.md) for the exact operations, parameters and schemas in each group.