API Overview

View as Markdown

Use the BCTRL REST API to create isolated spaces, launch browser runtimes, connect external automation tools, run hosted AI invocations, and inspect everything that happened during a run.

Mental model

BCTRL is organized around five core resources:

  • Spaces are task and permission boundaries. Runtimes, tools, storage, vault access, and AI credentials live inside a space.
  • Runtimes are live execution targets. A browser runtime is the stable runtime type today.
  • Connections let external tools control a live runtime, for example through CDP.
  • Invocations ask BCTRL-hosted agents to do work inside a runtime.
  • Runs are durable execution records. Events, commands, artifacts, live view, and recordings belong to runs.
Runtime = control
Run = observability

Use runtime routes to create, stop, connect to, invoke, and move files through a live runtime. Use run routes to inspect events, commands, artifacts, live view, and recordings.

Common flow

  1. Create a space.
  2. Create a browser runtime in that space.
  3. Create a CDP connection or start a hosted invocation.
  4. Use the runtime’s activeRunId to inspect the active run.
  5. Read run events, commands, and artifacts.

Authentication

All REST endpoints are authenticated with your BCTRL API key using a Bearer token.

1const response = await fetch("https://api.bctrl.ai/v1/spaces", {
2  method: "POST",
3  headers: {
4    Authorization: `Bearer ${process.env.BCTRL_API_KEY}`,
5    "Content-Type": "application/json",
6  },
7  body: JSON.stringify({ name: "my-space", region: "us-east" }),
8});
$curl -X POST "https://api.bctrl.ai/v1/spaces" \
>  -H "Authorization: Bearer ${BCTRL_API_KEY}" \
>  -H "Content-Type: application/json" \
>  -d '{"name":"my-space","region":"us-east"}'

Route groups

Spaces

Create and manage task boundaries.

Use spaces when you need a place to mount storage, vault secrets, AI credentials, tools, profiles, and runtimes.

Runtimes

Create, inspect, and stop live runtimes.

Browser runtimes are the primary runtime surface today. Runtime responses include activeRunId when a run is active.

Connections

Create, list, and revoke live runtime connections.

Use connections when you want Playwright, Puppeteer, Selenium, a debugger, or another CDP-compatible tool to connect to a BCTRL browser runtime.

Invocations

Create and manage hosted AI work.

Use invocations when BCTRL should run Stagehand or browser-use style agent work inside a runtime.

Runs

Inspect what happened.

Runs contain machine-readable events, platform command records, artifacts, live viewer leases, and recording viewer leases.

Artifacts

Fetch durable outputs from runs.

Artifacts point to files such as downloads, screenshots, recordings, PDFs, and collected runtime files.

Runtime Files

Move files between storage and a live runtime.

Use staging to place a storage file inside the runtime. Use collection to copy a runtime-local file back into storage and optionally register it as an artifact.

Space Storage

Manage durable files scoped to a space.

Use storage for files that should be reusable across invocations, runtimes, and runs.

Tools and Toolsets

Define reusable capabilities for hosted invocations.

Tools describe callable capabilities. Toolsets group tools and built-ins for an invocation.

Tool Calls

Inspect tool execution records.

Tool calls show sanitized execution status and timing for tool tests and invocation-time tools.

Configuration resources

Browser profiles, browser extensions, proxies, AI connections, and vault secrets configure how runtimes and invocations behave.

Admin resources

Subaccounts, budgets, and API keys manage account access and usage.