Skip to main content

Agent API

Configure a persistent agent once, then reuse it for multistep work, recurring responsibilities, messages, and timeline-driven workflows. REST files, application requests, and inactive setup and named schedules have separate deployment gates. Remote MCP also provides documented file operations.

For a complete create, message, and reply flow, start with the API quickstart.

Agents can use browser automation and other AI tools. They may also be configured to use MCP servers and connected app tools where available. If you want to connect an external AI client to the platform itself over MCP, see the Remote MCP Server guide.

Core capabilities include:

  • Create, list, update, archive, or restore persistent agents.
  • Run on a schedule using cron-like strings (@daily, @every 30m, or full cron expressions).
  • Activate/deactivate agents without losing configuration.
  • Link agents so they can coordinate through peer messages.
  • Send messages, fetch timelines, and wait for events to drive conversational workflows.
  • Fetch sanitized debug traces for bounded operational diagnostics without exposing raw prompts or secrets.
  • Inspect or stop current work and review recent browser tasks tied to the agent.

Names at creation​

The name field is optional by default. An Organization can require an explicit name for every new private or Team agent. In that mode, supply a nonblank name such as "Finance Review"; a name mentioned only in charter does not satisfy the requirement. Names are trimmed, limited to 255 characters, and checked against the existing destination workspace name rules. Missing or invalid names return 400 without creating an agent.

The same policy applies to Remote MCP create_agent and agent creation tools. Existing agents, restores, and workspace moves retain their names. Personal agents continue to receive a generated name when the field is omitted.

Base path​

All persistent agent routes live under /api/v1/agents/.

  • Production: https://your-deployment.example/api/v1/agents/

Authentication: include your API key header on every request (X-Api-Key: <api_key>).

Organization keys can be issued only by an active Owner or Admin. Every request rechecks the creator's active membership and Organization agent-management authority, including for Read only keys. Agent Admin can continue using a previously issued key. Insufficient authority, creator removal/inactivation or an inactive Organization blocks authentication with 403; another administrator does not become the key's principal. Restoring the same creator's authority restores access unless the key was revoked. Stored scopes are not silently downgraded, and cached idempotent responses still require current authority. Personal-key authentication is unchanged.

Read endpoints require agents:read. Sending messages, resolving human-input or outbox-review actions, and stopping work require agents:operate. Resolving agent-spawn, credential, contact, or OpenAPI-approval actions requires agents:manage, as does creating, configuring, activating/deactivating, archiving/restoring, and managing webhooks. Unknown pending-action types also require agents:manage. The schedule preview and event-wait endpoints only require agents:read even though they use POST.

Resource shape​

The collection uses a smaller representation than detail, creation, and update responses. List items omit short_description, schedule_snapshot, preferred_llm_tier, daily_credit_limit, and MCP server inventories. Fetch GET /agents/{id}/ when those fields are needed. Archived list items additionally include is_deleted and deleted_at.

Key fields in agent representations:

  • id (UUID): Agent identifier used in all routes.
  • name (string): Display name. Conditionally required at creation as described above; active names must be unique in the destination workspace. Organization-private names are scoped to their primary user, and Team names to that Team.
  • charter (string): Free-form instructions for what the agent should do.
  • schedule (string|null): Primary recurring cadence such as @daily or 0 */4 * * *. null disables this cadence; separate timers and creation-time work can still exist.
  • is_active (bool): Ordinary activation setting. An active agent can still be blocked by license, security policy or an emergency hold; this field does not establish current execution.
  • life_state (enum): active or expired (soft pause due to inactivity).
  • whitelist_policy (enum): Controls who can message the agent (default or manual).
  • contact_approval_mode (enum): require_approval or auto_approve_email.
  • email_sending_mode (enum): Requested outbound policy: review_all_external, review_new_contacts, or send_automatically.
  • effective_email_sending_mode (enum): The enforced policy after any stricter organization minimum is applied.
  • organization_minimum_email_sending_mode (enum|null): The governing organization minimum, when present.
  • preferred_contact_endpoint_id (UUID|null): Read-only ID of the selected contact endpoint. Write preferred_contact_endpoint to change the preference.
  • proactive_opt_in (bool): Whether the platform may proactively offer related help. It defaults to true; pass false during creation to opt out immediately.
  • browser_use_agent_id (UUID): The underlying browser automation worker.
  • available_mcp_servers / personal_mcp_server_ids (arrays): MCP server metadata and enabled personal servers where exposed.
  • preferred_llm_tier (string): Configured intelligence tier key, subject to the owner's entitlements.
  • daily_credit_limit: Deprecated, inactive historical read retained until an explicit breaking-release decision. Setting it returns an actionable retirement error; usage tracking does not enforce credit budgets.
  • planning_state, planning_plan, planning_completed_at: Read-only planning status, plan text, and completion time.
  • user_id (string): Local numeric user ID serialized as text.
  • Timestamps: created_at, updated_at, last_interaction_at.

