API Reference

Zatabase exposes a RESTful HTTP API at your project endpoint. All endpoints accept and return JSON unless otherwise noted. Authentication is required for all endpoints except health checks.

Base URL

https://your-project.zatabase.io

All paths below are relative to this base.

Authentication

Include the JWT access token in the Authorization header:

Authorization: Bearer <access_token>

See the Authentication guide for signup, login, and token refresh flows.

Endpoints Overview

Health (No Auth Required)

Method	Path	Description
GET	/health	Liveness check
GET	/health/ready	Readiness check (verifies subsystems)
GET	/healthz	Kubernetes-compatible liveness alias
GET	/metrics	Prometheus metrics endpoint

Authentication

Method	Path	Description
POST	/v1/auth/signup	Create a new account
POST	/v1/auth/login	Exchange credentials for tokens
POST	/v1/auth/refresh	Refresh an expired access token
POST	/v1/auth/logout	Revoke the current session
POST	/v1/auth/switch	Switch environment (live/sandbox)
GET	/v1/whoami	Get current session details
GET	/v1/environments	List available environments

SQL Execution

Method	Path	Description
POST	/v1/sql	Execute a SQL statement

Request body:

{
  "query": "SELECT * FROM products WHERE price > 10.0 LIMIT 20"
}

Response:

{
  "rows": [
    {"name": "Widget", "price": "29.99"}
  ],
  "affected_rows": 0
}

For INSERT, UPDATE, and DELETE, rows is empty and affected_rows contains the count.

Collections

Method	Path	Description
GET	/v1/collections	List all collections
POST	/v1/collections	Create a collection with optional projection
GET	/v1/collections/:name	Get collection metadata
DELETE	/v1/collections/:name	Delete a collection
GET	/v1/collections/:name/projection	Get projection definition
PUT	/v1/collections/:name/projection	Update projection
POST	/v1/collections/:name/ingest	Ingest documents (NDJSON or JSON array)

Vector Search

Method	Path	Description
POST	/v1/knn	Exact K-nearest neighbor search
POST	/v1/indexes/hnsw/build	Build an HNSW index
POST	/v1/indexes/hnsw/search	Approximate nearest neighbor search
GET	/v1/indexes/hnsw	List HNSW indexes
GET	/v1/indexes/hnsw/:table/:column/stats	Index statistics

ZQL Native

Method	Path	Description
POST	/api/zql/query	Execute arbitrary ZQL
POST	/api/zql/insert	Insert a record
POST	/api/zql/search	Similarity search
GET	/api/zql/record/:id	Get record by ID
DELETE	/api/zql/record/:id	Delete record by ID
POST	/api/zql/flush	Flush writes to disk
GET	/api/zql/info	Engine statistics

Jobs

Method	Path	Description
POST	/v1/jobs	Submit a new job
GET	/v1/jobs	List all jobs
GET	/v1/jobs/:id	Get job status
POST	/v1/jobs/:id/cancel	Cancel a running job
POST	/v1/jobs/:id/artifacts	Upload an artifact
GET	/v1/jobs/:id/artifacts	List job artifacts
GET	/v1/jobs/:id/artifacts/:aid	Download an artifact
WS	/v1/jobs/:id/logs	Stream job logs (WebSocket)

ZATA

Method	Path	Description
GET	/v1/credits/balance	Get ZATA balance
POST	/v1/credits/purchase	Purchase ZATA (Stripe checkout)
GET	/v1/credits/transactions	List transaction history
GET	/v1/credits/transactions/:tx_id	Get a single transaction
POST	/v1/credits/escrow/lock	Lock ZATA in escrow
POST	/v1/credits/escrow/:id/release	Release escrowed ZATA
POST	/v1/credits/escrow/:id/refund	Refund escrowed ZATA
GET	/v1/credits/escrow	List active escrows

Permissions

Method	Path	Description
GET	/v1/permissions	List all permission grants
PUT	/v1/permissions	Create or update a permission grant
GET	/v1/permissions/effective	Get effective permissions for session

Organizations

Requires the organizations feature flag.

Method	Path	Description
POST	/v1/organizations	Create a new organization
GET	/v1/organizations	List organizations
GET	/v1/organizations/:org_id	Get organization details
PUT	/v1/organizations/:org_id	Update organization
DELETE	/v1/organizations/:org_id	Delete organization

