REST API
The platform API lives under https://clankerbay.com/api/v1. Its contract is a first-party OpenAPI 3.1 document: /api/v1/openapi.json. It is also the schema behind the CLI's clankerbay namespace.
Endpoints
| Method & path | Auth | Purpose |
|---|---|---|
GET /pow | none | Proof-of-work parameters and server time |
POST /auth/signup | PoW | Create an account, returns an agent token |
POST /auth/signin | PoW | Exchange email and password for an agent token |
POST /auth/signout | token | Revoke the calling token |
GET /search?q= | token or PoW | Capability search |
GET /namespaces | none | List namespaces (paginated) |
GET /namespaces/{namespace} | none | Namespace details and commands |
GET /namespaces/{namespace}/openapi.json | none | OpenAPI document for clients (ETag) |
GET /account | token | The account and token in use |
GET /account/balance | account:read | Subscription and prepaid balances |
GET /account/usage | account:read | Usage records with credit source (paginated) |
GET /account/spending-controls | account:read | Account and token limits |
GET /billing/history | account:read | Charges, refunds and invoice links |
GET /subscription | account:read | Current plan |
GET|POST /agent-keys | keys:manage | List or create tokens |
POST /agent-keys/{id}/rotate | keys:manage | Rotate a token |
DELETE /agent-keys/{id} | keys:manage | Revoke a token |
* /gateway/{namespace}/{path} | gateway:call | Call a provider endpoint (details) |
Errors
All errors share one envelope:
{
"error": {
"code": "insufficient_credits",
"message": "This call costs 5 credits; 3 are available.",
"request_id": "01JA…"
}
}
Validation errors (422) add a fields object. Rate-limited responses (429) include Retry-After.
Pagination
List endpoints accept page and per_page (max 200) and return {"data": [...], "meta": {"page", "last_page", "total"}}.
Rate limits
- Authenticated platform API: 120 requests/minute per token.
- Anonymous reads: 60 requests/minute per IP, plus proof of work for search.
- Sign-in: 10/minute per IP and 5/minute per email. Sign-up: 5/hour per IP.
- Gateway: 600 requests/minute per token by default.
Idempotency
Send an Idempotency-Key header on gateway calls that must not run twice. Within 24 hours, a repeated key with the same token returns the stored result (or 409 idempotency_in_progress while the first call is running) and is never charged twice.