Skip to main content

​
Base URL

https://api.stablebrowse.ai/v1
During private beta the API is served from https://cs847b7b23.execute-api.us-west-2.amazonaws.com/v1. A custom domain lands before GA.

​
Authentication

Every request includes a bearer token in the Authorization header: 
Authorization: Bearer sb_live_...
Keys are minted in the dashboard under Settings → API Keys. See Authentication for rotation and revocation.

​
Request + response

All bodies are JSON. Content-Type: application/json required on all POST/PUT/DELETE calls with bodies. Responses are always JSON unless noted.

​
Async model

Task submission is asynchronous. POST /v1/tasks returns immediately with a taskId and status: "pending". The task runs in the background (typically 5-60 seconds). Poll GET /v1/tasks/{taskId} until status reaches a terminal value (completed, failed). The Python and TypeScript SDKs’ tasks.run(...) method hides the polling loop. Use it unless you need to drive polling yourself.

​
Error shape

Errors come back with an HTTP status code and a JSON body: 
{
  "error": "Human-readable description of what went wrong"
}

​
Status codes

CodeWhenExample
200 OKGET / DELETE successFetching a task, revoking a key
201 CreatedPOST successSubmitting a task, minting a key
400 Bad RequestInvalid JSON or validation failureMissing endUserId, blank task, endUserId > 256 chars
401 UnauthorizedMissing auth header, or token is of the wrong kind for the routeAPI key presented to /v1/api-keys (JWT-only route)
403 ForbiddenValid token but denied accessRevoked API key, cross-business ownership violation
404 Not FoundResource doesn’t exist or you don’t own itUnknown taskId, unknown sessionId
405 Method Not AllowedWrong HTTP verb for the routePOST to a GET-only endpoint
429 Too Many RequestsRate limit or quota exceededSee the response body for specifics
500 Internal Server ErrorOur bugRare. Retry with exponential backoff.
Full codes: Errors.

​
Endpoint summary

Submit task

POST /v1/tasks

Get task

GET /v1/tasks/{taskId}

List tasks

GET /v1/tasks

Get session

GET /v1/sessions/{sessionId}

Set credentials

PUT /v1/end-users/{endUserId}/credentials

Get credentials

GET /v1/end-users/{endUserId}/credentials

Delete credentials

DELETE /v1/end-users/{endUserId}/credentials

Create API key

POST /v1/api-keys

List API keys

GET /v1/api-keys

Revoke API key

DELETE /v1/api-keys/{prefix}