Developer Basics

What the API does

The platform exposes APIs for managing persistent AI agents, messaging them, inspecting their timelines, connecting external AI clients through Remote MCP, and receiving event callbacks. For end users those persistent workers are called agents; in API docs they are agents.

The primary developer resource is the persistent agent: a long-lived agent with a charter, status, timeline, schedule, contact endpoints, files, and tool configuration. The platform also supports a legacy browser-use task API for one-off browser automation jobs.

Key Concepts

Choose the integration model based on the product behavior you need:

Need	Use
Persistent agent lifecycle, settings, contacts, messages, and timeline	Agent API
Agent files, Team placement, and permitted integration setup	Remote MCP, with browser setup where required
External AI client should manage or message agents	Remote MCP
External security integration should halt scoped Organization agents and inspect enforcement	External Security Halt, when enabled for the deployment and Organization
Callback when asynchronous work or events complete	Webhooks And Events
Schema-guided browser-task output	Structured Data
One-off browser automation task	Legacy Browser Tasks

Base URLs

• hosted deployment: https://your-deployment.example/api/v1

Example curl that hits production with the full path:

curl -X GET \
  -H "X-Api-Key: $API_KEY" \
  https://your-deployment.example/api/v1/ping/

Authentication

Organization integrations can use resource-scoped service credentials when installation availability and Organization enablement are both active. These credentials authenticate as a nonhuman service, have explicit agent/Team grants, required expiry and bounded rotation overlap, and use a narrower initial REST/MCP operation matrix. They do not inherit the member-key privileges described below.

• For the Agent REST and legacy browser-task APIs, send your API key in the X-Api-Key header: X-Api-Key: <api_key>.
• Create and manage keys under API keys (/app/data/api-keys).

Choose the narrowest access level that fits the client:

Access level	Scopes	Intended use
Read only	agents:read	Inventory, timelines, status, files, and other reads.
Operator	agents:read, agents:operate	Read access plus messaging, stopping work, task operation, and file upload.
Administrator	agents:read, agents:operate, agents:manage	Full agent configuration, lifecycle, links, and webhook management.

Access levels are cumulative. Existing keys and API-created keys that omit an access level retain Administrator access for backward compatibility. New keys created in the Console default to Operator.

Keys are scoped to their owner. Personal keys select agents in that user's global personal workspace. Organization-private and Team agents require an organization key, even when the personal-key owner created the agent. The same boundary applies to linked browser profiles and tasks. Being a collaborator in the UI does not broaden a personal key's ownership filter. Organization keys cannot create a standalone legacy browser profile; they can submit organization-owned tasks. Remote MCP staff/superuser keys have explicit administrative targeting arguments; ordinary keys cannot use them.

All Organization profiles, including Read only, require Organization-wide agent authority. An active Owner or Admin can create them. Security Admin retains list, revoke and delete controls; Agent Admin can use a previously issued key but cannot create one.

Every Organization-key request checks the same creator's active user account, membership and Organization agent-management authority. Keys become Blocked when that authority is unavailable, including after removal or downgrade to Security Admin, Member or Viewer. Blocked keys cannot call REST or Remote MCP, read resources or replay stored responses. They do not inherit another administrator's authority. Restoring the same creator's authority restores access unless the key was revoked. Blocking does not cancel already accepted work.

Missing or invalid Agent REST API keys and insufficient API-key scopes return 403. With default company-license enforcement, use an Organization key for new work: new personal agent creation and personal execution are unavailable, and execution requires a valid Organization license, including its grace period. Authorized historical reads remain available under their existing ownership and scope checks. External communication also requires verified email and contact permissions. A valid API key alone does not establish execution readiness. See Errors and recovery for exact error shapes.

The External Security Response API uses a dedicated service credential in Authorization: Bearer <token>. An Owner, Admin, or Security Admin creates it in Governance → Policies → External security → Response access with an explicit agent allowlist. The UI defaults to security:read; select Request agent halts (security:halt) as well for a sender that creates holds and polls status. Either permission can be granted separately. Identity permissions and agent scope can be edited; existing tokens use the current authority. Authentication failures return 401; missing security permissions return 403. This deployment-gated API requires HTTPS by default and does not accept ordinary agent API keys. SCIM also has its own bearer-token contract.

