#HTTP API

ORCA's UI talks to a small local HTTP server. The same API is available to your own scripts.

• Desktop app: the server listens on 127.0.0.1 on a random port (visible in Settings → Data → Stats, or in the window title's dev tools).
• Web mode (npm run web): http://127.0.0.1:7860 by default; PORT and HOST change that.

There is no authentication. Anything that can reach the port can run tools with your user's permissions — keep it on loopback (default) or put an authenticating reverse proxy in front.

All request and response bodies are JSON (content-type: application/json) unless stated otherwise. Errors use the shape { "error": "message" } with an appropriate status (400, 404, 413); a few operational endpoints return 200 with ok:false so the UI can show the reason inline — this is noted per endpoint. CORS is open (access-control-allow-origin: *).

#Contents

• Health & version
• Chats
• Sending messages & runs
• Events (SSE)
• Approvals, questions & stopping
• Uploads & workspace files
• Checkpoints
• Configuration
• Providers & models
• Vault
• Generation test
• Background processes
• Memory, todos & search
• Backup & stats
• Updates

#Health & version

#GET /api/health

{ "ok": true, "version": "0.0.5", "builtin": true, "vault": true, "repo": "Nethyric/orca",
  "tools": ["run_shell", "…"], "electron": false,
  "bins": { "ffmpeg": true, "ytdlp": true, "chrome": true }, "vision": false,
  "judge": { "configured": false, "enabled": false, "model": "jev-latest", "cooling": false, "stats": { "calls": 0, "ok": 0, "failed": 0, "inputTokens": 0, "outputTokens": 0, "avgMs": 0, "lastError": "" } } }

builtin — the build carries a vault key; vault — the vault was fetched and decrypted; vision — a vision model is configured; bins.chrome — a Chromium browser for browser_check/screenshot was found; judge — state of the optional decision engine.

#Chats

A chat is { id, title, mode, model, models, createdAt, updatedAt, pinned, notes, tags[], forkedFrom?, messages[], votes[] }. A message is { id, role: "user" | "assistant", content, ts, model?, modelKey?, lane?, runId?, status?, events?[], usage?, tookMs?, pinned?, partial?, interrupted?, error?, hidden?, pastedPath? }. Assistant messages keep their run's event log (events[] = { event, data, ts }) so the UI can replay tool cards.

• status is running, done, question, stopped or error. A stopped/errored message with text keeps it (partial: true) so the UI can offer Continue.
• hidden: true marks internal user turns (e.g. the "continue" instruction) that the UI shows as a small note instead of a bubble.
• pastedPath is set when a very long paste (> 12 000 characters) was saved to attachments/paste-<timestamp>.txt and only a preview was sent inline.
• usage may carry estimated: true when the provider sent no usage chunk; tookMs is wall-clock time from the message creation to its final answer.

#Sending messages & runs

#POST /api/send

{
  "chatId": "mu41…",
  "text": "Build a snake game in games/snake/",
  "mode": "direct",
  "model": "auto",
  "models": ["minimax", "deepseek"],
  "planMode": false,
  "autonomy": "auto",
  "regenerateFrom": null,
  "images": ["attachments/shot.png"],
  "lang": "en"
}

Response:

{ "runId": "mu41p1e0rz7bf5", "lanes": [ { "runId": "mu41p1e0rz7bf5", "msgId": "…", "lane": "" } ], "models": ["minimax"] }

lanes has two entries for side/battle (runId suffixed :a / :b). Slash commands (/init, /compact, /plan, /help) are handled synchronously and answer with { runId: null, local: true, msgId, text }.

The run itself is asynchronous: subscribe to /api/events before or right after sending and filter by runId.

#Events (SSE)

#GET /api/events

A single text/event-stream carrying every run's events. Each message is data: <json> where the JSON is { runId, event, data } (runId is the lane run id, e.g. abc:a). Keep-alive comments are sent every 20 s.

Minimal client:

const es = new EventSource('http://127.0.0.1:7860/api/events');
es.onmessage = (e) => { const { runId, event, data } = JSON.parse(e.data); if (event === 'final') console.log(data.text); };
const chat = await (await fetch('http://127.0.0.1:7860/api/chats', { method: 'POST', body: '{}' })).json();
await fetch('http://127.0.0.1:7860/api/send', { method: 'POST', headers: { 'content-type': 'application/json' },
  body: JSON.stringify({ chatId: chat.id, text: 'List the 5 largest files in the workspace', autonomy: 'yolo' }) });

#Approvals, questions & stopping

Questions from the ask_user tool end the run (final with status: "question" on the message); answer by sending the next message in the same chat.

#Uploads & workspace files

#Checkpoints

Every mutating file tool records a before/after snapshot.

#Configuration

#GET /api/config

Returns the public view of the configuration: everything in config.json with secrets masked (apiKey: "sk-1…ab12", plus keySet: true|false), and computed fields:

{
  "lang": "en", "defaultModel": "auto", "autonomy": "auto", "…": "…",
  "providers": { "groq": { "name": "Groq", "baseUrl": "…", "apiKey": "gsk_…9f2a", "keySet": true, "models": [ … ] } },
  "models": [ { "key": "auto", "label": "ORCA", "tier": "auto", "builtin": true },
              { "key": "minimax", "label": "MiniMax M2.7", "vendor": "MiniMax", "tier": "strong", "builtin": true, "ready": true },
              { "key": "groq/llama-3.3-70b-versatile", "label": "llama-3.3-70b-versatile", "vendor": "Groq", "builtin": false, "ready": true } ],
  "builtin": true, "version": "0.0.5", "dataDir": "…", "workspaceDir": "…",
  "app": { "name": "ORCA", "company": "Nethyric", "repo": "Nethyric/orca", "homepage": "…" }
}

#POST /api/config

Partial patch, merged into the current configuration; returns the new public view. Rules:

• Top-level scalars replace; providers is merged per id — send { "providers": { "groq": null } } to delete one.
• Provider records: { name?, baseUrl, apiKey?, api?, models: [ { id, name?, maxTokens?, toolCall?, reasoning?, attachment? } ] }. Omit apiKey (or send the masked value) to keep the stored key.
• vision / imageGen / videoGen are merged field-by-field with the same key-keeping rule.

All keys are documented in configuration.md.

#Providers & models

#Vault

#GET /api/vault[?refresh=1]

{ "enabled": true, "ok": true, "source": "https://raw.githubusercontent.com/…/remote/vault.json",
  "fetchedAt": 1789559349816, "issued": "2026-09-16T10:00:00Z", "aliases": ["minimax", "deepseek", "glm", "glimmer"], "keys": 16, "error": "", "disabled": [] }

Never returns key material. refresh=1 forces a re-fetch. See vault.md.

#Decision engine

See decision-engine.md.

#Generation test

Generates one small sample (generated/test-image.png / generated/test-video.mp4) with the same code path the generate_image / generate_video tools use.

#Background processes

Processes started by the agent with start_process (bots, dev servers, workers). They live as long as the server does.

Every change is also pushed on the event stream as proc.

#Memory, todos & search

#Backup & stats

#Updates

Update checks call https://api.github.com/repos/<repo>/releases/latest (unauthenticated, 60 requests/hour per IP) at most once per 6 hours unless force=1.