API and OpenAPI

Parix exposes its customer integration API under /api/v1. Use it to discover the database configurations currently available to your organization, create and inspect databases, request deletion, and run supported TigerBeetle operations.

Use the live OpenAPI document as the source of truth for exact request and response schemas:

• Authoritative OpenAPI 3.1 document: /api/v1/openapi.json
• Interactive reference: /docs/openapi

The interactive page renders a bundled schema snapshot and can lag the live route document until the bundle is regenerated. Generate clients and validate new request fields against /api/v1/openapi.json from the environment you call.

The document includes local, development, staging, and production server entries. Choose the server that owns the organization and databases you intend to manage; credentials and database IDs are not interchangeable between environments.

Before you begin

You need:

• an API key created from global Settings > API keys, or an OAuth/CLI access token;
• the correct environment base URL;
• an organization membership for token authentication; and
• the database UUID for database-specific operations.

API key management is available to organization owners and administrators. A new or rotated key secret is shown once, so copy it to a secret manager before leaving the result screen.

Authenticate a request

Send exactly one of these authentication headers:

x-api-key: px_...

Authorization: Bearer <access-token-or-api-key>

Using one header removes ambiguity about which credential Parix should evaluate. Do not put credentials in URLs, request bodies, logs, or screenshots.

Start every new integration by calling the session endpoint:

curl "$PARIX_BASE_URL/api/v1/session" \
  -H "x-api-key: $PARIX_API_KEY"

A successful response identifies the authentication type, organization, granted scopes, and—when applicable—the API key's database boundary. This is the quickest way to detect a valid key that belongs to the wrong organization or is restricted to a different database.

Credential boundaries

API keys are granted both db:read and db:write; their configurable scope is the resource boundary, not a read-only/write toggle. A specific-database key cannot read a different database and cannot create or delete databases. OAuth/CLI tokens must include the scope required by the endpoint.

See API keys and authentication for 401, 403, and route troubleshooting.

Database lifecycle endpoints

The list endpoint accepts an optional search term and limit up to 100. Results are returned newest first. A specific-database key sees only its bound database.

Create a database safely

1. Read the current catalog

Call the create catalog immediately before presenting or submitting create choices:

curl "$PARIX_BASE_URL/api/v1/catalog/create" \
  -H "x-api-key: $PARIX_API_KEY"

The response groups the providers and regions available in the current environment and returns valid cluster configurations, cluster sizes, and storage tiers with provider capabilities. Treat these returned IDs as authoritative. Do not cache a provider or configuration indefinitely or assume an implementation is enabled for customer creation in every environment.

2. Create a Developer database

The current public create path reliably supports the shared Developer plan. Supply a unique idempotency key so a network retry does not create a second database:

curl -X POST "$PARIX_BASE_URL/api/v1/databases" \
  -H "content-type: application/json" \
  -H "x-api-key: $PARIX_API_KEY" \
  -H "Idempotency-Key: <unique-request-id>" \
  -d '{
    "name": "ledger-development",
    "planCode": "developer",
    "allowRegionFallback": true
  }'

allowRegionFallback permits placement in another configured shared region when the preferred pool cannot admit the project.

The request schema currently advertises dedicated and Production fields, but the service does not reliably propagate those plan selections and can default a non-shared request to Single Node. Create or import dedicated and Production databases through the dashboard until that API path is fixed. The create catalog describes infrastructure choices, but it does not return plan codes.

3. Interpret the body, not only HTTP 200

Database creation is an orchestration request. An HTTP 200 response does not by itself mean that a dedicated database is ready.

Check these fields:

• success: false means creation was blocked, commonly by eligibility or billing. When present, the billing object includes a machine-readable code, customer-facing message, and checkout URL.
• success: true with an active shared placement means the shared database is ready for supported operations.
• success: true with database/profile/job data means dedicated provisioning was created or queued. Poll the database endpoint until the profile becomes active or the latest job reports an error.
• A failed-to-enqueue provisioning status means the database record exists but no provisioning workflow started. Keep the returned database ID and use it when troubleshooting; do not blindly create another database with the same intent.
• A skipped or pending-provider result means the requested provider path did not start provisioning. Follow the response message and re-read the catalog before retrying.

See Provisioning and configuration for recovery steps.

Inspect readiness

Retrieve the database by UUID:

curl "$PARIX_BASE_URL/api/v1/databases/$DATABASE_ID" \
  -H "x-api-key: $PARIX_API_KEY"

The response separates the durable database record from its deployment state. Inspect the database, profile, latest provisioning job, provider/region, decommission state, and metric summary together. For a dedicated database, wait for an active profile before running operations or requesting configuration changes.

Use the returned UUID—not the display name from a dashboard URL—in API paths.

Request deletion

Deletion is destructive and has no self-service undo. Before running this request, verify the database UUID and display name, stop or redirect application traffic, and confirm any export or recovery requirement. Completed backup artifacts can remain until retention expiry, but that does not make deletion reversible.

curl -X DELETE "$PARIX_BASE_URL/api/v1/databases/$DATABASE_ID" \
  -H "x-api-key: $PARIX_API_KEY"

An accepted response contains status: "queued", a workflow ID, and a message. Deletion is asynchronous. If provisioning is still active, Parix records the deletion request and defers destructive work until provisioning finishes. A repeated request while deletion is already active returns a conflict instead of starting a second workflow.

Keep the workflow ID until the database reaches a terminal deletion state.

Handle errors consistently

Validation and operational errors use a Problem Details body. Read the JSON body even when your HTTP client throws on non-2xx responses.

{
  "type": "...",
  "title": "Validation Error",
  "status": 400,
  "detail": "Invalid request data",
  "instance": "/api/v1/...",
  "errors": [],
  "fieldErrors": {}
}

errors and fieldErrors are present when field-level validation information is available. Common statuses are:

TigerBeetle write conflicts add tbResults to the Problem Details response. See TigerBeetle operations for batch-result handling.