API

The Scuttle API manages realms, databases, accounts and grants. Base URL: https://scuttle.scailabs.ai/api/v1. Requests and responses are JSON.

Authentication#

Send Authorization: Bearer <token>. Automation uses Scuttle API tokens (sct_...), created under API tokens in the console and scoped to a tenant or a single realm with a role. Tokens are shown once and stored hashed. Console users authenticate through ScaiKey.

Asynchronous operations#

Every change to a database or account answers 202 Accepted with an operation object. Poll GET /operations/{id}; state moves from queued to running to succeeded or failed. A failed operation carries the exact difference between the requested and the observed state in error.

Errors#

Errors are RFC 9457 problem documents (application/problem+json) with type, title, status, detail and a request_id to quote in support requests. A resource you have no role on answers 404, not 403.

Pagination#

List endpoints take limit (default 50, maximum 200) and cursor, and return {items, next_cursor}.

Endpoints#

Method and path	Purpose
`GET /me`	your principal, tenant and realm roles
`GET /myip`	the address Scuttle sees you connecting from, and the `allowed_networks` entry for it (no authentication; `?format=text` for the bare address)
`GET /clusters`	clusters with region, service level and endpoint
`GET /tenants/{tenant}`	tenant and its quotas
`GET /tenants/{tenant}/usage?from=&to=`	daily usage per cluster
`GET, POST /tenants/{tenant}/realms`	list, create (`slug`, `display_name`)
`GET, PATCH, DELETE /tenants/{tenant}/realms/{realm}`	read, update, delete (only when empty)
`GET /tenants/{tenant}/realms/{realm}/members`	list members
`PUT, DELETE .../members/{principal}`	set role (`admin`, `operator`, `viewer`), remove
`GET, POST .../realms/{realm}/databases`	list, create (`name`, `cluster`, `charset?`, `collation?`)
`GET, DELETE .../databases/{name}`	read with connection info; delete (purged after 14 days)
`GET, POST .../realms/{realm}/accounts`	list, create (`name`, `cluster`, `grants`, `allowed_networks?` — IPv4 CIDRs and single IPv6 addresses `/128` —, `max_user_connections?`)
`GET, PATCH, DELETE .../accounts/{name}`	read; change attributes and grants (full replace); delete
`POST .../accounts/{name}:rotate-password`	returns the new password once
`GET /operations/{id}`, `GET /tenants/{tenant}/operations`	operation status and history
`GET, POST, DELETE /tenants/{tenant}/api-tokens`	list, create (`name`, `role`: `viewer` \| `operator` \| `admin` \| `tenant_admin`, `realm?` to limit it to one realm, `expires_at?`), revoke; the token itself is returned once, on creation
`GET /tenants/{tenant}/directory?q=`, `GET .../realms/{realm}/directory?q=`	find users and groups of your tenant by name, e-mail or group name, to grant a role to (tenant admins / realm admins)
`GET /tenants/{tenant}/admins`, `PUT, DELETE .../admins/{principal}`	tenant admins (users or groups; `{"principal_type": "user" \| "group"}`)
`GET .../databases/{name}/backups`	restorable window and backups
`POST .../databases/{name}:restore`	restore into a new database: `{"target": "...", "point_in_time": "..."}` (time optional: latest)
`POST .../databases/{name}:export`	build a `.sql.gz` of the database at a point in time (`{"point_in_time": ...}`, optional)
`GET .../databases/{name}/exports/{operation_id}`	the export's download link, valid 24 hours (operators)
`POST .../databases/{name}:purge-backups`	erase a deleted database's backups now (tenant admins)

Grants#

A grant is {"scope": "realm" | "database", "database": "<name>", "profile": "dba" | "readwrite" | "readonly"}. PATCH with grants replaces the complete set.

Quotas#

Defaults for std: 20 realms per tenant, 50 databases and 50 accounts per realm, 100 connections per account (up to 500), 14 days before a deleted database is purged, 14 days of point-in-time backups.