unsandbox.com

Execute code immediately and wait for results. Best for quick scripts and interactive use.

Request Parameters

Example (Zig)

const std = @import("std");

pub fn main() !void {
    var gpa = std.heap.GeneralPurposeAllocator(.{}){};
    defer _ = gpa.deinit();
    const allocator = gpa.allocator();

    var client = std.http.Client{ .allocator = allocator };
    defer client.deinit();

    const api_key = std.os.getenv("UNSANDBOX_API_KEY") orelse "unsb-sk-test0-vault-unlck-12345";
    const auth_header = try std.fmt.allocPrint(allocator, "Bearer {s}", .{api_key});
    defer allocator.free(auth_header);

    const uri = try std.Uri.parse("https://api.unsandbox.com/execute");
    const payload =
        \\{"language":"zig","code":"const std = @import(\"std\");\npub fn main() !void {\n    const stdout = std.io.getStdOut().writer();\n    try stdout.print(\"Hello from unsandbox!\\n\", .{});\n}"}
    ;

    var headers = std.http.Headers{ .allocator = allocator };
    defer headers.deinit();
    try headers.append("Content-Type", "application/json");
    try headers.append("Authorization", auth_header);

    var req = try client.request(.POST, uri, headers, .{});
    defer req.deinit();

    req.transfer_encoding = .{ .content_length = payload.len };
    try req.start();
    try req.writer().writeAll(payload);
    try req.finish();
    try req.wait();

    var body = std.ArrayList(u8).init(allocator);
    defer body.deinit();
    try req.reader().readAllArrayList(&body, 1024 * 1024);

    const parsed = try std.json.parseFromSlice(std.json.Value, allocator, body.items, .{});
    defer parsed.deinit();

    const result = parsed.value.object;
    if (result.get("success").?.bool) {
        std.debug.print("Output: {s}\n", .{result.get("stdout").?.string});
    } else {
        std.debug.print("Error: {s}\n", .{result.get("error").?.string});
    }
}

Response (Success)

{
  "success": true,
  "stdout": "Hello from unsandbox!\n",
  "stderr": "",
  "exit_code": 0,
  "language": "python",
  "job_id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
  "artifacts": [],
  "execution_mode": "pooled",
  "network_mode": "zerotrust",
  "total_time_ms": 523
}

Response (Error)

{
  "success": false,
  "stdout": "",
  "stderr": "SyntaxError: invalid syntax\n",
  "exit_code": 1,
  "language": "python",
  "job_id": "b2c3d4e5-f6a7-8901-bcde-f23456789012",
  "artifacts": [],
  "execution_mode": "pooled",
  "network_mode": "zerotrust",
  "total_time_ms": 312
}

Submit code for execution and receive a job ID to poll for results. Best for long-running scripts or when you need to decouple submission from execution.

Request Parameters

Example (Zig)

const std = @import("std");