REST ownership comes from the key. Personal keys remain limited to global personal agents, including authorized historical reads under company-license enforcement. New personal agent creation and personal execution are unavailable under default enforcement; use a licensed Organization for new work. Organization keys access agents governed by that Organization. Neither a creator's personal key nor UI collaborator access expands that boundary. REST creation with an Organization key defaults to the issuer's Organization-private workspace. Member keys can supply creation-only team_id for an authorized active Team when API_CONFIGURATION_ENABLED is enabled and Idempotency-Key is supplied. user_id, organization_id, and browser_use_agent_id are read-only. For guarded workspace moves and their history restrictions, see inactive setup; MCP create_agent.team_id and move_agent retain their separate contracts.

Endpoint summary​

  • GET /agents/ — List agents (paginated).
  • GET /agents/archived/ — List archived agents (paginated).
  • POST /agents/ — Create an agent.
  • GET /agents/{id}/ — Retrieve details.
  • PUT /agents/{id}/ — Update writable settings; omitted optional fields retain their values.
  • PATCH /agents/{id}/ — Partial update (name, charter, schedule, whitelist policy, preferred contact, MCP servers, etc.).
  • DELETE /agents/{id}/ — Archive an agent.
  • POST /agents/{id}/restore/ — Restore an archived agent without activating it.
  • POST /agents/{id}/activate/ — Mark active (also clears life_state=expired).
  • POST /agents/{id}/deactivate/ — Pause without deleting.
  • GET /agents/{id}/processing-status/ — Check current work and the next known scheduled run.
  • POST /agents/{id}/stop/ — Request a graceful stop and cancel active browser tasks without deactivating the agent.
  • POST /agents/{id}/schedule/preview/ — Validate a cron-like schedule and get a human-readable description.
  • GET /agents/{id}/timeline/ — Scrollable list of recent message/task events.
  • POST /agents/{id}/events/wait/ — Bounded long-poll for timeline events newer than a durable cursor.
  • GET /agents/{id}/debug-trace/ — Bounded, sanitized operational trace with selectable sections.
  • POST /agents/{id}/messages/ — Store an inbound message using a supported channel and allowed sender.
  • GET|POST /agents/{id}/contacts/ — List active contacts or add/reactivate an email or web contact.
  • GET|PATCH|DELETE /agents/{id}/contacts/{contact_id}/ — Inspect, update, or reversibly deactivate a contact.
  • GET|POST /agents/{id}/peer-links/ — List peer links or create/re-enable a link.
  • GET|PATCH|DELETE /agents/{id}/peer-links/{link_id}/ — Inspect, edit, disable, or remove a peer link.
  • GET /agents/{id}/contact-endpoints/ — Discover the agent endpoints and current preferred endpoint.
  • GET /agents/{id}/pending-actions/ — List pending decisions, including contact requests.
  • POST /agents/{id}/pending-actions/{actionId}/resolve/ — Resolve a typed decision; see all six pending-action contracts.
  • GET|POST /agents/{id}/webhooks/ — List or create outbound event-notification webhooks.
  • GET|PATCH|DELETE /agents/{id}/webhooks/{webhook_id}/ — Inspect, update, or delete an outbound webhook.
  • GET|POST /agents/{id}/inbound-webhooks/ — List or create endpoints that let external systems trigger the agent.
  • GET|PATCH|DELETE /agents/{id}/inbound-webhooks/{webhook_id}/ — Inspect, enable/disable, rename, or delete an inbound webhook.
  • POST /agents/{id}/webhooks/{webhook_id}/rotate-secret/ and the equivalent inbound-webhooks route — Rotate a webhook secret.
  • GET /agents/{id}/web-tasks/?limit=50&status=completed — Recent browser tasks executed by this agent.

