API overview

The API reference documents the browser use supervisor's owner and restricted service operations, with parameter tables, request schemas, cURL examples, response schemas, and success/error examples. Start with Company setup for API integration and the guardian proxy, which use separate endpoint namespaces.

Use /api/v1 for all owner, authentication, and restricted service HTTP endpoints. For example, create a run at /api/v1/owner/runs and execute an authorized operation at /api/v1/operation on its service origin.

Existing unversioned /api/... URLs remain compatibility aliases pinned to v1, with identical authentication, request bodies, responses, and streaming behavior. They do not redirect, and will not silently switch to a future API version. New integrations should use the versioned URLs. No removal date is scheduled.

Compatible additions stay within v1. Breaking request, response, or behavior changes require a new major URL version. The OpenAPI contract version is 1.0.0, independent of the application release and evidence format versions. Unknown versions return 404. OAuth browser callbacks (/auth/callback), MCP (/mcp), and the separate hosted storefront API are outside this HTTP version namespace.

Owner orchestration uses an authenticated owner session cookie. Every non-GET owner API request also requires x-halfspan-owner: 1. Owner endpoints reject service bearer credentials and enforce origin checks. These endpoints are reserved for trusted organization operators, not executor agents.

Start with Create a run, then Advance one step or Run until stopped. A paused run is returned with HTTP 200 and a stopContext; it is an application outcome, not a failed HTTP request.

An executor uses a restricted service bearer token against the exact merchant, bank, or broker origin. The trusted runtime creates that token; there is no public session-minting endpoint.

Read the observation, submit the proposal, then execute the exact permitted operation. An ALLOW verdict without a permit does not authorize execution.

These pages describe requests and responses; they do not execute mutations or grant authority. Use the service origin supplied by your integration operator, the credential appropriate to that interface, and current run, observation, and permit references. Owner requests must originate from the authorized owner origin.

Examples use synthetic data. UUIDs, keys, signatures, and permits in this reference are illustrative. Never paste credentials into a public document or commit them with a copied request.

OpenAPI 3.1 JSON is generated from shared runtime request schemas and maintained response contracts. Import it into an API client or use it to inspect fields programmatically.

The protocol guide covers authority, MCP, browser execution, signed evidence, and failure semantics. Recovery explains how to interpret stopped runs.