API reference

Swyftstack REST API

A predictable, org-scoped REST API for managed PostgreSQL, object storage and backups. Authenticate with an API key or connect an AI client with device login. Everything the console does, you can automate.

On this page: Authentication · Scopes · Rate limits · Errors · Pagination · Endpoints · Examples · Workflows

Overview

The base URL is below. Every response is JSON in a { data } envelope; errors use { error: { code, message } }. All timestamps are ISO-8601 UTC. IDs are prefixed public ids (db_…, proj_…, bucket_…).

Base URL
https://swyftstack.com/v1

Authentication

Send your API key as a bearer token on every request.

Authorization header
Authorization: Bearer sk_live_your_key_here

Device authentication (recommended for AI/CLI)

AI clients connect without a key using the OAuth 2.0 Device Authorization Grant (RFC 8628). The client calls POST /v1/device/authorize, shows you a short code, and polls POST /v1/device/token; you approve in the browser at /device and a scoped key is minted automatically. The official MCP server does this for you - see the MCP guide.

API keys (scripts & CI)

Create long-lived keys under Settings → API keys, with a scope preset and optional expiry. The secret is shown once. Keys are org-scoped and can be revoked anytime.

OAuth 2.0 (roadmap)

A full three-legged OAuth flow for third-party apps is on the roadmap. Today, use device login (for AI/CLI) or API keys (for your own automation).

Scopes

Each key is limited to the scopes you grant. Scopes marked destructive additionally require the key's dangerous-operations toggle.

Databasedatabase:createdatabase:readdatabase:updatedatabase:delete ⚠
Storagestorage:createstorage:readstorage:updatestorage:delete ⚠
Backupsbackup:createbackup:restorebackup:delete ⚠backup:downloadbackup:list
Accountaccount:read
Billingbilling:read
Teamsteam:read

⚠ = destructive. Presets: Read Only (view resources, usage, and backups. cannot create, change, or delete anything.) · Developer (create and manage databases, buckets, and backups. no destructive deletes.) · Full Access (every scope, including deletes (deletes still require the dangerous-operations toggle).)

Rate limits, errors & pagination

Rate limits

Reads are unlimited in normal use. Expensive/irreversible operations (create database, create/restore backup, create bucket, import) are rate-limited per key; exceeding a limit returns 429 with a Retry-After header.

Error responses

Error shape
{
  "error": {
    "code": "insufficient_scope",
    "message": "This API key is missing the required scope: database:create."
  }
}

Codes: unauthorized (401), forbidden / insufficient_scope / dangerous_not_allowed (403), not_found (404), conflict (409), validation_error (422), rate_limited (429), internal_error (500).

Pagination

List endpoints accept ?limit= (max 100). Log endpoints also accept ?page= and return meta.has_next. Results are newest-first.

Endpoints

A key can only see and act on resources in its own organization.

Databases

GET/v1/databasesdatabase:readList databases
POST/v1/databasesdatabase:createCreate a database
GET/v1/databases/:iddatabase:readGet a database
DELETE/v1/databases/:iddatabase:deleteDelete a database (destructive)
POST/v1/databases/:id/restartdatabase:updateRestart
POST/v1/databases/:id/rotate-passworddatabase:updateRotate password
GET/v1/databases/:id/connectiondatabase:readConnection details
GET/v1/databases/:id/ssldatabase:readSSL/TLS status

Network & security

GET/v1/databases/:id/allowlistdatabase:readGet IP allow-list
PUT/v1/databases/:id/allowlistdatabase:updateReplace IP allow-list
GET/v1/databases/:id/rlsdatabase:readRow-Level Security overview
POST/v1/databases/:id/rlsdatabase:updateEnable/disable RLS on a table

Backups & recovery

GET/v1/databases/:id/backupsbackup:listList backups
POST/v1/databases/:id/backupsbackup:createTrigger a manual backup
POST/v1/databases/:id/backups/:backupId/restorebackup:restoreRestore from a backup
POST/v1/databases/:id/backups/:backupId/pinbackup:createPin/unpin a backup
DELETE/v1/databases/:id/backups/:backupIdbackup:deleteDelete a backup (destructive)
GET/v1/databases/:id/recoverybackup:listPITR / WAL / recovery timeline
POST/v1/databases/:id/recovery/restore-requestbackup:restoreRequest a PITR restore
GET/v1/databases/:id/exportbackup:downloadLatest downloadable export

Imports

GET/v1/importsdatabase:readList imports
POST/v1/importsdatabase:createImport an external database
GET/v1/imports/:importIddatabase:readImport status + log

Storage

GET/v1/bucketsstorage:readList buckets
POST/v1/bucketsstorage:createCreate a bucket
DELETE/v1/buckets/:idstorage:deleteDelete a bucket (destructive)
GET/v1/buckets/:id/objectsstorage:readList objects
POST/v1/buckets/:id/objects?key=…storage:createUpload an object
DELETE/v1/buckets/:id/objects/:keystorage:deleteDelete an object

Account & agent

GET/v1/account/usageaccount:readUsage vs plan limits
GET/v1/account/limitsaccount:readPlan limits + features
GET/v1/account/billingbilling:readBilling + trial state
GET/v1/account/api-keysaccount:readList API keys
GET/v1/account/audit-logsaccount:readAPI + agent activity log
GET/v1/agent/statusaccount:readAI-optimized account snapshot
GET/v1/agent/recommendationsaccount:readActionable recommendations

Examples

Create a database, in four languages.

curl -X POST https://swyftstack.com/v1/databases \
  -H "Authorization: Bearer $SWYFTSTACK_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"project":"proj_xxx","name":"production"}'

Common workflows

  • Create a database: POST /v1/databases, then GET /v1/databases/:id/connection for the URL.
  • Import a database: POST /v1/imports, then poll GET /v1/imports/:importId.
  • Restore a backup: GET /v1/databases/:id/backups → POST /v1/databases/:id/backups/:backupId/restore.
  • Manage storage: POST /v1/buckets, then POST /v1/buckets/:id/objects?key=… to upload.
  • Rotate a password: POST /v1/databases/:id/rotate-password (returns fresh credentials once).
  • View usage: GET /v1/account/usage or the aggregated GET /v1/agent/status.
  • Manage API keys: list with GET /v1/account/api-keys; create/revoke in the dashboard.