HTTP API

Signs in. No token needed.

{ "username": "maria", "password": "…", "totp": "123456" }

totp is required for accounts with an authenticator, and for admins when require_totp_for_admins is on.

{ "token": "hs_…", "role": "operator", "expires_in": 43200, "idle_timeout": 3600 }

Revokes the current session. Returns { "ok": true }.

Liveness check without details. Returns { "ok": true }.

Returns { "username": "maria", "role": "operator" }.

Lists projects with a summary of each.

{
  "projects": [
    {
      "name": "shop-storefront",
      "status": "running",
      "source": "file",
      "running": 2,
      "retrying": 0,
      "tracker": "ClickUp · Sprint 42",
      "config_errors": [],
      "preflight_error": null,
      "limit_block": null,
      "auto_paused": null,
      "spend_today": { "cost_usd": 12.4, "tokens": 1830000, "runs": 9 },
      "parked": [
        { "issue_id": "86b1x", "issue_identifier": "CU-86b1x", "reason": "stopped after 5 failed attempts in a row …",
          "attempts": 5, "cost_usd": 3.1, "at": "2026-11-06T08:12:00Z" }
      ]
    }
  ]
}

source is file for projects in harnessd.yaml and harness for projects added from the app.

Adds a project from a repository URL. The server clones it into data_dir/repos/<name>, checks the workflow file, stores the project in its overlay and optionally starts it. Needs totp.

{
  "name": "shop-storefront",
  "repo": "git@github.com:your-org/shop-storefront.git",
  "workflow": "WORKFLOW.md",
  "auto_start": true,
  "set": { "SENTRY_DSN": "https://…" },
  "logins": [
    { "name": "shopper", "origins": ["http://localhost:3000"], "username": "qa@example.com", "password": "…" }
  ],
  "totp": "123456"
}

repo must be https://, ssh:// or user@host:path. workflow defaults to WORKFLOW.md and must be inside the repository. set and logins are optional: the project's variables and test logins.

Returns 201 with the project summary.

Removes a project added from the app: stops it and deletes its variables and test logins. The clone stays. Body: { "totp": "123456" }. Returns { "removed": "<p>" }. Projects in harnessd.yaml get 409 defined_in_config.

Starts the project's orchestrator. Returns the project summary. Also /stop, /pause (stop dispatching; agents continue) and /resume (which also clears an automatic pause).

Long-poll for the project's live state. Returns at once if the state's version differs from since, otherwise waits up to 25 seconds.

{
  "version": "a1b2c3d4e5f60718",
  "project": { "name": "shop-storefront", "status": "running", "…": "…" },
  "state": { "running": [ … ], "retrying": [ … ], "codex_totals": { … } },
  "board": {
    "columns": ["to do", "in progress", "review", "complete"],
    "editable": true,
    "issues": [
      { "id": "86b1x", "identifier": "CU-86b1x", "title": "…", "state": "in progress", "priority": 2,
        "labels": ["agent"], "running": true, "parked": null, "waits_on": [] }
    ]
  }
}

Each issue has the prompt-template fields plus running, parked (the reason, or null) and waits_on (linked tasks it waits on).

Long-poll for the full project as the Mac app mirrors it: configuration, running agents, retries, history and the workflow's text and version. Errors and messages are redacted. This is the app's internal format and may change.

One task, by id or identifier, with comments (author, body, at) and linked_tasks (project, identifier, title, state, done, wait). 404 issue_not_found if it isn't on the board.

Creates a task.

{ "title": "Fix the cart total rounding", "description": "Markdown…", "priority": 2,
  "state": "Todo", "labels": ["bug"], "blocked_by": ["HAR-3"] }

Only title is required (up to 300 characters). state defaults to the first board column and must be one of them. priority is 0–4; up to 20 labels. Returns 201 { "identifier": "HAR-14" }. 409 read_only_board for GitHub projects; 502 tracker_error if the tracker refuses.

Moves a task. Body: { "state": "Todo" }, one of the board's columns (400 bad_state otherwise). Returns the issue.

Adds a comment. Body: { "body": "Markdown" } (up to 50,000 characters). The comment is signed — <user> via SI Fabrik. Returns the issue.

Dispatches the task now. 409 not_running if the project isn't started. Returns the issue.

Stops the task waiting on its linked tasks. Returns the issue.

Un-parks a task a guardrail parked. Returns the project summary; 404 not_parked if it isn't parked.

Persisted run history, newest first. limit is 1–200, default 50.

{
  "project": "shop-storefront",
  "runs": [
    { "id": "7f0c…", "issue_id": "86b1x", "issue_identifier": "CU-86b1x", "title": "…",
      "outcome": "succeeded", "error": null, "started_at": "…", "ended_at": "…", "duration_s": 812.4,
      "turns": 6, "runner": "claude_code", "tokens": { "input": 120000, "output": 18000, "total": 138000 },
      "cost_usd": 2.31, "pull_request_url": "https://github.com/your-org/shop-storefront/pull/88", "delivery": "…" }
  ]
}

One run with its transcript: items with at, kind, title and body, redacted and trimmed as stored. 404 run_not_found.

Long-poll for new transcript items of a running agent, after the first n.

{ "running": true, "identifier": "CU-86b1x", "total": 42, "phase": "streamingTurn",
  "items": [ { "at": "…", "kind": "toolCall", "title": "Bash", "body": "npm test" } ] }

