Orca
26 Download
Docs/AI and automation

REST API

Base URL, authentication, the event stream and a reference of every Orca daemon endpoint, with curl examples.

On this page

Everything the Orca app does goes through the daemon's REST API, so you can script it too. This page covers authentication, the event stream, and lists every endpoint grouped by area.

For AI agents, the MCP and agent endpoints are usually a better fit. For the shell, see the CLI.

Base URL

http://127.0.0.1:9477/api/v1

The daemon listens on the loopback address only, unless it was started with a different --bind address.

Authentication

Every request needs the daemon's API token as a Bearer header:

Authorization: Bearer <token>

Find the token in Settings → AI & agents → HTTP endpoint (advanced), or as api_token in the config file (~/Library/Application Support/orca/config.json on macOS, ~/.config/orca/config.json on Linux, %APPDATA%\orca\config.json on Windows). A missing or wrong token returns 401.

Exceptions:

  • GET /health and GET /ca/certificate need no token.
  • WebSocket endpoints (/containers/{id}/terminal, /k8s/pods/{namespace}/{name}/terminal, /k8s/enable-stream, /tunnel) take the token as a ?token= query parameter.
  • /webhooks/github and /webhooks/dockerhub are checked with the webhook secret instead.

Errors come back as JSON: {"error": "message"}. Authenticated responses carry an x-orca-version header with the daemon version.

Examples

Check that the daemon runs:

Terminal
curl -s http://127.0.0.1:9477/api/v1/health
# {"status":"ok","version":"..."}

List containers:

Terminal
TOKEN=...   # from Settings or the config file
curl -s -H "Authorization: Bearer $TOKEN" http://127.0.0.1:9477/api/v1/containers

Read the last 50 log lines of a container without following:

Terminal
curl -sN -H "Authorization: Bearer $TOKEN" \
  "http://127.0.0.1:9477/api/v1/containers/web/logs?tail=50&follow=false"

Run a command in a container:

Terminal
curl -s -X POST -H "Authorization: Bearer $TOKEN" -H "Content-Type: application/json" \
  http://127.0.0.1:9477/api/v1/containers/web/exec \
  -d '{"command": ["ls", "-la", "/app"]}'

Event stream

GET /events is a Server-Sent Events stream of changes in the engine. Each event has a type and a JSON data payload:

EventWhen
container.created, container.started, container.stopped, container.died, container.removedContainer lifecycle
image.pulled, image.removedImage changes
volume.created, volume.removedVolume changes
build.started, build.completedImage builds
machine.started, machine.stopped, machine.errorMachine state
dev.instanceWorktree instance changes

A keepalive comment is sent every 15 seconds.

Terminal
curl -sN -H "Authorization: Bearer $TOKEN" http://127.0.0.1:9477/api/v1/events

Endpoint reference

Paths are relative to /api/v1. {id} accepts a container or image ID or name.

System

MethodPathDescription
GET/healthStatus and daemon version. No token needed.
GET/eventsServer-Sent Events stream.
GET/system/healthEngine connection, disk, memory, CPU and warnings. ?refresh=1 recomputes disk usage.
GET/system/host-uidHost UID:GID, for running containers as the host user.
GET/machinesList machines.
GET/machines/{name}Inspect a machine.

Containers

MethodPathDescription
GET/containersList all containers.
POST/containersCreate a container.
GET/containers/statsStats for all running containers.
GET/containers/{id}Inspect a container.
DELETE/containers/{id}Remove a container.
POST/containers/{id}/startStart.
POST/containers/{id}/stopStop.
POST/containers/{id}/killKill.
POST/containers/{id}/updateChange CPU and memory limits or restart policy.
POST/containers/{id}/renameRename.
POST/containers/{id}/commitCommit the container to an image.
GET/containers/{id}/statsCPU, memory and network usage.
GET/containers/{id}/logsLogs as Server-Sent Events. ?tail= (default 200), ?follow= (default true).
POST/containers/{id}/execRun a command and return its output.
GET/containers/{id}/terminalInteractive terminal (WebSocket).
GET/containers/{id}/filesList files in the container.
GET/containers/{id}/fileRead a file from the container.
GET/containers/{id}/export/runEquivalent docker run command.
GET/containers/{id}/export/composeEquivalent Compose service definition.
GET/containers/{id}/export/tarExport the container filesystem as a tar archive.

