Code

Code APIs execute interpreter-style snippets inside a live Sandbox. They do not create Command 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

Provider context IDs are private and never appear in API responses.

Create a code context

POST /v1/sandboxes/{sandboxId}/code/contexts - requires scope code:run. Requires an Idempotency-Key header.

Creates an explicit interpreter context in a live sandbox.

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:

{
  "context": {
    "id": "cctx_abc123",
    "sandboxId": "sbx_abc123",
    "language": "python",
    "cwd": "/workspace",
    "createdAt": "2026-06-12T07:00:00.000Z"
  }
}

List code contexts

GET /v1/sandboxes/{sandboxId}/code/contexts - requires scope code:run.

Returns active Code Contexts for the sandbox:

{
  "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 /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

POST /v1/sandboxes/{sandboxId}/code/runs - requires scope code:run, plus artifact:create when artifactPolicy is promote. Requires an Idempotency-Key header.

Runs code and waits for the interpreter result. Code Runs are not durable resources in v1.

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.

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": { ... } }:

{
  "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:

{
  "run": {
    "sandboxId": "sbx_abc123",
    "contextId": "cctx_abc123",
    "language": "python",
    "executionCount": 2,
    "stdout": [],
    "stderr": [],
    "outputs": [],
    "error": {
      "name": "ZeroDivisionError",
      "message": "division by zero"
    }
  }
}

Stream code run events

POST /v1/sandboxes/{sandboxId}/code/runs/stream - requires the same scopes, body fields, and idempotency behavior as Run code.

The response is server-sent events (SSE):

content-type: text/event-stream; charset=utf-8
cache-control: no-store

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: <type>. Its JSON data is the full CodeRunEvent object:

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":[]}}

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.

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.