Flow Mesh API Reference

Base URL: http://127.0.0.1:8300 (or your configured external URL)

Authentication

All /api/* endpoints (except /api/health) require authentication:

# Option 1: Bearer token (set FLOW_MESH_API_TOKEN env var)
curl -H "Authorization: Bearer YOUR_TOKEN" http://localhost:8300/api/work-items

# Option 2: Query param
curl "http://localhost:8300/api/work-items?token=YOUR_TOKEN"

# Option 3: Session cookie (from /login)
curl -c jar -X POST http://localhost:8300/login -d "username=admin&password=mesh&remember=1"
curl -b jar http://localhost:8300/api/work-items

Health

GET /api/health

Auth-exempt. Returns service status.

{
  "status": "ok",
  "db": true,
  "asana": true,
  "discord": true,
  "uptime_seconds": 8100,
  "version": "v0.3.1"
}

Scanner

GET /api/scanner

Returns current scanner configuration.

{
  "roots": ["/home"],
  "excludes": ["node_modules", ".cache"]
}

PUT /api/scanner

Update scanner roots and excludes. Persists to config.yaml.

curl -X PUT http://localhost:8300/api/scanner \
  -H "Content-Type: application/json" \
  -d '{"roots":["/home","/data"],"excludes":["node_modules"]}'

Connectivity

POST /api/test-connectivity

Test connection to Asana or Discord.

curl -X POST http://localhost:8300/api/test-connectivity \
  -d "provider=asana"

Response: {"ok":true,"name":"Workspace Name"} or {"ok":false,"error":"..."}


Work Items

GET /api/work-items

List work items. Query params: ?ps=<project_space_id>, ?status=<status>, ?limit=100

{
  "items": [
    {
      "id": "wi-abc123",
      "project_space_id": "ps-def456",
      "title": "Implement feature X",
      "status": "in_progress",
      "created_at": "2026-02-18T14:30:00Z"
    }
  ]
}

POST /api/work-items

Create a work item.

curl -X POST http://localhost:8300/api/work-items \
  -H "Content-Type: application/json" \
  -d '{
    "project_space_id": "ps-def456",
    "title": "New task",
    "status": "backlog",
    "description": "Task details here"
  }'

Export

GET /api/export/events

Export event ledger. Query params: ?format=json|csv, ?ps=<id>, ?state=<state>, ?limit=500

# JSON
curl http://localhost:8300/api/export/events?format=json

# CSV
curl http://localhost:8300/api/export/events?format=csv > events.csv

GET /api/export/snapshot

Full database snapshot as JSON. Includes all tables.

curl http://localhost:8300/api/export/snapshot > snapshot.json

Auto Mesh

GET /api/auto-mesh/status

{
  "enabled": true,
  "interval": "5m",
  "last_poll": "2026-02-18T21:30:00Z",
  "folders": 2,
  "templates": 3
}

POST /api/auto-mesh/poll

Force an immediate poll of watched folders.

curl -X POST http://localhost:8300/api/auto-mesh/poll

GET /api/auto-mesh/templates

List auto mesh policy templates.

POST /api/auto-mesh/templates

Create a template.

curl -X POST http://localhost:8300/api/auto-mesh/templates \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Standard",
    "sync_mode": "bidirectional",
    "comment_mode": "mirror",
    "server_representation": "managed",
    "asana_representation": "linked",
    "discord_representation": "linked"
  }'

PUT /api/auto-mesh/templates

Update a template. Include id in body.

DELETE /api/auto-mesh/templates

Delete a template. ?id=<template_id>

GET /api/auto-mesh/folders

List watched folders.

POST /api/auto-mesh/folders

Add a watched folder.

curl -X POST http://localhost:8300/api/auto-mesh/folders \
  -H "Content-Type: application/json" \
  -d '{"path":"/home/user/projects","template_id":"tmpl-abc"}'

DELETE /api/auto-mesh/folders

Remove a watched folder. ?path=/home/user/projects


Path Suggestions

GET /api/paths/suggest

Autocomplete for filesystem paths. Used by pill input UI.

Query: ?q=<prefix>&limit=10

{
  "paths": [
    {"path": "/home/user/project-a", "has_git": true, "has_beads": true},
    {"path": "/home/user/project-b", "has_git": true, "has_beads": false}
  ]
}

GET /api/paths/suggest-html

Same as above but returns htmx-compatible HTML fragment for dropdown.


Webhooks

POST /api/webhooks/register

Register Asana webhook for a project.

curl -X POST http://localhost:8300/api/webhooks/register \
  -H "Content-Type: application/json" \
  -d '{"project_gid":"1234567890","target":"https://mesh.example.com/webhooks/asana"}'

POST /webhooks/asana

Asana webhook receiver. Auth-exempt (uses Asana's HMAC signature verification).


OAuth

GET /auth/asana

Starts Asana OAuth2 flow. Redirects to Asana authorization page.

Requires FLOW_MESH_ASANA_CLIENT_ID and FLOW_MESH_ASANA_CLIENT_SECRET.

GET /auth/asana/callback

OAuth callback. Exchanges code for token, stores in DB.


Error Responses

All API errors return JSON:

{
  "error": "description of the error"
}
Status Meaning
400 Bad request (invalid input)
401 Unauthorized (missing/invalid auth)
403 Forbidden (invalid CSRF token)
404 Not found
429 Rate limit exceeded
500 Internal server error

Intelligence Endpoints

WebSocket Chat

WS /ws/chat

Send {"text":"..."}, receive {"text":"...","model":"...","intent":"..."}. Per-session conversation context. Requires auth cookie.

HTTP Chat

POST /api/intelligence/chat
Content-Type: application/json
{"text":"list my tasks"}
→ {"text":"Here are your tasks...","model":"claude-3-5-haiku","intent":"chat"}

Intelligence Config

POST /api/intelligence
Content-Type: application/x-www-form-urlencoded
enabled=true&chat_model=claude-3-5-haiku&chat_provider=anthropic&...
→ {"ok":true}

Delegation Status

GET /api/intelligence/delegations
→ {"pending":[],"active":[],"completed":[]}

Delegation Actions

POST /api/intelligence/delegations
Content-Type: application/json
{"id":"deleg-123","action":"approve"}
→ {"ok":true}

Providers

GET /api/providers

List registered providers and their status.

[
  {"name": "asana", "display_name": "Asana", "role": "tracker", "connected": true},
  {"name": "discord", "display_name": "Discord", "role": "chat", "connected": true}
]

Intelligence (Additional)

GET /api/intelligence/delegation-status

Get status of a running delegation.

Query params: delegation_id (required)

{
  "delegation_id": "abc-123",
  "status": "running",
  "started_at": "2026-02-23T12:00:00Z",
  "output": "Working on task..."
}

GET /api/intelligence/skills

List all registered intelligence skills.

[
  {
    "name": "task_list",
    "description": "List work items with optional status filter"
  },
  {
    "name": "triage",
    "description": "Triage inbox — list unlinked or uncategorized tasks and suggest actions"
  }
]

WebSocket

WS /ws/chat

WebSocket endpoint for real-time intelligence chat. Send JSON messages, receive streamed responses.

// Send:
{"text": "Create a task for auth implementation", "channel": "web"}

// Receive:
{"text": "I'll create that task...", "intent": "task_create"}

OAuth

GET /auth/asana

Redirects to Asana OAuth authorization page. Requires FLOW_MESH_ASANA_CLIENT_ID and FLOW_MESH_ASANA_CLIENT_SECRET env vars.

GET /auth/asana/callback

OAuth callback handler. Exchanges code for access token and stores in DB.


Webhooks

POST /webhooks/asana

Asana webhook receiver. Handles:

  • Handshake: Echoes X-Hook-Secret header on initial setup
  • Events: Verifies X-Hook-Signature (HMAC-SHA256), logs events

Auth: Webhook signature verification (not session auth).


Health (Alias)

GET /health

Alias for /api/health. Same response, auth-exempt.


Served v1 surface, and what is only declared

internal/operations is the contract: it is the single declaration every surface (OpenAPI, JSON Schema, CLI, agent tools, MCP) is generated from. It is deliberately larger than what the daemon answers today, and that difference is now a typed artifact instead of an assumption.

internal/api/v1_routes.go holds the implementation side: one entry per v1 request shape that has a handler behind it. operations.BuildParity compares the two and produces a flowmesh.operation-parity.v1 report with three states:

  • served - the operation is answered at the path the registry declares;
  • served_at_another_path - implemented, but somewhere else. This is drift, and it is only accepted while internal/operations/parity-gaps.v1.json explains it;
  • not_served - no handler exists yet. The ledger supplies the reason and the owning gap frame.

A stream is a served operation like any other, with one extra contract: every frame carries an id: that the client echoes back as Last-Event-ID, a reconnect resumes strictly after that position, and a position that cannot be placed in history produces event: resync (reason: cursor_not_found) carrying the newest window instead of a silent gap. The two streams use different cursors — (occurred_at, event_id) for activity, (updated_at, card_id) for progress cards — because they resume over different ledgers.

Served today:

Operation Method Path
work_item.list GET /api/v1/projects/{project_id}/work-items
progress_card.create POST /api/v1/projects/{project_id}/progress-cards
progress_card.list GET /api/v1/projects/{project_id}/progress-cards
progress_card.get GET /api/v1/projects/{project_id}/progress-cards/{card_id}
progress_card.replace PATCH /api/v1/projects/{project_id}/progress-cards/{card_id}
progress_card.cancel DELETE /api/v1/projects/{project_id}/progress-cards/{card_id}
progress_card.step.update PATCH /api/v1/projects/{project_id}/progress-cards/{card_id}/steps/{step_id}
progress_card.card_stream GET /api/v1/projects/{project_id}/progress-cards/{card_id}/stream
progress_card.scoped_state GET /api/v1/projects/{project_id}/progress-cards/{card_id}/scoped-state
capability.list GET /api/v1/capabilities
activity.list GET /api/v1/projects/{project_id}/activity
adapter.list GET /api/v1/adapters
activity.stream GET /api/v1/projects/{project_id}/activity-stream (SSE, resumable)
progress_card.stream GET /api/v1/projects/{project_id}/progress-stream (SSE, resumable)
webhook.ingest POST /api/v1/integrations/{adapter_id}/webhooks/{project_id}/{binding_id}
batch.read POST /api/v1/batch/read
adapter.validate POST /api/v1/adapters/{adapter_id}/validate
adapter.health POST /api/v1/adapters/{adapter_id}/health
work_item.get GET /api/v1/work-items/{work_item_id}
work_item.update PATCH /api/v1/work-items/{work_item_id}
work_item.complete POST /api/v1/work-items/{work_item_id}/complete
work_item.reopen POST /api/v1/work-items/{work_item_id}/reopen
work_item.delegate POST /api/v1/work-items/{work_item_id}/delegate
work_item.comment.create POST /api/v1/work-items/{work_item_id}/comments
work_item.link.list GET /api/v1/work-items/{work_item_id}/links
batch.mutate POST /api/v1/batch/mutate
integration.reconcile POST /api/v1/projects/{project_id}/integrations/{adapter_id}/reconcile
integration.discover POST /api/v1/projects/{project_id}/integrations/{adapter_id}/discover
integration.list GET /api/v1/projects/{project_id}/integrations
integration.bind POST /api/v1/projects/{project_id}/integrations/{adapter_id}/bind
integration.unbind DELETE /api/v1/projects/{project_id}/integrations/{adapter_id}/bind/{binding_id}
integration.revoke POST /api/v1/projects/{project_id}/integrations/{adapter_id}/revoke
integration.health GET /api/v1/projects/{project_id}/integrations/{adapter_id}/health
instruction.create POST /api/v1/projects/{project_id}/instructions
instruction.list GET /api/v1/projects/{project_id}/instructions
instruction.acknowledge POST /api/v1/instructions/{instruction_id}/acknowledge?project_id=
instruction.reject POST /api/v1/instructions/{instruction_id}/reject?project_id=
evidence.create POST /api/v1/projects/{project_id}/evidence
evidence.list GET /api/v1/projects/{project_id}/evidence
evidence.get GET /api/v1/evidence/{evidence_id}?project_id=
adapter.get GET /api/v1/adapters/{adapter_id}
project.list GET /api/v1/projects
project.get GET /api/v1/projects/{project_id}
project.summary GET /api/v1/projects/{project_id}/summary
schema.list GET /api/v1/schemas
schema.get GET /api/v1/schemas/{name}/{version}

capability.list returns the registry itself: every operation with its method, path, CLI binding, required capability and scope, plus a served flag and delivery_state computed from the parity report. A caller can therefore discover what exists and what is actually answered without reading source.

schema.list and schema.get serve the generated contract document itself: the list returns {name, version, revision} descriptors and the read returns the full definition. The document is produced from the registry per request, so what a caller fetches is what the build ships; a copied artifact would drift after the first regeneration.

Project reads return the mesh's own admission record from project_spaces, not a live provider read: a project the mesh has not admitted has no row, and inventing one would report a scope the mesh does not govern. The _global ledger bucket is excluded from the list because it is where system events hang, not a project anyone admitted. project.summary counts work whose status still represents owed work, so archived and done items are not counted as open.

activity.list pages the ledger in (occurred_at, event_id) order and the cursor carries that pair, not a timestamp alone. A single source emitting a burst gives several events the same instant; a boundary keyed on time would repeat or drop them, which is invisible until someone audits a page.

adapter.list and adapter.get read the live provider registry, so an adapter appears only when this deployment actually constructed it — a static catalogue would advertise drivers that are compiled but never registered. Manifests carry field and environment-variable names, never values.

Evidence is a first-class, project-scoped record: kind, evidence_ref (the handle a reader resolves), target_ref (what it proves) and summary (what it shows) are all required, because evidence without a handle cannot be inspected and a bare reference does not say what it demonstrates. Recording the same handle for the same target twice is a CONFLICT; a retry with the same Idempotency-Key returns the original record with 200 instead of claiming a second creation. The read by id requires project_id, because an unscoped lookup would answer from another project.

Instructions encode the rule that mapping is not authority: a new instruction is always pending, and acknowledge answers POLICY_DENIED unless both an authority_ref and a receipt_ref are supplied. Acceptance without proof of authority is refused by the state machine, not by convention, and a settled instruction cannot be transitioned again (CONFLICT).

An integration binding is a project decision, not an adapter observation: the adapter may be able to see many projects, channels or task lists, and none of them belong to the flow until a bind row says so. integration.list therefore reports bindings with adapter_registered alongside state, so a binding whose adapter was removed is visibly orphaned instead of looking healthy. unbind revokes rather than deletes — "we used to sync this" is history worth keeping — and integration.revoke reports how many bindings it changed, because "revoked 0" and "revoked 3" are different answers. integration.health reports only what this deployment can observe; connect, discover and reconcile remain declared and unserved, each with a recorded reason, and they answer NOT_FOUND rather than a plausible-looking result.

The work-item surface is addressed by work item rather than by project, because the id already identifies exactly one row; the project is reported rather than required. PATCH requires expected_revision: two agents editing one work item is the normal case here, and a last-write-wins update silently discards the other change. A stale revision answers CONFLICT, complete on an already-complete item answers CONFLICT rather than claiming success, and delegate refuses an empty assignee because delegating to nobody would clear ownership while reporting success. links reports only real projections — "not in Asana" and "in Asana under an empty id" are different answers.

Progress cards are addressed project-nested everywhere they are served, so the registry declaration was corrected rather than the served path moved, and the surface now accepts the declared spellings too (PUT beside PATCH for replace, POST .../cancel beside DELETE on the card).

adapter.validate checks a submitted manifest against the same rules a registered adapter must satisfy and answers with individual findings, because "invalid" does not tell an adapter author what to fix; the verdict is derived from those findings rather than set beside them, since a report that says valid while listing a failure is worse than no report. adapter.health reports registration and whether the credential the adapter names is present — by variable name and a boolean, never by value. adapter.conformance stays declared and unserved: the runner drives a deterministic fixture, and this deployment registers live adapters, so there is no honest driver.

batch.read executes up to twenty read operations in one request. It dispatches through the server's own handler rather than calling internals, so a batch can only contain operations this deployment actually serves — an entry naming an unserved operation fails here exactly as it would fail directly. Mutations and streaming operations are refused by name, since a batch read that wrote would make the name a lie and would bypass the idempotency and revision guards those surfaces require. Each result carries the status the operation would have returned on its own, so a caller can treat a batched read and a direct call identically. batch.mutate stays declared and unserved with that reason recorded.

webhook.ingest accepts one provider delivery. The binding in the path decides the project — an inbound delivery must resolve to a project through an existing binding, never by reading the payload and guessing which project the sender meant. The delivery is refused unless a signing secret for that adapter is configured (FLOW_MESH_WEBHOOK_SECRET_<ADAPTER>); an unverifiable webhook is an unauthenticated write, so the safe answer is to refuse rather than record whatever arrived. The signature is HMAC-SHA256 over the raw body, compared in constant time. A repeat of the same X-Delivery-Id answers 200 with duplicate: true, which stops the sender retrying without inventing a second event; a delivery with no id header is keyed by its body digest. The stored payload is a summary, not the provider's body.

The two streams are resumable server-sent events. activity.stream carries id: <cursor> on every frame, where the cursor is the same (occurred_at, event_id) encoding the activity list uses — so a client can page with activity.list and then continue live from the last row it read. A reconnect with Last-Event-ID (or ?cursor=) resumes exactly where it stopped instead of re-reading or skipping what arrived while it was away. progress_card.stream emits the project's cards whenever any of them changes. Both accept interval_ms between 50 and 30000, send a keep-alive comment when idle so a proxy does not close an event stream that is simply quiet, and set X-Accel-Buffering: no because a buffering proxy would hold every frame until the stream ended and make a live stream look like a hang.

integration.discover asks the registered adapter what it can see, and answers with each entity marked bound or unbound plus the binding id when the project already owns it. Nothing is written: discovery that bound anything would make "what can you see" indistinguishable from "what did you adopt", and a test asserts zero bindings are created. An unregistered adapter answers NOT_FOUND rather than an empty catalogue, because an empty list reads as "this adapter sees nothing", which is a different and untrue claim. A provider failure is reported as PROVIDER_UNAVAILABLE (502) with the adapter's own message, not swallowed into an empty result.

integration.reconcile pulls one poll of adapter events for every live binding in the project and ingests them through the ledger. The three answers it refuses to blur:

  • no live binding → 409, because reconciling nothing looks exactly like a successful sync that found nothing;
  • a webhook-driven adapter → 409 naming its inbound mode, because a zero-event success would read as "nothing changed" when in truth nothing was polled;
  • a provider error → 502 with the adapter's own message rather than an empty result.

Repeating is safe by construction: the ledger's loop guard deduplicates on the adapter's fingerprint, and the same Idempotency-Key returns the first receipt instead of pulling a second time. The receipt reports events_ingested beside events_duplicate, because "0 new, 3 already known" and "nothing was there" are different answers.

Serving it exposed two storage-layer mismatches, both fixed rather than worked around: event_ledger.source_system was pinned to the five systems that predate the adapter registry (migration 032), and the provider SDK's event vocabulary needed one canonical mapping to ledger operations (internal/provider/eventmap.go) instead of each caller coercing it.

batch.mutate dispatches mutations through the same handlers a direct call hits, and its safety comes from the items rather than from the batch: every item must carry its own idempotency_key (an item without one is refused rather than given a generated key the caller cannot reproduce) and its own body, which is where expected_revision lives. A read inside batch.mutate is refused, as is a mutation inside batch.read; a streaming operation cannot be batched at all. Replaying one batch writes once, because the per-item key is what the underlying operation already deduplicates on.

The generated batch-read-request / batch-mutate-request envelopes were previously declared as the generic single-key shape, which did not describe either body — and the -request suffix branch made the specific declarations unreachable, so the published contract and the accepted body disagreed. Both now declare the real items array.

At this revision the report reads 54 operations: 46 served, 0 drifted, 8 not served. Drift is zero because the progress-card operations were moved onto the project-nested paths that actually serve them (/api/v1/projects/{project_id}/progress-cards/{card_id}); while they were declared flat, the registry described a route with no handler and the parity test had to keep the disagreement on record. A flat path is not a shorter spelling of a nested one — project scope is part of the identity of a card, so the nested path is the true one.

Check the current boundary with:

go test ./internal/api -run TestParityReportDescribesTheServedBoundary -v

The surrounding tests keep the boundary from becoming decoration:

  • TestEveryServedRouteIsARegisteredOperation - the served table cannot claim an operation the registry does not declare;
  • TestEveryServedRouteIsActuallyDispatched - each entry is driven through the real dispatcher and must not answer NOT_FOUND;
  • TestParityReportDescribesTheServedBoundary - every unserved or drifted operation must carry a reason and an owning gap;
  • TestEveryDeclaredGapReasonIsUsed and TestServedOperationsHaveNoDeclaredGap - a stale reason is a failure in both directions;
  • TestCapabilityListSatisfiesItsGeneratedSchema - the served body is validated against the committed schema, because a handler whose fields its own contract forbids fails in the caller's runtime, not in ours.

Generated from the Flow Mesh repository by scripts/build-docs-site.sh. If a page is wrong here, the file it was rendered from is wrong.