API Overview

View as Markdown

Use the BCTRL REST API to create workspaces, launch browser runtimes, manage durable browser resources, and run automation or AI workflows from your own backend or services.

Core workflows

Workspaces and Runtimes

Create a workspace, launch a browser runtime, execute steps, and stop the runtime when finished.

Browser Profiles and Extensions

Manage durable browser profiles and reusable browser extensions for profile-backed launches.

Operations and Updates

Track long-running agent work, wait on operation state, and subscribe to organization updates.

Storage, Vault, and Artifacts

Upload workspace files, retrieve secrets safely at runtime, and inspect artifacts produced by execution.

Supporting APIs

AI Credentials

Store reusable provider keys or use platform-managed credentials for agent workloads.

Runtime Events

Read or wait on low-level browser runtime events such as console, network, and page lifecycle activity.

OpenAPI Reference

Use the generated API reference for full request and response schemas.

Authentication

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

1const response = await fetch("https://api.bctrl.ai/v1/workspaces", {
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-workspace" }),
8});
$curl -X POST "https://api.bctrl.ai/v1/workspaces" \
>  -H "Authorization: Bearer ${BCTRL_API_KEY}" \
>  -H "Content-Type: application/json" \
>  -d '{"name":"my-workspace"}'

Workspaces and Runtimes

Workspaces are the task boundary in BCTRL. Inside a workspace, you create one or more runtimes and target them with execute, state, help, events, embeds, and operations.

Typical flow:

  1. Create a workspace.
  2. Launch a browser runtime, either ephemerally or from a saved browser profile.
  3. Execute structured browser steps or AI agent calls against that runtime.
  4. Inspect runtime state, events, operations, and artifacts.
  5. Stop the runtime when finished.

Browser Profiles and Extensions

Browser profiles are durable browser identities and launch configuration. Browser extensions are reusable browser-only resources that profiles or ephemeral launches can reference.

Operations and Updates

Long-running agent calls create durable operations. Use the operations API to fetch current state or wait for completion, and use the updates stream for coarse-grained lifecycle notifications across your organization.

Storage, Vault, and Artifacts

Use storage endpoints to upload workspace files and list durable objects. Use vault endpoints for secrets and credentials. Artifacts are typed outputs produced by runtime execution, such as browser downloads and exported files.

AI Credentials

AI credential resources let you store provider-backed keys and select between platform-managed, saved, or inline authentication for browser-use and Stagehand agent workloads.

Runtime Events

Runtime events expose low-level browser activity over list and wait APIs. The SDK builds fluent page.on(...) and waitForEvent(...) behavior on top of those HTTP routes.

OpenAPI Reference

Use the API Reference section in this tab to inspect every public endpoint, request body, response schema, and example in detail.

The API reference documents the public surface only. Internal host and routing APIs are intentionally excluded.