HTTP API

Every Spiral service has an HTTP API at https://api.spiraldb.dev that takes JSON and a bearer token, and sign-in happens at https://auth.spiraldb.com. The SDKs and the CLI call these same APIs. Call them directly when you work in a language without an SDK, or when you want to see exactly what a call does. This page lists the hosts, the conventions every service shares, and the reference for each service.

HostsCopy Anchor Link

Authenticate a requestCopy Anchor Link

Send an access token in the Authorization header of each request:

curl https://api.spiraldb.dev/v1/projects \
  -H "Authorization: Bearer $SPIRAL_TOKEN"

The discovery documents and the public signing keys need no token, and an operation's reference says when it is anonymous. See Authentication to get a token.

Requests and responsesCopy Anchor Link

• Send request bodies as JSON with Content-Type: application/json. The OAuth token endpoints are the exception: they take form-encoded bodies, as the OAuth 2.0 specification requires.
• Read response bodies as JSON. Some read operations stream other media, and their reference names the media type.
• Field names are camelCase on /api routes. Other routes use camelCase or snake_case, so check the operation's reference for the exact names.
• On /api routes, 64-bit integers are decimal strings, so that JavaScript clients keep their precision. The server also accepts JSON numbers within the exact range of a double.

Route familiesCopy Anchor Link

Routes on api.spiraldb.dev come in two families, and some conventions depend on the family:

• /api routes are the Catalog (/api/catalog/...) and Applications (/api/apps/...). They share one error envelope, one pagination style and strict field rules, which the pages in this section describe exactly.
• Service routes are all the others. Each service follows its own conventions for errors and pagination, and the pages in this section say which service does what.

Service routes use one of three path forms:

OAuth and discovery endpoints use the paths their specifications define, such as /oauth/token and /.well-known/openid-configuration.

Unknown fieldsCopy Anchor Link

/api routes apply one rule in each direction:

• Requests. The server rejects unknown fields, unknown enum values, unknown union variants and repeated JSON keys with Contract:InvalidRequest.
• Responses. Clients ignore fields they do not know, and keep enum values and union variants they do not know.

That is what lets a service add response fields without breaking your client. Write your own client the same way: send only the fields the reference lists, and ignore new ones in responses.

Service routes differ. Some request types reject unknown fields, for example Task creation and Location versions, and others ignore them. Send only the fields the reference lists.

ConventionsCopy Anchor Link

Service referenceCopy Anchor Link

Each service documents every public operation, with its path, request, response and errors, in its own HTTP reference:

The OAuth endpoints of the Authentication service follow the OAuth 2.0 RFCs, and the Authentication API reference names the RFC for each one. Operations that are internal, or that a newer operation replaces, are not part of the public reference.

Permissions lists the permissions each service checks and the OAuth scope that delegates each one. Resource addresses defines the path@ref form that the SDKs accept.