Skip to main content

HTTP API

Overview​

The HTTP API provides programmatic access to execute code in isolated Firecracker microVMs.

Quick Start​

Start the API server
infra.operator api --port 8080
Execute Python code
curl -X POST http://localhost:8080/api/v1/execute \
  -H "Content-Type: application/json" \
  -d '{"language": "python", "code": "print(1 + 1)"}'

Endpoints​

MethodEndpointDescription
GET/healthHealth check
GET/api/v1/languagesList supported languages
GET/api/v1/languages/:langGet language details
POST/api/v1/executeExecute code
GET/api/v1/rootfsList rootfs images
POST/api/v1/rootfsCreate rootfs
GET/api/v1/snapshotsList snapshots
POST/api/v1/snapshotsCreate snapshot

Execute Code​

The main endpoint for running code in isolated microVMs.

POST /api/v1/execute

Request​

FieldTypeRequiredDescription
languagestringYesProgramming language
codestringYesSource code to execute
timeoutintegerNoTimeout in seconds (default: 30)

Example​

Execute code request
curl -X POST http://localhost:8080/api/v1/execute \
  -H "Content-Type: application/json" \
  -d '{
    "language": "python",
    "code": "print(\"Hello World!\")",
    "timeout": 30
  }'
Response
{
  "stdout": "Hello World!\n",
  "stderr": "",
  "exit_code": 0,
  "load_time": "125ms",
  "exec_time": "45ms"
}

Language Examples​

Execute Python code via API
curl -X POST http://localhost:8080/api/v1/execute \
  -H "Content-Type: application/json" \
  -d '{"language": "python", "code": "print(sum(range(100)))"}'
Execute Node.js code via API
curl -X POST http://localhost:8080/api/v1/execute \
  -H "Content-Type: application/json" \
  -d '{"language": "nodejs", "code": "console.log(Array.from({length:10},(_,i)=>i*i))"}'
Execute Go code via API
curl -X POST http://localhost:8080/api/v1/execute \
  -H "Content-Type: application/json" \
  -d '{"language": "go", "code": "package main\nimport \"fmt\"\nfunc main() { fmt.Println(\"Hello Go!\") }"}'
Execute Rust code via API
curl -X POST http://localhost:8080/api/v1/execute \
  -H "Content-Type: application/json" \
  -d '{"language": "rust", "code": "fn main() { println!(\"Hello Rust!\"); }"}'

Health Check​

GET /health

Health check request
curl http://localhost:8080/health
Response
{
  "status": "healthy",
  "version": "1.0.0"
}

List Languages​

GET /api/v1/languages

List languages request
curl http://localhost:8080/api/v1/languages
Response
{
  "languages": [
    {"name": "python", "extension": ".py"},
    {"name": "nodejs", "extension": ".js"},
    {"name": "go", "extension": ".go"},
    {"name": "rust", "extension": ".rs"}
  ],
  "count": 45
}

List Rootfs​

GET /api/v1/rootfs

Query ParamDescription
remote=trueList from S3 instead of local
List local rootfs
curl http://localhost:8080/api/v1/rootfs
List S3 rootfs
curl "http://localhost:8080/api/v1/rootfs?remote=true"
Response
{
  "rootfs": [
    {"language": "python", "size": 1288490188, "path": "/srv/firecracker/images/rootfs-python.ext4"},
    {"language": "nodejs", "size": 845000000, "path": "/srv/firecracker/images/rootfs-nodejs.ext4"}
  ]
}

List Snapshots​

GET /api/v1/snapshots

Query ParamDescription
remote=trueList from S3 instead of local
List local snapshots
curl http://localhost:8080/api/v1/snapshots
Response
{
  "snapshots": [
    {"language": "python", "vmstate_size": 13516, "mem_size": 536870912},
    {"language": "nodejs", "vmstate_size": 14100, "mem_size": 536870912}
  ]
}

Create Rootfs​

POST /api/v1/rootfs

Create rootfs request
curl -X POST http://localhost:8080/api/v1/rootfs \
  -H "Content-Type: application/json" \
  -d '{"language": "python", "size_mb": 1024}'
Response (202 Accepted)
{
  "message": "rootfs creation started",
  "language": "python"
}

Create Snapshot​

POST /api/v1/snapshots

Create snapshot request
curl -X POST http://localhost:8080/api/v1/snapshots \
  -H "Content-Type: application/json" \
  -d '{"language": "python", "mem_mb": 512, "vcpus": 1}'
Response (202 Accepted)
{
  "message": "snapshot creation started",
  "language": "python"
}

Error Handling​

All errors return JSON with an error field:

Error response
{
  "error": "language not found: ruby2"
}
StatusDescription
200Success
202Accepted (async operation)
400Bad request
404Not found
500Server error

SDK Examples​

Python​

Python SDK
import requests

class RunnerClient:
    def __init__(self, url="http://localhost:8080"):
        self.url = url

    def execute(self, language, code, timeout=30):
        response = requests.post(
            f"{self.url}/api/v1/execute",
            json={"language": language, "code": code, "timeout": timeout}
        )
        return response.json()

# Usage
client = RunnerClient()
result = client.execute("python", "print(2 ** 10)")
print(result["stdout"])  # 1024

JavaScript​

JavaScript SDK
class RunnerClient {
  constructor(url = "http://localhost:8080") {
    this.url = url;
  }

  async execute(language, code, timeout = 30) {
    const res = await fetch(`${this.url}/api/v1/execute`, {
      method: "POST",
      headers: { "Content-Type": "application/json" },
      body: JSON.stringify({ language, code, timeout })
    });
    return res.json();
  }
}

// Usage
const client = new RunnerClient();
const result = await client.execute("nodejs", "console.log(2 ** 10)");
console.log(result.stdout); // 1024

Next Steps​