# REST API

The SDKs wrap a plain JSON API. Use it from any language, or from curl.

## Base URL

```text Base URL
https://api.kestrel.dev/v1
```

## Authentication

Send your [API key](/api-key) as a bearer token on every request.

```bash Terminal
curl https://api.kestrel.dev/v1/runs \
  -H "Authorization: Bearer $KESTREL_API_KEY"
```

## Errors

Errors use HTTP status codes and a JSON body with a `type` and a message written for a person.

```json JSON
{
  "error": {
    "type": "forbidden",
    "message": "This key can't see acme/billing. Give it access in Settings → API keys."
  }
}
```

| Status | `type` |
|---|---|
| 400 | `invalid_request` |
| 401 | `auth` |
| 403 | `forbidden` |
| 404 | `not_found` |
| 409 | `conflict`, for example killing a sandbox twice |
| 429 | `rate_limited` |
| 5xx | `server` |

## Pagination

List endpoints return 20 items by default, up to 100 with `limit`. Pass the `next` cursor from a response to get the page after it.

```json JSON
{ "data": [ ... ], "next": "cur_7Hc2" }
```

## Endpoints

- [Runs](/api/runs): create, read, list, cancel, trace.
- [Sandboxes](/api/sandboxes): create, run commands, files, pause, resume, kill.