API reference
Introduction
The Crackle API is a JSON API over HTTPS. This page covers what every request has in common; the pages beside it cover each request one at a time.
Base URL
https://goblins-call-api.onrender.comEvery path in this reference is relative to it, and every path starts with /v1.
Authentication
Send an API key as a bearer token with every request. Keys are made in the studio under API keys: see Authentication.
curl "https://goblins-call-api.onrender.com/v1/me" \
-H "Authorization: Bearer $CRACKLE_API_KEY"Requests and responses
- Bodies are JSON. Send
Content-Type: application/jsonwith any request that has one. - Responses are JSON, with the result under a named key, such as
agent,callsorwebhook. - Times are ISO 8601 strings in UTC, such as
2026-10-11T05:56:12.000Z. Durations are in seconds and money is in US dollars. - IDs are strings with a prefix that says what they are:
ua_for an agent,tool_for a tool,wh_for a webhook subscription andusr_for a workspace. A call’s ID is a UUID.
Your workspace
A key acts in the one workspace it belongs to, so nothing needs to say which workspace a request is about. Things in other workspaces answer 404. In paths, a workspace is a user: /v1/users/:id is your workspace, not a person.
Paging
List calls returns a page at a time, newest first, with a nextCursor when there is more. Pass it back as before to get the next page. List voices pages the same way with nextPage and after. The other lists are short and come back whole.
Errors
A failed request answers with a 4xx or 5xx status and a body of { error, code, status }. Branch on code. The full list is in Errors, and the limits behind a 429 are in Rate limits and concurrency.
Endpoints
Agents
GET/v1/agentsList agentsPOST/v1/agentsCreate an agentGET/v1/agents/:idGet an agentPATCH/v1/agents/:idUpdate an agentDELETE/v1/agents/:idDelete an agentPOST/v1/agents/:id/rotate-keyRotate an agent’s keyPOST/v1/agents/:id/rotate-public-keyRotate the publishable keyCalls
POST/v1/callsStart a callGET/v1/callsList callsGET/v1/calls/:idGet a callPOST/v1/calls/:id/saySpeak into a callPOST/v1/calls/:id/endEnd a callTools
GET/v1/toolsList toolsPOST/v1/toolsCreate a toolGET/v1/tools/:idGet a toolPUT/v1/tools/:idUpdate a toolDELETE/v1/tools/:idDelete a toolPOST/v1/tools/:id/testTest a toolKnowledge
GET/v1/knowledge/documentsList documentsPOST/v1/knowledge/documentsAdd a documentGET/v1/knowledge/documents/:idGet a documentPOST/v1/knowledge/documents/:id/retryRead a document againDELETE/v1/knowledge/documents/:idDelete a documentPOST/v1/knowledge/searchSearch documentsWebhooks
GET/v1/webhooks/eventsList event typesGET/v1/webhooksList subscriptionsPOST/v1/webhooksCreate a subscriptionGET/v1/webhooks/:idGet a subscriptionPATCH/v1/webhooks/:idUpdate a subscriptionDELETE/v1/webhooks/:idDelete a subscriptionPOST/v1/webhooks/:id/testSend a test event