When the agent isn't running, returns { "running": false, "total": <n>, "items": [] }. Bodies are redacted and capped at 64,000 characters.

Stops the running agent for a task, in whichever project. Returns { "ok": true }, or 404 run_not_found.

Returns { "text": "---\ntracker: …", "version": "<sha256 of text>" }.

Saves WORKFLOW.md and hot-reloads the project.

{ "text": "---\n…", "base_version": "<version from GET>" }

Returns { "version": "…" }.

The project's task workspaces: [{ "key": "CU-86b1x", "branch": "symphony/CU-86b1x", "saved": true, "in_use": false, "modified": "…" }].

Saves the workspace's task branch into the project repository, then removes it. Returns { "removed": "<key>" }. 404 not_found if there's no such workspace; 409 running if an agent is in it; 409 not_removed if the branch couldn't be saved.

Server facts for the General tab: listen, tls, certificate_sha256, tools_listen, require_totp_for_admins, session, users, projects, docker, which credentials are set (booleans), and the effective gateway, limits and sandbox.

The effective settings, where each section comes from, and (for admins) variable names.

{
  "gateway": { "enabled_by_default": true, "base_url": "http://10.8.0.20:4000", "auth_header": "bearer",
               "opus_model": "", "sonnet_model": "", "haiku_model": "claude-haiku-5-5", "codex_model": "",
               "tag_requests": true, "disable_experimental_betas": false, "wire_api": "responses" },
  "limits": { "max_concurrent_agents": 6, "daily_budget_usd": 200 },
  "sandbox": { "allow": ["registry.npmjs.org", "pypi.org"], "cloudflare_bridge_url": null },
  "sources": { "gateway": "file", "limits": "harness", "sandbox": "file" },
  "variables": [ { "name": "CLICKUP_API_TOKEN", "source": "file" } ],
  "can_edit": true
}

One Save: any of the sections, server-wide variables and resets, under one code.

{
  "limits": { "max_concurrent_agents": 8, "daily_budget_usd": 250 },
  "reset": ["sandbox"],
  "set": { "HARNESS_GATEWAY_API_KEY": "sk-…" },
  "remove": ["OLD_TOKEN"],
  "totp": "123456"
}

gateway, limits and sandbox take the same shapes as the GET response. reset returns sections to harnessd.yaml. Returns the new settings. 400 bad_settings with problems if a value is invalid. An empty change returns the current settings without asking for a code.

Lists the gateway's models from the server. Body: { "base_url": "http://10.8.0.20:4000", "auth_header": "bearer", "key": "optional" } (without key, the saved key is used). Returns { "models": [...], "latency_ms": 42 }, or 502 gateway_unreachable.

Starts a throwaway Cloudflare sandbox with no network, runs a command and destroys it, with the saved token. Body: { "bridge_url": "optional" }. Returns { "ok": true, "message": "Connected — a sandbox started and ran a command" }.

The server's Sandboxes screen: docker (engine info), running_containers, agent_image and browser_image (reference, present, size, built), containers (only this server's), build (building, browser, log, succeeded), cloudflare (bridge_url, token_set, healthy, relay_connected, relay_routes, relayed_requests, hub, projects) and kept Cloudflare workspaces.

A container's logs, redacted: { "name": "…", "logs": "…" }. Only this server's containers (404 not_found otherwise). An id prefix of 12 or more characters works.

Stops and removes one of this server's containers. Returns { "stopped": "<name>" }, or 502 docker_error.

Builds harness-agent:latest, or with { "browser": true } the browser image. Returns 202 { "building": true }; follow progress in /api/v1/server/sandboxes. 409 docker_unavailable or 409 building.

Server-wide variable names: { "variables": [ { "name": "CLICKUP_API_TOKEN", "source": "file" } ] }. source is file (from secrets.env) or harness (set from the app).

Sets a server-wide value in the overlay. Body: { "value": "…", "totp": "123456" }. One line, up to 16 KB. Returns the list. DELETE with { "totp": "…" } removes the overlay value, falling back to the file's.

The project's variable names, and its test logins without passwords: name, username, origins, has_totp, problems.

Sets a project value. Same body as server-wide. DELETE removes it.

Saves a test login.

{ "origins": ["http://localhost:3000"], "username": "qa@example.com", "password": "…",
  "totp_secret": "JBSWY3DPEHPK3PXP", "totp": "123456" }

400 bad_login with problems if it isn't valid. DELETE with { "totp": "…" } removes it.

Aggregated runtime state across projects: counts (running, retrying), running and retrying entries, codex_totals (input_tokens, output_tokens, total_tokens, seconds_running), rate_limits and per-project snapshots. Add ?project=<name> for one project.

Runtime detail for one task (for example /api/v1/HAR-12): its running or retry state, workspace, recent events and log paths. 404 issue_not_found if it isn't in the current runtime state.

Polls and reconciles now. Returns 202 { "queued": true, "coalesced": false, "requested_at": "…", "operations": ["poll", "reconcile"] }. Repeated requests are coalesced.

An MCP streamable-HTTP endpoint (JSON responses) for one agent session, served only on tools_listen. It supports initialize, ping, tools/list and tools/call; DELETE ends the session, and SSE streams aren't supported. The token is per run and is injected into Claude Code with --mcp-config and into Codex through its mcp_servers config. Unknown or expired tokens get a JSON-RPC error. See Agent MCP tools.