Create an agent​

curl -X POST \
  -H "Content-Type: application/json" \
  -H "X-Api-Key: $API_KEY" \
  -H "Idempotency-Key: agent-create-2024-07-01-001" \
  -d '{
    "name": "Ops Teammate",
    "charter": "Monitor our status page and file an incident if downtime exceeds 2 minutes.",
    "schedule": "@every 15m",
    "whitelist_policy": "manual",
    "template_code": null,
    "enabled_personal_server_ids": []
  }' \
  https://your-deployment.example/api/v1/agents/

Sample response (selected fields; generated descriptions and policy defaults can vary):

{
  "id": "b5f0f2c8-1c2b-4bb5-836b-9b4e2f86b743",
  "name": "Ops Teammate",
  "charter": "Monitor our status page and file an incident if downtime exceeds 2 minutes.",
  "short_description": "",
  "schedule": "@every 15m",
  "schedule_snapshot": null,
  "is_active": true,
  "life_state": "active",
  "whitelist_policy": "manual",
  "contact_approval_mode": "require_approval",
  "email_sending_mode": "send_automatically",
  "effective_email_sending_mode": "send_automatically",
  "organization_minimum_email_sending_mode": null,
  "last_interaction_at": "2024-07-01T18:10:00Z",
  "created_at": "2024-07-01T18:10:00Z",
  "updated_at": "2024-07-01T18:10:00Z",
  "user_id": "123",
  "organization_id": null,
  "browser_use_agent_id": "339251c0-7b57-4a22-8ba8-ddecf1ab9665",
  "preferred_contact_endpoint_id": null,
  "proactive_opt_in": true,
  "proactive_last_trigger_at": null,
  "available_mcp_servers": [],
  "personal_mcp_server_ids": []
}

Creation and setup effects​

Creation defaults to is_active: true and requests an initial processing cycle after the database commit. Active provisioning also creates a separate First check-in one-time timer by default, controlled by PERSISTENT_AGENT_DEFAULT_CHECKIN_DELAY_SECONDS (24 hours by default; a nonpositive value disables it). These effects are independent of a null primary schedule. proactive_opt_in: false opts out of proactive offers; it does not remove the first-check-in timer or suppress the initial processing request.

To prepare settings and integrations before execution, create with is_active: false, schedule: null, and, if desired, proactive_opt_in: false. Inactive creation skips the first-check-in timer and initial processing publication; description/tag/avatar metadata jobs can still be scheduled. Configure the agent, then activate deliberately and send its first message. A 201 response establishes creation, not worker/model readiness.

Additional creation inputs:

FieldBehavior
template_codeOptional active company template owned by the destination Organization; public and bundled catalog templates are unavailable. A blank or null value uses no template; an unknown code returns 400. Legacy updates ignore it; versioned updates reject this creation-only field.
team_idCreation-only placement in an authorized active Team of the key's Organization; requires the configuration gate and retry key. Use the guarded workspace route for later moves.
enabled_personal_server_idsOptional UUID list assigning the issuer's personal MCP servers; [] clears assignments. Ownership, availability, and server limits apply. Available server metadata is exposed in agent detail.
preferred_llm_tierA deployed intelligence-tier key, validated against the effective owner's entitlements. Null resolves the owner's default tier.
daily_credit_limitDeprecated, inactive historical read retained until an explicit breaking-release decision. Writes return a retirement error.

A template can supply an omitted/blank charter and a jittered primary schedule. REST reapplies an explicitly supplied charter and schedule after provisioning, so schedule: null overrides the template cadence. Omitting schedule permits the template cadence. schedule_snapshot remains server-managed. To preserve a template's charter, omit charter rather than explicitly sending an empty string.

Retrieve or list agents​

List your agents (default page size 10, use ?page_size= to increase up to 100):

curl -H "X-Api-Key: $API_KEY" \
  "https://your-deployment.example/api/v1/agents/?page_size=20"

Fetch a single agent by id:

curl -H "X-Api-Key: $API_KEY" \
  https://your-deployment.example/api/v1/agents/b5f0f2c8-1c2b-4bb5-836b-9b4e2f86b743/

