# API reference

Use Composal OpenAPI to build typed clients for Verify, hosting, and registry workflows. Learn authentication, authorization, and concurrency rules.

Use `https://api.composal.com` as the hosted API origin, keeping the
`/api/v1/...` path. Existing `https://composal.com/api/...` URLs remain
supported during the transition. Browser pages and sign-in approval live on
`https://composal.com`.

## OpenAPI document

Use the generated OpenAPI document to build an SDK or typed client, or load it into an interactive API client.

[Open the OpenAPI JSON](/api/v1/openapi)

## API areas

- Authentication and current user session
- [Persistent agents](/docs/persistent-agents/api): configuration, lifecycle, messages, conversations, outcomes, memory, files and triggers
- Organizations, members, and invitations
- Projects, Scenarios, Personas, Credentials, environments and revisions
- Grouped Scenario Runs, PR relevance selection, discovery and run evidence
- Findings, evidence, metrics, and organization memory
- Hosting apps, environments, services, deployments, domains, CDN, and static sites
- Image repositories, registry tokens, and tag listing

## Authenticated web landing

`GET /api/v1/me/landing` returns a `path` for the signed-in user's active organization. It opens the only active project directly, or Verify home when there are zero or multiple active projects. Archived projects are excluded. The endpoint requires authentication and does not change the selected organization.

## Browser runners

The browser runner API and its MCP tools are available in production. Organization administrators can create a standalone browser, or select a project, environment and credential using `POST /api/v1/organizations/{organization_id}/browser_sessions`. Supply an `Idempotency-Key` header, then read the returned session until its status is `ready`. A project is optional. Session lifetime defaults to 15 minutes and can be set with `max_seconds` between 60 and 43,200.

With `controller: external`, the session returns a browser-level `cdp_url` when external control is available. That client shares the worker's tabs, cookies and authenticated state. Project credential selection permits that full browser access.

Selecting a credential with an app URL or environment starts an automatic sign-in task in the same browser. Saved sessions and learned sign-in scripts are reused when available; the agent uses the selected account's instructions, opaque credential handles and assigned inbox. Read `authentication_status` separately from session readiness. `pending` means sign-in is still running; `ready` means an independently judged signed-in landmark survived a reload. `authentication_task_id` identifies the task whose activity and result explain a blocked login. The requested controller receives the browser after the task settles. A failed or cancelled sign-in leaves `authentication_status: blocked` and preserves the browser for manual CDP use. Without a resolvable app URL, automatic sign-in is blocked and CDP remains available.

Submitting a plain-text instruction automatically transfers control from an external CDP client to the agent before model dispatch. The handoff revokes previous CDP connections and waits for dispatched actions to settle; unsettled effects block the handoff. One task or handoff owns browser input at a time. To transfer control separately, use `POST /control` with the requested `controller`, the current session `control_generation` as `generation`, and an `Idempotency-Key`, then read `GET /controls/{control_id}` until the handoff is `completed`.

`POST /tasks` accepts `instruction`, optional `outcome`, and an `Idempotency-Key`. Read `GET /tasks/{task_id}` for public activity and the result. The task uses the organization's execution model in the same browser, with a default two-minute limit; `max_seconds` accepts 10–900 and `max_rounds` accepts 1–400. `GET /events?after={next_cursor}` resumes activity and completion events. One task or handoff owns browser input at a time.

`POST /tasks/{task_id}/cancel` stops an instruction while keeping the browser and recording open. Wait for the task to become terminal before submitting another task or rotating CDP control. A result with `effects_unknown: true` means an application action may have happened without confirmation; inspect the app before repeating it. Retry the original request with the same idempotency key to read its existing task. To return to CDP, `POST /connections` with the current `generation` and an `Idempotency-Key`, then read the control receipt for its connection.

Use these paths beneath the session URL to capture the selected tab:

- `POST /screenshots` creates a screenshot with an `Idempotency-Key`.
- `POST /recordings` starts one video clip with an `Idempotency-Key`.
- `POST /recordings/{capture_id}/stop` requests an idempotent stop, including while startup is pending.
- `GET /media` lists captures; `GET /media/{capture_id}` returns progress and retained files.

Wait for a clip to finish before starting the next one. Completed video segments are retained during recording. Capture failures preserve stored footage as `partial`; inspect `failure_code` and `capture_omissions` before treating a clip as complete. Files remain available for 30 days after capture, including after the browser closes. Use each file's authenticated `download_path`, or refresh its short-lived video `playback_url` by reading the capture again. Downloads support byte ranges. Storage limits can stop a recording while leaving the browser running.

`DELETE` the session URL to close it. Closing is asynchronous; read until `closed_at` is present to confirm cleanup and final runtime accounting.

## Authorization and concurrency

Verify endpoints require organization membership and Verify access. Actions that change configuration or runs require administrator access whenever the dashboard requires it. The [Verify MCP connector](/docs/verification#remote-mcp) uses OAuth scoped to one organization and the verification resource. Each endpoint also checks your permissions.

The API caches the user identity from a valid personal access token for up to 20 minutes to speed up repeated requests. Token revocation and changes to the cached user profile can take up to 20 minutes to reach every API worker. A cache entry expires no later than the token. The API checks organization membership and repository permissions separately from this identity cache.

Browser-session user identities use the same 20-minute cache window. Profile and account-access changes can take up to that long to become visible to an existing session. The browser session cookie must still be valid; signing out removes it from the browser.

When retrying a Verify request that changes state, reuse its idempotency key and the IDs and digests returned by planning. See the [CLI reference](/docs/cli) for commands that use the same API contract.
