> ## Documentation Index
> Fetch the complete documentation index at: https://docs.stablebrowse.com/llms.txt
> Use this file to discover all available pages before exploring further.

# API reference

> Base URL, auth, error conventions.

## Base URL

```
https://api.stablebrowse.ai/v1
```

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

## Authentication

Every request includes a bearer token in the `Authorization` header:

```http theme={null}
Authorization: Bearer sb_live_...
```

Keys are minted in the [dashboard](https://main.d30scu9fjpgpae.amplifyapp.com) under **Settings → API Keys**. See [Authentication](/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:

```json theme={null}
{
  "error": "Human-readable description of what went wrong"
}
```

## Status codes

| Code                        | When                                        | Example                                                    |
| --------------------------- | ------------------------------------------- | ---------------------------------------------------------- |
| `200 OK`                    | GET / DELETE success                        | Fetching a task, clearing credentials                      |
| `201 Created`               | POST success                                | Submitting a task                                          |
| `400 Bad Request`           | Invalid JSON or validation failure          | Missing `endUserId`, blank `task`, `endUserId > 256 chars` |
| `401 Unauthorized`          | Missing or malformed `Authorization` header | Header omitted entirely                                    |
| `403 Forbidden`             | Valid token but denied access               | Revoked API key, cross-business ownership violation        |
| `404 Not Found`             | Resource doesn't exist or you don't own it  | Unknown `taskId`, unknown `sessionId`                      |
| `405 Method Not Allowed`    | Wrong HTTP verb for the route               | POST to a GET-only endpoint                                |
| `429 Too Many Requests`     | Rate limit or quota exceeded                | See the response body for specifics                        |
| `500 Internal Server Error` | Our bug                                     | Rare. Retry with exponential backoff.                      |

Full codes: [Errors](/errors).

## Endpoint summary

<CardGroup cols={2}>
  <Card title="Submit task" icon="paper-plane" href="/api-reference/tasks/submit">
    `POST /v1/tasks`
  </Card>

  <Card title="Get task" icon="magnifying-glass" href="/api-reference/tasks/get">
    `GET /v1/tasks/{taskId}`
  </Card>

  <Card title="List tasks" icon="list" href="/api-reference/tasks/list">
    `GET /v1/tasks`
  </Card>

  <Card title="Get session" icon="comments" href="/api-reference/sessions/get">
    `GET /v1/sessions/{sessionId}`
  </Card>

  <Card title="Set credentials" icon="upload" href="/api-reference/end-users/set-credentials">
    `PUT /v1/end-users/{endUserId}/credentials`
  </Card>

  <Card title="Get credentials" icon="eye" href="/api-reference/end-users/get-credentials">
    `GET /v1/end-users/{endUserId}/credentials`
  </Card>

  <Card title="Delete credentials" icon="trash" href="/api-reference/end-users/delete-credentials">
    `DELETE /v1/end-users/{endUserId}/credentials`
  </Card>
</CardGroup>