Agents API

Persistent agent endpoints for creating, scheduling, messaging, and managing agents through the API.

📄️Get agents

List resources visible to this API key using page-number pagination. Requires `agents:read`.

Create an agent in the API key's owner scope; an Organization key creates in the issuer's Organization-private workspace. Active creation requests initial processing and, by default, a separate first-check-in timer even when the primary schedule is null. Use is_active=false to prepare a paused agent without initial processing publication or a first-check-in timer; metadata-generation jobs remain. Optional team_id uses current member/destination authority, requires Idempotency-Key and API_CONFIGURATION_ENABLED for fresh creation. template_code applies only on creation; see the Agent API guide for template and schedule precedence. Requires `agents:manage`.

📄️Get Agent

Retrieve one resource visible to this API key. Inaccessible resources return 404. Requires `agents:read`.

📄️Agent - Update

Update the supplied writable fields. Omitted optional fields retain their values; this does not reset the resource to defaults. Requires `agents:manage`.

📄️Agent - Patch

Update only supplied writable fields. Read-only and unknown fields are ignored by the model serializer. Requires `agents:manage`.

📄️Agent - Archive

Archive the agent and release its communication endpoints. Use archived/ and restore/ to recover it. Requires `agents:manage`.

📄️Activate Agent

Activate the agent and clear expired state. The server may restore its saved schedule. No request body is needed; updated indicates whether state changed. Requires `agents:manage`.

📄️List Contact Endpoints

Discover the agent's persisted communication endpoints and current preferred endpoint before sending messages or changing contact preference. Requires `agents:read`.

📄️List Agent Contacts

List active contacts and their communication permissions. Set include_inactive=true to include deactivated entries; returns contacts and count. Requires `agents:read`.

📄️Add or Reactivate Contact

Add or reactivate an email or web contact. An active contact selects manual allowlist policy. Requires `agents:manage`.

📄️Get Agent Contact

Read one contact and its inbound, outbound, configuration, and activation permissions. Contact channel and address are immutable. Requires `agents:read`.

📄️Update Agent Contact

Update supplied contact permissions or is_active. To change channel or address, deactivate this contact and add a replacement. Requires `agents:manage`.

📄️Deactivate Agent Contact

Reversibly deactivate this contact while preserving its identity and history. Repeating deactivation is safe; return the updated contact. Requires `agents:manage`.

📄️Deactivate Agent

Pause the agent without archiving it. No request body is needed; repeating the call returns updated=false once paused. Requires `agents:manage`.

📄️Agent Debug Trace - Get

Return a bounded, sanitized diagnostic trace for one agent. Raw prompt archives and secret-like values are never returned. Repeat `include` or use comma-separated values to select sections; use `recent_minutes=null` to disable the default recent window. Foreign, transferred or purged application history requires principal-scoped request reads. Requires `agents:read`.

📄️Agent Events - Wait

Long-poll one agent's durable timeline for up to 30 seconds. Events are strictly newer than `after_cursor`; the response always returns the latest cursor for the next wait. This read-only operation requires `agents:read` even though it uses POST. Each snapshot rejects foreign, transferred or purged application history; use scoped request waits. Requires `agents:read`.

📄️listPersistentAgentInboundWebhooks

List inbound webhook metadata without invocation URLs or secrets. Use the manage-scoped detail endpoint to obtain an invocation URL. Requires `agents:read`.

📄️createPersistentAgentInboundWebhook

Create a secret-bearing URL for external systems to trigger this agent. Invoking that URL uses a separate ingestion contract documented in Webhooks and events. Requires `agents:manage`.

📄️getPersistentAgentInboundWebhook

Retrieve one inbound webhook and its secret-bearing invocation URL. This credential-bearing read requires manage scope. Requires `agents:manage`.

📄️updatePersistentAgentInboundWebhook

Update the name or enabled state of an inbound webhook. Disabled webhooks reject invocation without storing an inbound message. Requires `agents:manage`.

📄️deletePersistentAgentInboundWebhook

Delete an inbound webhook registration and invalidate its invocation URL. Previously accepted agent messages remain in history. Requires `agents:manage`.

📄️rotatePersistentAgentInboundWebhookSecret

Replace the inbound webhook invocation secret immediately and return the replacement URL. External senders must switch to the new URL. Requires `agents:manage`. Optional protected retries require API_EXTENDED_RETRIES_ENABLED for new admissions; retained retries survive disabling admission. Original outcomes expire after 24 hours by default; current authority is rechecked. Task creation requires wait to be omitted. Secret rotation retries conflict if superseded.

