API reference
Implemented Arc0 REST endpoints, MCP tools, authentication and execution receipts.
Use the configured Arc0 API origin. Local development uses http://localhost:4312.
REST requests authenticate with Authorization: Bearer <API key>. MCP OAuth uses a bearer access
token; MCP's configured-key alternative uses x-api-key, keeping invalid OAuth tokens from
falling back to API-key authentication.
Public component status
Unauthenticated GET /v1/status on the API origin returns:
{"status":"operational","components":{"api":"operational","storage":"operational"}}Completed probe results are cached for 30 seconds. While a probe is pending, the
previous component health is served with a one-second expiry (degraded without a
previous sample), and late completion updates the cache immediately.
HTTP 200 means the document is available;
inspect status and components.storage for operational or degraded.
This is an API/storage availability check, not a provider, worker or global uptime report.
No credentials, customer state or internal diagnostics are included.
Management API and OpenAPI
Download the OpenAPI 3.1 specification. The API also serves the same
specification at https://api.arc0.ai/openapi.json. It describes the public status endpoint and management operation
catalog; the runtime and embedded-session endpoints below retain their existing contracts.
Management requests use a server-held business key through Authorization: Bearer or
x-api-key. Organization and project come from that key; requests cannot select another
tenant. User-bound runtime keys cannot call management operations. Each operation lists its
required scopes in x-arc0-scopes; manage implies read only where the API-key scope catalog
explicitly defines that implication. Project discovery returns only the key's bound project
and requires apps:read.
Management responses return {data}. Paginated reads take limit (1–100, default 50 unless specified otherwise) and
cursor, returning {data, nextCursor}. Cursors belong to one operation, project and filter
set. Errors return {error: {code, message, requestId}}. End-user references in management
operations accept an internal ID or external:<external ID>; resolution stays inside the
key's project.
Management PUT operations are naturally idempotent and do not save responses for header-based
replay. Send an Idempotency-Key header on management POST requests to replay the first successful
result within 24 hours. Reusing it with different input returns 409 idempotency_conflict. The key is scoped
to the calling key, project and operation. Responses are retained encrypted; retry records
commit atomically with the write. Failed transactions can be retried. After 24 hours, a retained record returns 410 idempotency_expired;
reconcile the original action before resubmitting. The worker automatically purges expired records in bounded maintenance batches,
after which that header value may be reused. Key creation and rotation
replays return the original secret, so keep retry headers and responses in your backend.
The catalog includes project reads, users, groups and memberships, project app configuration
(/v1/project-apps), tools and pins (/v1/project-tools), auth configurations and MCP OAuth clients/branding, Connect branding
and domains, policies, approvals, audit, usage and API keys. GET /v1/audit supports event,
actorId and resourceId filters. Auth configuration secrets are write-only. Key management
cannot create or rotate a key with broader scopes or a longer lifetime than the caller.
The console uses the same services and retains its session authorization.
Connect sessions, return origins, embedded tickets, connection management, events and custom
sources continue to use their existing contracts documented below and in their guides.
Return-origin reads accept connect_settings:read, writes require connect_settings:manage;
embedded:manage remains a compatibility grant for those two endpoints only.
Console search and auth configs
Signed-in console sessions can read GET /v1/orgs/:orgId/projects/:projectId/search or
GET /v1/orgs/:orgId/direct/search. These are session endpoints on the Core origin,
separate from the API-key management OpenAPI catalog. They accept q (trimmed, at most
300 characters) and limit (1–20, default 5 per group). An empty query returns empty groups.
Responses contain {apps, tools, connections}: app IDs/names; tool IDs/names with
appId/appName; and connection IDs, display names, app IDs/names, end-user IDs and status.
Search checks membership and project scope, filters private and preview catalog entries,
and restricts Direct connections to the signed-in user. It returns no credentials or tool
payloads, does not enable tools or pin versions, and disables response caching. A session can make 60 search requests per minute across
project and Direct contexts; excess requests return 429 search_rate_limited and
Retry-After. The existing IP limit also applies.
The project Auth configs page combines existing app, connection-form, OAuth-client and connection metadata. It shows each visible authentication lane, configuration source, connection count and enabled status, with links to OAuth client settings. Secrets remain write-only. Its timestamp column describes the last recorded configuration change; when a reliable change timestamp is unavailable, the page says so rather than inferring one from connection activity. Project settings can copy the project ID or an allowlisted debug bundle containing project, organization, member and app version identifiers for support.
Usage aggregates and execution logs
GET /v1/usage/summary requires usage:read and returns {data} with tool-call count,
error count and rate, distinct active end users, funded wallet spend, daily UTC call counts,
and the top apps and end users. range accepts 7d, 30d (default), or 90d.
Funded spend is a USD micro-unit string from settled ledger charges, excluding credits,
reservations and releases. Activity totals describe the selected window; they are separate
from billable connected-user counts and subscription invoices.
GET /v1/execution-logs requires audit:read. Filter by range, app, endUserId,
status, or exact action; use limit (default 100) and cursor to page through results. Rows include
start/finish times and duration_ms (null while unfinished). These are redacted execution
metadata: no arguments, provider response bodies, credentials or tokens are returned.
GET /v1/execution-logs/:id retrieves the same metadata for one call, including calls
outside the list window, and requires audit:read. These endpoints inherit the business
key's organization/project binding.
The signed-in console exposes the same summary at organization and project scope, and a self-bound summary in Direct workspaces. Its execution log supports the same filters and an optional polling live tail. The details drawer shows metadata only.
| Operation | Method and path | Required scopes |
|---|---|---|
| get funded access | GET /v1/funded-access | funded_access:read |
| set funded access | PUT /v1/funded-access | funded_access:manage |
| get mcp oauth settings | GET /v1/mcp-oauth-clients | auth_configs:read |
| create mcp oauth client | POST /v1/mcp-oauth-clients | auth_configs:manage |
| rotate mcp oauth client | POST /v1/mcp-oauth-clients/{id}/rotate | auth_configs:manage |
| retire mcp oauth client | POST /v1/mcp-oauth-clients/{id}/retire | auth_configs:manage |
| select mcp oauth client | POST /v1/mcp-oauth-clients/{id}/select | auth_configs:manage |
| update mcp client branding | PUT /v1/mcp-client-branding | auth_configs:manage |
| create auth config | POST /v1/auth-configs | auth_configs:manage |
| list auth configs | GET /v1/auth-configs | auth_configs:read |
| disable auth config | POST /v1/auth-configs/{id}/disable | auth_configs:manage |
| get approval | GET /v1/approvals/{approvalId} | approvals:read |
| decide approval | POST /v1/approvals/{approvalId}/decision | approvals:decide |
| get connect settings | GET /v1/connect-settings | connect_settings:read |
| update connect branding | PUT /v1/connect-settings | connect_settings:manage |
| create connect domain | POST /v1/connect-settings/domains | connect_settings:manage |
| verify connect domain | POST /v1/connect-settings/domains/{domainId}/verify | connect_settings:manage |
| list projects | GET /v1/projects | apps:read |
| list end users | GET /v1/users | users:read |
| create end user | POST /v1/users | users:manage |
| get end user | GET /v1/users/{endUserId} | users:read |
| set end user | PUT /v1/users/{id} | users:manage |
| list groups | GET /v1/groups | users:read |
| create group | POST /v1/groups | users:manage |
| set group | PUT /v1/groups/{id} | users:manage |
| list group memberships | GET /v1/memberships | users:read |
| add group member | POST /v1/groups/{groupId}/members | users:manage |
| remove group member | DELETE /v1/groups/{groupId}/members/{endUserId} | users:manage |
| list project connections | GET /v1/project-connections | connections:read |
| list project apps | GET /v1/project-apps | apps:read |
| enable app | POST /v1/project-apps | apps:manage |
| list tools | GET /v1/project-tools | apps:read |
| configure tool | PUT /v1/project-tools | apps:manage |
| pin tool | POST /v1/project-tools/{action}/pin | apps:manage |
| select auth config | PUT /v1/project-apps/{app}/oauth-config | auth_configs:manage |
| get policy | GET /v1/policy | policies:read |
| update policy | PUT /v1/policy | policies:manage |
| list approvals | GET /v1/approvals | approvals:read |
| get audit | GET /v1/audit | audit:read |
| get usage summary | GET /v1/usage/summary | usage:read |
| list live sessions | GET /v1/live-sessions | audit:read |
| list execution logs | GET /v1/execution-logs | audit:read |
| get execution log | GET /v1/execution-logs/{id} | audit:read |
| get usage | GET /v1/usage | usage:read |
| list api keys | GET /v1/keys | keys:manage |
| create api key | POST /v1/keys | keys:manage |
| rotate api key | POST /v1/keys/{id}/rotate | keys:manage |
| revoke api key | DELETE /v1/keys/{id} | keys:manage |
| Create a short-lived hosted Arc0 Connect session for an existing end user. Returns a short-lived bearer capability URL with its token in the fragment, not provider credentials. Hand this link straight to the intended end user; never browse/fetch it, log it, commit it, or use it as agent authorization. Register return origins first when supplying a return URL. | POST /v1/management/connect-sessions | connect:create |
| Search the supported app catalog by name or ID. Returns up to 50 matches; enabling an app is a separate operation. | GET /v1/management/catalog | apps:read |
| Replace the complete allowed browser-origin list for embedded management. Supply exact origins, at most 20; Production requires HTTPS. Existing origins omitted here are removed. | PUT /v1/management/embedded-origins | embedded:manage |
| Replace the complete allowed return-origin list for hosted Connect sessions. Supply exact origins, at most 20; Production requires HTTPS. Existing origins omitted here are removed. | PUT /v1/management/return-origins | connect_settings:manage |
| Create an organization-owned HTTPS webhook endpoint. The signing secret is available only through the console; use send_test_event and get_webhook_test to verify delivery. | POST /v1/management/webhooks | events:manage |
| Queue one signed arc0.test webhook probe for an enabled organization-owned endpoint. One outstanding probe per project and at most one per minute per endpoint are allowed. Delivery is asynchronous; poll get_webhook_test. | POST /v1/management/webhook-tests | events:manage |
| Read the pending, sending, delivered or failed state and HTTP status of a queued webhook probe. An uncertain sending state does not prove receipt and is never retried automatically. | GET /v1/management/webhook-tests/{id} | events:manage |
| Inspect project setup readiness: keys, apps, branding, origins, webhooks and a delivered probe, BYO OAuth, and signing configuration. Returns booleans only; Development readiness does not prove Production/provider acceptance. | GET /v1/management/setup-status | apps:readconnect_settings:readauth_configs:read |
| Read project OAuth user verification settings | GET /v1/oauth-user-verification | connect_settings:read |
| Set project OAuth user verification URL and return a new signing key once | PUT /v1/oauth-user-verification | connect_settings:manage |
| get project webhook | GET /v1/management/project-webhooks | events:manage |
| save project webhook | PUT /v1/management/project-webhooks | events:manage |
| test project webhook | POST /v1/management/project-webhooks/test | events:manage |
| list project webhook deliveries | GET /v1/management/project-webhooks/deliveries | events:manage |
| Pending, unexpired invitations to the verified signed-in email across workspaces. | GET /v1/account/invitations | See API schema |
| Leave a workspace after confirming its name. The last owner cannot leave. | POST /v1/orgs/{orgId}/leave | See API schema |
| Owner transfers workspace ownership to an existing member and becomes an administrator. Personal connections do not transfer. Requires a current session created within the last 10 minutes. | POST /v1/orgs/{orgId}/transfer-ownership | See API schema |
| Owner lists current active members and their explicit monthly funded caps in USD micros (string; null means inherited workspace settings). New collaborators default to zero. | GET /v1/orgs/{orgId}/direct/member-funded-caps | See API schema |
| Owner explicitly approves a nonnegative monthly funded cap for one active collaborator. Workspace funding, budgets and wallet balance still apply. | PUT /v1/orgs/{orgId}/direct/member-funded-caps/{memberId} | See API schema |
| List sharing settings, active member recipients and the caller's own outgoing connection grants. | GET /v1/orgs/{orgId}/direct/sharing | See API schema |
| Owner/admin opts into workspace sharing. Disabling revokes grants; re-enabling never restores consent. | PUT /v1/orgs/{orgId}/direct/sharing | See API schema |
| Connection owner explicitly consents to sharing one account with one active workspace member. No credential export or spend authority is granted. | POST /v1/orgs/{orgId}/direct/connections/{connectionId}/shares | See API schema |
| Connection owner revokes one explicit shared-use grant. | DELETE /v1/orgs/{orgId}/direct/connections/{connectionId}/shares/{grantId} | See API schema |
| Public API and storage component availability (30s cache; 1s while probing). | GET /v1/status | None (public) |
REST endpoints
| Method and path | Purpose | Request |
|---|---|---|
GET /v1/tools | Read the scoped Apps/Tools catalog and configured access | No body |
POST /v1/actions/search | Search tools or retrieve an exact versioned schema | query, optional app, action, version, limit; acting user where required |
POST /v1/execute | Execute through policy, credentials and usage tracking | action, actionVersion, arguments, idempotencyKey; optional account selection and priceVersionId to reject price drift |
GET /v1/executions/:executionId | Retrieve a caller-bound execution receipt | Acting-user query parameter for an unbound management key |
POST /v1/connect | Start hosted connection setup | app, acting user and any supported connection options |
POST /v1/connect-sessions | Create a short-lived multi-app Connect session | Exactly one of endUserId or externalUserId; optional apps, catalogFilter, authMethod, returnUrl, state, expiresInSeconds; server-held connect key |
GET /v1/apps | List enabled apps and the selected user's connection state | Exactly one of endUserId or externalUserId; server-held connections:manage key |
GET /v1/connect-sessions/return-origins | Read the project's exact return-origin registrations | Server-held embedded:manage key |
PUT /v1/connect-sessions/return-origins | Replace the project's return-origin registrations | {origins: [...]}; server-held embedded:manage key |
POST /v1/proxy | Call an approved provider path through its mapped tool | app, method: "GET", path, endUserId, idempotencyKey, optional connectionId |
POST /v1/users/upsert | Provision an Embedded end user idempotently | externalId, name; unbound Embedded key with users:manage |
GET /v1/connections | List one Embedded end user's private connections | endUserId, optional cursor, limit (1–100); connections:manage |
POST /v1/connections/:id/revoke | Revoke that user's connection | endUserId; connections:manage |
POST /v1/users/:endUserId/keys | Mint a short-lived user-bound runtime key | name, optional permissions (execute, connect), optional expiresIn (60–86,400 seconds); server-side mcp:keys issuer |
POST /v1/mcp/authorization-tickets | Issue a one-use Embedded identity-link ticket | See MCP clients; management authorization is required |
The server derives organization and project from the key. The acting user is the internal
project-scoped endUserId, not an email address or an external account identifier. Self-bound
keys supply that identity automatically; they cannot impersonate another user. Operations also
require the appropriate execute or connect permission.
search returns { "tools": [...] }. Each result names the action, immutable version, app,
risk, selected access source and readiness. An exact action lookup also returns inputSchema
and outputSchema. Search currently uses scoped PostgreSQL lexical ranking; semantic retrieval
and reranking are planned improvements.
Runtime keys return { id, key, endUserId, expiresIn }. They inherit live parent authority;
see Embedded identity for issuance, permissions and revocation.
The SDK execution clients accept these keys; minting is a server-side REST operation.
Embedded user and connection management
Use a server-held Embedded integration key. users:manage and connections:manage are
management permissions; Direct keys and delegated user runtime keys cannot use these endpoints.
Provisioning returns { id, externalId, name, status }. The same external ID in the same project
returns the same user, updates its name, and never reactivates a disabled user.
Connection listing returns { items, nextCursor }. Each item contains only id, app,
displayName, status, and authMethod. Group-owned connections and provider credentials are
excluded. Revocation returns { ok: true }; local execution access stops while provider token
retirement may finish asynchronously. Poll the connection status before claiming provider cleanup.
Resolve the acting user from your authenticated server session. Never accept an arbitrary
endUserId from an end-user browser. See the TypeScript client.
Connect sessions return { id, url, expiresAt }, expire after 60–600 seconds, and authorize
one app selection. External IDs must already be provisioned in the same project. Return URLs
must match a registered exact origin. The apps catalog returns { items } with presentation,
supported authentication methods and the selected user's personal connection status; it does
not expose provider credentials or group connections. These endpoints reject browser Origin
headers and user-bound runtime keys. See Arc0 Connect for selection,
reconnect restrictions, return signals and signed connection lifecycle events. Hosted catalog
and browser client availability is tracked separately from this implemented backend contract.
Execution receipts
{
"id": "2d6ab915-f55c-47c1-a6f1-132bba8dfe3f",
"actionVersion": "1",
"status": "succeeded",
"result": {},
"error": null,
"replayed": false
}Possible states include pending, awaiting_approval, running, succeeded, denied, failed
and outcome_unknown. An approval receipt can include approvalId. Provider result content is
untrusted data; a successful transport response is not a reason to execute instructions found in it.
Use the receipt's id for result retrieval. Keep the original idempotency key when retrying the
same execution. Results can expire or become inaccessible after access changes; a historical
success does not grant permanent access to its data.
HTTP admission failures use { "error": "code" }. Execution failures may instead be represented
by the receipt's status and error, so inspect both the HTTP status and returned receipt.
MCP
POST /mcp provides stateless Streamable HTTP. User-bound paths of the form
/mcp/p/:projectId/u/:endUserId must match the authenticated binding. OAuth metadata is available
at /.well-known/oauth-protected-resource/mcp.
| Tool | Arguments |
|---|---|
search_actions | Optional query, app, action, version, limit, Embedded groupId |
manage_connections | operation: list, list_apps, status, connect, reconnect or revoke; app and optional authMethod/non-secret config for connect; connectionId for status/reconnect/revoke; confirm: true for revoke |
arc0_help | Optional query (up to 500 characters) searches end-user docs and returns excerpts with source links |
execute_action | action, actionVersion, arguments, idempotencyKey, optional connectionId, Embedded groupId |
get_execution | executionId |
MCP calls derive the acting user from the authenticated binding. Tool failures use MCP
isError: true with a structured error code in the text content. Approved selected tools may
also be exposed individually with version-qualified names.
Connection self-service exposes only the authenticated user's own connections in the
authenticated project. groupId and caller-supplied user/project selectors are rejected;
group-owned and granted/shared credentials are invisible here. Runtime keys require
connect permission for connect, reconnect and revoke. Revoke also requires explicit user
confirmation of the selected account. Its destructive annotation applies to the whole
manage_connections tool; arc0_help is read-only. See the
end-user guide.
Dashboard and operations
Dashboard management endpoints use Better Auth sessions and organization membership, not the
public execution key. Organization billing uses GET /v1/orgs/:orgId/billing and owner/admin
POST endpoints ending in /billing/checkout or /billing/portal. These run on the core origin,
which is http://localhost:4311 in local development.
Dodo subscription callbacks arrive at POST /v1/billing/dodo/webhook on the API origin and require
verified Standard Webhooks signatures. They are not customer-authenticated plan-change endpoints.
Project notifications and account access
Project-bound business keys with events:manage use the catalog operations
GET/PUT /v1/management/project-webhooks,
POST /v1/management/project-webhooks/test, and
GET /v1/management/project-webhooks/deliveries. These return {data}; the deliveries
read returns the latest 100 records. Signing secrets are available only through the console.
Settings reads include dropped_count and last_dropped_at for the 1,000-delivery queue
limit. Sending a test returns the outstanding test ID if one exists, or HTTP 409 when
the queue is full. See Project webhooks for HMAC verification,
event coverage, retention and fair dispatch limits.
On the Core origin, owner/admin dashboard sessions use
GET/PUT /v1/orgs/:orgId/projects/:projectId/webhooks,
POST /v1/orgs/:orgId/projects/:projectId/webhooks/rotate-secret,
POST /v1/orgs/:orgId/projects/:projectId/webhooks/test, and
GET /v1/orgs/:orgId/projects/:projectId/webhooks/deliveries.
Create and rotate responses disclose the signing secret once; settings reads do not.
Account-wide GET /v1/account/keys lists the signed-in user's issued key metadata
only in organizations where they are still a member;
DELETE /v1/account/keys/:id revokes only a key issued by that user, including by
known ID after membership ends as a kill-switch. Browser sessions
and runtime/management MCP authorizations retain their existing revoke APIs. These are
session-authenticated Core endpoints, outside the business-key OpenAPI catalog.
See Sessions, access and support.
GET /v1/users includes owned connection health counts and last execution activity,
and accepts an optional health=active|expired|failed|inactive filter.
Wallet and funded access
These endpoints run on the Core origin, using an authenticated dashboard session rather than an execution API key. Wallet metadata, ledger, activity, billing history and funded-access reads require organization membership. Organization billing, top-up and limit operations require owner/admin membership. Mutations require the configured dashboard Origin. The grant endpoints use the signed-in Arc0 user's identity; a claim also requires verified email and the user's eligible first-created organization.
| Method and path | Purpose | Request / response |
|---|---|---|
GET /v1/wallet/grant | Read starting-credit eligibility and claim status | {currency, amountMicros, organizationId, eligible, claimed, claimedAt, reason} |
POST /v1/wallet/grant | Claim configured starting credit once | {}; repeats return the original claim |
GET /v1/orgs/:orgId/billing | Read plan, projects, funded limits and wallet | Wallet includes available, held and spent amounts plus ledger entries |
GET /v1/orgs/:orgId/wallet | Read wallet and organization mode | Members; includes canManage for billing controls |
GET /v1/orgs/:orgId/wallet/activity | Recent funded executions and settled spend | range=7d|30d|90d, chargedOnly=true|false, optional numeric before; {calls, nextBefore, spentMicros, topTools} |
GET /v1/orgs/:orgId/wallet/executions/:executionId | Redacted funded-call metadata across organization projects | Member; required projectId; non-funded calls remain inaccessible |
GET /v1/orgs/:orgId/wallet/history | Signup grants, Dodo top-ups, adjustments and refunds | Optional numeric before; {items, nextBefore} from credit ledger entries |
GET /v1/orgs/:orgId/funded-access | Read organization Instant switch | Members; {enabled} |
PUT /v1/orgs/:orgId/funded-access | Turn organization funded access on/off | Owners/admins; {enabled: boolean}; audited |
GET /v1/orgs/:orgId/wallet/ledger | Read wallet balance and ledger history | Optional before ledger ID; {currency, availableMicros, heldMicros, spentMicros, ledger, nextBefore} |
POST /v1/orgs/:orgId/billing/topup | Create or recover a Dodo top-up checkout | {requestId: "<UUID>", amountCents: 1000} → {checkoutUrl, sessionId} |
PUT /v1/orgs/:orgId/projects/:projectId/funded-limits | Set project/default-user or individual-user monthly limits | {monthlyMicros: number | null, defaultEndUserMicros?: number | null, endUserId?: string} → {ok: true} |
Wallet balances are integer micro-USD strings (1 USD = 1,000,000 micros). Limit inputs are
nonnegative safe integers or null; omit endUserId for project/default-user limits. An
individual-user limit cannot include defaultEndUserMicros. Limits use UTC calendar months.
Ledger pagination uses the returned nextBefore value, ending at null.
Top-ups default to $10 and accept $10 multiples up to $10,000, subject to configured Dodo
product availability. Reuse the same requestId only for the same checkout intent. Returning
from checkout does not credit the wallet: a matching verified payment webhook does, with
payment-ID deduplication. Starting credit defaults to $2 per verified Arc0 user and can be
configured or disabled; display the amount and eligibility returned by grant status.
Funded execution still uses the ordinary search/execute endpoints. Inspect the selected offer's published per-call price and immutable price version before executing. Admission reserves the maximum charge; a dispatched failure or unknown outcome can consume it. Wallet balance, monthly limits and bounded provider quota must all permit the call. A free connectivity plan or Development project does not make funded provider consumption free. Provider activation, permission and real payment acceptance remain separate gates. See Billing.
REST walkthrough
Search, execute, retry and read a receipt.
Arc0 MCP
Authenticate agent clients and discover tools.
TypeScript SDK
Typed search and execution.
Python SDK
Python clients and stable retries.
App events
Project API keys use the event endpoints below. Lists return { items, nextCursor } with limit (1–50)
and an optional cursor; trigger discovery returns { items }. Event management requires
an authorized event-management key. Self-bound callers remain restricted to their end user.
| Method | Path | Purpose |
|---|---|---|
| GET | /v1/events/triggers | Available trigger versions and configuration schemas |
| GET, POST | /v1/events/subscriptions | List or create subscriptions |
| GET | /v1/events/subscriptions/:id | Subscription details |
| POST | /v1/events/subscriptions/:id/state | Set active, paused or archived state |
| GET, POST | /v1/events/endpoints | List or create destinations; creation returns a secret once |
| POST | /v1/events/endpoints/:id/state | Enable or disable a destination |
| POST | /v1/events/endpoints/:id/rotate-secret | Rotate the destination signing secret |
| GET, POST | /v1/events/routes | List or connect subscriptions and destinations |
| POST | /v1/events/routes/:id/state | Enable or disable a route |
| GET | /v1/events/records | Retained event metadata |
| GET | /v1/events/records/:id | Event payload, or 410 after expiry |
| GET | /v1/events/deliveries | Delivery history; filter by subscriptionId, endpointId or state |
| GET | /v1/events/deliveries/:id | Delivery details and attempt history |
| POST | /v1/events/deliveries/:id/replay | Create another delivery generation |
See App events for setup and SDK examples.
Private tools and execution helpers
| Method | Path | Purpose |
|---|---|---|
| GET, POST | /v1/action-sources | List or register a private app implementation |
| GET | /v1/action-sources/:id | Source details and published tools; no credentials |
| POST | /v1/action-sources/:id/sync | Prepare a candidate revision |
| GET | /v1/action-sources/:id/candidates | Review candidate schemas |
| POST | /v1/action-sources/:id/publish | Publish explicitly selected tools and risk classifications |
| POST | /v1/action-sources/:id/pins | Pin a source tool's version and credential selection |
| POST | /v1/action-sources/:id/state | Enable or disable a source |
| POST | /v1/actions/:action/draft-arguments | Return a validated argument draft without execution |
| POST | /v1/execution-batches | Create an idempotent ordered batch, maximum ten steps |
| GET | /v1/execution-batches/:id | Batch state and child receipts |
| POST | /v1/execution-batches/:id/resume | Advance eligible work under current authority |
| POST | /v1/execution-batches/:id/cancel | Cancel remaining work |
| POST | /v1/local-executions/prepare | Authorize an SDK-local call or request approval |
| POST | /v1/local-executions/:id/complete | Submit a caller-reported result using its completion claim |
Source management requires sources:manage; it does not imply execution permission. Private
source ownership and the caller's existing subject binding apply to every operation. See
Custom apps and Execution helpers for SDK examples.
Sessions, compute and retained files
Upcoming: hosted compute is deferred to a future release. These endpoints describe the local development implementation and require a configured runner.
These operations require execution authority and retain the original caller and subject binding. See Workbench for limits, lifecycle and examples.
| Method | Path | Purpose |
|---|---|---|
| GET / POST | /v1/agent-sessions | List owned sessions or create a session with tool/version allowlist, connection aliases and optional limits |
| GET | /v1/agent-sessions/:id | Read session metadata and configuration |
| POST | /v1/agent-sessions/:id/config | Save a narrowed immutable configuration revision |
| POST | /v1/agent-sessions/:id/close | Close compute authority; retain authorized file access |
| POST | /v1/agent-sessions/:id/restart | Replace compute generation with explicit artifactIds to restore |
| POST | /v1/agent-sessions/:id/runs | Queue {language, code, idempotencyKey, artifactIds?} |
| GET | /v1/agent-sessions/:id/runs/:runId | Read an authorized run receipt and bounded output |
| GET / POST | /v1/agent-sessions/:id/artifacts | List metadata or upload {name, dataBase64, mimeType?} within the file limit |
| GET / DELETE | /v1/agent-sessions/:id/artifacts/:artifactId | Read metadata or delete a retained file |
| GET | /v1/agent-sessions/:id/artifacts/:artifactId/download | Download authenticated binary contents |
Session and artifact lists return {items, nextCursor} with opaque cursor and bounded limit
parameters. List responses never contain file bytes or submitted code. Reuse a run's idempotency
key only for an identical submission; never automatically rerun an uncertain operation.
Public documentation MCP
POST /docs/mcp is a separate, unauthenticated, read-only Streamable HTTP server
prepared for release on the API origin. It exposes search_docs({query, limit?})
and read_doc({slug}) over public documentation only, with no customer-data access.
Until deployed, use the local API endpoint or Markdown docs. See
Build with your coding agent.
The management REST catalog, generated OpenAPI and audit reads are documented above. The management MCP and its setup-status tools use the same Embedded project authority as the management REST catalog.
Organization funded-access setting
The management catalog exposes GET /v1/funded-access with funded_access:read and
PUT /v1/funded-access with funded_access:manage. Both use {enabled: boolean}.
Writes require the originating key owner's current owner/admin membership. Management MCP
exposes get_funded_access and set_funded_access; changing this organization-wide setting
requires human proposal approval in both Sandbox and Live.
When disabled, new funded executions fail with funded_access_disabled before reservation.
Existing reservations may settle or release. Wallet reads expose fundedEnabled,
minimumReservationMicros and accessState (off, paused, ready, unavailable).
paused means the balance cannot cover the cheapest currently funded per-call reservation.
Spend windows use settled ledger entries, independently of execution creation time. Charged-call
rows show a single customer amount; switching off charged-only also shows reserved and released calls.
Direct wallet activity, top-tool aggregates and funded-call details are self-bound for ordinary
members, matching the Direct execution log. Owners/admins can inspect organization-wide funded
activity. The full_access API-key preset excludes funded_access:manage; choose that scope
explicitly to allow organization funded-access changes. Org-level funded-access audit events
are exported to every enabled OTel destination within the organization.
Ordinary Direct members' wallet ledger pages contain organization credit entries and only their own reservation, settlement and release entries. Filtering applies before pagination; wallet balance totals remain organization-wide. Owners/admins retain organization-wide ledger history.
Personal workspaces and organization lifecycle
These Core console APIs use a signed-in Arc0 session, rather than a business API key.
Mutations require the console Origin header. The generated OpenAPI marks their server as
Core and their authentication as loginSession.
| Method and path | Purpose |
|---|---|
GET /v1/account/invitations | Pending, unexpired invitations to your verified login email across organizations. |
POST /v1/orgs/{orgId}/leave | Leave with {confirmation: "exact workspace name"}. The last owner cannot leave. |
POST /v1/orgs/{orgId}/transfer-ownership | Owner confirms workspace name and targetMemberId; target becomes owner and initiating owner becomes admin. |
GET /v1/orgs/{orgId}/direct/sharing | Workspace sharing setting, active recipients and your outgoing grants. |
PUT /v1/orgs/{orgId}/direct/sharing | Owner/admin sets {enabled: boolean}. Disabling revokes grants; enabling does not restore them. |
POST /v1/orgs/{orgId}/direct/connections/{connectionId}/shares | Connection owner grants use to an active memberId, with explicit confirm: true consent. |
DELETE /v1/orgs/{orgId}/direct/connections/{connectionId}/shares/{grantId} | Connection owner revokes one shared-use grant. |
Use the Team page to invite a member and share their invitation link. Accepting a Direct invitation requires a verified email; the new collaborator explicitly activates their personal subject before using the workspace. Invitations never share connections. Each connection needs separate owner consent, and a collaborator executes as their own subject. Shared use does not permit credential export or managing the owner's account. Activated collaborators follow the workspace funded-access settings, balance and project/per-subject spending caps. A newly activated Direct collaborator defaults to a monthly cap of zero; an owner explicitly raises it on the members screen. Existing owner/admin subjects keep their limits. Funded calls debit the organization wallet and retain the acting collaborator's subject. Ownership transfer changes administration and does not transfer private accounts.
Leaving or removal retires a Direct member's subject, keys, incoming/outgoing connection grants and owned connections. Rejoining never restores those authorizations. Management MCP grants are revoked on departure in both modes. Embedded business keys continue to follow the existing issuer-offboarding controls; review them when removing colleagues.
The existing management MCP is restricted to Embedded business projects and has no organization membership, invitation, ownership-transfer or connection-grant operations. These personal consent and lifecycle operations remain session-bound; a management grant cannot share a person's private connection or transfer workspace ownership.
Direct owners can read GET /v1/orgs/{orgId}/direct/member-funded-caps and update one current
member through PUT /v1/orgs/{orgId}/direct/member-funded-caps/{memberId} with
{monthlyMicros: number} (a nonnegative safe integer in USD micros). Read amounts are strings;
null means an existing inherited limit. Individual Direct caps are owner-only through the legacy
project funded-limits API too. Changing a cap does not override other funding or policy checks.
Ownership transfer also requires the current stored login session to have been created within
10 minutes. A stale session returns fresh_session_required; sign out and sign in again, then
re-enter the workspace and target confirmation. Background session refresh does not renew freshness.
Live session observations and OAuth user verification
GET /v1/live-sessions groups redacted execution metadata by end user and stored
agent session. It requires a business key with audit:read and returns
{data, nextCursor}. See Live sessions for paging and bounds.
GET and PUT /v1/oauth-user-verification read or configure the optional project
callback. Use connect_settings:read or connect_settings:manage, respectively.
See OAuth user verification for the signed protocol
and the once-only signing key returned on save.