Your First API Call#

This guide takes you from API key to a working code execution in under 5 minutes.

Prerequisites#

1. Make your first call (sync)#

The simplest pattern: submit code and wait for the result in a single request.

curl -s -X POST "https://api.rustbox.sh/api/submit?wait=true" \
  -H "Content-Type: application/json" \
  -H "X-API-Key: rb_live_your_key_here" \
  -d '{"language": "python", "code": "print(2 + 2)"}' | jq

Replace rb_live_your_key_here with your actual API key. Request access to get one.

Response:

{
  "id": "f2c6c5f7-1203-46e5-8a4f-a619c12bfeb0",
  "schema_version": "2.0",
  "language": "python",
  "profile": "judge",
  "status": "completed",
  "timestamps": {
    "created_at": "2026-04-03T08:05:23.540110+00:00",
    "started_at": "2026-04-03T08:05:23.540218+00:00",
    "completed_at": "2026-04-03T08:05:23.570195+00:00"
  },
  "result": {
    "verdict": "AC",
    "cause": "normal_exit",
    "actor": "runtime",
    "exit_code": 0,
    "signal": null,
    "error_message": null
  },
  "output": {
    "stdout": "42\n",
    "stderr": "",
    "integrity": "complete"
  },
  "metrics": {
    "cpu_time_secs": 0.009142,
    "wall_time_secs": 0.01,
    "memory_peak_bytes": 3862528,
    "cpu_wall_ratio": 0.9,
    "divergence": "cpu_bound"
  },
  "evidence": {
    "isolation": {
      "mode": "strict",
      "controls_applied": ["pid_namespace", "mount_namespace", "network_namespace", "memory_limit", "process_limit", "no_new_privileges"],
      "controls_missing": [],
      "proc_policy": "hardened",
      "sys_policy": "builtin-deny",
      "pidfd_mode": "native",
      "reason": "All configured controls applied"
    },
    "limits": {
      "rlimits": {
        "cpu_secs": { "soft": 4, "hard": 4 },
        "as_bytes": { "soft": 1073741824, "hard": 1073741824 },
        "nofile": { "soft": 32, "hard": 32 },
        "nproc": { "soft": 10, "hard": 10 }
      },
      "cgroup_backend": "cgroup_v2",
      "cgroup": {
        "memory_limit_bytes": 268435456,
        "memory_peak_bytes": 3862528,
        "oom_events": 0,
        "oom_kill_events": 0,
        "cpu_usage_usec": 9142,
        "process_count": 0,
        "process_limit": 10
      }
    },
    "teardown": {
      "reap_status": "clean",
      "descendant_containment": "ok",
      "zombie_count": 0,
      "cleanup_verified": true,
      "residual_mounts": [],
      "collection_errors": []
    }
  }
}

result.verdict: "AC" means the code ran successfully with a clean exit.

2. Async pattern (submit, then poll)#

For batch workloads or when you do not want to hold a connection open.

sequenceDiagram
    autonumber
    participant Client
    participant Rustbox as Rustbox API
    participant Worker

    Client->>Rustbox: POST /api/submit {language, code}
    Rustbox-->>Client: 202 {id, status: "pending"}
    Rustbox->>Worker: enqueue(id)
    Worker->>Worker: sandbox · execute · evidence
    loop until completed
        Client->>Rustbox: GET /api/result/{id}
        Rustbox-->>Client: {status, result?, output?, evidence?}
    end

Submit:

curl -s -X POST "https://api.rustbox.sh/api/submit" \
  -H "Content-Type: application/json" \
  -H "X-API-Key: rb_live_your_key_here" \
  -d '{"language": "python", "code": "print(42)"}' | jq

{
  "id": "550e8400-e29b-41d4-a716-446655440000",
  "status": "pending",
  "queue_depth": 0
}

Poll:

curl -s "https://api.rustbox.sh/api/result/550e8400-e29b-41d4-a716-446655440000" \
  -H "X-API-Key: rb_live_your_key_here" | jq

Poll until status is completed or error.

3. Passing stdin#

Many use cases require feeding input to the executed code. Use the stdin field:

curl -s -X POST "https://api.rustbox.sh/api/submit?wait=true" \
  -H "Content-Type: application/json" \
  -H "X-API-Key: rb_live_your_key_here" \
  -d '{
    "language": "python",
    "code": "name = input()\nprint(f\"Hello, {name}!\")",
    "stdin": "World"
  }' | jq