📄️Message Agent

Ingest a message from an allowed sender using a supported channel and agent endpoint. Email is a supported input. Returns 201 with the stored timeline event, not an agent reply or proof of processing. Inactive agents return 409; disallowed senders return 403. REST does not accept file attachments here. Requires `agents:operate`.

📄️Peer Links - List

List this agent's symmetric peer links, including disabled links. Requires agents:read. Requires `agents:read`.

📄️Peer Link - Create or Enable

Create or re-enable a symmetric peer link. Requires agents:manage and access to both agents. Omitted quotas default to 30 messages per 6 hours, including for existing links. Requires `agents:manage`.

📄️Peer Link - Get

Retrieve a peer link attached to this agent. Requires agents:read. Requires `agents:read`.

📄️Peer Link - Update

Edit peer-link quotas or enabled state without replenishing credits. Requires agents:manage. Requires `agents:manage`.

📄️Peer Link - Remove

Remove the peer link while preserving historical conversations and messages. Requires agents:manage. Requires `agents:manage`.

📄️List Pending Actions

List visible unresolved decisions with typed IDs, data, and allowed_decisions. Includes human input, outbox review, spawn, secrets, contacts, and OpenAPI approvals. Requires `agents:read`.

📄️Resolve Pending Action

Requires `agents:operate` for human_input and outbox_review; other action types require `agents:manage`. Optional protected retries require API_EXTENDED_RETRIES_ENABLED for new admissions; retained retries survive disabling admission. Original outcomes expire after 24 hours by default; current authority is rechecked. Task creation requires wait to be omitted. Secret rotation retries conflict if superseded.

📄️Get Agent Processing Status

Read current processing state and a snapshot of active browser tasks and the next known scheduled run. This does not wait for work to finish. Requires `agents:read`.

📄️Agent - Restore

Restore an archived agent and reclaim available endpoints and peer links. The agent remains inactive; a conflicting active name returns 409. Requires `agents:manage`.

📄️Preview Agent Schedule

Validate the primary recurring schedule without saving it. Returns valid, disabled, and a description; empty or null input previews an unscheduled agent. Requires `agents:read`.

📄️Stop Agent Work

Request a graceful stop of current processing and cancel active browser tasks without deactivating the agent. Returns stopping state, cancellation count, and processing snapshot. Requires `agents:operate`.

📄️Get Agent Timeline

Read the unified timeline using an opaque cursor and direction. Returns events, boundary cursors, pagination flags, and processing state. Nested event fields use camelCase; envelope fields use snake_case. Requires `agents:read`.

📄️List Web Tasks

List recent browser tasks run by this persistent agent. This bounded results envelope uses limit and status, not page-number pagination. Requires `agents:read`.

📄️listPersistentAgentWebhooks

List outbound webhook metadata and subscriptions. Destination URLs and signing secrets are omitted; use the manage-scoped detail endpoint for them. Requires `agents:read`.

📄️createPersistentAgentWebhook

Create an outbound webhook destination and return its signing secret. Select pending-action subscriptions explicitly; the default agent.message type describes explicit agent tool sends. Requires `agents:manage`.

📄️getPersistentAgentWebhook

Retrieve one outbound webhook, including its destination and signing secret. Treat this response as credentials; read-only keys cannot retrieve it. Requires `agents:manage`.

📄️updatePersistentAgentWebhook

Update supplied outbound webhook settings, including event subscriptions and enabled state. Returns the webhook's current configuration. Requires `agents:manage`.

📄️deletePersistentAgentWebhook

Delete an outbound webhook registration so it is no longer available for future sends. Historical agent activity is not erased. Requires `agents:manage`.

📄️rotatePersistentAgentWebhookSecret

Replace the outbound webhook signing secret immediately and return the new value. The sender does not provide a dual-secret grace period. Requires `agents:manage`. Optional protected retries require API_EXTENDED_RETRIES_ENABLED for new admissions; retained retries survive disabling admission. Original outcomes expire after 24 hours by default; current authority is rechecked. Task creation requires wait to be omitted. Secret rotation retries conflict if superseded.

📄️Archived Agents - List

List archived agents in this key's owner scope, using page and page_size. Archived agents are excluded from the ordinary collection. Requires `agents:read`.

📄️Legacy Browser-Use Agent - Patch