REST API and proxy

Discover versioned tools, execute authorized actions, and retrieve execution results over HTTP.

REST and Arc0 MCP use the same permissions and execution services. Set ARC0_API_URL to your Arc0 API origin and use your scoped API key as a bearer token for REST. For a local installation, the API origin is http://localhost:4312.

curl "$ARC0_API_URL/v1/tools" \
  -H "Authorization: Bearer $ARC0_API_KEY"

A self-bound key determines the acting user. An Embedded management key must supply the project-scoped endUserId when calling user-specific REST endpoints. Supplying a different user with a self-bound key is rejected.

Discover before executing

Search returns a short list of enabled tools, versions, access sources and readiness:

curl "$ARC0_API_URL/v1/actions/search" \
  -H "Authorization: Bearer $ARC0_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"query":"public repository","app":"github"}'

Fetch an exact tool's schema by sending {"action":"github.get_public_repository"} to the same endpoint. Only use a version returned for your current project. A result that needs a connection is discoverable but cannot execute until its access requirements are satisfied.

Execute a tool

Enable the tool and select its access source in Arc0 before executing it. For the public GitHub repository tool, no user connection is required:

curl "$ARC0_API_URL/v1/execute" \
  -H "Authorization: Bearer $ARC0_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "action":"github.get_public_repository",
    "actionVersion":"1",
    "arguments":{"owner":"octocat","repo":"Hello-World"},
    "idempotencyKey":"repository-check-2026-10-07"
  }'

Replace actionVersion with the exact discovered version. A receipt contains id, status, actionVersion, result, error and replayed. Approval-required calls also identify the pending approval. Treat outcome_unknown as unresolved: reconcile the existing execution instead of starting another write with a new idempotency key.

Reuse the same key and identical request for retries. Changing the action, arguments or selected connection while reusing the key is rejected. Replays recheck current authority.

Retrieve a result

curl "$ARC0_API_URL/v1/executions/$EXECUTION_ID" \
  -H "Authorization: Bearer $ARC0_API_KEY"

An Embedded management key includes ?endUserId=<project-scoped-user-id>. Results are bound to the original caller and acting user and remain subject to current access and retention. The result can be unavailable even when the recorded execution status is succeeded.

Catalog-bound proxy

POST /v1/proxy supports approved provider paths mapped to existing actions. It is not an arbitrary URL forwarding endpoint. Supply app, method, path, endUserId, a stable idempotencyKey, and an optional connectionId. Only supported GET paths are accepted; unknown paths or methods are rejected. Policies and audit still apply.

On this page