API DOCS

Use the deployed contract.

OpenAPI defines the currently supported routes, authentication rules, and response shapes.

Open Playground OpenAPI JSON

Base URL

https://api.openbot.ai

Selected routes

OpenAPI

3.1

Quickstart

Start with a key, inspect the deployed OpenAPI contract, then call only the platform routes your integration needs.

1. Create a key

Use the console to create an organization-scoped API key.

2. Read OpenAPI

Treat the deployed OpenAPI document as the source of truth for supported routes.

3. Call the platform

Use curl or openbot-sdk as a thin authenticated HTTP client.

Agent contract

Agents should use OpenAPI for discovery, bearer keys for organization-scoped calls, and idempotency keys for mutating requests.

agent-contract.json

{
  "base_url": "https://api.openbot.ai",
  "openapi": "https://api.openbot.ai/openapi.json",
  "auth": "Authorization: Bearer ob_live_...",
  "content_type": "application/json",
  "idempotency_header": "Idempotency-Key",
  "error_shape": { "error": { "type": "string", "code": "string", "message": "string" } }
}

agent-minimal-flow.sh

OPENBOT_API_KEY="ob_live_..."
BASE="https://api.openbot.ai"

curl "$BASE/openapi.json"

curl "$BASE/health"

Bearer-key API calls are org-scoped. Console-only endpoints use the signed browser session and should not be used by autonomous agents unless the agent is explicitly operating a user console.

API Playground

Build a request from the deployed OpenAPI contract and inspect the real response.

API keys stay in the current tab and out of the URL and curl preview.
Console-only operations remain read-only on the public page.
Inspect status, duration, request ID, rate limits, headers, and body.

Open API Playground

Selected endpoint index

These examples are grouped by method, auth, deployment state, and execution type; the deployed OpenAPI document is the complete route inventory.

This table reports current availability. The 0.1.0 plan validates Stripe test mode only in an isolated non-production environment; production Checkout remains disabled until the 0.2.0 live-payment gates pass. See the repository version roadmap.

Core

Method	Path	Auth	Status	Use
GET	/	Public	deployed route	Service metadata.
GET	/health	Public	deployed route	Dependency-aware health probe.
GET	/openapi.json	Public	deployed route	Machine-readable OpenAPI 3.1 spec.

Keys

Method	Path	Auth	Status	Use
GET	/v1/me	Bearer	deployed route	Validate a Bearer key and inspect workspace, scopes, expiry, and rate limit.
GET	/v1/access/manifest	Console	deployed route	Read the released key-scope and operation contract.
GET	/v1/keys	Console	deployed route	List API keys for the signed-in console user.
POST	/v1/keys	Console	deployed route	Create an API key for the signed-in console user.
POST	/v1/keys/{id}/rotate	Console	deployed route	Revoke an active key and return a replacement secret once.
DELETE	/v1/keys/{id}	Console	deployed route	Revoke an API key.
DELETE	/v1/keys/{id}/record	Console	deployed route	Remove a revoked key from Console listings while retaining audit history.
GET	/v1/webhooks/secret	Console	deployed route	Read the current org webhook signing secret.

Billing

Method	Path	Auth	Status	Use
GET	/v1/billing/credits	Console	deployed route	Read org credit balance.
POST	/v1/billing/bootstrap	Console	deployed route	Idempotently initialize Free Beta credits.
GET	/v1/billing/packages	Console	deployed route	List credit packages.
POST	/v1/billing/checkout	Console	deployed · disabled	Deployed but disabled during current validation; the server rejects Checkout and payment fulfillment.

Errors

Error responses are JSON. Agents should branch on `error.code`, not prose text.

Code	Name	Description
400	Bad Request	Malformed JSON or a failed validation. Check error.details.
401	Unauthorized	Missing, invalid, expired, or revoked API key.
403	Forbidden	The key lacks the required scope or the account cannot use this operation.
404	Not Found	The resource does not exist or belongs to another organization.
409	Conflict	Idempotency key already resolved to an existing resource.
429	Rate Limited	Too many requests. Respect Retry-After.
500	Internal Error	Server error. Retry with exponential backoff.

error.json

{
  "error": {
    "type": "validation_error",
    "code": "invalid_input",
    "message": "Invalid request body.",
    "details": [
      { "path": ["dataset_id"], "message": "Required" }
    ]
  }
}