Skip to main content

​
Execute Code

Execute code in a sandboxed Docker container and wait for the result. 
POST /api/v1/execute

​
Headers

HeaderTypeRequiredDescription
X-API-KeystringYesYour Sandbox API key
Content-TypestringYesMust be application/json

​
Request Body

{
  "code": "print('Hello, World!')",
  "language": "python",
  "stdin": "optional input",
  "environment": {
    "MY_VAR": "value"
  },
  "timeout": 30,
  "session_id": "optional-session-id"
}

​
Parameters

ParameterTypeRequiredDescription
codestringYesThe code to execute
languagestringYesProgramming language (see supported languages)
stdinstringNoStandard input to provide to the program
environmentobjectNoEnvironment variables as key-value pairs
timeoutintegerNoExecution timeout in seconds (default: 30, max: 300)
session_idstringNoOptional session ID for tracking related executions

​
Response

{
  "execution_id": "550e8400-e29b-41d4-a716-446655440000",
  "stdout": "Hello, World!\n",
  "stderr": "",
  "exit_code": 0,
  "execution_time": 0.123,
  "language": "python",
  "session_id": null
}

​
Response Fields

FieldTypeDescription
execution_idstringUnique identifier for this execution
stdoutstringStandard output from the program
stderrstringStandard error output from the program
exit_codeintegerProcess exit code (0 = success)
execution_timefloatExecution time in seconds
languagestringThe language that was executed
session_idstring | nullSession ID if provided

​
Error Responses

​
400 Bad Request

{
  "detail": "Unsupported language: invalid. Supported languages: python, javascript, ..."
}
Returned when:
  • Invalid or unsupported language
  • Invalid code syntax
  • Invalid parameters

​
429 Too Many Requests

{
  "detail": "Rate limit exceeded. Please try again later."
}
Returned when rate limit for your API key is exceeded.

​
500 Internal Server Error

{
  "detail": "Execution failed: container timeout"
}
Returned when execution fails due to internal error or timeout.

​
Examples

​
Python

curl -X POST http://localhost:8002/api/v1/execute \
  -H "X-API-Key: your-api-key" \
  -H "Content-Type: application/json" \
  -d '{
    "code": "print(\"Hello, World!\")\nprint(2 + 2)",
    "language": "python"
  }'
Response: 
{
  "execution_id": "550e8400-e29b-41d4-a716-446655440000",
  "stdout": "Hello, World!\n4\n",
  "stderr": "",
  "exit_code": 0,
  "execution_time": 0.08,
  "language": "python",
  "session_id": null
}

​
JavaScript

curl -X POST http://localhost:8002/api/v1/execute \
  -H "X-API-Key: your-api-key" \
  -H "Content-Type: application/json" \
  -d '{
    "code": "console.log(\"Hello from Node.js\");",
    "language": "javascript"
  }'

​
With Standard Input

curl -X POST http://localhost:8002/api/v1/execute \
  -H "X-API-Key: your-api-key" \
  -H "Content-Type: application/json" \
  -d '{
    "code": "name = input(\"Enter your name: \")\nprint(f\"Hello, {name}!\")",
    "language": "python",
    "stdin": "Nadoo"
  }'
Response: 
{
  "execution_id": "550e8400-e29b-41d4-a716-446655440000",
  "stdout": "Enter your name: Hello, Nadoo!\n",
  "stderr": "",
  "exit_code": 0,
  "execution_time": 0.05,
  "language": "python",
  "session_id": null
}

​
With Environment Variables

curl -X POST http://localhost:8002/api/v1/execute \
  -H "X-API-Key: your-api-key" \
  -H "Content-Type: application/json" \
  -d '{
    "code": "import os\nprint(os.environ[\"API_URL\"])",
    "language": "python",
    "environment": {
      "API_URL": "https://api.example.com"
    }
  }'

​
With Custom Timeout

curl -X POST http://localhost:8002/api/v1/execute \
  -H "X-API-Key: your-api-key" \
  -H "Content-Type: application/json" \
  -d '{
    "code": "import time\ntime.sleep(5)\nprint(\"Done!\")",
    "language": "python",
    "timeout": 10
  }'

​
Resource Limits

All executions are subject to the following resource limits:
ResourceDefaultMaximum
CPU1 core2 cores
Memory512 MB2 GB
Timeout30 seconds300 seconds
Disk100 MB1 GB
See Resource Limits for more information.

​
Security

All code executions run in isolated Docker containers with:
  • No network access by default
  • Read-only filesystem except for temporary execution directory
  • Resource limits enforced by Docker
  • Automatic cleanup after execution
See Security for more information.

​
Rate Limiting

API requests are rate-limited by API key to prevent abuse. The default limit is 100 requests per minute. If you exceed the rate limit, you’ll receive a 429 Too Many Requests error. Wait before making additional requests.

​
Best Practices

  1. Set appropriate timeouts: Use shorter timeouts for simple operations to free up resources faster
  2. Handle errors gracefully: Check exit_code and stderr for execution errors
  3. Use session IDs: Group related executions with session_id for better tracking
  4. Clean up sessions: Call the session cleanup endpoint when done
  5. Monitor execution time: Track execution_time to optimize your code