# API overview (/docs/api/overview)



The CrowNest REST API gives you programmatic control over sandboxes,
commands, Workspace Runs, code runs, files, artifacts, previews, and usage.
Every SDK and the CLI is built on this API, so anything they can do, you can
do with plain HTTP.

## Base URL and versioning [#base-url-and-versioning]

All requests go to a single base URL, and every route is versioned under
`/v1`:

```text
https://api.crownest.dev/v1
```

Breaking changes ship under a new version prefix. Additive changes, such as
new optional fields or new endpoints, can appear within `/v1` without
notice, so write clients that ignore unknown fields.

## Content type [#content-type]

The API speaks JSON. Send request bodies as `application/json` and expect
JSON responses, including for errors. A typical request looks like this:

```bash title="Terminal"
curl https://api.crownest.dev/v1/sandboxes \
  -H "Authorization: Bearer $CROWNEST_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"template": "python-node"}'
```

## Resource model [#resource-model]

CrowNest organizes resources under an organization. An organization owns
projects, and most resources belong to both. Each resource ID carries a
prefix that identifies its type:

| Prefix  | Resource                                             |
| ------- | ---------------------------------------------------- |
| `org_`  | Organization                                         |
| `prj_`  | Project                                              |
| `key_`  | API key                                              |
| `sbx_`  | Sandbox — isolated live execution environment        |
| `cmd_`  | Command — top-level process invocation record        |
| `cctx_` | Code Context — language-specific interpreter state   |
| `art_`  | Artifact — durable, indexed output in object storage |
| `prv_`  | Preview — authenticated exposed HTTP service         |
| `tpl_`  | Template — user-facing environment slug              |
| `tplv_` | TemplateVersion — immutable resolved environment     |
| `wsr_`  | Workspace Run — one command against an archive       |
| `upl_`  | Upload — staged archive transfer target              |

IDs are opaque strings. Don't parse anything after the prefix.

## Rate limits [#rate-limits]

Each API key can make 120 requests per 60-second window. When you exceed
the limit, the API responds with HTTP 429 and the error code
`rate_limited`. Back off and retry after a short delay.

<Callout type="info" title="Note">
  Rate limits and quotas vary by plan tier and are subject to change.
</Callout>

## Reference sections [#reference-sections]

The reference is organized by resource. Cross-cutting behavior such as
authentication, error handling, pagination, and idempotency has its own
pages:

* [Authentication](/docs/api/authentication) — API keys and scopes
* [Errors](/docs/api/errors) — error envelope and codes
* [Pagination and idempotency](/docs/api/pagination-and-idempotency)
* [Sandboxes](/docs/api/sandboxes)
* [Commands](/docs/api/commands)
* [Workspace Runs](/docs/api/workspace-runs)
* [Code](/docs/api/code)
* [Files](/docs/api/files)
* [Artifacts](/docs/api/artifacts)
* [Previews](/docs/api/previews)
* [Projects and usage](/docs/api/projects-and-usage)
* [Capability matrix](/docs/api/capabilities)

## Next steps [#next-steps]

* Set up credentials in [Authentication](/docs/api/authentication).
* Create your first sandbox in [Sandboxes](/docs/api/sandboxes).