Update, pause, archive, or restore​

Patch mutable fields such as name, charter, schedule, whitelist_policy, or contact preferences:

The example below uses legacy unconditional updates. For protection against concurrent configuration edits, retrieve the agent's ETag and select X-API-Contract: 2026-10-14 with If-Match and Idempotency-Key; new conditional writes require the configuration gate. See conditional ordinary agent updates.

curl -X PATCH \
  -H "Content-Type: application/json" \
  -H "X-Api-Key: $API_KEY" \
  -d '{
    "schedule": "0 */4 * * *",
    "whitelist_policy": "default",
    "preferred_contact_endpoint": "email"
  }' \
  https://your-deployment.example/api/v1/agents/b5f0f2c8-1c2b-4bb5-836b-9b4e2f86b743/

The schedule field is the agent's primary recurring cadence. Set it to a cron expression or shorthand such as @every 30m; set it to null to disable that cadence. schedule_snapshot is server-managed and cannot be changed through the API.

Activation and deactivation take no request body and return {"status":"activated","updated":true} or {"status":"deactivated","updated":true}. Repeating an unchanged transition returns updated: false.

Toggle availability without deleting the agent:

# Activate (also clears expired state)
curl -X POST -H "X-Api-Key: $API_KEY" \
  https://your-deployment.example/api/v1/agents/b5f0f2c8-1c2b-4bb5-836b-9b4e2f86b743/activate/

# Deactivate
curl -X POST -H "X-Api-Key: $API_KEY" \
  https://your-deployment.example/api/v1/agents/b5f0f2c8-1c2b-4bb5-836b-9b4e2f86b743/deactivate/

DELETE archives an agent and releases its communication endpoints. Archived agents are excluded from the normal list:

curl -X DELETE -H "X-Api-Key: $API_KEY" \
  https://your-deployment.example/api/v1/agents/b5f0f2c8-1c2b-4bb5-836b-9b4e2f86b743/

curl -H "X-Api-Key: $API_KEY" \
  "https://your-deployment.example/api/v1/agents/archived/?page_size=20"

Restore an archived agent by id:

curl -X POST -H "X-Api-Key: $API_KEY" \
  https://your-deployment.example/api/v1/agents/b5f0f2c8-1c2b-4bb5-836b-9b4e2f86b743/restore/

Restore reclaims available communication endpoints and peer links, but the restore request itself does not reactivate the agent or restore its previous schedule. Review schedule and schedule_snapshot before activating; activation can reinstate a server-managed schedule snapshot. Repeating restore is safe. If another active agent now uses the archived agent's name in the same workspace, restore returns 409 Conflict and leaves the archive unchanged.

The lower-level DELETE /agents/browser-use/{profile_id}/ requires agents:manage and permanently deletes standalone browser profiles and their browser-task history. A profile backing a persistent agent returns 409 Conflict with code: "browser_profile_in_use" and the agent's archive URL. Archive the persistent agent through DELETE /agents/{id}/; its browser profile and retained history remain available for restoration. Archived or inaccessible profiles return 404. Personal keys cannot delete Organization profiles, and Organization keys cannot delete standalone profiles.

Contacts and communication policy​

Add or reactivate an email contact. Adding an active contact moves the agent to manual allowlist policy:

curl -X POST \
  -H "Content-Type: application/json" \
  -H "X-Api-Key: $API_KEY" \
  -H "Idempotency-Key: contact-ops-001" \
  -d '{
    "channel": "email",
    "address": "ops@example.com",
    "allow_inbound": true,
    "allow_outbound": true,
    "can_configure": false
  }' \
  https://your-deployment.example/api/v1/agents/b5f0f2c8-1c2b-4bb5-836b-9b4e2f86b743/contacts/

The collection returns {"contacts": [...], "count": n}. Creation returns 201 for a new contact and 200 for an existing one, with contact, created, and reactivated. Email addresses are normalized to lowercase. Reposting an existing contact updates its permissions: omitted allow_inbound and allow_outbound default to true, and omitted can_configure defaults to false. Use PATCH to preserve permissions you do not supply.

