***

title: API Overview
description: >-
Create workspaces, launch browser runtimes, and automate them over the BCTRL
REST API.
slug: /api
----------

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

<CardGroup cols={2}>
  <Card title="Workspaces and Runtimes" icon="globe" href="#workspaces-and-runtimes">
    Create a workspace, launch a browser runtime, execute steps, and stop the runtime when finished.
  </Card>

  <Card title="Browser Profiles and Extensions" icon="id-badge" href="#browser-profiles-and-extensions">
    Manage durable browser profiles and reusable browser extensions for profile-backed launches.
  </Card>

  <Card title="Operations and Updates" icon="sparkles" href="#operations-and-updates">
    Track long-running agent work, wait on operation state, and subscribe to organization updates.
  </Card>

  <Card title="Storage, Vault, and Artifacts" icon="database" href="#storage-vault-and-artifacts">
    Upload workspace files, retrieve secrets safely at runtime, and inspect artifacts produced by execution.
  </Card>
</CardGroup>

## Supporting APIs

<CardGroup cols={3}>
  <Card title="AI Credentials" icon="key" href="#ai-credentials">
    Store reusable provider keys or use platform-managed credentials for agent workloads.
  </Card>

  <Card title="Runtime Events" icon="waveform-lines" href="#runtime-events">
    Read or wait on low-level browser runtime events such as console, network, and page lifecycle activity.
  </Card>

  <Card title="OpenAPI Reference" icon="compass" href="#openapi-reference">
    Use the generated API reference for full request and response schemas.
  </Card>
</CardGroup>

## Authentication

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

```ts
const response = await fetch("https://api.bctrl.ai/v1/workspaces", {
  method: "POST",
  headers: {
    Authorization: `Bearer ${process.env.BCTRL_API_KEY}`,
    "Content-Type": "application/json",
  },
  body: JSON.stringify({ name: "my-workspace" }),
});
```

```bash
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.