HTTP API Examples (curl + REST)

Many teams integrate with nfltr.xyz from CI, internal portals, or agent frameworks using plain HTTP. This guide mirrors what the hosted dashboard does internally: dispatch work, read task status, watch live events, and fetch terminal results—all with curl and your API key.

You need an API key from Settings → API Keys and a running planner that consumes the command queue (typically a long-lived orchestration process on a coordinator machine). Workers must be online under the same account.

Authentication

Every example below uses the same header pattern the relay accepts for programmatic access:

export NFLTR_API_KEY="nfltr_live_xxxxxxxx"   # placeholder — copy from the dashboard

# Preferred for scripts and curl:
curl -s https://nfltr.xyz/api/v1/orchestration/tasks \
  -H "Authorization: ApiKey $NFLTR_API_KEY"

# Equivalent (also accepted by the relay):
curl -s https://nfltr.xyz/api/v1/orchestration/tasks \
  -H "X-Api-Key: $NFLTR_API_KEY"

Browser sessions on the dashboard use cookies instead; for SaaS automation, always send Authorization: ApiKey … or X-Api-Key.

1. Dispatch a task

Queue a new implementer task the same way the dashboard + Start form does. Generate a client-side task id (prefix api- is fine) and POST the dispatch payload. Your planner picks it up on the next command poll (~2s).

TASK_ID="api-$(date +%s)000"

curl -X POST https://nfltr.xyz/api/v1/orchestration/dispatch \
  -H "Authorization: ApiKey $NFLTR_API_KEY" \
  -H "Content-Type: application/json" \
  -d "{
    \"task_id\": \"$TASK_ID\",
    \"type\": \"start_task\",
    \"payload\": {
      \"objective\": \"Add a regression test for the widget cache bug\",
      \"worker_id\": \"MacBook-pro.my-worker-085850\",
      \"execution_role\": \"implementer\"
    }
  }"

Response (200): {"id":"cmd-…","planner_id":"…"} — the command id your planner will ack after calling orch.StartTask.

2. Status (read the digest)

Task state lives in the planner digest the relay stores. Poll the scoped task list—the same source as the dashboard orchestration panel.

curl -s "https://nfltr.xyz/api/v1/orchestration/tasks" \
  -H "Authorization: ApiKey $NFLTR_API_KEY" \
  | jq '.tasks[] | select(.task_id=="'"$TASK_ID"'") | {task_id, state, execution_role, progress_message, pending_question}'

Typical state values: queued, running, waiting_for_input, completed, failed. The row also carries events[] (kind, detail, timestamp) for a lightweight timeline without a separate history call.

3. Watch — live events (poll, SSE, dashboard parity)

The dashboard Operations tab refreshes orchestration events on the same cadence as task polling. You can mirror that in scripts two ways.

Poll the event tail (REST)

# Last 50 fleet-wide events (in-flight tasks); same URL the dashboard uses
curl -s "https://nfltr.xyz/api/v1/orchestration/events/tail?limit=50" \
  -H "Authorization: ApiKey $NFLTR_API_KEY" \
  | jq '.events[] | select(.task_id=="'"$TASK_ID"'")'

Server-Sent Events (SSE)

For streaming consumers, request text/event-stream on the tail endpoint. Hold the connection open; the relay emits JSON event lines as the digest updates (same event kinds as tasks[].events).

curl -N "https://nfltr.xyz/api/v1/orchestration/events/tail?limit=50" \
  -H "Authorization: ApiKey $NFLTR_API_KEY" \
  -H "Accept: text/event-stream"

If the relay returns 405 or 501 for SSE on your environment, fall back to polling GET /api/v1/orchestration/tasks every 2–5s—the dashboard does this automatically.

WebSocket

Live orchestration events are HTTP/SSE-first on nfltr.xyz. WebSocket on the hosted relay is reserved for browser SSH terminals (/dashboard/ws/terminal/{agentId}), not for task event streams. Use SSE or REST polling above for watch semantics.

4. Result (terminal tasks)

When state is completed or failed, read the summary and artifact manifest from the same digest row—no second download endpoint.

curl -s "https://nfltr.xyz/api/v1/orchestration/tasks" \
  -H "Authorization: ApiKey $NFLTR_API_KEY" \
  | jq '.tasks[] | select(.task_id=="'"$TASK_ID"'") | {
      state,
      result_summary,
      error_detail,
      result_manifest_json
    }'

result_manifest_json lists artifact metadata (name, path, sha256) when the worker returned structured artifacts. Pull large blobs through your planner's artifact exchange flow rather than pasting multi-megabyte JSON into tickets.

Steer mid-flight (optional)

Approve dispatch, answer a worker question, or abort—same command queue as dispatch:

# Approve a task waiting on pending_approval
curl -X POST https://nfltr.xyz/api/v1/orchestration/commands \
  -H "Authorization: ApiKey $NFLTR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"task_id":"'"$TASK_ID"'","type":"approve_dispatch"}'

# Answer a pending_question
curl -X POST https://nfltr.xyz/api/v1/orchestration/commands \
  -H "Authorization: ApiKey $NFLTR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"task_id":"'"$TASK_ID"'","type":"answer_question","payload":{"answer":"Use option A"}}'

Endpoint map (relay)

Related docs

• Orchestration control plane — dashboard buttons and command types
• Observe orchestration — watch runs in the browser
• Agent orchestration — roles, workers, and planners