Limits and Compatibility
Supported integration surfaces
| Surface | Intended use |
|---|---|
/api/v1/agents/ | Persistent agent lifecycle, communication, contacts, peer links, status, events, and decisions |
/api/v1/agents/browser-use/, /api/v1/tasks/browser-use/ | Legacy browser profiles and one-off tasks |
/api/v1/mcp/ | Documented JSON-RPC methods and the tool catalog; includes file access |
/api/v1/security/interventions, /api/v1/security/interventions/{id}, /api/v1/security/targets/agent/{id}/control-state | External Security Halt: durable agent halts and enforcement reads using dedicated scoped service credentials; deployment- and Organization-gated |
| Generated inbound webhook URLs | External event ingestion using a URL secret |
/scim/v2/{organization_slug}/ | Organization directory provisioning with its own bearer token |
/api/schema/, /openapi.yaml on the docs site | Runtime REST schema and downloadable docs snapshot |
The Console's /console/api/ and system-settings routes use application-session and administration contracts. Their existence does not make them general public APIs. Provider callback routes, the custom-tool bridge, and computer-device pairing/relay endpoints also have dedicated product protocols; do not use platform API keys as a substitute for their credentials.
External Security Halt supports explicitly scoped Organization-owned agents only. Service credentials have security:halt and/or security:read permissions and require HTTPS by default. The API has no external release operation; recovery requires an authorized human. Routes in the OpenAPI schema do not establish that the deployment gates are enabled or that containment has been validated against the deployed release.
Browser-session tickets are staff-only development tooling, available in local debug, preview, or staging and disabled in production. They are intentionally excluded from the public REST reference. See the repository development guide for their limitations.
The REST file workflow supports gated upload/replacement, status, bounded listing and safe downloads; move/delete and resumable uploads remain deferred. Inactive setup and named schedules support separately gated Team placement, conditional configuration, named-schedule CRUD and permitted existing integration bindings. New credentials, OAuth consent and integration publication retain their human setup flows. Remote MCP provides its documented file and Team/integration controls. A capability visible in the product is not necessarily writable through REST.
Limits
General Organization service credentials require both default-off installation availability and explicit Organization enablement. Their allowlist excludes agent creation, legacy channel messaging, MCP messaging, human approvals and control administration; principal-addressed application requests are a separately gated supported REST workflow. Versions expire within 90 days (deployment policy may lower this); rotation overlap is at most 24 hours with no more than two unrevoked slots. Identity edits accept at most 1,000 explicit agent/Team selections. Service configuration rejects unsupported fields, and service operations serialize within an Organization; no throughput target is published. These are distinct from the dedicated security credentials described above.
| Operation | Current bound |
|---|---|
| REST page-number collections | 10 items by default; page_size at most 100 |
| MCP agent listing | page 1–100,000; page_size 1–100, default 20 |
| REST timeline | 40 by default; limit clamped to 1–100 |
| MCP timeline | 40 by default; limits outside 1–100 rejected |
| Event waits | 10 seconds by default; 0–30 seconds; 20 events by default, at most 100 |
| Recent agent browser tasks | 50 by default; at most 200 |
| Debug trace | 20 by default; at most 50 per section; explicit time window at most seven days |
Legacy task wait | 0–1,350 seconds when general admission is off; omit the field when it is enabled |
| JSON output schema | Maximum traversal depth 40 and 2,000 counted object keys across the schema |
| MCP inline attachments | At most 10 per message |
| MCP control discovery | page 1–10,000; page_size 1–100, default 20 |
| MCP control mutation approval | Approval valid for 10 minutes and subject to current authentication policy; replay record lifetime defaults to 24 hours; at most 100 pending, unexpired requests per key |
| File size | Deployment MAX_FILE_SIZE, default 10 MiB; base64 increases HTTP payload size |
| Idempotency key | At most 255 characters; default replay retention 24 hours |
| External Security Halt create | Strict JSON, at most 16 KiB; event ID 1–160 characters, reason 1–1,000, optional incident reference at most 255 |
| Peer link quota configuration | 1–500 messages per 1–168 hours |
These are application bounds, not promises that every proxy accepts an equally large or long request. Configure HTTP timeouts around bounded waits, and prefer asynchronous task submission. Hosting providers can impose additional request-body and rate limits. The default-off shared admission contract below publishes deployment-configurable quotas and RateLimit-* snapshots; proxy limits and headers remain independent.
Agent execution requires a licensed Organization under default company-license enforcement; new personal agent creation and personal execution are unavailable. Authorized historical reads remain available under their existing ownership and scope checks. All licensed companies have the same product capabilities. Concurrent work, intelligence tiers, communication options and schedule frequencies still depend on deployment configuration and operational runtime policy. Remote MCP get_agent_config_options returns the deployed options; do not infer operational limits from example values or historical plan names.
Request and response conventions
Use UTF-8 JSON with Content-Type: application/json, except for the explicitly documented multipart and SCIM flows. Send API credentials from a trusted client, not a public webpage bundle. Browser-originated MCP requests must satisfy the deployment's origin allowlist; arbitrary origins are not enabled by presenting an API key. A preflight can use OPTIONS and the documented authorization and MCP headers.
Use full endpoint paths with trailing slashes where shown. Agents, tasks, contacts, links, and webhook IDs are UUIDs; Django user IDs are numeric and REST agent user_id is serialized as a decimal string. Timestamps are ISO 8601 and may include Z or an explicit offset. The primary REST schedule has no separate timezone parameter. Treat nested event casing and collection envelopes as endpoint-specific.
External Security Halt routes have no trailing slash. They use dedicated bearer credentials and lifetime service-identity/event deduplication rather than Agent REST API keys and the 24-hour Idempotency-Key replay contract.
Without a selected contract version, ordinary agent/task serializers retain legacy handling of unknown and read-only input fields; retired credit writes still reject. X-API-Contract: 2026-10-14 selects strict inputs on supported create/update routes as described below. External Security Halt rejects unknown root and target fields. Event waits, debug traces, peer-link requests, and Remote MCP tools validate their own supported fields more strictly. Validate client payloads before sending instead of relying on ignored input to change state.
Versions and changes
The REST URL namespace is /api/v1; the OpenAPI info.version is schema metadata. The separate X-API-Contract: 2026-10-14 request header selects the documented strict-input and error contracts on supported routes. Remote MCP reports its protocol version in initialize; the current handler does not negotiate another version or validate the version header. "Legacy" identifies the browser task integration model; no shutdown date or migration deadline is currently specified by this documentation.
For upgrades, compare the schema and MCP tools/list from the deployment you are upgrading. Tolerate additional response fields, handle unknown event kinds, and inspect errors instead of interpreting every 2xx as completed work. Ordinary agent GET returns an ETag; selected PUT/PATCH supports conditional updates with the exact token and retry key behind configuration admission. Legacy writes remain unconditional. Setup resources, outbox actions and SCIM use their own version checks and tokens.
See Availability and deployment gates for features that are off by default. Other compatibility or deprecation guarantees should be stated explicitly when introduced, rather than inferred from endpoint names.
Application request bounds and rollout
Broad REST/MCP history/debug/wait and filespace read/reuse require every application request on the agent to be visible to the current principal/owner and retained. Otherwise use scoped request routes; broad reads return application_request_scope_required. This also limits referenced-attachment admission when an agent carries foreign or purged application history. Exact application attachment resources check all linked source requests and current retention. Shared generated context/general filespace remain outside per-request confidentiality; use separate agents/workspaces for independent context and files.
Application Requests are additive and require default-off API_APPLICATION_REQUESTS_ENABLED for admission. Body is at most 64 KiB UTF-8, reference 255 characters, attachments ten existing UUIDs, lists 40/default and 100/max, waits 30 seconds/max, and detail references 100 per inventory with truncation flags. Cursors bind principal/agent/resource/filter/page size and expire after 24 hours. Without general admission enabled, default application-request wait capacity is four per credential/principal and 32 per effective owner; excess returns 429 with a one-second retry hint. This does not establish a general HTTP/work quota or throughput guarantee. No new MCP request tools, SSE or request cancellation are included. REST files have their own linked contract. Upgrade/drain every instrumented writer and qualify the exact candidate before enabling admission.
Public admission and backpressure
Deployment-configurable API_ADMISSION_ENABLED defaults to false. When enabled, API-credential REST and MCP requests share atomic limits across web processes. A member's user ID or a service's identity ID is intersected with the effective personal/Organization owner; replacing member keys or rotating service versions does not reset limits. Accepted retries still count as HTTP traffic, but never reserve new queued-input capacity. Session routes, SCIM, security halt/human recovery, provider callbacks and internal bridges retain their separate contracts. Stop, deactivate, task cancellation/deletion, pending-action decisions and MCP archive remain outside normal request quotas.
| Setting | Initial default when enabled |
|---|---|
API_ADMISSION_REDIS_URL | Deployment REDIS_URL; real Redis required, no fake/fail-open fallback; 32 connections/process, one-second socket deadlines, no automatic coordinator retries |
API_ADMISSION_WINDOW_SECONDS | 60 seconds, fixed windows using Redis server time |
API_ADMISSION_REQUEST_PRINCIPAL_LIMIT / API_ADMISSION_REQUEST_OWNER_LIMIT | 120 / 600 requests per window |
API_ADMISSION_WAIT_PRINCIPAL_LIMIT / API_ADMISSION_WAIT_OWNER_LIMIT | 4 / 32 concurrent waits |
API_ADMISSION_WORK_PRINCIPAL_LIMIT / API_ADMISSION_WORK_OWNER_LIMIT | 16 / 128 queued public inputs |
Every configured window/cap must be an integer from 1 to 1,000,000. Invalid configuration fails closed. Successful metered requests return RateLimit-Limit (the smaller configured limit), RateLimit-Remaining (the smaller remaining principal/owner allowance at admission) and RateLimit-Reset (seconds until reset). These are snapshots, not capacity reservations or throughput promises. Fixed windows may admit a boundary burst. Proxy/body-size limits, licensing and runtime policy still apply independently.
request_quota_exceeded and wait_capacity_exceeded return HTTP 429. admission_unavailable and work_capacity_exceeded return HTTP 503. Every admission rejection includes Retry-After; request quota retry reflects window reset, wait retry the oldest lease expiry, and coordination/work saturation uses a one-second hint. Add jitter and bounded backoff; the hint does not promise capacity will be ready. Admission rejection occurs before new input mutation. Already accepted input instead retains its publication/execution state and existing recovery.
Application revision waits and REST/MCP timeline waits share paired 35-second leases and retain their 30-second maximum wait. Normal completion, timeout and observed disconnect/error release the exact lease. Enabled timeline state reads use PostgreSQL local one-second lock and two-second statement deadlines, matching application-request snapshot limits; 30 seconds is a polling deadline, with projection/response overhead outside that promise. Leases bound admitted pollers, not a hard count of live server threads under an application/process stall. A process crash or unobserved client disconnect retains it until expiry/handler exit; synchronous HTTP does not provide immediate disconnect detection. Without general admission enabled, application-request retains its original database wait caps. Enforced legacy browser task creation requires omitting wait, including wait: 0; retrieve the accepted task separately.
Queued input capacity covers Application Request input, legacy REST messages, MCP messages with trigger_processing=true, and public browser tasks. The claim commits with input and durable publication and releases only on verified model-input consumption (messages) or actual browser-worker execution claim or non-dispatchable publication cleanup. Broker or message-worker acknowledgement alone does not release it; broker outages therefore retain accepted input and occupy capacity until recovery. Claims never expire by age and a halt/reset never renews their generation. Bounded existing publication sweeps also remove permanently fenced, terminal-task and purged-input claims, then prune empty principal mutexes without deleting live claims. This bounds queued ingress, not running model turns/browser execution, later continuations, agent/profile creation, other ingress channels, webhook delivery, provider concurrency or total deployment throughput. Existing runtime concurrency/lifecycle limits remain independent.
Operators apply 0584_api_admission, upgrade/drain all covered web writers/consumers/Beat, configure consistent Redis/caps, validate in a non-production environment and then explicitly enable enforcement. Redis loss/eviction/restart can reset volatile quotas/leases; use a dedicated durable, no-eviction coordinator where this policy must survive those events. Never clear shared keys while handlers are waiting. Retain database/publication/replay history. manage.py api_admission_status --principal member:USER_ID --owner user:USER_ID reads bounded counters without tokens or bodies; service/Organization namespaces use service:IDENTITY_UUID and org:ORGANIZATION_UUID. Wait diagnostics include expired entries until the next claim prunes them.
Rollback to API_ADMISSION_ENABLED=false stops new enforcement/claims; it preserves accepted work and its existing replay, publication, generation fences and unconditional claim cleanup. Lowering caps never cancels accepted work. Validate load and worker behavior in your deployment; these defaults establish no measured throughput or availability claim.
With general admission enabled, inline MCP message attachments require filesystem-backed default/quarantine intake; remote inline writes return admission_unavailable before storage/input/capacity mutation because that existing path has no prestaging boundary. Already uploaded available file paths remain supported, as does the application-request separately staged attachment path. Direct MCP uploads keep their existing contract. Remote inline prestaging remains a later files increment.
Capacity claims are prospective: only new API-credential inputs admitted while enforcement is enabled are charged. Drain/reconcile pre-enable or unenforced backlog before activation; accepted replay never backfills a claim. Diagnostics count tracked claims, not the complete broker backlog. Session/internal traffic retains its separate contract.
Published input that loses its original owner or is archived is rechecked and blocked before its queued-capacity claim is released. Historical input and its emergency generation remain intact; later restoration does not revive a publication already blocked by that check. MCP resource reads charge the resource's effective owner, including authorized staff targeting through either resource tools or resources/read.
Reproducible configuration limits
Named schedules and inactive setup require default-off API_CONFIGURATION_ENABLED for new REST writes; reads and currently authorized retained replay survive disabling admission. Named-schedule totals, active counts, recurring-day budgets, minimum recurrence and one-time lead use existing deployment/owner policy. REST placement rejects historical work and populated/shared filespaces; binding controls never export or borrow credentials. Configuration readiness does not validate workers, network or providers. No availability is implied.
Operational read limits
Usage/audit reads require API_OPERATIONAL_READS_ENABLED and explicit reporting scopes. Windows are at most 31 days, selections at most 10,000 retained rows, pages 1–100 and signed authority-bound cursors 15 minutes. Admission and PostgreSQL query/lock deadlines apply. Null measurements are unknown, not zero; transfer/archive/purge and pending-finalization limits apply. No evidence export, fleet-wide reporting, or invoice accuracy is implied.
Structured application result limits
The default-off structured-result feature adds optional result_schema and a private singleton /requests/{id}/result/ read. Its restricted Draft 2020-12 profile permits no refs, regex or combinators. Schemas: 16 KiB, depth 8, 256 nodes including keys. Results: 64 KiB, depth 16, 4096 nodes. Maximum sixteen advertised contracts and two formatting attempts per request/turn; one immutable version-1 artifact per request. This result contract adds no agent configuration fields, MCP send fields, repair inference or arbitrary file formats. Upgrade/drain instrumented writers and qualify exact deployment/model behavior before enabling API_STRUCTURED_RESULTS_ENABLED; disable prospective admission for rollback while preserving accepted history/runtime/retention. See structured data.
Opt-in strict configuration inputs
X-API-Contract: 2026-10-14 selects strict ordinary persistent-agent/browser-agent create/update and browser-task create/update inputs. Unknown fields and attempted read-only writes reject before mutation with stable field codes; omission retains legacy permissiveness. Declared nested serializers/lists apply the same checks. Arbitrary task output_schema and secrets dictionaries retain their existing schema/size/security validators. External serializer aliases are authoritative (webhook, not webhook_url); no alias becomes another side effect. Deprecated credit writes remain rejected under both modes. Persistent-agent team_id and template_code are creation-only; enabled_personal_server_ids updates are unsupported in the conditional version. Partial updates validate supplied keys only. the strict serializers, SCIM and dedicated security inputs keep their existing rules independent of this header. See errors and configuration.
Browser-task secret updates now persist on pending, unclaimed tasks in both contract modes. A supplied map replaces all task credentials; {} clears them and omission preserves them. Explicit null remains invalid. This corrects earlier 200 responses that discarded secret updates; it does not introduce live credential rotation. Existing rows are not rewritten. Creation/update request schemas distinguish empty-map support and use nested string maps; normalization collisions reject. Encryption unavailability returns a safe 503 task_secrets_unavailable. Deploy matching web handlers/docs/client and drain older web writers before relying on these semantics; older handlers can still acknowledge without saving. Cipher format, member-key scope requirements, service restrictions and worker/generation fences remain unchanged.
Selected create requests check unknown/read-only field shape before returning any retained legacy acceptance. This does not rerun fresh-create quota or uniqueness checks for replay. Omit the version to retain the earlier acceptance's legacy input behavior. Conditional ordinary agent writes also retain the adapter's visibility filters (including its eval-agent exclusion) before both fresh writes and replay.