Images

MethodPathDescription
GET/imagesList images.
GET/images/{id}Inspect an image.
DELETE/images/{id}Remove an image.
POST/images/pullPull an image.
POST/images/buildBuild an image.
POST/images/pruneRemove unused images.
POST/images/batch-deleteRemove several images.
GET/images/searchSearch Docker Hub.
POST/images/{source}/tagTag an image.
POST/images/importLoad an image from a tar file on disk.
GET/images/{id}/saveDownload an image as a tar archive.
GET/images/{id}/filesList files in an image.
GET/images/{id}/fileRead a file from an image.
GET/images/{id}/historyLayer history.
GET/images/{id}/scanVulnerability scan.

Builds

MethodPathDescription
GET/buildsList builds.
POST/buildsStart a build.
POST/builds/from-urlBuild from a Git or HTTP(S) URL.
GET/builds/statsBuild statistics.
POST/builds/compareCompare two builds.
GET/builds/targetsList build targets from stacks' orca.yaml files.
POST/builds/targets/{name}Start a build from a named target.
GET/builds/{id}Build details.
DELETE/builds/{id}Delete a build record.
GET/builds/{id}/logsBuild log.
POST/builds/{id}/cancelCancel a running build.

Registries

MethodPathDescription
GET/registriesList saved registry credentials.
POST/registriesAdd registry credentials.
DELETE/registries/{server}Remove registry credentials.

Volumes

MethodPathDescription
GET/volumesList volumes.
POST/volumesCreate a volume.
GET/volumes/sizesDisk usage per volume. ?refresh=1 recomputes.
GET/volumes/{name}Inspect a volume.
DELETE/volumes/{name}Remove a volume.
GET/volumes/{name}/filesList files in a volume.
GET/volumes/{name}/fileRead a file from a volume.
GET/volumes/{name}/containersContainers using the volume.

Networks

MethodPathDescription
GET/networksList networks.
POST/networksCreate a network.
GET/networks/topologyContainers and networks as a graph.
GET/networks/{name}Inspect a network.
DELETE/networks/{name}Remove a network.

Stacks

MethodPathDescription
GET/stacksList Compose stacks.
GET/stacks/{name}Stack details.
POST/stacks/{name}/startStart the stack's containers.
POST/stacks/{name}/stopStop the stack's containers.
POST/stacks/{name}/restartRestart the stack's containers.
POST/stacks/{name}/updocker compose up.
POST/stacks/{name}/downdocker compose down.
POST/stacks/{name}/pulldocker compose pull.
PATCH/stacks/{name}/envSet one variable in the stack's .env file.
GET, PUT/stacks/{name}/profilesRead or set the Compose profiles to run.
GET, PUT/stacks/{name}/orca-yamlRead or save the stack's orca.yaml.
GET/stacks/{name}/dirThe stack's directory.
POST/stacks/deployBring up a stack from a folder in Orca's stacks directory.
POST/stacks/validateValidate a Compose file.
POST/orca-yaml/validateValidate orca.yaml content.

Templates

MethodPathDescription
GET/templatesList app templates.
POST/templates/refreshRefresh the community template catalog.
POST, DELETE/templates/userSave or delete a user template.
POST/templates/{id}/deployDeploy a template.

Worktree projects and instances

MethodPathDescription
GET/dev/projectsList registered projects.
POST/dev/projectsRegister a git repo.
GET/dev/projects/{id}Project details and instances.
DELETE/dev/projects/{id}Unregister a project.
GET/dev/projects/{id}/setupAnalyse the repo for worktree setup.
PUT/dev/projects/{id}/orca-yamlWrite the project's orca.yaml.
POST/dev/projects/{id}/orca-yaml/validateValidate orca.yaml for the project.
POST/dev/projects/{id}/agents-snippetAdd the Orca section to CLAUDE.md or AGENTS.md.
POST/dev/projects/{id}/adoptTake over an existing Compose stack's data as the shared services.
POST/dev/projects/{id}/shared/upStart the shared services.
POST/dev/projects/{id}/shared/downStop the shared services.
PUT/dev/projects/{id}/instances/{name}Change an instance's settings.
GET/dev/projects/{id}/instances/{name}/planPreview what up would do.
POST/dev/projects/{id}/instances/{name}/upStart or rebuild an instance (returns a job).
POST/dev/projects/{id}/instances/{name}/downStop an instance (returns a job).
POST/dev/projects/{id}/instances/{name}/removeStop an instance and delete its volumes, images and generated files (returns a job).
GET/dev/projects/{id}/instances/{name}/logsInstance logs.
GET/dev/projects/{id}/instances/{name}/dataData mode per shared service.
POST/dev/projects/{id}/instances/{name}/data/{service}/resetReset the instance's own database.
POST, DELETE/dev/projects/{id}/instances/{name}/host-routes/{service}Route a service to a dev server on the host, or remove that route.
GET/dev/jobsList jobs.
GET/dev/jobs/{id}Job status and steps.
POST/dev/resolveFind the project and instance for a path.
GET/dev/candidatesGit repos with running Compose stacks that aren't registered yet.

