Skip to main content
The Code Interpreter API enables execution of code in multiple programming languages using Jupyter kernels. It supports stateful execution contexts, allowing variables and state to persist across multiple code executions within the same session.

​
Create Code Context

Creating a context is optional. If you don’t provide a context when executing code, the system will use stateless execution.
curl -X POST http://localhost:44772/code/context \
  -H "X-EXECD-ACCESS-TOKEN: your-token" \
  -H "Content-Type: application/json" \
  -d '{
    "language": "python"
  }'
Creates a new code execution environment and returns a session ID for subsequent code executions. The context maintains state across multiple code runs within the same session.
​
language
string
required
Execution runtime (python, bash, java, etc.)
​
id
string
Unique session identifier for the created context
​
language
string
Execution runtime
{
  "id": "session-abc123",
  "language": "python"
}

​
Execute Code

curl -X POST http://localhost:44772/code \
  -H "X-EXECD-ACCESS-TOKEN: your-token" \
  -H "Content-Type: application/json" \
  -d '{
    "context": {
      "id": "session-123",
      "language": "python"
    },
    "code": "print(\"Hello, World!\")\nresult = 2 + 2\nresult"
  }'
Executes code using Jupyter kernel in a specified execution context and streams the output in real-time using SSE (Server-Sent Events). Supports multiple programming languages and maintains execution state within the session.
​
code
string
required
Source code to execute
​
context
object
Execution context (optional for stateless execution)
​
type
string
Event type: init, status, stdout, stderr, result, execution_complete, execution_count, error, ping
​
text
string
Textual data for status, init, and stream events
​
execution_count
integer
Cell execution number in the session (Jupyter-style)
​
execution_time
integer
Execution duration in milliseconds
​
timestamp
integer
When the event was generated (Unix milliseconds)
​
results
object
Execution output in various MIME types (e.g., “text/plain”, “text/html”, “image/png”)
​
error
object
Execution error details if an error occurred
data: {"type":"init","text":"Initializing execution","timestamp":1700000000000}

data: {"type":"stdout","text":"Hello, World!\n","timestamp":1700000000100}

data: {"type":"result","results":{"text/plain":"4"},"timestamp":1700000000200}

data: {"type":"execution_complete","execution_time":150,"execution_count":1,"timestamp":1700000000250}

​
List Code Contexts

curl -X GET "http://localhost:44772/code/contexts?language=python" \
  -H "X-EXECD-ACCESS-TOKEN: your-token"
Lists all active/available code execution contexts. If language is provided, only contexts under that language/runtime are returned.
​
language
string
required
Filter contexts by execution runtime (python, bash, java, etc.)
​
contexts
array
Array of active contexts
[
  {
    "id": "session-abc123",
    "language": "python"
  },
  {
    "id": "session-def456",
    "language": "python"
  }
]

​
Get Code Context

curl -X GET http://localhost:44772/code/contexts/session-abc123 \
  -H "X-EXECD-ACCESS-TOKEN: your-token"
Retrieves the details of an existing code execution context (session) by ID. Returns the context ID, language, and any associated metadata.
​
context_id
string
required
Session/context ID to retrieve
​
id
string
Unique session identifier
​
language
string
Execution runtime
{
  "id": "session-abc123",
  "language": "python"
}

​
Delete Code Context

curl -X DELETE http://localhost:44772/code/contexts/session-abc123 \
  -H "X-EXECD-ACCESS-TOKEN: your-token"
Deletes an existing code execution context (session) by ID. This terminates the underlying context thread/process and releases resources.
​
context_id
string
required
Session/context ID to delete
{}

​
Delete All Contexts by Language

curl -X DELETE "http://localhost:44772/code/contexts?language=python" \
  -H "X-EXECD-ACCESS-TOKEN: your-token"
Deletes all existing code execution contexts under the specified language/runtime. This is a bulk operation intended for code-interpreter context cleanup.
​
language
string
required
Target execution runtime whose contexts should be deleted
{}

​
Interrupt Code Execution

curl -X DELETE "http://localhost:44772/code?id=session-123" \
  -H "X-EXECD-ACCESS-TOKEN: your-token"
Interrupts the currently running code execution in the specified context. This sends a signal to terminate the execution process and releases associated resources.
​
id
string
required
Session ID of the execution context to interrupt
{}

​
Stateful vs Stateless Execution

​
Stateful Execution

When you provide a context with an ID, variables and state persist across executions: 
# First execution
{
  "context": {"id": "session-123", "language": "python"},
  "code": "x = 10"
}

# Second execution - x is still available
{
  "context": {"id": "session-123", "language": "python"},
  "code": "print(x + 5)"  # Output: 15
}

​
Stateless Execution

When you omit the context or don’t provide an ID, each execution is independent: 
# Stateless execution
{
  "code": "echo 'Hello from shell'"
}

​
Supported Languages

The Code Interpreter supports any language with a Jupyter kernel installed:
  • Python - IPython kernel
  • JavaScript - Node.js kernel
  • Bash - Bash kernel
  • Java - IJava kernel
  • R - IRkernel
  • And many more…
The available languages depend on the kernels installed in your sandbox environment.

Build docs developers (and LLMs) love

Get started for freeTalk to us