# Code (/docs/api/code) Code APIs execute interpreter-style snippets inside a live [Sandbox](/docs/api/sandboxes). They do not create [Command](/docs/api/commands) records. Use Commands when you need a top-level process invocation; use Code for notebook-style execution, rich outputs, and streamed interpreter events. Supported languages are `python`, `javascript`, and `typescript`. REST requests must include `language`; SDK and CLI helpers default to `python`. ## The Code Context object [#the-code-context-object] | Field | Type | Description | | ----------- | ------- | ------------------------------------------------ | | `id` | string | Code Context ID, prefixed `cctx_` | | `sandboxId` | string | Sandbox the context belongs to, prefixed `sbx_` | | `language` | string | `python`, `javascript`, or `typescript` | | `cwd` | string | Working directory inside the sandbox | | `isDefault` | boolean | Whether CrowNest created it as a default context | | `createdAt` | string | ISO 8601 creation timestamp | | `expiresAt` | string | Optional expiry timestamp | Provider context IDs are private and never appear in API responses. ## Create a code context [#create-a-code-context] `POST /v1/sandboxes/{sandboxId}/code/contexts` - requires scope `code:run`. Requires an [`Idempotency-Key`](/docs/api/pagination-and-idempotency) header. Creates an explicit interpreter context in a live sandbox. | Field | Type | Required | Default | Constraints | | ----------- | ------- | -------- | ------------ | --------------------------------------- | | `language` | string | Yes | - | `python`, `javascript`, or `typescript` | | `cwd` | string | No | `/workspace` | Must resolve inside the workspace | | `timeoutMs` | integer | No | 30000 | Max 600000 | ```bash title="Terminal" curl -X POST https://api.crownest.dev/v1/sandboxes/sbx_abc123/code/contexts \ -H "Authorization: Bearer $CROWNEST_API_KEY" \ -H "Content-Type: application/json" \ -H "Idempotency-Key: 9d2e4f1b-code-context-01" \ -d '{ "language": "python", "cwd": "/workspace" }' ``` Returns `201` with the context: ```json { "context": { "id": "cctx_abc123", "sandboxId": "sbx_abc123", "language": "python", "cwd": "/workspace", "createdAt": "2026-06-12T07:00:00.000Z" } } ``` ## List code contexts [#list-code-contexts] `GET /v1/sandboxes/{sandboxId}/code/contexts` - requires scope `code:run`. Returns active Code Contexts for the sandbox: ```json { "data": [ { "id": "cctx_abc123", "sandboxId": "sbx_abc123", "language": "python", "cwd": "/workspace", "createdAt": "2026-06-12T07:00:00.000Z" } ], "hasMore": false } ``` ## Get a code context [#get-a-code-context] `GET /v1/sandboxes/{sandboxId}/code/contexts/{contextId}` - requires scope `code:run`. Returns `{ "context": { ... } }` for an active Code Context. Unknown, deleted, foreign-org, and wrong-sandbox contexts all return `not_found`. ## Run code [#run-code] `POST /v1/sandboxes/{sandboxId}/code/runs` - requires scope `code:run`, plus `artifact:create` when `artifactPolicy` is `promote`. Requires an [`Idempotency-Key`](/docs/api/pagination-and-idempotency) header. Runs code and waits for the interpreter result. Code Runs are not durable resources in v1. | Field | Type | Required | Default | Constraints | | ---------------- | ------- | -------- | ------------- | --------------------------------------- | | `code` | string | Yes | - | Non-empty; max 256 KB | | `language` | string | Yes | - | `python`, `javascript`, or `typescript` | | `contextId` | string | No | - | Must start with `cctx_` | | `cwd` | string | No | `/workspace` | Must match the context when provided | | `timeoutMs` | integer | No | 60000 | Max 600000 | | `artifactPolicy` | string | No | `inline_only` | `inline_only` or `promote` | When you omit `contextId`, CrowNest lazily creates or reuses one default Code Context per sandbox and language. The response returns the real `contextId`, which you can delete later. ```bash title="Terminal" curl -X POST https://api.crownest.dev/v1/sandboxes/sbx_abc123/code/runs \ -H "Authorization: Bearer $CROWNEST_API_KEY" \ -H "Content-Type: application/json" \ -H "Idempotency-Key: 9d2e4f1b-code-run-01" \ -d '{ "code": "print(\"hello\")", "language": "python", "artifactPolicy": "inline_only" }' ``` Returns `200` with `{ "run": { ... } }`: ```json { "run": { "sandboxId": "sbx_abc123", "contextId": "cctx_abc123", "language": "python", "executionCount": 1, "stdout": "hello\n", "stderr": "", "outputs": [ { "kind": "inline", "format": "text", "value": "hello\n" } ], "durationMs": 43 } } ``` Execution errors and timeouts are not transport errors. The HTTP request succeeds with `200`, and the result includes `run.error`: ```json { "run": { "sandboxId": "sbx_abc123", "contextId": "cctx_abc123", "language": "python", "executionCount": 2, "stdout": "", "stderr": "", "outputs": [], "error": { "name": "ZeroDivisionError", "message": "division by zero" } } } ``` `timeoutMs` bounds CrowNest's response, but the current Cloudflare provider cannot guarantee that a timed-out kernel execution stops immediately. Delete the Code Context, or destroy the Sandbox, when hard termination is required. ## Stream code run events [#stream-code-run-events] `POST /v1/sandboxes/{sandboxId}/code/runs/stream` - requires the same scopes, body fields, and idempotency behavior as [Run code](#run-code). The response is server-sent events (SSE): ```http content-type: text/event-stream; charset=utf-8 cache-control: no-store ``` ```bash title="Terminal" curl -N -X POST https://api.crownest.dev/v1/sandboxes/sbx_abc123/code/runs/stream \ -H "Authorization: Bearer $CROWNEST_API_KEY" \ -H "Content-Type: application/json" \ -H "Idempotency-Key: 9d2e4f1b-code-run-stream-01" \ -d '{ "code": "print(\"hello\")", "language": "python" }' ``` Each SSE frame uses `event: `. Its JSON `data` is the full `CodeRunEvent` object: ```text event: stdout data: {"type":"stdout","data":"hello\n"} event: complete data: {"type":"complete","data":{"sandboxId":"sbx_abc123","contextId":"cctx_abc123","language":"python","executionCount":1,"stdout":"hello\n","stderr":"","outputs":[]}} ``` | Event | `data` payload | | ---------- | ---------------------------- | | `stdout` | String stdout chunk | | `stderr` | String stderr chunk | | `output` | `CodeOutput` object | | `error` | `CodeExecutionError` object | | `complete` | Final `RunCodeResult` object | Execution errors may arrive as a live `error` event and are also preserved on the final `complete.data.error` result. Platform or transport errors after the SSE stream has opened are emitted as `error` events with the public error code in `data.name`. Stream replay is result-only in v1. Reusing the same completed `Idempotency-Key` emits a single `complete` event with the stored `RunCodeResult`; stdout, stderr, and output history are not replayed as separate frames. Code streams do not assign SSE event IDs or support `Last-Event-ID` resume in v1. If the client disconnects before `complete`, CrowNest cancels the provider iterator and marks the abandoned idempotency record failed so a retry with the same key is not stuck behind `idempotency_request_in_progress`. As with a timeout, disconnecting does not guarantee immediate kernel termination; delete the Code Context or Sandbox for a hard stop. ## Delete a code context [#delete-a-code-context] `DELETE /v1/sandboxes/{sandboxId}/code/contexts/{contextId}` - requires scope `code:run`. Deletes a live Code Context by public `cctx_` ID. Provider deletion is best-effort; CrowNest metadata is authoritative.