> ## Documentation Index
> Fetch the complete documentation index at: https://docs.runtools.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# API Overview

> Current public RunTools REST API surfaces

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](/sdk/overview) 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`.

```text theme={null}
https://api.runtools.ai/v1
```

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

```text theme={null}
https://tools.runtools.ai/v1
```

OAuth account connections:

```text theme={null}
https://auth.runtools.ai/v1
```

Workspace file APIs:

```text theme={null}
https://storage.runtools.ai/v1
```

Billing, credits, usage, and top-ups:

```text theme={null}
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:

```bash theme={null}
curl https://api.runtools.ai/v1/sandboxes \
  -H "X-API-Key: $RUNTOOLS_API_KEY"
```

Dashboard and CLI sessions use bearer tokens:

```bash theme={null}
curl https://api.runtools.ai/v1/me \
  -H "Authorization: Bearer $RUNTOOLS_ACCESS_TOKEN"
```

<Card title="Create an API key" icon="key" href="/api-reference/authentication">
  API keys are managed from the Credentials page or through the CLI.
</Card>

## Request Format

JSON endpoints expect:

```text theme={null}
Content-Type: application/json
Accept: application/json
```

```bash theme={null}
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:

```json theme={null}
{
  "data": {
    "id": "sandbox-abc123"
  },
  "meta": {
    "requestId": "req_xxx"
  }
}
```

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

### Errors

```json theme={null}
{
  "error": {
    "code": "not_found",
    "message": "Sandbox not found",
    "requestId": "req_xxx"
  }
}
```

## Pagination

List endpoints that page results return cursor metadata:

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

```json theme={null}
{
  "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

<CardGroup cols={2}>
  <Card title="Sandboxes" icon="server" href="/api-reference/sandboxes/create">
    Create sandboxes, execute commands, pause, resume, and destroy them.
  </Card>

  <Card title="Workspaces" icon="folder-tree" href="/api-reference/workspaces/manage">
    Manage persistent workspaces and file operations.
  </Card>

  <Card title="Agents" icon="robot" href="/api-reference/agents/run">
    Create agents and run one-shot or threaded agent tasks.
  </Card>

  <Card title="Threads" icon="book-open" href="/api-reference/threads">
    Read cloud thread history, subscribe to live frames, and publish local runtime events.
  </Card>

  <Card title="Models" icon="brain" href="/api-reference/models">
    List selectable Platform/BYOK models and use the platform model proxy.
  </Card>

  <Card title="RunMesh" icon="server" href="/api-reference/runmesh">
    Link local devices and manage private mesh nodes.
  </Card>

  <Card title="Activity" icon="clock-rotate-left" href="/api-reference/activity">
    Query customer-visible resource activity.
  </Card>

  <Card title="Billing" icon="credit-card" href="/api-reference/billing">
    Read credits, usage, top-ups, and customer-facing resource billing summaries.
  </Card>

  <Card title="Tools" icon="wrench" href="/api-reference/tools/list">
    Search Tool Hub, install tools, store credentials, and execute actions.
  </Card>
</CardGroup>

## SDK

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

```typescript theme={null}
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();
```