pub fn main() !void {
    var gpa = std.heap.GeneralPurposeAllocator(.{}){};
    defer _ = gpa.deinit();
    const allocator = gpa.allocator();

    var client = std.http.Client{ .allocator = allocator };
    defer client.deinit();

    const api_key = std.os.getenv("UNSANDBOX_API_KEY") orelse "unsb-sk-test0-vault-unlck-12345";
    const auth_header = try std.fmt.allocPrint(allocator, "Bearer {s}", .{api_key});
    defer allocator.free(auth_header);

    // Submit job
    const uri = try std.Uri.parse("https://api.unsandbox.com/execute/async");
    const payload =
        \\{"language":"rust","code":"fn main() { println!(\"Computing...\"); }","ttl":300}
    ;

    var headers = std.http.Headers{ .allocator = allocator };
    defer headers.deinit();
    try headers.append("Content-Type", "application/json");
    try headers.append("Authorization", auth_header);

    var req = try client.request(.POST, uri, headers, .{});
    defer req.deinit();

    req.transfer_encoding = .{ .content_length = payload.len };
    try req.start();
    try req.writer().writeAll(payload);
    try req.finish();
    try req.wait();

    var body = std.ArrayList(u8).init(allocator);
    defer body.deinit();
    try req.reader().readAllArrayList(&body, 1024 * 1024);

    const job = try std.json.parseFromSlice(std.json.Value, allocator, body.items, .{});
    defer job.deinit();

    const job_id = job.value.object.get("job_id").?.string;
    std.debug.print("Job submitted: {s}\n", .{job_id});

    // Poll for results
    var status_url_buf: [256]u8 = undefined;
    const status_url = try std.fmt.bufPrint(&status_url_buf, "https://api.unsandbox.com/jobs/{s}", .{job_id});

    while (true) {
        const status_uri = try std.Uri.parse(status_url);

        var status_headers = std.http.Headers{ .allocator = allocator };
        defer status_headers.deinit();
        try status_headers.append("Authorization", auth_header);

        var status_req = try client.request(.GET, status_uri, status_headers, .{});
        defer status_req.deinit();

        try status_req.start();
        try status_req.finish();
        try status_req.wait();

        var status_body = std.ArrayList(u8).init(allocator);
        defer status_body.deinit();
        try status_req.reader().readAllArrayList(&status_body, 1024 * 1024);

        const status = try std.json.parseFromSlice(std.json.Value, allocator, status_body.items, .{});
        defer status.deinit();

        const state = status.value.object.get("status").?.string;

        if (std.mem.eql(u8, state, "completed")) {
            const result = status.value.object.get("result").?.object;
            if (result.get("success").?.bool) {
                std.debug.print("Output: {s}\n", .{result.get("stdout").?.string});
            } else {
                std.debug.print("Error: {s}\n", .{result.get("stderr").?.string});
            }
            break;
        } else if (std.mem.eql(u8, state, "timeout") or std.mem.eql(u8, state, "cancelled")) {
            std.debug.print("Job {s}\n", .{state});
            break;
        }

        std.time.sleep(1 * std.time.ns_per_s);
    }
}

Initial Response

{
  "job_id": "job_1234567890_abc",
  "status": "pending"
}

Check the status and results of an asynchronous job. Poll this endpoint after submitting a job via /execute/async or /run/async.

URL Parameters

Example (Zig)

const std = @import("std");

pub fn main() !void {
    var gpa = std.heap.GeneralPurposeAllocator(.{}){};
    defer _ = gpa.deinit();
    const allocator = gpa.allocator();

    var client = std.http.Client{ .allocator = allocator };
    defer client.deinit();

    const api_key = std.os.getenv("UNSANDBOX_API_KEY") orelse "unsb-sk-test0-vault-unlck-12345";
    const auth_header = try std.fmt.allocPrint(allocator, "Bearer {s}", .{api_key});
    defer allocator.free(auth_header);

    const job_id = "job_1234567890_abc";
    var url_buf: [256]u8 = undefined;
    const url = try std.fmt.bufPrint(&url_buf, "https://api.unsandbox.com/jobs/{s}", .{job_id});
    const uri = try std.Uri.parse(url);

    var headers = std.http.Headers{ .allocator = allocator };
    defer headers.deinit();
    try headers.append("Authorization", auth_header);

    var req = try client.request(.GET, uri, headers, .{});
    defer req.deinit();

    try req.start();
    try req.finish();
    try req.wait();

    var body = std.ArrayList(u8).init(allocator);
    defer body.deinit();
    try req.reader().readAllArrayList(&body, 1024 * 1024);

    const job = try std.json.parseFromSlice(std.json.Value, allocator, body.items, .{});
    defer job.deinit();

    const status = job.value.object.get("status").?.string;
    std.debug.print("Status: {s}\n", .{status});

    if (std.mem.eql(u8, status, "completed")) {
        const result = job.value.object.get("result").?.object;
        std.debug.print("Success: {}\n", .{result.get("success").?.bool});
        std.debug.print("Output: {s}\n", .{result.get("stdout").?.string});
    }
}

Response (Completed)

