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.

OperationMethod and pathRequired scopes
get funded accessGET /v1/funded-accessfunded_access:read
set funded accessPUT /v1/funded-accessfunded_access:manage
get mcp oauth settingsGET /v1/mcp-oauth-clientsauth_configs:read
create mcp oauth clientPOST /v1/mcp-oauth-clientsauth_configs:manage
rotate mcp oauth clientPOST /v1/mcp-oauth-clients/{id}/rotateauth_configs:manage
retire mcp oauth clientPOST /v1/mcp-oauth-clients/{id}/retireauth_configs:manage
select mcp oauth clientPOST /v1/mcp-oauth-clients/{id}/selectauth_configs:manage
update mcp client brandingPUT /v1/mcp-client-brandingauth_configs:manage
create auth configPOST /v1/auth-configsauth_configs:manage
list auth configsGET /v1/auth-configsauth_configs:read
disable auth configPOST /v1/auth-configs/{id}/disableauth_configs:manage
get approvalGET /v1/approvals/{approvalId}approvals:read
decide approvalPOST /v1/approvals/{approvalId}/decisionapprovals:decide
get connect settingsGET /v1/connect-settingsconnect_settings:read
update connect brandingPUT /v1/connect-settingsconnect_settings:manage
create connect domainPOST /v1/connect-settings/domainsconnect_settings:manage
verify connect domainPOST /v1/connect-settings/domains/{domainId}/verifyconnect_settings:manage
list projectsGET /v1/projectsapps:read
list end usersGET /v1/usersusers:read
create end userPOST /v1/usersusers:manage
get end userGET /v1/users/{endUserId}users:read
set end userPUT /v1/users/{id}users:manage
list groupsGET /v1/groupsusers:read
create groupPOST /v1/groupsusers:manage
set groupPUT /v1/groups/{id}users:manage
list group membershipsGET /v1/membershipsusers:read
add group memberPOST /v1/groups/{groupId}/membersusers:manage
remove group memberDELETE /v1/groups/{groupId}/members/{endUserId}users:manage
list project connectionsGET /v1/project-connectionsconnections:read
list project appsGET /v1/project-appsapps:read
enable appPOST /v1/project-appsapps:manage
list toolsGET /v1/project-toolsapps:read
configure toolPUT /v1/project-toolsapps:manage
pin toolPOST /v1/project-tools/{action}/pinapps:manage
select auth configPUT /v1/project-apps/{app}/oauth-configauth_configs:manage
get policyGET /v1/policypolicies:read
update policyPUT /v1/policypolicies:manage
list approvalsGET /v1/approvalsapprovals:read
get auditGET /v1/auditaudit:read
get usage summaryGET /v1/usage/summaryusage:read
list live sessionsGET /v1/live-sessionsaudit:read
list execution logsGET /v1/execution-logsaudit:read
get execution logGET /v1/execution-logs/{id}audit:read
get usageGET /v1/usageusage:read
list api keysGET /v1/keyskeys:manage
create api keyPOST /v1/keyskeys:manage
rotate api keyPOST /v1/keys/{id}/rotatekeys:manage
revoke api keyDELETE /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-sessionsconnect: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/catalogapps: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-originsembedded: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-originsconnect_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/webhooksevents: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-testsevents: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-statusapps:readconnect_settings:readauth_configs:read
Read project OAuth user verification settingsGET /v1/oauth-user-verificationconnect_settings:read
Set project OAuth user verification URL and return a new signing key oncePUT /v1/oauth-user-verificationconnect_settings:manage
get project webhookGET /v1/management/project-webhooksevents:manage
save project webhookPUT /v1/management/project-webhooksevents:manage
test project webhookPOST /v1/management/project-webhooks/testevents:manage
list project webhook deliveriesGET /v1/management/project-webhooks/deliveriesevents:manage
Pending, unexpired invitations to the verified signed-in email across workspaces.GET /v1/account/invitationsSee API schema
Leave a workspace after confirming its name. The last owner cannot leave.POST /v1/orgs/{orgId}/leaveSee 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-ownershipSee 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-capsSee 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/sharingSee API schema
Owner/admin opts into workspace sharing. Disabling revokes grants; re-enabling never restores consent.PUT /v1/orgs/{orgId}/direct/sharingSee 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}/sharesSee 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/statusNone (public)

