Skip to main content

​
Base URL

All API requests go to: 
https://api.chowder.dev/v1
Every path in this reference is relative to that base.

​
Authentication

Chowder uses Bearer token authentication. Include your API key in the Authorization header on every request (except Signup, which doesn’t require auth). 
Authorization: Bearer chd_org_abc123...
There are two key types:
PrefixTypeAccess
chd_org_*Organization keyFull access to all endpoints and instances in your org.
chd_sk_*Scoped keyRestricted to specific instances with granular permissions (read, interact, configure).
You get an org key when you sign up. Scoped keys are created separately and are useful for giving external apps limited access to individual instances.

​
Content Type

All request and response bodies are JSON. Set the header: 
Content-Type: application/json

​
Error Format

When something goes wrong, the API returns a JSON body with a detail field: 
{
  "detail": "Instance not found."
}
Some errors (like gateway proxy failures) return a nested object: 
{
  "detail": {
    "error": "Gateway unavailable – the sandbox may have been stopped or deleted. Try restarting the instance."
  }
}

​
Status Codes

CodeMeaning
200Success. The response body contains the requested resource.
201Created. A new resource was created and is returned in the body.
204No Content. The request succeeded but there’s nothing to return (e.g. delete).
400Bad Request. Something is wrong with your input — check the detail message.
401Unauthorized. Missing or invalid API key.
403Forbidden. Your key doesn’t have permission for this action.
404Not Found. The resource doesn’t exist, or it belongs to a different org.
409Conflict. The resource is in a state that prevents this action (e.g. starting an already-running instance).
422Validation Error. The request body failed schema validation.
500Internal Server Error. Something broke on our side — please reach out if it persists.
502Bad Gateway. The instance’s sandbox or gateway is unreachable. Usually means the sandbox was stopped or deleted.

​
Rate Limits

There are no rate limits currently enforced. Be reasonable — we reserve the right to introduce limits in the future if needed.

​
Instance Lifecycle

When you create an instance, it goes through a provisioning phase (~90 seconds) where a cloud sandbox is spun up and configured. You can poll the status endpoint to know when it’s ready. Possible instance statuses:
StatusDescription
provisioningThe sandbox is being created and configured. Not ready yet.
runningThe instance is live and accepting messages.
stoppedThe sandbox is hibernated. Start it to resume.
errorProvisioning failed. Check error_message on the instance.
terminatedThe instance was deleted. It won’t appear in list results.