> ## Documentation Index
> Fetch the complete documentation index at: https://docs.rotascale.com/llms.txt
> Use this file to discover all available pages before exploring further.

# API overview

> Base URL, authentication, versioning, and the shape of the endpoints.

The HTTP API is what the SDKs speak. Use it directly where there is no SDK for
your language, or where you are integrating from something that is not an agent.

## Base URL

Your deployment. There is no hosted endpoint, because the platform runs
single-tenant inside your environment.

```
https://rotagrant.internal.example/v1
```

## Authentication

```
authorization: Bearer rsk_...
```

See [Authentication](/authentication) for where keys come from and what they are
scoped to.

## Versioning

The path carries the major version. Within `v1`, fields are added and never
removed or repurposed, so a client that ignores unknown fields keeps working.

The decision record is the exception that gets stronger treatment: fields in a
sealed record are never changed, because a record that means something different
after an upgrade is not a record.

## The endpoints

|                                            |                                                               |
| ------------------------------------------ | ------------------------------------------------------------- |
| `POST /v1/agents`                          | Register an agent. Idempotent by name.                        |
| `POST /v1/grants`                          | Issue a grant.                                                |
| `POST /v1/grants/preview`                  | What a grant of this shape would decide, without creating it. |
| `GET /v1/grants/{id}`                      | Fetch one.                                                    |
| `GET /v1/grants/pending`                   | Grants awaiting approval.                                     |
| `POST /v1/grants/{id}/approve`             | Approve one.                                                  |
| `POST /v1/grants/{id}/delegate`            | Issue an attenuated child.                                    |
| `POST /v1/grant-families`                  | Define a template.                                            |
| `POST /v1/grant-families/{id}/instantiate` | Issue from a template.                                        |
| `POST /v1/authorize`                       | **The decision.**                                             |
| `POST /v1/decisions/{ledger_id}/settle`    | Settle an amount against a decision.                          |

## Errors

Refusals are **not** HTTP errors. `POST /v1/authorize` returns `200` with an
`outcome` of `deny`, `exhausted` or `gated`, because a refusal is a successful
decision and the SDK turns it into an exception on your side.

HTTP `4xx` means the request was malformed or unauthenticated. `5xx` means the
platform failed, and the SDK fails closed on it by default.