{
  "job_id": "c3d4e5f6-a7b8-9012-cdef-345678901234",
  "status": "completed",
  "created_at": 1699564800,
  "started_at": 1699564801,
  "completed_at": 1699564805,
  "result": {
    "success": true,
    "stdout": "Hello from unsandbox!\n",
    "stderr": "",
    "exit_code": 0,
    "language": "python",
    "artifacts": [],
    "execution_mode": "pooled",
    "network_mode": "zerotrust",
    "total_time_ms": 4021
  }
}

Possible Status Values

• pending - Job queued, waiting to execute
• running - Job currently executing
• completed - Job finished (check result field)
• timeout - Job exceeded TTL limit
• cancelled - Job was cancelled via DELETE

List all active (pending or running) jobs for your API key. Useful for monitoring multiple async executions.

Example (Zig)

const std = @import("std");

pub fn main() !void {
    var gpa = std.heap.GeneralPurposeAllocator(.{}){};
    defer _ = gpa.deinit();
    const allocator = gpa.allocator();

    var client = std.http.Client{ .allocator = allocator };
    defer client.deinit();

    const api_key = std.os.getenv("UNSANDBOX_API_KEY") orelse "unsb-sk-test0-vault-unlck-12345";
    const auth_header = try std.fmt.allocPrint(allocator, "Bearer {s}", .{api_key});
    defer allocator.free(auth_header);

    const uri = try std.Uri.parse("https://api.unsandbox.com/jobs");

    var headers = std.http.Headers{ .allocator = allocator };
    defer headers.deinit();
    try headers.append("Authorization", auth_header);

    var req = try client.request(.GET, uri, headers, .{});
    defer req.deinit();

    try req.start();
    try req.finish();
    try req.wait();

    var body = std.ArrayList(u8).init(allocator);
    defer body.deinit();
    try req.reader().readAllArrayList(&body, 1024 * 1024);

    const jobs = try std.json.parseFromSlice(std.json.Value, allocator, body.items, .{});
    defer jobs.deinit();

    for (jobs.value.array.items) |job| {
        const job_obj = job.object;
        std.debug.print("{s}: {s} ({s})\n", .{
            job_obj.get("job_id").?.string,
            job_obj.get("status").?.string,
            job_obj.get("language").?.string,
        });
    }
}

Response

{
  "jobs": [
    {
      "job_id": "job_1234567890_abc",
      "status": "running",
      "language": "python",
      "submitted_at": "2024-01-15T10:30:00Z"
    },
    {
      "job_id": "job_0987654321_xyz",
      "status": "pending",
      "language": "go",
      "submitted_at": "2024-01-15T10:29:45Z"
    }
  ]
}

Cancel a pending or running job. If the job is already executing, it will be terminated and partial output returned.

URL Parameters

Example (Zig)

const std = @import("std");

pub fn main() !void {
    var gpa = std.heap.GeneralPurposeAllocator(.{}){};
    defer _ = gpa.deinit();
    const allocator = gpa.allocator();

    var client = std.http.Client{ .allocator = allocator };
    defer client.deinit();

    const api_key = std.os.getenv("UNSANDBOX_API_KEY") orelse "unsb-sk-test0-vault-unlck-12345";
    const auth_header = try std.fmt.allocPrint(allocator, "Bearer {s}", .{api_key});
    defer allocator.free(auth_header);

    const job_id = "job_1234567890_abc";
    var url_buf: [256]u8 = undefined;
    const url = try std.fmt.bufPrint(&url_buf, "https://api.unsandbox.com/jobs/{s}", .{job_id});
    const uri = try std.Uri.parse(url);

    var headers = std.http.Headers{ .allocator = allocator };
    defer headers.deinit();
    try headers.append("Authorization", auth_header);

    var req = try client.request(.DELETE, uri, headers, .{});
    defer req.deinit();

    try req.start();
    try req.finish();
    try req.wait();

    var body = std.ArrayList(u8).init(allocator);
    defer body.deinit();
    try req.reader().readAllArrayList(&body, 1024 * 1024);

    const result = try std.json.parseFromSlice(std.json.Value, allocator, body.items, .{});
    defer result.deinit();

    std.debug.print("Cancelled: {s}\n", .{result.value.object.get("message").?.string});
    if (result.value.object.get("result")) |partial| {
        std.debug.print("Partial output: {s}\n", .{partial.object.get("stdout").?.string});
    }
}