{
  "id": "b1c2d3e4-5f6a-7b8c-9d0e-f1a2b3c4d5e6",
  "schema_version": "2.0",
  "language": "python",
  "profile": "judge",
  "status": "completed",
  "timestamps": {
    "created_at": "2026-04-03T08:06:11.120000+00:00",
    "started_at": "2026-04-03T08:06:11.121000+00:00",
    "completed_at": "2026-04-03T08:06:11.146000+00:00"
  },
  "result": {
    "verdict": "AC",
    "cause": "normal_exit",
    "actor": "runtime",
    "exit_code": 0,
    "signal": null,
    "error_message": null
  },
  "output": {
    "stdout": "Hello, World!\n",
    "stderr": "",
    "integrity": "complete"
  },
  "metrics": {
    "cpu_time_secs": 0.013,
    "wall_time_secs": 0.025,
    "memory_peak_bytes": 3200000,
    "cpu_wall_ratio": 0.52,
    "divergence": "cpu_bound"
  }
}

4. Webhooks (fire and forget)#

For high-throughput workloads, add a webhook endpoint to your project in the dashboard. Every execution submitted with an API key scoped to that project will deliver its result to active project webhooks.

curl -s -X POST "https://api.rustbox.sh/api/submit" \
  -H "Content-Type: application/json" \
  -H "X-API-Key: rb_live_your_project_key_here" \
  -d '{"language": "python", "code": "print(42)"}' | jq

The result is delivered to your URL with HMAC-SHA256 signature headers following the Standard Webhooks spec. See the Webhooks reference for verification details.

5. Handling errors#

Not all code runs cleanly. Here is what a runtime error looks like:

curl -s -X POST "https://api.rustbox.sh/api/submit?wait=true" \
  -H "Content-Type: application/json" \
  -H "X-API-Key: rb_live_your_key_here" \
  -d '{"language": "python", "code": "raise RuntimeError(\"something broke\")"}' | jq

{
  "id": "64374887-a809-4542-9c85-4002d2ebf3fa",
  "schema_version": "2.0",
  "language": "python",
  "profile": "judge",
  "status": "completed",
  "timestamps": {
    "created_at": "2026-04-03T08:07:02.300000+00:00",
    "started_at": "2026-04-03T08:07:02.301000+00:00",
    "completed_at": "2026-04-03T08:07:02.311000+00:00"
  },
  "result": {
    "verdict": "RE",
    "cause": "re_nonzero_exit",
    "actor": "runtime",
    "exit_code": 1,
    "signal": null,
    "error_message": null
  },
  "output": {
    "stdout": "",
    "stderr": "Traceback (most recent call last):\n  File \"/tmp/rustbox-uid-0/60000/workdir/solution.py\", line 1, in <module>\n    raise ValueError(\"boom\")\nValueError: boom\n",
    "integrity": "complete"
  },
  "metrics": {
    "cpu_time_secs": 0.009511,
    "wall_time_secs": 0.01,
    "memory_peak_bytes": 3858432,
    "cpu_wall_ratio": 0.95,
    "divergence": "cpu_bound"
  },
  "evidence": {
    "isolation": {
      "mode": "strict",
      "controls_applied": ["pid_namespace", "mount_namespace", "network_namespace", "memory_limit", "process_limit", "no_new_privileges"],
      "controls_missing": []
    }
  }
}

result.verdict: "RE" (Runtime Error) means the process exited with a non-zero code. The output.stderr field contains the traceback. The result.exit_code tells you exactly what the process returned.

6. Try another language#

All 8 languages work the same way. Just change the language field:

curl -s -X POST "https://api.rustbox.sh/api/submit?wait=true" \
  -H "Content-Type: application/json" \
  -H "X-API-Key: rb_live_your_key_here" \
  -d '{"language": "javascript", "code": "console.log(\"Hello from JS\")"}' | jq

curl -s -X POST "https://api.rustbox.sh/api/submit?wait=true" \
  -H "Content-Type: application/json" \
  -H "X-API-Key: rb_live_your_key_here" \
  -d '{"language": "c", "code": "#include <stdio.h>\nint main() { printf(\"Hello from C\\n\"); return 0; }"}' | jq

curl -s -X POST "https://api.rustbox.sh/api/submit?wait=true" \
  -H "Content-Type: application/json" \
  -H "X-API-Key: rb_live_your_key_here" \
  -d '{"language": "go", "code": "package main\nimport \"fmt\"\nfunc main() { fmt.Println(\"Hello from Go\") }"}' | jq

Next steps#