Pagination and idempotency

List endpoints page through results with an opaque cursor, and create-style POST endpoints accept an Idempotency-Key header so retries can never duplicate work. Both behave the same way everywhere they appear.

Pagination

All list endpoints use cursor-based pagination and return results sorted by createdAt descending (newest first).

Request parameters:

Response shape:

{
  "data": [],
  "hasMore": true,
  "nextCursor": "eyJjcmVhdGVkQXQiOiAi..."
}

• data — the page of results.
• hasMore — whether more results exist.
• nextCursor — pass as ?cursor= to fetch the next page. Omitted on the last page.

To walk a full collection, repeat the request with cursor=nextCursor until hasMore is false:

curl "https://api.crownest.dev/v1/sandboxes?limit=100&cursor=eyJjcmVhdGVkQXQiOiAi..." \
  -H "Authorization: Bearer $CROWNEST_API_KEY"

Cursors are opaque. Don't construct or modify them.

Idempotency

Network failures leave you unsure whether a POST landed. The Idempotency-Key header makes retries safe: send the same key with the same request, and the API guarantees the operation runs at most once.

curl -X POST https://api.crownest.dev/v1/sandboxes \
  -H "Authorization: Bearer $CROWNEST_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: 0f6b2c1e-create-sandbox-01" \
  -d '{"template": "python"}'

Choose any unique string per logical operation — a UUID works well. The CrowNest SDKs generate keys automatically.

Scope and retention

A key is scoped to the combination of organization, credential, HTTP method, route, and key value. The same key value on a different endpoint or from a different API key is a different idempotency record. Records are retained for 24 hours; after that, the same key behaves like a new request.

Replay and conflict behavior

What happens on a repeated key depends on the state of the original request:

• Same key, same request, original completed — the API replays the original response without re-running the operation.
• Same key, original still in progress — 409 with code idempotency_request_in_progress. Wait and retry.
• Same key, different request body — 409 with code idempotency_key_reused. Pick a new key for the new operation.

Endpoints that accept Idempotency-Key

The header is honored on POST endpoints that create resources or start work:

• POST /v1/sandboxes — create a sandbox
• POST /v1/sandboxes/{sandboxId}/commands/run — run a command
• POST /v1/sandboxes/{sandboxId}/commands/start — start a command
• POST /v1/sandboxes/{sandboxId}/artifacts — create an artifact

Delete and cancel endpoints don't need the header: they're idempotent by state, so repeating them returns the already-deleted or already-canceled resource.

Next steps

• Apply these patterns in Sandboxes and Commands.
• Review retry guidance in Errors.