Gateway

MethodPathDescription
GET/gateway/statusRunning state, domain, ports and route count.
POST/gateway/startStart the gateway.
POST/gateway/stopStop the gateway.
GET/gateway/routesList routes.
POST/gateway/routesAdd a route.
PUT/gateway/routes/{hostname}Update a route.
DELETE/gateway/routes/{hostname}Remove a route.
GET, PUT/gateway/configRead or update domain, ports and TLS settings.
GET, PUT/gateway/landingRead or update the landing page settings.
GET, PUT/gateway/linksRead or update stack link groups.
GET/gateway/port-checkCheck whether the HTTP and HTTPS ports are free.
GET/gateway/traefik-statusStatus of the k3s Traefik integration.
PUT/gateway/traefik-modeSet how the gateway works with k3s Traefik.
POST/gateway/dismiss-suggestionDismiss a route suggestion.
POST/gateway/clear-dismissedClear dismissed suggestions.
GET/gateway/dismissed-suggestionsList dismissed suggestions.

CA

MethodPathDescription
GET/ca/certificateThe Orca CA certificate (PEM). No token needed.
GET/ca/infoSubject, expiry and fingerprint.

Kubernetes cluster

MethodPathDescription
GET/k8s/statusCluster status.
POST/k8s/enableEnable Kubernetes.
GET/k8s/enable-streamEnable with progress output (WebSocket).
POST/k8s/disableDisable Kubernetes.
POST/k8s/startStart the cluster.
POST/k8s/resetReset the cluster.
GET, PUT/k8s/runtimeRead or set the container runtime (docker or containerd).
GET/k8s/kubeconfigKubeconfig for the cluster.
POST/k8s/applyApply a YAML manifest.
GET/k8s/yaml/{kind}/{namespace}/{name}YAML of a resource.
GET/k8s/events/{namespace}Recent events.
GET/k8s/metrics/{namespace}Pod CPU and memory metrics.
GET/k8s/storage-classesList storage classes.
GET/k8s/crdsList custom resource definitions.
GET/k8s/pvsList persistent volumes.

Kubernetes workloads

MethodPathDescription
GET/k8s/namespacesList namespaces.
POST/k8s/namespacesCreate a namespace.
DELETE/k8s/namespaces/{name}Delete a namespace.
GET/k8s/pods/{namespace}List pods.
DELETE/k8s/pods/{namespace}/{name}Delete a pod.
GET/k8s/pods/{namespace}/{name}/logsPod logs.
GET/k8s/pods/{namespace}/{name}/terminalInteractive shell in a pod (WebSocket).
GET/k8s/deployments/{namespace}List deployments.
POST/k8s/deployments/{namespace}/{name}/scaleScale a deployment.
POST/k8s/deployments/{namespace}/{name}/restartRolling restart.
GET/k8s/deployments/{namespace}/{name}/historyRollout history.
POST/k8s/deployments/{namespace}/{name}/rollbackRoll back a deployment.
GET/k8s/statefulsets/{namespace}List StatefulSets.
POST/k8s/statefulsets/{namespace}/{name}/scaleScale a StatefulSet.
POST/k8s/statefulsets/{namespace}/{name}/restartRestart a StatefulSet.
DELETE/k8s/statefulsets/{namespace}/{name}Delete a StatefulSet.
GET/k8s/daemonsets/{namespace}List DaemonSets.
DELETE/k8s/daemonsets/{namespace}/{name}Delete a DaemonSet.
GET/k8s/replicasets/{namespace}List ReplicaSets.
DELETE/k8s/replicasets/{namespace}/{name}Delete a ReplicaSet.
GET/k8s/jobs/{namespace}List Jobs.
DELETE/k8s/jobs/{namespace}/{name}Delete a Job.
GET/k8s/cronjobs/{namespace}List CronJobs.
POST/k8s/cronjobs/{namespace}/{name}/triggerRun a CronJob now.
PUT/k8s/cronjobs/{namespace}/{name}/suspendSuspend or resume a CronJob.
DELETE/k8s/cronjobs/{namespace}/{name}Delete a CronJob.
GET/k8s/hpas/{namespace}List HorizontalPodAutoscalers.
POST/k8s/hpas/{namespace}Create a HorizontalPodAutoscaler.
DELETE/k8s/hpas/{namespace}/{name}Delete a HorizontalPodAutoscaler.