Response

{
  "message": "Job cancelled",
  "job_id": "e5f6a7b8-c9d0-1234-efgh-567890123456",
  "result": {
    "success": false,
    "stdout": "Partial output before cancel...",
    "stderr": "",
    "exit_code": -1,
    "language": "python",
    "artifacts": [],
    "execution_mode": "pooled",
    "network_mode": "zerotrust",
    "total_time_ms": 1523
  }
}

Execute code with automatic language detection via shebang. Send raw code as the request body with Content-Type: text/plain.

Request

• Content-Type: text/plain
• Body: Raw code with shebang (e.g., #!/usr/bin/env python3)

Query Parameters

Example (Zig)

const std = @import("std");

pub fn main() !void {
    var gpa = std.heap.GeneralPurposeAllocator(.{}){};
    defer _ = gpa.deinit();
    const allocator = gpa.allocator();

    var client = std.http.Client{ .allocator = allocator };
    defer client.deinit();

    const api_key = std.os.getenv("UNSANDBOX_API_KEY") orelse "unsb-sk-test0-vault-unlck-12345";
    const auth_header = try std.fmt.allocPrint(allocator, "Bearer {s}", .{api_key});
    defer allocator.free(auth_header);

    const uri = try std.Uri.parse("https://api.unsandbox.com/run");
    const code =
        \\#!/usr/bin/env python3
        \\print("Language auto-detected!")
    ;

    var headers = std.http.Headers{ .allocator = allocator };
    defer headers.deinit();
    try headers.append("Content-Type", "text/plain");
    try headers.append("Authorization", auth_header);

    var req = try client.request(.POST, uri, headers, .{});
    defer req.deinit();

    req.transfer_encoding = .{ .content_length = code.len };
    try req.start();
    try req.writer().writeAll(code);
    try req.finish();
    try req.wait();

    var body = std.ArrayList(u8).init(allocator);
    defer body.deinit();
    try req.reader().readAllArrayList(&body, 1024 * 1024);

    const result = try std.json.parseFromSlice(std.json.Value, allocator, body.items, .{});
    defer result.deinit();

    std.debug.print("Detected: {s}\n", .{result.value.object.get("detected_language").?.string});
    std.debug.print("Output: {s}\n", .{result.value.object.get("stdout").?.string});
}

Response

{
  "success": true,
  "stdout": "Language auto-detected!\n",
  "stderr": "",
  "exit_code": 0,
  "language": "python",
  "detected_language": "python",
  "job_id": "f6a7b8c9-d0e1-2345-fghi-678901234567",
  "artifacts": [],
  "execution_mode": "pooled",
  "network_mode": "zerotrust",
  "total_time_ms": 412
}

Submit code with automatic language detection and receive a job ID. Combines the convenience of /run with the flexibility of async execution.

Request

• Content-Type: text/plain
• Body: Raw code with shebang (e.g., #!/usr/bin/env ruby)

Query Parameters

Example (Zig)

const std = @import("std");

pub fn main() !void {
    var gpa = std.heap.GeneralPurposeAllocator(.{}){};
    defer _ = gpa.deinit();
    const allocator = gpa.allocator();

    var client = std.http.Client{ .allocator = allocator };
    defer client.deinit();

    const api_key = std.os.getenv("UNSANDBOX_API_KEY") orelse "unsb-sk-test0-vault-unlck-12345";
    const auth_header = try std.fmt.allocPrint(allocator, "Bearer {s}", .{api_key});
    defer allocator.free(auth_header);

    // Submit job
    const uri = try std.Uri.parse("https://api.unsandbox.com/run/async");
    const code =
        \\#!/usr/bin/env ruby
        \\puts "Running async with auto-detect!"
    ;

    var headers = std.http.Headers{ .allocator = allocator };
    defer headers.deinit();
    try headers.append("Content-Type", "text/plain");
    try headers.append("Authorization", auth_header);

    var req = try client.request(.POST, uri, headers, .{});
    defer req.deinit();

    req.transfer_encoding = .{ .content_length = code.len };
    try req.start();
    try req.writer().writeAll(code);
    try req.finish();
    try req.wait();

    var body = std.ArrayList(u8).init(allocator);
    defer body.deinit();
    try req.reader().readAllArrayList(&body, 1024 * 1024);

    const job = try std.json.parseFromSlice(std.json.Value, allocator, body.items, .{});
    defer job.deinit();

    const job_id = job.value.object.get("job_id").?.string;
    std.debug.print("Job submitted: {s}\n", .{job_id});

    // Poll for results
    var status_url_buf: [256]u8 = undefined;
    const status_url = try std.fmt.bufPrint(&status_url_buf, "https://api.unsandbox.com/jobs/{s}", .{job_id});

    while (true) {
        const status_uri = try std.Uri.parse(status_url);

        var status_headers = std.http.Headers{ .allocator = allocator };
        defer status_headers.deinit();
        try status_headers.append("Authorization", auth_header);

        var status_req = try client.request(.GET, status_uri, status_headers, .{});
        defer status_req.deinit();

        try status_req.start();
        try status_req.finish();
        try status_req.wait();

        var status_body = std.ArrayList(u8).init(allocator);
        defer status_body.deinit();
        try status_req.reader().readAllArrayList(&status_body, 1024 * 1024);

        const status = try std.json.parseFromSlice(std.json.Value, allocator, status_body.items, .{});
        defer status.deinit();

        const state = status.value.object.get("status").?.string;

        if (std.mem.eql(u8, state, "completed")) {
            const result = status.value.object.get("result").?.object;
            std.debug.print("Detected: {s}\n", .{result.get("detected_language").?.string});
            if (result.get("success").?.bool) {
                std.debug.print("Output: {s}\n", .{result.get("stdout").?.string});
            }
            break;
        } else if (std.mem.eql(u8, state, "timeout") or std.mem.eql(u8, state, "cancelled")) {
            std.debug.print("Job {s}\n", .{state});
            break;
        }

        std.time.sleep(1 * std.time.ns_per_s);
    }
}

Initial Response

{
  "job_id": "job_1234567890_abc",
  "status": "pending"
}

Job Result (via GET /jobs/{id})

{
  "job_id": "a7b8c9d0-e1f2-3456-ghij-789012345678",
  "status": "completed",
  "created_at": 1699564800,
  "started_at": 1699564801,
  "completed_at": 1699564802,
  "result": {
    "success": true,
    "stdout": "Running async with auto-detect!\n",
    "stderr": "",
    "exit_code": 0,
    "language": "ruby",
    "detected_language": "ruby",
    "artifacts": [],
    "execution_mode": "pooled",
    "network_mode": "zerotrust",
    "total_time_ms": 1234
  }
}

Upload files to your sandbox execution. Files are written to the working directory and can be accessed directly by filename.

File Object Schema

Example Request

{
  "language": "python",
  "code": "print(open('data.csv').read())",
  "input_files": [
    {
      "filename": "data.csv",
      "content": "bmFtZSxhZ2UKQWxpY2UsMzAKQm9iLDI1"
    }
  ]
}

Limits

• Maximum files: 10 files per execution
• Maximum total size: 10MB (decoded)
• Maximum single file: 5MB (decoded)
• Filename length: 256 characters max

File Access

Files are placed in the working directory. Access them directly:

• Python: open('data.csv')
• Node.js: fs.readFileSync('data.csv')
• Ruby: File.read('data.csv')
• Go: os.ReadFile("data.csv")

Security

• Files are isolated per execution
• Filenames cannot contain path separators (no / or ..)
• Files are deleted after execution completes