GET detail, PATCH, and DELETE wrap the result in contact; mutations also return reactivated or deactivated. PATCH changes permissions or reactivates an inactive contact with {"is_active": true}. DELETE only deactivates the entry; it does not erase it or reset manual allowlist policy, and repeating the request is safe. Pass ?include_inactive=true when listing to include deactivated contacts; false is the default, 1/0 are also accepted, and other values return 400. A contact's channel and address are immutable; deactivate it and add a replacement to change its identity.

Web contacts use web://user/{numeric_user_id}/agent/{agent_uuid} with the target agent's UUID. Adding a web contact grants communication permissions; it does not grant UI access or expand API-key ownership.

Discover persisted endpoints with GET /contact-endpoints/, then set one through the normal agent patch:

{"preferred_contact_endpoint": "<endpoint-uuid>"}

You may also use "email" instead of an endpoint UUID, or null to clear the preference. A channel shortcut selects the agent's own matching endpoint first. If none exists, a personal agent can fall back to its owner's email; an Organization agent returns 400. A UUID is accepted when it belongs to this agent, is an unowned endpoint matching its owner's email, or is its already-selected unowned endpoint. Inspect safe_for_preferred_contact from /contact-endpoints/ rather than guessing eligibility. That collection contains the agent's own endpoints and its current preference; it is not the contact allowlist.

Configure outbound behavior with whitelist_policy, contact_approval_mode, and email_sending_mode in POST /agents/ or PATCH /agents/{id}/. Use effective_email_sending_mode when displaying the result; an organization can make the effective mode stricter than the requested mode.

For a pending contact request, find its contact_request:{request_id} action in GET /pending-actions/ and resolve it with:

{
  "decision": "approve",
  "allow_inbound": true,
  "allow_outbound": true,
  "can_configure": false
}

Peer links let two agents exchange messages and coordinate work. A link is symmetric: either participating agent's route addresses the same link. Creating a link requires access to both agents through your API key, and the agents must share an owner or organization. Archived and evaluation agents are excluded.

curl -X POST \
  -H "Content-Type: application/json" \
  -H "X-Api-Key: $API_KEY" \
  -H "Idempotency-Key: research-review-link-001" \
  -d '{
    "peer_agent_id": "a0f92112-6e13-41dd-946d-5dc2d9a1a0ad",
    "messages_per_window": 30,
    "window_hours": 6
  }' \
  https://your-deployment.example/api/v1/agents/b5f0f2c8-1c2b-4bb5-836b-9b4e2f86b743/peer-links/

POST returns 201 with {"link": {...}, "created": true} for a new pair. If the pair already exists, it returns 200 with created: false, re-enables the link, and updates its quotas. Reversing the two agent IDs still finds the same pair. Omitted quotas default to 30 messages per 6 hours, even for an existing link. Use PATCH to preserve fields you omit.

messages_per_window accepts integers from 1 to 500; window_hours accepts integers from 1 to 168. PATCH accepts those fields and is_enabled. For example, {"is_enabled": false} pauses peer communication without removing the link. Agent identities cannot be changed. Feature flags are included in responses for visibility but cannot be set through REST.

Quota edits update existing communication states immediately and clamp remaining credits to a reduced limit. Editing quotas or re-enabling a link does not replenish credits or change the current window's reset time. Creating the link does not send introductions or start agent processing.

GET on the collection returns {"links": [...], "count": n}, including disabled links, newest first. GET and PATCH on a link return {"link": {...}}. The link representation matches Remote MCP and includes its UUID, both agent references, health, quotas, enabled state, feature flag, pair key, creator ID, and timestamps. A link's health reports inactive, expired, or deleted peers independently of its enabled state.

DELETE returns 204, removes the link, and preserves historical conversations and messages. A subsequent GET or DELETE returns 404. To retry a deletion safely, supply the same Idempotency-Key on both requests: POST, PATCH, and DELETE support replay of the original status and body for 24 hours. Keys are scoped to the API key; reusing a key with a different method, path, or body returns 409.

GET requires agents:read; POST, PATCH, and DELETE require agents:manage. Missing or inaccessible agents and unrelated link IDs return 404. Invalid request fields, quotas, or agent pairings return 400. See Peer Linking for workflow examples and Remote MCP Server for MCP access.

Webhook management​

Outbound webhooks notify a client when subscribed agent events occur. Create one with a destination URL and one or more event types:

