API overview - Rotascale

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

​Base URL

​Authentication

​Versioning

​The endpoints

​Errors

Base URL

Authentication

Versioning

The endpoints

Errors