API Overview - Runtools.ai

The REST API is the platform underneath the SDK, CLI, and dashboard — anything they do, you can do with an HTTP request. In practice, reach for the SDK first: it handles the base URLs, auth headers, and response envelopes below for you. Drop to raw REST when you need a language the SDK doesn’t cover, or full control over the wire.

API Bases

RunTools exposes a few public API bases. The SDK routes calls for you, so most applications only need RUNTOOLS_API_KEY.

https://api.runtools.ai/v1

Tool Hub, custom tools, installed tool credentials, and secrets:

https://tools.runtools.ai/v1

OAuth account connections:

https://auth.runtools.ai/v1

Workspace file APIs:

https://storage.runtools.ai/v1

Billing, credits, usage, and top-ups:

https://billing.runtools.ai/v1

The TypeScript SDK routes calls to the correct API base when you use rt.sandbox, rt.agent, rt.tools, rt.secrets, rt.auth, or rt.billing.

Authentication

API keys use the X-API-Key header:

curl https://api.runtools.ai/v1/sandboxes \
  -H "X-API-Key: $RUNTOOLS_API_KEY"

Dashboard and CLI sessions use bearer tokens:

curl https://api.runtools.ai/v1/me \
  -H "Authorization: Bearer $RUNTOOLS_ACCESS_TOKEN"

Create an API key

API keys are managed from the Credentials page or through the CLI.

Request Format

JSON endpoints expect:

Content-Type: application/json
Accept: application/json

curl -X POST https://api.runtools.ai/v1/sandboxes \
  -H "X-API-Key: $RUNTOOLS_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "template": "base-ubuntu",
    "name": "build-runner"
  }'

Response Format

Most APIs return a JSON envelope:

{
  "data": {
    "id": "sandbox-abc123"
  },
  "meta": {
    "requestId": "req_xxx"
  }
}

Some execution endpoints return raw engine payloads for compatibility. The SDK normalizes the common cases.

Errors

{
  "error": {
    "code": "not_found",
    "message": "Sandbox not found",
    "requestId": "req_xxx"
  }
}

Pagination

List endpoints that page results return cursor metadata:

curl "https://api.runtools.ai/v1/sandboxes?limit=50&cursor=abc" \
  -H "X-API-Key: $RUNTOOLS_API_KEY"

{
  "data": [],
  "meta": {
    "hasMore": false,
    "nextCursor": null
  }
}

The SDK exposes both high-level collection methods and page-aware methods where pagination matters. For sandboxes, use rt.sandbox.list() for all pages or rt.sandbox.listPage() when you need the cursor.

Core Resources

Sandboxes

Create sandboxes, execute commands, pause, resume, and destroy them.

Workspaces

Manage persistent workspaces and file operations.

Agents

Create agents and run one-shot or threaded agent tasks.

Threads

Read cloud thread history, subscribe to live frames, and publish local runtime events.

Models

List selectable Platform/BYOK models and use the platform model proxy.

RunMesh

Link local devices and manage private mesh nodes.

Activity

Query customer-visible resource activity.

Billing

Read credits, usage, top-ups, and customer-facing resource billing summaries.

Tools

Search Tool Hub, install tools, store credentials, and execute actions.

SDK

Use the SDK when you can. It handles service URLs, authentication headers, response envelopes, and common validation.

import { RunTools } from '@runtools-ai/sdk';

const rt = new RunTools({ apiKey: process.env.RUNTOOLS_API_KEY });

const sandbox = await rt.sandbox.create({
  template: 'base-ubuntu',
  name: 'docs-runner',
});

await sandbox.waitForReady();
const result = await sandbox.exec('node --version');
console.log(result.stdout);
await sandbox.destroy();

​API Bases

​Authentication