curl -X POST \
  -H "Content-Type: application/json" \
  -H "X-Api-Key: $API_KEY" \
  -H "Idempotency-Key: outbound-webhook-001" \
  -d '{
    "name": "Agent events",
    "url": "https://client.example.com/agent-events",
    "event_types": ["agent.message", "agent.pending_action.*"]
  }' \
  https://your-deployment.example/api/v1/agents/b5f0f2c8-1c2b-4bb5-836b-9b4e2f86b743/webhooks/

Legacy subscriptions are agent.message, the specific pending-action lifecycle events created, resolved, and expired, the agent.pending_action.* wildcard, and the global * wildcard. agent.message delivers explicit agent tool sends; it does not automatically capture every message. Separately gated automatic subscriptions add agent.message.created, agent.request.updated, and agent.request.responded, with principal-scoped visibility and delivery recovery. See automatic agent events for their exact contract. Creation and detail responses include the signing secret; lists do not. Store the secret securely and verify the X-DT-Signature header before accepting a delivery.

Inbound webhooks provide a secret-bearing URL that an external system can call to wake an agent:

curl -X POST \
  -H "Content-Type: application/json" \
  -H "X-Api-Key: $API_KEY" \
  -H "Idempotency-Key: inbound-webhook-001" \
  -d '{"name": "Deployment completed", "is_active": true}' \
  https://your-deployment.example/api/v1/agents/b5f0f2c8-1c2b-4bb5-836b-9b4e2f86b743/inbound-webhooks/

The creation response includes the complete invocation URL. Send a JSON or multipart POST to that URL to trigger the agent. Set is_active to false with PATCH to disable it without deleting it. Rotating the secret returns a new URL and immediately invalidates the previous one.

Webhook lists require agents:read. Creating, changing, deleting, rotating, or retrieving a secret-bearing webhook detail requires agents:manage. These are native agent webhook APIs and do not depend on an external integration provider.

Messaging and timelines​

Send an inbound message using the agent's persisted channel endpoint and an allowed sender. Email is a common input; the request schema also lists the other channel values. API ingestion does not authenticate a provider or deliver a message to the selected recipient itself:

curl -X POST \
  -H "Content-Type: application/json" \
  -H "X-Api-Key: $API_KEY" \
  -H "Idempotency-Key: status-alert-2024-07-01-001" \
  -d '{
    "channel": "email",
    "sender": "alerts@example.com",
    "recipient": "agent@example.com",
    "subject": "Status page alert",
    "body": "Uptime check failed for api.example.com",
    "metadata": {"source": "pagerduty"}
  }' \
  https://your-deployment.example/api/v1/agents/b5f0f2c8-1c2b-4bb5-836b-9b4e2f86b743/messages/

Omit recipient to use the agent's primary email endpoint by default.

The required fields are channel, sender, and nonblank body; recipient, subject, and object-valued metadata are optional. There is no REST attachment field. A 201 response contains the persisted inbound event; later execution remains subject to policy and emergency admission. Use the event cursor to observe replies, and reconcile a processing delay before resubmitting the message.

For email, subject is retained with the message and supplied to agent context and applicable content inspection. It is separate from body and never affects recipient routing. Omitted, null, empty or whitespace-only subjects mean no subject; other values are trimmed at the edges and limited to 512 Unicode code points after trimming. Unicode and internal text are preserved. A new non-email request with a nonblank subject returns 400 with a subject field error; authorized subjectless web messages retain their existing behavior. Nested metadata.subject is ordinary metadata. Older accepted replay responses keep their original contents, including a missing subject; deployment cannot reconstruct discarded historical text.

Use a new Idempotency-Key value for each logical agent create, message, contact create, peer-link mutation, or webhook create. Retrying the same request with the same value for up to 24 hours returns the original status and body without duplicating the resource or message. Reusing it with different input returns 409 Conflict.

Fetch the event timeline (message history plus processing markers).

curl -H "X-Api-Key: $API_KEY" \
  "https://your-deployment.example/api/v1/agents/b5f0f2c8-1c2b-4bb5-836b-9b4e2f86b743/timeline/"