Additional sub-routes for hierarchy, members, settings, quotas, branding, and collaboration are available under /v1/organizations/:org_id/*.

Teams

Requires the organizations feature flag.

Method	Path	Description
POST	/v1/teams	Create a new team
GET	/v1/teams	List teams
GET	/v1/teams/:team_id	Get team details
PUT	/v1/teams/:team_id	Update team
DELETE	/v1/teams/:team_id	Delete team

Additional sub-routes for hierarchy, members, invitations, and analytics are available under /v1/teams/:team_id/*.

Graph Queries (Cypher)

Requires the cypher feature flag.

Method	Path	Description
POST	/v1/cypher	Execute a Cypher graph query

Request body:

{
  "query": "MATCH (n:User)-[:KNOWS]->(m) RETURN n, m LIMIT 10"
}

Events

Requires the events feature flag.

Method	Path	Description
POST	/v1/events	Publish a new event
GET	/v1/events	Query events
POST	/v1/events/replay	Replay events
GET	/v1/events/stats	Get event statistics
POST	/v1/webhooks	Create a webhook
GET	/v1/webhooks	List webhooks
GET	/v1/webhooks/:id	Get a specific webhook
DELETE	/v1/webhooks/:id	Delete a webhook
POST	/v1/triggers	Create an event trigger
GET	/v1/triggers	List event triggers
POST	/v1/tasks	Create a task
GET	/v1/tasks	List tasks

WebSocket

Method	Path	Description
GET	/ws	WebSocket upgrade (topic subscriptions, real-time updates)

With the websocket feature flag:

Method	Path	Description
GET	/ws/exactly-once	Enhanced WebSocket with exactly-once delivery

WebSocket messages support subscribe/unsubscribe to topics (e.g., jobs/{id} for real-time job logs).

WebRTC

Requires the webrtc feature flag. All WebRTC routes use the /v2 prefix.

Room management:

Method	Path	Description
POST	/v2/rtc/rooms	Create a new RTC room
GET	/v2/rtc/rooms	List all RTC rooms
GET	/v2/rtc/rooms/:room_id	Get room details
DELETE	/v2/rtc/rooms/:room_id	Delete a room
POST	/v2/rtc/rooms/:room_id/join	Join a room
POST	/v2/rtc/rooms/:room_id/leave	Leave a room
GET	/v2/rtc/rooms/:room_id/participants	List room participants
GET	/v2/rtc/rooms/:room_id/participants/:session_id	Get participant details
PUT	/v2/rtc/rooms/:room_id/participants/:session_id	Update participant

Session management:

Method	Path	Description
GET	/v2/rtc/sessions	List all sessions
GET	/v2/rtc/sessions/:session_id	Get session details
PUT	/v2/rtc/sessions/:session_id	Update session
GET	/v2/rtc/sessions/:session_id/transactions	Get session transaction status
POST	/v2/rtc/sessions/:session_id/transactions/:tx_id/rollback	Force rollback

Signaling:

Method	Path	Description
POST	/v2/rtc/offer	WebRTC offer/answer exchange
POST	/v2/rtc/ice-candidate	Add ICE candidate
POST	/v2/rtc/sessions/:session_id/offer	Create session offer
POST	/v2/rtc/sessions/:session_id/answer	Set session answer
POST	/v2/rtc/sessions/:session_id/handle-offer	Handle incoming offer
POST	/v2/rtc/sessions/:session_id/ice-candidate	Add session ICE candidate
GET	/v2/rtc/sessions/:session_id/connection-stats	Connection statistics
GET	/v2/rtc/sessions/:session_id/status	Session status
POST	/v2/rtc/sessions/:session_id/close	Close session

Subscriptions and triggers:

Method	Path	Description
POST	/v2/rtc/subscriptions	Create a subscription
GET	/v2/rtc/subscriptions	List subscriptions
GET	/v2/rtc/subscriptions/:id	Get subscription details
PUT	/v2/rtc/subscriptions/:id	Update subscription
DELETE	/v2/rtc/subscriptions/:id	Delete subscription
POST	/v2/rtc/triggers	Create a trigger
GET	/v2/rtc/triggers	List triggers
GET	/v2/rtc/triggers/:id	Get trigger details
PUT	/v2/rtc/triggers/:id	Update trigger
DELETE	/v2/rtc/triggers/:id	Delete trigger
POST	/v2/rtc/triggers/:id/execute	Execute trigger manually
GET	/v2/rtc/triggers/:id/history	Trigger execution history

Transactions

Requires the transactions feature flag.

Basic transactions:

Method	Path	Description
POST	/v1/transactions/begin	Begin a transaction
POST	/v1/transactions/:id/execute	Execute within a transaction
POST	/v1/transactions/:id/commit	Commit a transaction
POST	/v1/transactions/:id/rollback	Rollback a transaction
GET	/v1/transactions/:id/status	Get transaction status

Distributed transactions:

Method	Path	Description
POST	/v1/distributed-transactions/begin	Begin distributed transaction
GET	/v1/distributed-transactions/:id/status	Get distributed transaction status
POST	/v1/distributed-transactions/:id/abort	Abort distributed transaction
GET	/v1/distributed-transactions	List distributed transactions
GET	/v1/distributed-transactions/metrics	Distributed transaction metrics

Sagas:

Method	Path	Description
POST	/v1/sagas/start	Start a saga
GET	/v1/sagas/:id/status	Get saga status
POST	/v1/sagas/:id/abort	Abort a saga
GET	/v1/sagas	List sagas

Payments

ACH, ZATA, and Plaid (mounted at /v1/payments):

Method	Path	Description
POST	/v1/payments/payouts/ach	Create ACH payout
POST	/v1/payments/payouts/zrt	Create ZATA payout
GET	/v1/payments/payouts/:payout_id	Get payout status
POST	/v1/payments/payouts/:payout_id/cancel	Cancel payout
POST	/v1/payments/banking/validate	Validate bank account
GET	/v1/payments/banking/routing/:routing_number	Look up bank by routing number
GET	/v1/payments/zrt/exchange-rate	Get current ZATA exchange rate
POST	/v1/payments/zrt/convert	Preview ZATA conversion
GET	/v1/payments/analytics	Payment analytics
POST	/v1/payments/plaid/link-token	Create Plaid link token
POST	/v1/payments/plaid/exchange	Exchange Plaid token
GET	/v1/payments/health	Payment subsystem health

Serverless Functions

Requires the functions feature flag. See Serverless Functions for detailed documentation.

Method	Path	Description
POST	/v1/functions	Create a new function
GET	/v1/functions	List functions
GET	/v1/functions/:id	Get function details
PUT	/v1/functions/:id	Update function
DELETE	/v1/functions/:id	Delete function

Additional endpoints for deployments, execution, metrics, triggers, and the template marketplace are nested under /v1/functions/*.

HTTP function invocation is available at /fn/:function_name/*path (all HTTP methods).

Projects

Requires the projects feature flag.

Method	Path	Description
POST	/v1/projects	Create a new project
GET	/v1/projects	List projects
GET	/v1/projects/:project_id	Get project details
PUT	/v1/projects/:project_id	Update project
DELETE	/v1/projects/:project_id	Delete project
GET	/v1/projects/:project_id/stats	Project statistics
PUT	/v1/projects/:project_id/config	Update project configuration

Additional endpoints for environments, deployments, and deployment operations (deploy, promote, rollback) are available.

Analytics

Method	Path	Description
POST	/v1/analytics/insights	Get analytics insights
GET	/v1/analytics/resources	Get resource metrics (CPU, memory, disk)
POST	/v1/analytics/costs	Cost analysis for a time period
GET	/v1/analytics/anomalies	Detect anomalies

API Documentation

Method	Path	Description
GET	/v1/openapi.json	OpenAPI 3.0.3 specification (JSON)
GET	/v1/docs	Interactive Swagger UI documentation

Prometheus Metrics

Method	Path	Description
GET	/metrics	Prometheus-format metrics (no auth required)

Additional Feature Routes

These routes are available when the corresponding feature flags are enabled:

Feature	Path Prefix	Description
identity	/v1/identity/*	Verifiable credential management
mesh	/v1/mesh/*	Mesh network peer management and economics
domains	/v1/domains/*	Custom domain management and SSL certificates
notifications	/v1/notifications/*	Email/SMS notification delivery and templates
sdk-generator	/v1/sdk/*	SDK generation and publishing
cloud	/v1/cloud/*	Multi-cloud deployment management
security-hardening	/v1/security/health	Security hardening health check
integrations	/v1/integrations/*	Cross-service integration orchestration

Error Responses

All errors follow a consistent format:

{
  "error": "Forbidden",
  "message": "Insufficient permissions: requires Read on Tables",
  "status": 403
}

Common status codes:

Code	Meaning
400	Bad request (malformed JSON, invalid SQL)
401	Unauthorized (missing or expired token)
403	Forbidden (insufficient permissions)
404	Resource not found
409	Conflict (duplicate resource)
422	Unprocessable entity (valid JSON but invalid semantics)
429	Rate limited
500	Internal server error

Rate Limiting

Zatabase applies per-organization rate limits. Default limits are generous for development. Production deployments should configure limits based on the organization tier. Responses include standard rate limit headers:

X-RateLimit-Limit: 1000
X-RateLimit-Remaining: 997
X-RateLimit-Reset: 1709300060