Environments

• Production: Multi-tenant hosted deployment at https://your-deployment.example with managed upgrades.

Content & security conventions

• Requests and responses use JSON with UTF-8 encoding; set Content-Type: application/json on writes.
• Timestamps are ISO 8601; the primary REST schedule has no separate timezone parameter.
• Agent and task identifiers are UUIDs. REST agent user_id is a decimal string; pending-action IDs are typed strings.
• Use the authentication header required by the chosen API: X-Api-Key for Agent REST, or the dedicated bearer credential for External Security Halt and SCIM. Add Content-Type: application/json when sending JSON bodies.

HTTP patterns

• Agents (/agents/):
  • GET /agents/ lists agents (paginated).
  • POST /agents/ creates an agent; API-key clients can make it replay-safe with Idempotency-Key.
  • GET /agents/{agentId}/ retrieves a single agent.
  • PUT/PATCH /agents/{agentId}/ updates supplied writable settings; omitted optional fields keep their current values.
  • DELETE /agents/{agentId}/ archives an agent; use /restore/ to recover it.
• Legacy browser tasks (/tasks/browser-use/ or /agents/browser-use/{agentId}/tasks/):
  • POST submits a task; omit wait for asynchronous acceptance and poll /result/. Explicit wait is unavailable with general admission or protected creation; see task wait limits.
  • GET lists tasks (paginated) or retrieves a task.
  • PUT/PATCH can update prompt, output_schema, requires_vision, agent, and secrets while pending and unclaimed. A supplied secrets map replaces the whole snapshot; omission preserves it, {} clears it, and null rejects. See task secret updates for atomicity and race limits. DELETE soft-deletes; use /cancel/ to stop work first. metadata is not a writable task field.
• Remote MCP (/mcp/):
  • POST JSON-RPC requests using X-Api-Key or Authorization: Bearer.
  • Supports initialize, ping, tools/list, tools/call, and documented resource discovery/read methods.
• Pagination: Ordinary REST collections default to 10 with page and page_size (max 100). Timeline, web-task, and contact collections differ; see the pagination matrix.

Retry-safe writes

The idempotency guide lists the API-key operations that support Idempotency-Key and the two supported MCP tools. External Security Halt instead deduplicates by service identity and external_event_id for the Organization lifetime; see the guide's separate retry contract.

References and next steps

Start with the end-to-end quickstart. The API reference contains the public REST operations and their required scopes or security service permissions; download its OpenAPI YAML for client generation. On an application deployment, /api/schema/ exposes the runtime schema. MCP has a separate tool reference; directory provisioning has a separate SCIM reference. Security integrations should follow the External Security Halt guide.

See limits and compatibility for protocol boundaries, configurable limits, and upgrade expectations.

Quickstart: health check

Verify connectivity and your API key with the ping endpoint:

curl -X GET \
  -H "X-Api-Key: $API_KEY" \
  https://your-deployment.example/api/v1/ping/

Sample response:

{
  "pong": true,
  "user": "you@example.com"
}

If you see pong: true, your key is valid and the API is reachable. Next, create or inspect a persistent agent with the Agent API, or connect an MCP client with Remote MCP.

Reporting credentials

The additional explicit usage:read and audit:read scopes enable bounded usage and audit metadata reads when the deployment gate is enabled. Existing agent profiles do not gain them. Current member issuer reporting capabilities and service original ownership/resource grants remain required; no browser cookies or evidence export are included.

For machine recovery, select X-API-Contract: 2026-10-14 on supported REST resources and retain X-Request-ID for this HTTP exchange. This preserves Agent REST's existing missing/invalid-key 403 status while providing authentication_required/authentication_failed codes. Current scopes, issuer eligibility, service grants and guarded human setup remain required. SCIM and Security Halt continue using their dedicated Bearer challenges and protocol errors.