To observe a reply to a submitted message, use its creation response's event.cursor as after_cursor. Fetching the timeline afterward and starting from newest_cursor can skip a reply that has already arrived. The wait is capped at 30 seconds, returns immediately when a matching event appears, and always supplies latest_cursor for the next call. An event at the exact after_cursor is excluded.

curl -X POST \
  -H "Content-Type: application/json" \
  -H "X-Api-Key: $API_KEY" \
  -d '{
    "after_cursor": "1720000000000000:message:0b1fbb92-c018-4814-a57f-c80b24e3eb87",
    "timeout_seconds": 30,
    "event_types": ["message"],
    "filters": {"from_actor_type": "agent", "channel": "email"}
  }' \
  https://your-deployment.example/api/v1/agents/b5f0f2c8-1c2b-4bb5-836b-9b4e2f86b743/events/wait/

Supported event types are message, steps, thinking, and plan. Filters support from_actor_type, from_agent_id, to_agent_id, message_id, peer_link_id, channel, status, and tool_name. This is a read-only operation and accepts an agents:read key despite using POST.

For operational diagnosis, request a sanitized debug trace. include accepts repeated or comma-separated section names: timeline, audit_events, completions, eval_debug_artifacts, and diagnostics.

curl -H "X-Api-Key: $API_KEY" \
  "https://your-deployment.example/api/v1/agents/b5f0f2c8-1c2b-4bb5-836b-9b4e2f86b743/debug-trace/?include=timeline,diagnostics&detail=standard&recent_minutes=60"

Traces are limited to a seven-day window and never return raw prompt archives. Common credential patterns and secret-bearing fields are recursively redacted. Use recent_minutes=null to disable the default 60-minute window while retaining result limits, or supply since and until as ISO 8601 timestamps.

Check the current processing snapshot:

curl -H "X-Api-Key: $API_KEY" \
  https://your-deployment.example/api/v1/agents/b5f0f2c8-1c2b-4bb5-836b-9b4e2f86b743/processing-status/
{
  "processing_active": false,
  "processing_snapshot": {
    "active": false,
    "webTasks": [],
    "nextScheduledAt": "2024-07-02T13:00:00Z"
  }
}

Stop current work without changing the agent's active configuration:

curl -X POST -H "X-Api-Key: $API_KEY" \
  https://your-deployment.example/api/v1/agents/b5f0f2c8-1c2b-4bb5-836b-9b4e2f86b743/stop/

The response reports whether a running loop is still stopping, how many active browser tasks were cancelled, and the latest processing snapshot. Repeating the request is safe; once the agent is idle, the cancellation count is 0.

For cursor bounds, exact wait filters, response envelopes, and reply correlation, see Timeline and events.

Validate a schedule​

Verify a cron-like primary schedule string and get a friendly description. The schedule field is required in this preview body; null, an empty string or whitespace returns valid: true, disabled: true, and description: null. Preview checks format and interval representability without saving or enforcing the owner's minimum schedule interval. Oversized interval components, overflowing combined durations and intervals whose next date exceeds the scheduler's supported date range return HTTP 400 with a schedule field error. Creation/update use the same interval validation. There is no fixed eight-year maximum for the primary cadence; the named REST schedule limit is separate:

curl -X POST \
  -H "Content-Type: application/json" \
  -H "X-Api-Key: $API_KEY" \
  -d '{"schedule": "0 9 * * 1-5"}' \
  https://your-deployment.example/api/v1/agents/b5f0f2c8-1c2b-4bb5-836b-9b4e2f86b743/schedule/preview/

Example response:

{
  "valid": true,
  "disabled": false,
  "description": "At 09:00 on Monday, Tuesday, Wednesday, Thursday, and Friday"
}

This route controls one primary recurring cadence. Named schedules and one-time reminders have a separately gated REST workflow, or you can ask the agent to configure them with send_agent_message. Follow progress through the timeline or wait tools. Those schedules are included when nextScheduledAt is calculated; an invalid stored primary interval has an unknown next date until corrected.

Reproducible inactive setup​

Use the configuration and named-schedule workflow for direct Team placement, conditional inactive configuration, explicit named scheduling, permitted bindings and browser setup handoffs. Inactive creation skips initial processing publication and the default first-check-in timer; metadata jobs remain. A null primary cadence or proactive opt-out on active creation does not suppress its initial work.

Last updated on