REST endpoints

Method and pathPurposeRequest
GET /v1/toolsRead the scoped Apps/Tools catalog and configured accessNo body
POST /v1/actions/searchSearch tools or retrieve an exact versioned schemaquery, optional app, action, version, limit; acting user where required
POST /v1/executeExecute through policy, credentials and usage trackingaction, actionVersion, arguments, idempotencyKey; optional account selection and priceVersionId to reject price drift
GET /v1/executions/:executionIdRetrieve a caller-bound execution receiptActing-user query parameter for an unbound management key
POST /v1/connectStart hosted connection setupapp, acting user and any supported connection options
POST /v1/connect-sessionsCreate a short-lived multi-app Connect sessionExactly one of endUserId or externalUserId; optional apps, catalogFilter, authMethod, returnUrl, state, expiresInSeconds; server-held connect key
GET /v1/appsList enabled apps and the selected user's connection stateExactly one of endUserId or externalUserId; server-held connections:manage key
GET /v1/connect-sessions/return-originsRead the project's exact return-origin registrationsServer-held embedded:manage key
PUT /v1/connect-sessions/return-originsReplace the project's return-origin registrations{origins: [...]}; server-held embedded:manage key
POST /v1/proxyCall an approved provider path through its mapped toolapp, method: "GET", path, endUserId, idempotencyKey, optional connectionId
POST /v1/users/upsertProvision an Embedded end user idempotentlyexternalId, name; unbound Embedded key with users:manage
GET /v1/connectionsList one Embedded end user's private connectionsendUserId, optional cursor, limit (1–100); connections:manage
POST /v1/connections/:id/revokeRevoke that user's connectionendUserId; connections:manage
POST /v1/users/:endUserId/keysMint a short-lived user-bound runtime keyname, optional permissions (execute, connect), optional expiresIn (60–86,400 seconds); server-side mcp:keys issuer
POST /v1/mcp/authorization-ticketsIssue a one-use Embedded identity-link ticketSee 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.

ToolArguments
search_actionsOptional query, app, action, version, limit, Embedded groupId
manage_connectionsoperation: 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_helpOptional query (up to 500 characters) searches end-user docs and returns excerpts with source links
execute_actionaction, actionVersion, arguments, idempotencyKey, optional connectionId, Embedded groupId
get_executionexecutionId

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 pathPurposeRequest / response
GET /v1/wallet/grantRead starting-credit eligibility and claim status{currency, amountMicros, organizationId, eligible, claimed, claimedAt, reason}
POST /v1/wallet/grantClaim configured starting credit once{}; repeats return the original claim
GET /v1/orgs/:orgId/billingRead plan, projects, funded limits and walletWallet includes available, held and spent amounts plus ledger entries
GET /v1/orgs/:orgId/walletRead wallet and organization modeMembers; includes canManage for billing controls
GET /v1/orgs/:orgId/wallet/activityRecent funded executions and settled spendrange=7d|30d|90d, chargedOnly=true|false, optional numeric before; {calls, nextBefore, spentMicros, topTools}
GET /v1/orgs/:orgId/wallet/executions/:executionIdRedacted funded-call metadata across organization projectsMember; required projectId; non-funded calls remain inaccessible
GET /v1/orgs/:orgId/wallet/historySignup grants, Dodo top-ups, adjustments and refundsOptional numeric before; {items, nextBefore} from credit ledger entries
GET /v1/orgs/:orgId/funded-accessRead organization Instant switchMembers; {enabled}
PUT /v1/orgs/:orgId/funded-accessTurn organization funded access on/offOwners/admins; {enabled: boolean}; audited
GET /v1/orgs/:orgId/wallet/ledgerRead wallet balance and ledger historyOptional before ledger ID; {currency, availableMicros, heldMicros, spentMicros, ledger, nextBefore}
POST /v1/orgs/:orgId/billing/topupCreate or recover a Dodo top-up checkout{requestId: "<UUID>", amountCents: 1000} → {checkoutUrl, sessionId}
PUT /v1/orgs/:orgId/projects/:projectId/funded-limitsSet 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.

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.

