API overview

The CrowNest REST API gives you programmatic control over sandboxes, commands, 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

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

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

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

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

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:

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

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.

[!NOTE] Rate limits and quotas are configurable beta defaults. They depend on your plan and may change.

Reference sections

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

• Authentication — API keys and scopes
• Errors — error envelope and codes
• Pagination and idempotency
• Sandboxes
• Commands
• Files
• Artifacts
• Previews
• Projects and usage

Next steps

• Set up credentials in Authentication.
• Create your first sandbox in Sandboxes.