Docs / Reference / SDK & API
Reference

SDK & API reference

Two zero-dependency SDKs and a small REST surface. The SDKs are thin wrappers over the HTTP API: anything you can do in Python or TypeScript, you can do with curl.

Authentication

Send your key as a bearer token on every request. Keys come in tiers:

col_live_…
Standard key for exec, batch, and sessions.
col_scale_…
Admin / scale key. Additionally manages templates (create & delete).
Rate limit
100 requests/second per key (429 when exceeded).
Base URL
https://api.collimate.ai (hosted) or your dedicated BYOC endpoint.
http
Authorization: Bearer col_live_...

Python SDK

bash
pip install collimate
python
from collimate import Sandbox

sb = Sandbox(api_key, base_url="https://api.collimate.ai")

# run(code, template_id, timeout=30) -> Result
r = sb.run("print(1 + 1)", "python", timeout=30)

# run_batch(codes, template_id, timeout=30) -> list[Result]
rs = sb.run_batch(["print(1)", "print(2)"], "python")

Result fields: id, stdout, stderr, exit_code, fork_time_ms, exec_time_ms, total_time_ms.

TypeScript SDK

bash
npm install @collimate/sdk
typescript
import { Sandbox } from "@collimate/sdk";

const sb = new Sandbox(apiKey, "https://api.collimate.ai");

// run(code, templateId, options?) -> Promise<Result>
const r = await sb.run("console.log(1 + 1)", "node", { timeout: 30 });

// runBatch(codes, templateId, options?) -> Promise<Result[]>
const rs = await sb.runBatch(["console.log(1)", "console.log(2)"], "node");

REST API

MethodPathDescription
POST/v1/execRun code in one throwaway VM.
POST/v1/exec/batchRun many snippets in parallel VMs.
POST/v1/sessionsOpen a stateful session (held-alive VM).
POST/v1/sessions/{id}/execRun a step in a session; state persists.
POST/v1/sessions/{id}/forkBranch a live session (mid-trajectory fork).
GET / DELETE/v1/sessions/{id}Status, or destroy (?force=true).
POST / GET / DELETE/v1/templatesRegister, list, inspect, evict templates (admin).
GET/v1/healthTemplate readiness.
GET/v1/metricsPrometheus-format metrics.

POST /v1/exec

http
POST /v1/exec
{ "code": "print(1 + 1)", "template_id": "python", "timeout_seconds": 30 }

200 OK
{
  "id": "019cf684-1fd5-73c0-9299-52253f9aa79c",
  "stdout": "2\n",
  "stderr": "",
  "exit_code": 0,
  "fork_time_ms": 0.75,
  "exec_time_ms": 7.2,
  "total_time_ms": 8.0
}
  • code string, required: code to run.
  • template_id string, required: the template to spawn from.
  • timeout_seconds int, optional: default 30.

POST /v1/exec/batch

http
POST /v1/exec/batch
{ "executions": [
    { "code": "print(1)", "template_id": "python" },
    { "code": "console.log(2)", "template_id": "node" }
] }

200 OK
{ "results": [ { "stdout": "1\n", "exit_code": 0, ... }, { ... } ] }

Sessions

http
POST /v1/sessions                    { "template_id": "my-env" }
  -> 201 { "session_id": "sess_...", "fork_time_ms": 1.3, "create_time_ms": 64.2 }

POST /v1/sessions/{id}/exec          { "commands": [["python","-m","pytest","-x"]] }
POST /v1/sessions/{id}/exec          { "files": [{ "path": "/app/x.py", "content": "..." }] }
POST /v1/sessions/{id}/fork          -> 201 { "session_id": "sess_child...", "fork_time_ms": 6.8 }
GET  /v1/sessions/{id}               -> { "age_secs": ..., "idle_secs": ..., "exec_count": ... }
DELETE /v1/sessions/{id}?force=true  -> 204

Templates admin

http
POST   /v1/templates?id=my-env&mem_mib=512   -> 202 { "id": "my-env", "status": "building" }
GET    /v1/templates/my-env                  -> 200 { "id": "my-env", "status": "ready" }
GET    /v1/templates                         -> 200 { "templates": { ... } }
DELETE /v1/templates/my-env                  -> 204

GET /v1/health

http
GET /v1/health
200 OK
{ "status": "ok", "templates": { "python": { "ready": true }, "node": { "ready": true } } }

Status codes

401
Missing or invalid key.
403
Key lacks the tier for this action (e.g. template admin).
404 / 410
Unknown session/template · session VM gone.
409
Template not ready, or duplicate template id.
429
Rate limit or session capacity exceeded.
503 / 504
VM spawn/restore failed · environment bring-up timed out.
__ICO_code__

Both SDKs use only their language's standard library, with no transitive dependencies to audit.

Related

__ICO_quickstart__
Quickstart

Five steps to your first VM.

Start →
__ICO_session__
Stateful sessions

The full session lifecycle, explained.

Read →