API reference

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 areas

• Authentication and current user session
• Persistent agents: 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 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 for commands that use the same API contract.