API reference overview

Base URL, authentication, the error envelope, streaming and rate limits shared by every route.

Base URL

https://swarm.thundera.eu. All routes below are under /api/v1 unless shown. Bodies and responses are JSON.

Authentication

Routes marked Session or API key accept the swarm_session cookie or an API key (Authorization: Bearer, or x-api-key). Admin role routes additionally need the Thundera admin role. See Authentication and keys.

Errors

Errors use one envelope:

{"error":{"code":"INSUFFICIENT_CREDITS","message":"Your credit balance is too low to complete this request.","details":{}}}

Code	HTTP	Meaning
`UNAUTHENTICATED`	401	No or invalid session/key.
`SESSION_REVOKED`	401	The Thundera session was revoked; sign in again.
`FORBIDDEN`	403	Missing role.
`NOT_FOUND`	404	Unknown resource.
`VALIDATION_ERROR`	400	`details.fields` lists each field and message.
`INSUFFICIENT_CREDITS`	402	Balance cannot cover the reservation.
`MODEL_DISABLED`	422	The model is not enabled.
`RATE_LIMITED`	429	Retry after `Retry-After` seconds.
`UPSTREAM_ERROR`	502	The provider failed; the reservation is refunded.
`INTERNAL_ERROR`	500	Unexpected failure.

Streaming

With stream: true the response is text/event-stream. The last event before [DONE] carries the swarm block with the real debit. If you disconnect, the call is aborted and refunded.

The `swarm` block

Field	Meaning
`credits_debited`	Credits charged for this call.
`credit_balance_after`	Your balance after settlement.
`usage_event_id`	Id of the ledger row; matches `/usage`.
`token_source`	Whether token counts came from the provider or an estimate.
`cached_tokens`	Input tokens served from the provider cache.
`dropped_params`	Present only if a parameter was removed for this model.