MethodPathPurpose
GET/v1/events/triggersAvailable trigger versions and configuration schemas
GET, POST/v1/events/subscriptionsList or create subscriptions
GET/v1/events/subscriptions/:idSubscription details
POST/v1/events/subscriptions/:id/stateSet active, paused or archived state
GET, POST/v1/events/endpointsList or create destinations; creation returns a secret once
POST/v1/events/endpoints/:id/stateEnable or disable a destination
POST/v1/events/endpoints/:id/rotate-secretRotate the destination signing secret
GET, POST/v1/events/routesList or connect subscriptions and destinations
POST/v1/events/routes/:id/stateEnable or disable a route
GET/v1/events/recordsRetained event metadata
GET/v1/events/records/:idEvent payload, or 410 after expiry
GET/v1/events/deliveriesDelivery history; filter by subscriptionId, endpointId or state
GET/v1/events/deliveries/:idDelivery details and attempt history
POST/v1/events/deliveries/:id/replayCreate another delivery generation

See App events for setup and SDK examples.

Private tools and execution helpers

MethodPathPurpose
GET, POST/v1/action-sourcesList or register a private app implementation
GET/v1/action-sources/:idSource details and published tools; no credentials
POST/v1/action-sources/:id/syncPrepare a candidate revision
GET/v1/action-sources/:id/candidatesReview candidate schemas
POST/v1/action-sources/:id/publishPublish explicitly selected tools and risk classifications
POST/v1/action-sources/:id/pinsPin a source tool's version and credential selection
POST/v1/action-sources/:id/stateEnable or disable a source
POST/v1/actions/:action/draft-argumentsReturn a validated argument draft without execution
POST/v1/execution-batchesCreate an idempotent ordered batch, maximum ten steps
GET/v1/execution-batches/:idBatch state and child receipts
POST/v1/execution-batches/:id/resumeAdvance eligible work under current authority
POST/v1/execution-batches/:id/cancelCancel remaining work
POST/v1/local-executions/prepareAuthorize an SDK-local call or request approval
POST/v1/local-executions/:id/completeSubmit 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.

MethodPathPurpose
GET / POST/v1/agent-sessionsList owned sessions or create a session with tool/version allowlist, connection aliases and optional limits
GET/v1/agent-sessions/:idRead session metadata and configuration
POST/v1/agent-sessions/:id/configSave a narrowed immutable configuration revision
POST/v1/agent-sessions/:id/closeClose compute authority; retain authorized file access
POST/v1/agent-sessions/:id/restartReplace compute generation with explicit artifactIds to restore
POST/v1/agent-sessions/:id/runsQueue {language, code, idempotencyKey, artifactIds?}
GET/v1/agent-sessions/:id/runs/:runIdRead an authorized run receipt and bounded output
GET / POST/v1/agent-sessions/:id/artifactsList metadata or upload {name, dataBase64, mimeType?} within the file limit
GET / DELETE/v1/agent-sessions/:id/artifacts/:artifactIdRead metadata or delete a retained file
GET/v1/agent-sessions/:id/artifacts/:artifactId/downloadDownload 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 pathPurpose
GET /v1/account/invitationsPending, unexpired invitations to your verified login email across organizations.
POST /v1/orgs/{orgId}/leaveLeave with {confirmation: "exact workspace name"}. The last owner cannot leave.
POST /v1/orgs/{orgId}/transfer-ownershipOwner confirms workspace name and targetMemberId; target becomes owner and initiating owner becomes admin.
GET /v1/orgs/{orgId}/direct/sharingWorkspace sharing setting, active recipients and your outgoing grants.
PUT /v1/orgs/{orgId}/direct/sharingOwner/admin sets {enabled: boolean}. Disabling revokes grants; enabling does not restore them.
POST /v1/orgs/{orgId}/direct/connections/{connectionId}/sharesConnection 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.

On this page