API Reference

Complete REST API reference for the AxiomDB Gateway. All endpoints require a valid PASETO v4 Bearer token unless noted as public.

Base URL

https://api.axiomdb.squareexp.com

Authentication

All API requests (except /api/v1/health and /api/v1/auth/*) require:

Authorization: Bearer <paseto-v4-token>

Health

`GET /api/v1/health`

Public — no auth required.

{ "status": "ok", "timestamp": "2025-07-02T12:00:00Z" }

Authentication endpoints

`GET /api/v1/auth/square/login`

Redirect to Square IdP authorization endpoint.

Query	Required	Description
`return_to`	❌	URL to redirect to after successful login

`GET /api/v1/auth/square/callback`

OAuth2 callback. Exchanges auth code for PASETO token pair.

Query	Required	Description
`code`	✅	Authorization code from IdP
`state`	✅	CSRF state value

`POST /api/v1/auth/login`

Password-based login (Base IdP / Square IdP).

Body:

{
  "email": "string",
  "password": "string",
  "provider": "base_idp | square_idp"
}

Response: { access_token, refresh_token, pre_auth_token, requires_2fa, requires_2fa_setup, method, user }

`POST /api/v1/auth/signup`

Create a new account.

Body:

{
  "name": "string",
  "email": "string",
  "password": "string",
  "provider": "base_idp"
}

`POST /api/v1/auth/magic-link/start`

Request a magic link / email OTP.

Body: { "email": "string" }

`POST /api/v1/auth/magic-link/verify`

Verify magic link code.

Body: { "email": "string", "challenge_id": "string", "code": "string" }

`POST /api/v1/auth/cli/start`

Start CLI PKCE flow.

Body:

{
  "redirect_uri": "string",
  "state": "string",
  "code_challenge": "string",
  "code_challenge_method": "S256"
}

`POST /api/v1/auth/cli/exchange`

Exchange PKCE auth code for tokens.

Body:

{
  "code": "string",
  "redirect_uri": "string",
  "code_verifier": "string"
}

`POST /api/v1/auth/refresh`

Refresh an access token.

Body: { "refresh_token": "string" }

`POST /api/v1/auth/2fa/setup`

Generate TOTP secret. Requires Authorization: Bearer <pre-auth-token>.

`POST /api/v1/auth/2fa/verify-setup`

Confirm 2FA setup. Requires Authorization: Bearer <pre-auth-token>.

Body: { "code": "string" }

Verify 2FA code during login. Requires Authorization: Bearer <pre-auth-token>.

Body: { "code": "string" }

`POST /api/v1/auth/2fa/skip`

Skip 2FA setup for this session. Requires Authorization: Bearer <pre-auth-token>.

Network utilities

`GET /api/v1/network/my-ip`

Auth required. Returns the caller's IP and suggested CIDR.

{ "ip": "203.0.113.10", "suggested_cidr": "203.0.113.10/32" }

Projects

`GET /api/v1/projects`

List all projects for the authenticated tenant.

`POST /api/v1/projects`

Create a new project (async provisioning).

Body: { "name": "string", "app_key": "string", "env": "string" }

`GET /api/v1/projects/lookup?name=<query>`

Find a project by name, slug, or app_key.

`GET /api/v1/projects/:project_id`

Get a single project.

`DELETE /api/v1/projects/:project_id`

Delete a project and all its branches. Requires owner or admin role.

`GET /api/v1/projects/:project_id/credentials`

Get runtime and direct connection strings for the project's main database.

`POST /api/v1/projects/:project_id/credentials/rotate`

Rotate a database role password.

Body: { "role": "runtime | direct | readonly", "confirm": "rotate {slug} {role}" }

`GET /api/v1/projects/:project_id/usage`

Get storage usage and branch count.

`GET /api/v1/projects/:project_id/metrics`

Get live database metrics for all project databases.

Branches

`GET /api/v1/projects/:project_id/branches`

List all branches for a project.

`POST /api/v1/projects/:project_id/branches`

Create a new branch.

Body:

{
  "branch_name": "string",
  "source_branch_id": "uuid | null",
  "lifespan": "7d | 1m | 6m | 1y | forever"
}

`GET /api/v1/projects/:project_id/branches/lookup`

Find a branch by name or ID.

Query	Description
`name`	Branch name
`id`	Branch UUID

`DELETE /api/v1/projects/:project_id/branches/:branch_id`

Delete a branch. Protected branches cannot be deleted.

`GET /api/v1/projects/:project_id/branches/:branch_ref/credentials`

Get connection strings for a specific branch.

`GET /api/v1/projects/:project_id/branches/:branch_ref/metrics/summary`

Get live metrics for a specific branch.

Network rules

`GET /api/v1/projects/:project_id/network/rules`

List all active network rules for a project.

Query	Description
`branch_id`	Filter to a specific branch
`include_project`	Also include project-scoped rules when filtering by branch

`POST /api/v1/projects/:project_id/network/rules`

Create a network allowlist rule.

Body:

{
  "cidr": "string",
  "label": "string",
  "ports": "runtime | direct | both",
  "scope": "project | branch",
  "branch_id": "uuid | null",
  "expires_in": "1h | 24h | 7d | 30d | 1y | null"
}

`PATCH /api/v1/projects/:project_id/network/rules/:rule_id`

Update an existing rule.

`DELETE /api/v1/projects/:project_id/network/rules/:rule_id`

Delete a network rule and revoke firewall entry.

`POST /api/v1/projects/:project_id/network/public-mode`

Change network access mode.

Body: { "mode": "restricted | public_runtime", "confirm": "make runtime public" }

Table browser

`GET /api/v1/projects/:project_id/branches/:branch_ref/tables`

List all user tables in a branch database.

`GET /api/v1/projects/:project_id/branches/:branch_ref/tables/:table/rows`

Browse rows in a table.

Query	Default	Description
`limit`	50	Max rows per page (max 200)
`offset`	0	Row offset for pagination
`sort_by`	—	Column to sort by
`sort_dir`	`asc`	`asc` or `desc`

`PATCH /api/v1/projects/:project_id/branches/:branch_ref/tables/:table/rows`

Update a single cell.

Body: { "column": "string", "id": "string", "primary_key": "string", "value": "any" }

`DELETE /api/v1/projects/:project_id/branches/:branch_ref/tables/:table/rows`

Delete rows by primary key.

Body: { "ids": ["string"], "primary_key": "string" }

Backups

`GET /api/v1/projects/:project_id/backups`

List all backups with PITR availability window.

`POST /api/v1/projects/:project_id/backups/restore-plan`

Generate a dry-run restore plan (async job).

Body: { "target": "string", "target_type": "time | label" }

`POST /api/v1/projects/:project_id/backups/restore`

Execute a point-in-time restore (async job). Requires owner or admin role.

Body: { "target": "string", "target_type": "time | label", "confirm": "restore {database_name}" }

`GET /api/v1/projects/:project_id/backups/policy`

Get backup schedule and retention policy.

`PUT /api/v1/projects/:project_id/backups/policy`

Update backup schedule and retention policy.

Provisioning jobs

`GET /api/v1/jobs/:job_id`

Get a provisioning job by ID. Returns status, output, and error_text.

CORS

`GET /api/v1/projects/:project_id/cors`

List allowed CORS origins.

`PUT /api/v1/projects/:project_id/cors`

Set allowed CORS origins.

Body: { "origins": ["string"] }

Error responses

All errors follow this structure:

{
  "error": "short machine-readable code",
  "message": "Human-readable description"
}

HTTP Status	Error Code	Meaning
400	`bad_request`	Invalid input
401	`unauthorized`	Missing or invalid Bearer token
403	`forbidden`	Insufficient role
404	`not_found`	Resource does not exist
409	`conflict`	Duplicate resource (e.g. project slug already taken)
422	`validation_error`	Request body failed validation
429	`branch_limit_exceeded`	10-branch limit reached
500	`internal_error`	Server error — contact support
503	`circuit_breaker_open`	VPS unreachable, square-dbctl calls blocked

All 5xx errors from square-dbctl operations are retried up to the circuit breaker threshold (default: 5 failures). After tripping, subsequent requests fail immediately with 503 until the circuit auto-resets after 60 seconds.

On this page