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

# API Overview

> Everything you need to know before making your first Chowder API call.

## 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](/api-reference/organization/signup), which doesn't require auth).

```bash theme={"theme":{"light":"github-light","dark":"github-dark-dimmed"}}
Authorization: Bearer chd_org_abc123...
```

There are two key types:

| Prefix      | Type             | Access                                                                                        |
| ----------- | ---------------- | --------------------------------------------------------------------------------------------- |
| `chd_org_*` | Organization key | Full access to all endpoints and instances in your org.                                       |
| `chd_sk_*`  | Scoped key       | Restricted 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:

```json theme={"theme":{"light":"github-light","dark":"github-dark-dimmed"}}
{
  "detail": "Instance not found."
}
```

Some errors (like gateway proxy failures) return a nested object:

```json theme={"theme":{"light":"github-light","dark":"github-dark-dimmed"}}
{
  "detail": {
    "error": "Gateway unavailable – the sandbox may have been stopped or deleted. Try restarting the instance."
  }
}
```

## Status Codes

| Code  | Meaning                                                                                                          |
| ----- | ---------------------------------------------------------------------------------------------------------------- |
| `200` | Success. The response body contains the requested resource.                                                      |
| `201` | Created. A new resource was created and is returned in the body.                                                 |
| `204` | No Content. The request succeeded but there's nothing to return (e.g. delete).                                   |
| `400` | Bad Request. Something is wrong with your input — check the `detail` message.                                    |
| `401` | Unauthorized. Missing or invalid API key.                                                                        |
| `403` | Forbidden. Your key doesn't have permission for this action.                                                     |
| `404` | Not Found. The resource doesn't exist, or it belongs to a different org.                                         |
| `409` | Conflict. The resource is in a state that prevents this action (e.g. starting an already-running instance).      |
| `422` | Validation Error. The request body failed schema validation.                                                     |
| `500` | Internal Server Error. Something broke on our side — please reach out if it persists.                            |
| `502` | Bad 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](/api-reference/instances/status) to know when it's ready.

Possible instance statuses:

| Status         | Description                                                 |
| -------------- | ----------------------------------------------------------- |
| `provisioning` | The sandbox is being created and configured. Not ready yet. |
| `running`      | The instance is live and accepting messages.                |
| `stopped`      | The sandbox is hibernated. Start it to resume.              |
| `error`        | Provisioning failed. Check `error_message` on the instance. |
| `terminated`   | The instance was deleted. It won't appear in list results.  |