Skip to main content

Documentation Index

Fetch the complete documentation index at: https://docs.nonhumans.ai/llms.txt

Use this file to discover all available pages before exploring further.

The Compute API gives your agent an always-on execution environment. Run code in isolated sandboxes, spin up headless browser sessions for web automation, and persist files across runs on a dedicated filesystem — all without managing infrastructure. Every execution is scoped to your agent and billed per millisecond of active compute.

​
POST /v1/compute/run

Execute code in a sandboxed environment. The sandbox is ephemeral — it starts fresh for each request — but can read from and write to your agent’s persistent filesystem via /v1/compute/fs. 
curl -X POST https://api.nonhumans.ai/v1/compute/run \
  -H "Authorization: Bearer $NONHUMANS_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "language": "python",
    "code": "import math\nresult = math.factorial(10)\nprint(f\"10! = {result}\")",
    "timeout": 30
  }'
​
code
string
required
The source code to execute. Multiline strings are supported.
​
language
string
required
Execution runtime. One of python, typescript, or bash.
​
timeout
integer
Maximum execution time in seconds. Defaults to 30. Maximum 300 (5 minutes). Executions that exceed the timeout are terminated and return a non-zero exit_code.
Example response: 
{
  "stdout": "10! = 3628800\n",
  "stderr": "",
  "exit_code": 0,
  "duration_ms": 142
}
​
stdout
string
Standard output captured during execution.
​
stderr
string
Standard error output. Non-empty stderr does not necessarily mean failure — check exit_code.
​
exit_code
integer
Process exit code. 0 indicates success; any other value indicates an error.
​
duration_ms
integer
Wall-clock execution time in milliseconds.
Use the bash language to chain multiple tools, invoke Python and TypeScript scripts together, or run shell commands like curl, jq, or ffmpeg — all available in the sandbox by default.

​
POST /v1/compute/browser/sessions

Open a new headless Chromium browser session. Returns a WebSocket URL you can use to control the browser via the Chrome DevTools Protocol (CDP) or Playwright. 
curl -X POST https://api.nonhumans.ai/v1/compute/browser/sessions \
  -H "Authorization: Bearer $NONHUMANS_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "url": "https://example.com"
  }'
​
url
string
Optional starting URL. The browser navigates to this page immediately after the session is created. If omitted, the browser opens a blank tab.
Example response: 
{
  "session_id": "bsn_01HXYZ001",
  "ws_url": "wss://compute.nonhumans.ai/browser/bsn_01HXYZ001",
  "expires_at": "2024-12-01T18:00:00Z"
}
​
session_id
string
Unique identifier for the browser session.
​
ws_url
string
WebSocket endpoint for CDP control. Connect using Playwright, Puppeteer, or any CDP-compatible client.
​
expires_at
string (ISO 8601)
Sessions automatically terminate after 60 minutes of inactivity to avoid runaway billing.
Example — connecting with Playwright: 
import { chromium } from "playwright";

const session = await fetch("https://api.nonhumans.ai/v1/compute/browser/sessions", {
  method: "POST",
  headers: { Authorization: `Bearer ${process.env.NONHUMANS_KEY}` },
}).then((r) => r.json());

const browser = await chromium.connectOverCDP(session.ws_url);
const page = await browser.newPage();
await page.goto("https://example.com");
const title = await page.title();
console.log("Page title:", title);
await browser.close();

​
GET /v1/compute/browser/sessions//screenshot

Capture a PNG screenshot of the current state of a browser session. Useful for visual verification and debugging. 
curl "https://api.nonhumans.ai/v1/compute/browser/sessions/bsn_01HXYZ001/screenshot" \
  -H "Authorization: Bearer $NONHUMANS_KEY"
​
id
string
required
The browser session ID returned when the session was created.
Example response: 
{
  "image": "iVBORw0KGgoAAAANSUhEUgAAA...",
  "width": 1280,
  "height": 800,
  "captured_at": "2024-12-01T17:45:00Z"
}
​
image
string
Base64-encoded PNG image of the browser viewport.
​
width
integer
Viewport width in pixels.
​
height
integer
Viewport height in pixels.

​
GET /v1/compute/fs

List files and directories in your agent’s persistent filesystem. The filesystem persists across compute runs and browser sessions, making it ideal for storing intermediate results, downloaded files, and agent state. 
curl "https://api.nonhumans.ai/v1/compute/fs?path=/reports" \
  -H "Authorization: Bearer $NONHUMANS_KEY"
​
path
string
Directory path to list. Defaults to / (the root of the agent’s filesystem).
Example response: 
{
  "path": "/reports",
  "entries": [
    {
      "name": "q4-analysis.csv",
      "type": "file",
      "size_bytes": 48920,
      "modified_at": "2024-12-01T14:00:00Z"
    },
    {
      "name": "charts",
      "type": "directory",
      "modified_at": "2024-12-01T13:00:00Z"
    }
  ]
}

​
PUT /v1/compute/fs

Write a file to your agent’s persistent filesystem. Creates the file if it doesn’t exist; overwrites it if it does. Intermediate directories are created automatically. 
curl -X PUT https://api.nonhumans.ai/v1/compute/fs \
  -H "Authorization: Bearer $NONHUMANS_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "path": "/reports/summary.txt",
    "content": "UmVwb3J0IHN1bW1hcnkgY29udGVudC4="
  }'
​
path
string
required
Absolute path where the file should be written (e.g. /reports/summary.txt).
​
content
string
required
Base64-encoded file content. Maximum file size is 100 MB per write.
Example response: 
{
  "path": "/reports/summary.txt",
  "size_bytes": 24,
  "written_at": "2024-12-01T17:50:00Z"
}
Files written to the persistent filesystem are accessible from subsequent POST /v1/compute/run executions at the same path. Use this to share data between tasks without making network calls.