Public API Reference

This page documents the current public deployment API as implemented in the product today.

Base Surface

Current routes:

• GET /api/public/v1/deployments/indexer
• POST /api/public/v1/deployments/indexer
• GET /api/public/v1/deployments/indexer/[id]
• GET /api/public/v1/deployments/channel
• POST /api/public/v1/deployments/channel
• GET /api/public/v1/deployments/channel/[id]

These routes are organization-scoped through the API key that authenticates the request.

Authentication

Accepted credentials:

• Authorization: Bearer <API_KEY>
• x-api-key: <API_KEY>

API keys:

• use the obk_ token format
• are stored hashed in the database
• can be revoked
• can expire
• are limited by scopes

Current scopes:

• deployments:read
• deployments:write

Only organization owner and admin members can create or revoke these keys from the workspace.

Request Context Headers

Optional request headers:

• x-request-id
• idempotency-key

Behavior:

• if x-request-id is missing, the server creates one
• if idempotency-key is missing, the request ID is reused
• create requests are idempotent per template and request body

Response Headers

Every successful and error response includes:

• x-public-api-version
• x-request-id

Rate-limit headers:

• x-ratelimit-limit
• x-ratelimit-remaining
• x-ratelimit-reset
• x-ratelimit-reset-at
• retry-after

Default rate limit:

• 120 requests per 60 seconds per API key unless environment configuration overrides it

Endpoint Summary

List Query Parameters

Shared list query model:

Create Indexer Deployment

Request body:

Example:

curl -X POST \
  -H "Authorization: Bearer <API_KEY>" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: indexer-prod-2026-03-12" \
  -d '{"name":"indexer-prod-01","template":"dubhe-indexer-api","configJsonUrl":"https://example.com/indexer.config.json"}' \
  "https://your-app.example.com/api/public/v1/deployments/indexer"

Create Channel Deployment

Request body:

Example:

curl -X POST \
  -H "Authorization: Bearer <API_KEY>" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: channel-prod-2026-03-12" \
  -d '{"name":"channel-prod-01","template":"dubhe-channel-api","rpcUrl":"https://rpc.example.com","syncTimeSeconds":5}' \
  "https://your-app.example.com/api/public/v1/deployments/channel"

Preconditions On Create

Create endpoints currently require all of these to pass:

• the organization has managed infrastructure access
• provisioning queue capacity is available
• provisioning preflight succeeds
• the API key has deployments:write

Idempotency Behavior

Create endpoints hash the request body and pair it with the idempotency key.

If the same key is reused:

• with the same payload, the existing deployment is returned
• with a different payload, the API returns 409 idempotency_conflict

This is the correct pattern for retry-safe automation.

Error Model

The public API normalizes errors into JSON with:

• error
• message
• optional details
• optional requestId

Current notable error codes:

• unauthorized
• forbidden
• invalid_request
• invalid_json
• not_found
• precondition_failed
• queue_capacity_exceeded
• rate_limit_exceeded
• idempotency_conflict
• internal_error

What The API Returns

List routes return:

• total
• pagination
• deployments

Create routes return:

• deployment
• task
• idempotentReplay

Single-deployment routes return the deployment plus recent task and audit history for that deployment.

Operational Notes

• API requests update the key's lastUsedAt timestamp
• rate limiting is enforced per API key, not globally per organization
• create routes write provisioning audit logs with source public_api

Related Pages

• API Keys and Public Deployment API
• Reference Overview
• Role And Permission Matrix
• Production Readiness