Gateway

Integrate with the Parix TigerBeetle operations API, including authentication, responses, limits, and retry behavior.

The Parix gateway is the public data boundary for every database plan. Applications send HTTPS requests to Parix; they never connect directly to TigerBeetle replicas, provider hosts, tunnels, or private gateway routes.

Prerequisites

Before integrating, obtain:

a Ready database and its immutable database ID
an active API key that can reach the database
db:read for read operations and db:write for write operations
the production API origin, https://parix.io

For a first request, complete Connect to a database.

Endpoint

All supported TigerBeetle operations use one public route:

POST /api/v1/databases/{databaseId}/tb/{operation}

Authenticate with an API key in x-api-key:

curl --request POST \
  "https://parix.io/api/v1/databases/$PARIX_DATABASE_ID/tb/lookup_accounts" \
  --header "content-type: application/json" \
  --header "x-api-key: $PARIX_API_KEY" \
  --data '["1"]'

Bearer authentication is also accepted:

Authorization: Bearer px_...

Use one authentication form per request. Prefer x-api-key in direct HTTP integrations because it makes the credential type explicit.

Supported operations

Operation	Required scope	Request purpose
`create_accounts`	`db:write`	Create a batch of accounts.
`create_transfers`	`db:write`	Create a batch of transfers.
`lookup_accounts`	`db:read`	Look up accounts by ID.
`lookup_transfers`	`db:read`	Look up transfers by ID.
`get_account_balances`	`db:read`	Retrieve balance history for one account filter.
`get_account_transfers`	`db:read`	Retrieve transfers for one account filter.
`query_accounts`	`db:read`	Search accounts using a query filter.
`query_transfers`	`db:read`	Search transfers using a query filter.

Request bodies follow TigerBeetle field, flag, and integer rules, represented as JSON. Use TigerBeetle operations for operation examples and the generated API reference for the current schemas.

Implement a request

Keep the API origin, database ID, and secret in environment-specific configuration.
Select an operation and validate the request body before sending it.
Send the request to the database-ID route with content-type: application/json and one authentication header.
Require HTTP 200 before parsing the successful response envelope.
Confirm that databaseId and operation match the request.
Read the TigerBeetle operation result from responsePayload.
For a write, accept the operation as committed only when persisted is true.

Do not derive an endpoint from provider, targetHost, or any address visible in diagnostics. Those values describe gateway routing and are not stable customer connection targets.

Response contract

A successful response includes:

Field	Meaning
`databaseId`, `databaseName`	The resolved Parix database.
`clusterId`	The managed TigerBeetle cluster identifier.
`operation`, `operationLabel`	The operation that was executed.
`requestPayload`	The validated request payload.
`responsePayload`	The TigerBeetle result to consume.
`mode`	The gateway execution mode reported for diagnostics.
`persisted`	Whether the result represents a persisted operation.
`provider`, `replicaCount`, `targetHost`	Routing diagnostics; do not use them as connection configuration.
`docsUrl`, `message`	Operation guidance returned by the gateway.

The gateway can report stub or live mode. Do not equate HTTP 200 with a committed write: a stub or any other response with persisted: false is non-persistent and must not be recorded as a successful ledger mutation.

Limits and batching

Array-based create and lookup payloads accept at most 8,190 items at the schema boundary.
Plan entitlements can impose a lower events-per-request limit, request rate, or concurrency limit. Developer shared databases use shared-plan limits.
Split work into bounded batches below the effective plan limit and avoid synchronized retry bursts.
Keep TigerBeetle IDs stable across a write retry. Generating new IDs can turn a retry into a second logical operation.

Review the active values in Plans and limits rather than hard-coding a catalog limit into your application.

Errors and retries

Status	Meaning	Client action
`400`	Invalid operation payload.	Correct the payload; do not retry unchanged.
`401`	Missing, malformed, disabled, or unknown credential.	Replace or reactivate the credential.
`403`	The key lacks database reach or the required read/write scope.	Correct the key scope or requested database.
`404`	The route or database cannot be resolved for the credential context.	Verify the database ID, organization, and public path.
`409`	A TigerBeetle batch write returned conflicting item results.	Inspect `tbResults`, which contains `index` and numeric `result` entries. Reconcile the batch before retrying.
`429`	A request, event, or concurrency quota was exceeded.	Reduce load and retry with bounded exponential backoff and jitter.
`503`	The target is temporarily unavailable.	Retry reads with backoff. For writes, preserve the same IDs and first determine whether the previous attempt persisted.
`500`	The gateway could not complete the operation.	Capture the response and request context, then retry only when the operation is safe to repeat.

Never retry an invalid payload or authorization failure in a tight loop. Do not log API-key secrets or complete request payloads that contain sensitive ledger data.

Security boundary

Public clients must use the documented /api/v1 route. Private health, ping, tenant-resolution, signed provider, and replica-management routes are operator infrastructure and are not supported customer interfaces. A Dedicated or Production database provides isolation and additional operational surfaces; it does not create a direct TigerBeetle protocol path.

Troubleshooting

Use API keys and authentication for credential and database-scope failures. Use Observability, backups, and CDC to understand which diagnostics are available on shared and dedicated plans.

Next steps

Validate exact request fields in TigerBeetle operations.
Apply the storage and rotation controls in API-key security.
Review current quotas in Plans and limits.

On this page