Kubernetes networking, config and storage

MethodPathDescription
GET/k8s/services/{namespace}List services.
GET/k8s/ingresses/{namespace}List ingresses.
GET/k8s/network-policies/{namespace}List network policies.
DELETE/k8s/network-policies/{namespace}/{name}Delete a network policy.
GET/k8s/configmaps/{namespace}List ConfigMaps.
GET/k8s/secrets/{namespace}List Secrets.
POST/k8s/secrets/{namespace}Create a Secret.
PUT/k8s/secrets/{namespace}/{name}Update a Secret.
DELETE/k8s/secrets/{namespace}/{name}Delete a Secret.
GET/k8s/pvcs/{namespace}List PersistentVolumeClaims.
POST/k8s/pvcs/{namespace}Create a PersistentVolumeClaim.
DELETE/k8s/pvcs/{namespace}/{name}Delete a PersistentVolumeClaim.

Helm

MethodPathDescription
GET/k8s/helm/releasesList installed releases.
GET/k8s/helm/availableWhether Helm is available.
POST/k8s/helm/installInstall a chart.
POST/k8s/helm/uninstallUninstall a release.

Deploy rules and schedules

MethodPathDescription
GET/deploy/rulesList auto-deploy rules.
POST/deploy/rulesSave a rule.
DELETE/deploy/rules/{id}Delete a rule.
GET/deploy/historyDeploy history.
POST/deploy/testDry run: which rules a webhook would trigger.
POST/deploy/webhook-secretSet the webhook secret.
POST/webhooks/githubGitHub webhook receiver (signed with the webhook secret).
POST/webhooks/dockerhubDocker Hub webhook receiver.
GET/schedulesList scheduled actions.
POST/schedulesSave a scheduled action (cron expression).
DELETE/schedules/{id}Delete a scheduled action.

Environment

MethodPathDescription
GET/environment/statusRuntime environment checks.
POST/environment/fixRun a fix action.
POST/environment/fix-streamRun a fix action with streamed output.
GET/environment/docker-desktop-statusWhether Docker Desktop is installed or running.
POST/environment/switch-to-orcaSwitch the Docker CLI to Orca's runtime.
POST/environment/stop-docker-desktopStop Docker Desktop.

AI and settings

MethodPathDescription
POST/ai/askAsk the built-in assistant (query, optional context and history).
GET, POST/settings/aiRead or save the AI provider, key, model and URL.
GET/settings/ai/modelsModels available from the configured provider.
GET, POST/settings/generalRead or save general settings (start on login, tray icon, telemetry, Docker Desktop URL handling).
GET, POST/settings/limaRead or change the Lima VM's CPUs, memory and disk (macOS).
POST/settings/cleanupClean up config, VMs, templates or Docker resources.
POST/settings/reconnectReconnect to the container runtime.

Agents

MethodPathDescription
POST/agent/mcpMCP JSON-RPC endpoint.
GET/agent/toolsAgent tool definitions in OpenAI function format.
POST/agent/executeRun one tool: {"tool": "...", "arguments": {...}}.
POST/agent/openai/chat/completionsExecute OpenAI-style tool calls.

See AI agents and MCP for request formats and the tool list.

Tunnel

MethodPathDescription
GET/tunnelTCP port forwarding over WebSocket (?host=, ?port=, ?token=).
Edit this page on GitHub