API reference overview

The Orca Registry API is the REST surface that every Agent Engine client uses to manage resources on a Workspace. The ork CLI, the TypeScript, Python, and Go SDKs, and HTTP clients use it to define agents, run sessions, automate them with triggers, mount files and vaults, and manage StreamNative Cloud integrations.

This tab renders operation pages from current portable core and StreamNative Cloud extension contracts, in three groups: the core API, the extension groups that the open-source engine ships, and the StreamNative Cloud extension group. See How the API is organized. Browse a resource family in the sidebar for request and response schemas.

Base URL

On StreamNative Cloud, each Workspace publishes its registry endpoint in status.serviceEndpoints[]; on a self-hosted deployment, use the URL of the registry's public listener. Export this host root as ORCA_REGISTRY_URL: append /v1/... for core operations and /apis/<group>/<version>/... for extensions.

For example, list agents through the core route:

curl -fsS "$ORCA_REGISTRY_URL/v1/agents" \
  -H "Authorization: Bearer $ORCA_ACCESS_TOKEN"

Authentication

Core operations accept one of two credentials:

For example, call a core operation with a Workspace API key:

curl -fsS "$ORCA_REGISTRY_URL/v1/agents" \
  -H "x-api-key: $ORCA_API_KEY"

The ork CLI accepts exactly one of --access-token / ORCA_ACCESS_TOKEN and --api-key / ORCA_API_KEY. Its API-key option sends x-api-key; its access-token option sends a Bearer header. The TypeScript and Python SDKs read ORCA_API_KEY as a Bearer token (apiKey in TypeScript and api_key in Python), so do not reuse a Workspace API key as either SDK's ORCA_API_KEY value. The Go SDK sends ORCA_API_KEY as x-api-key and ORCA_ACCESS_TOKEN as a Bearer header.

The Cloud extension contract declares Bearer authentication. Use an OIDC access token for requests under /apis/cloud.sn.io/v1.

Each credential resolves to one Workspace, and the registry limits every request to that Workspace's resources. Treat every Workspace API key as full access to its Workspace's resources. See Control registry access.

Beta headers

The core contract accepts anthropic-beta for SDK compatibility and ignores its value. Use orca-beta only where an operation documents an Orca-native response alias.

How the API is organized

The registry serves a core API and versioned extension groups on the same host. The sidebar lists operations in three groups:

The DNS-shaped group name identifies who owns the API; requests still go to the registry host.

Core API

• Discovery (/api, /apis) - API versions and extension groups a deployment advertises.
• Health (/healthz, /readyz) - unauthenticated liveness and readiness probes.
• Agents (/v1/agents) - versioned definitions: model, system prompt, MCP servers, tools, and skills.
• Sessions (/v1/sessions) - running instances of an agent, with events, status, outcomes, and resource bindings.
• Session outcomes (/v1/sessions/{id}/outcome) - the evaluation result for a rubric that a session defines with user.define_outcome.
• Environments (/v1/environments) - reusable sandbox templates.
• Files (/v1/files) - assets that sessions mount as resources.
• Memory stores (/v1/memory_stores) - durable memory an agent reads and writes across sessions.
• Skills (/v1/skills) - filesystem-shaped capability bundles that agents load on demand.
• Vaults (/v1/vaults) - per-Workspace credential storage that sessions reference for MCP authentication.
• Git credentials (/v1/git-creds) - tokens used to clone repositories into a session sandbox.
• Triggers (/v1/triggers) - durable automation that starts sessions on a cron schedule.

Orca-only operations in the core API, such as /v1/triggers, carry the orca-extension tag in the source contract. They are core routes, not extension groups, so they stay under Core API.

Extensions

Each extension group is one resource family in the sidebar. The family also includes the group's own discovery route, GET /apis/<group>/v1.

The guides also cover the separate organization-admin write routes for guardrails and model prices. A deployment, including StreamNative Cloud, may not expose runtime.runorca.ai/v1; check GET /apis before using it.

Cloud extensions

StreamNative Cloud serves cloud.sn.io/v1 for Workspace integration resources: providers, catalog entries, connections, functions, packages, and connector families. The open-source registry does not serve this group.

Triggers remain core operations on /v1/triggers; they are not an agenttriggers extension group. The portable contract covers the cron subset. StreamNative Cloud widens the same request and response schemas with Kafka and Pulsar sources, additional session modes, and multiple replicas. See Managed Trigger extensions before sending a Cloud-only value to a deployment.

Versioning and preview

The Registry API is part of the Agent Engine Developer Preview. The core surface is versioned at /v1; extension groups carry their own version in the path. Path-level breaking changes increment the version segment, while field-level additions can ship between preview releases.

While Agent Engine is in Developer Preview:

• Operation IDs and response field names can change between releases.
• Pin generated clients to a reviewed source-contract revision.
• StreamNative Cloud can temporarily disable an operation on a Workspace during an upgrade.

Source contracts

This reference vendors three source artifacts at pinned revisions. The generated core pages remain faithful to the core contract; review the deployment overlay alongside them for StreamNative Cloud deviations and extensions.

• apis/registry-api/managed-agents.yaml - portable core contract from orca-agent-engine tag v0.5.1 (commit 5176ec6d). Its SHA-256 matches the generated source contract at that tag.
• apis/registry-api/cloud-extensions.yaml - StreamNative Cloud extension contract synced from orca-sdk-typescript commit 927a37a.
• apis/registry-api/managed-agents-deployment.overlay.yaml - Cloud deviations from portable core, including Trigger schema extensions, from orca-sdk-typescript commit 8657ccab.

The core contract includes the runtime.runorca.ai harness catalog. Check deployment discovery to confirm whether your endpoint exposes that group.

triggers.yaml is a current portable Trigger subset generated from the vendored core contract. The docs site does not currently publish full core, Cloud, or overlay inputs as downloads. Do not generate new clients from historical registry-admin.yaml; it is not a source for this reference.

The raw core contract retains orca-extension tags for machine consumers. The docs build splits the contracts into one render bundle per sidebar group and files each operation under one resource family, so the sidebar does not duplicate operations. The core bundle omits the internal binary Git smart-HTTP transport, which the API renderer cannot display; the vendored source contract keeps its exact media types.

What's next