HTTP API

Mainark's HTTP surface. Read routes are open; write routes require a bearer token.

Running it

src/index.ts starts the full daemon (reconciliation loop, interrupted-run recovery, Linear-poll dispatch) and serves HTTP as part of that. Hosts running the ledger path — mainark coordinate --watch --auto-review — want the API without those loops, so there is a standalone entry point:

bun run src/server/standalone.ts

It migrates the database and serves. Nothing else.

Required — it exits at boot listing whatever is missing:

POST /api/issues supports TASK_BACKEND=sqlite only.

Do not bind to 0.0.0.0. The intended deployment is a private interface only — a tailnet address, matching how Valkey is bound on the Fulreach hosts. There is no TLS termination here and the token is the only credential.

Authentication

Write routes and POST /agents/probe require Authorization: Bearer <MAINARK_API_TOKEN>. The probe runs the real developer and reviewer agents, which spend credits. Tokens are compared in constant time. Failure modes:

Unset fails closed rather than leaving the endpoint open.

POST /api/issues

Creates one issue in the configured task backend. This is the ingest door for clients that cannot run the CLI — Cursor on a phone, and later the Fulreach customer request frontend.

curl -X POST http://127.0.0.1:3000/api/issues \
  -H "Authorization: Bearer $MAINARK_API_TOKEN" \
  -H 'content-type: application/json' \
  -d '{"title":"Fix the empty state on /campaigns","description":"## Problem\n..."}'

{
  "issue": {
    "id": "MAI-41",
    "title": "Fix the empty state on /campaigns",
    "workStatus": "todo",
    "url": "mainark:issue/MAI-41",
    "autoDispatch": false
  }
}

Body

Issues are always created as work_status: todo. Everything arriving here is new work; moving it on is the dispatcher's job.

The identifier comes from id_sequences using MAINARK_ISSUE_PREFIX, so it is allocated the same way as any issue created by the CLI.

Errors

POST /api/issues/plan

Creates a whole plan: one issue per step, with dependencies between steps, all or nothing. Bearer token as above. It uses the same format and rules as the plan inbox, and cli/push-plan.mjs sends it.

{
  "title": "Move sessions to Supabase",
  "autoDispatch": true,
  "steps": [
    { "title": "Add the sessions table", "description": "…" },
    { "title": "Write sessions through it", "description": "…", "dependsOn": [1] }
  ]
}

It returns 201 with {"issues": [{"id": "MAI-50", "title": …}, …], "autoDispatch": true}. The ids are in step order. A bad plan returns 400 invalid_plan with the reason, and nothing is written.

Read routes

Unauthenticated, mounted at /api/issues:

Plus GET /health. POST /agents/probe is not open — see Authentication.

Architecture

Product architecture snapshots and derived gaps. Design notes: product-architecture.md.

Snapshot body (required fields): product, generatedAt, gitSha, ingestSequence (integer ≥ 0), manifest (with matching product, optional services / domains / workflows), nx (projects, dependencies: [{from,to}]), optional notes.

Stale ingest (ingestSequence older than stored) returns 409 with status: "ignored_stale". Same sequence + same gitSha returns 200 unchanged. Same sequence + different gitSha returns 409 with status: "sequence_conflict" (DB unchanged).

Product content (docs / changelog)

Git-backed product documentation via the GitHub Contents API. All content routes require bearer MAINARK_API_TOKEN (no open-read). The web app proxies them behind a session so the browser never sees MAINARK_API_TOKEN or GITHUB_PAT.

Save body: { path, content, expectedBlobSha, titleHint? }.

Configured products (v1: fulreach) live in src/content/productContentConfig.ts. Fulreach contract: product repo docs/ops/mainark-docs-contract.md. Design notes: product-content.md.