HTTP API Examples (curl + REST)

Many teams integrate with nfltr.xyz from CI, internal portals, or agent frameworks using plain HTTP. This guide uses the relay's task API with curl and your API key: dispatch a task to a connected worker, read its status, watch live events, and steer or cancel it.

You need an API key from Account → API keys and a connected worker under the same account (the dashboard Machines view lists them). Hub agents are different: a hub spawns, steers, and stops its agents itself (see Agent Orchestration). The task list below includes them, but steer and cancel on a hub agent answer 404 with a hint to ask its hub.

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/presence/agents \
  -H "Authorization: ApiKey $NFLTR_API_KEY"

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

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

1. Who is connected

List your connected agents (the same scope as /api/v1/my/agents), optionally only those whose labels match:

curl -s "https://nfltr.xyz/api/v1/presence/agents?selector%5Bnfltr.runtime%5D=node" \
  -H "Authorization: ApiKey $NFLTR_API_KEY" \
  | jq '{cursor, agents: [.agents[] | {agent_id, labels}]}'

The answer carries a cursor taken before the list, so a watcher that starts from it misses nothing.

2. Watch agents come and go

A long-poll: it answers as soon as an agent you may see connects (up), leaves (down) or advertises new labels (labels), or after wait_ms (at most 25000) with no events. Pass the returned cursor to the next call. reset: true means changes may be missing (the cursor is too old, or the relay restarted): list again.

CURSOR=$(curl -s https://nfltr.xyz/api/v1/presence/events -H "Authorization: ApiKey $NFLTR_API_KEY" | jq -r .cursor)
while :; do
  R=$(curl -s "https://nfltr.xyz/api/v1/presence/events?cursor=$CURSOR&wait_ms=25000" -H "Authorization: ApiKey $NFLTR_API_KEY")
  echo "$R" | jq -c '.events[]?'
  CURSOR=$(echo "$R" | jq -r .cursor)
done

Errors are google.rpc.Status JSON: branch on details[0].reason (for example ERROR_REASON_UNAUTHENTICATED, ERROR_REASON_LIMIT_EXCEEDED), never on the message.

3. Tasks live in your hub

The relay carries your agents' traffic but stores no task state: each task belongs to the hub that started it. Read and control tasks from that hub while it runs, with the CLI (it finds your online hubs and asks them, end to end encrypted):

nfltr orch task list --active
nfltr orch task status --task "$TASK_ID" --json
nfltr orch task events --task "$TASK_ID" --tail 0 --json
nfltr orch task steer --task "$TASK_ID" --message "narrow the change to the cache package"
nfltr orch task cancel --task "$TASK_ID" --reason "stuck past SLA"

With no hub of yours online the CLI says so (hub_offline); a hub that is not running cannot be asked. On the hub's machine, nfltr orch hub runs and nfltr orch hub show read the same agents from the hub's own files, running or not.

Endpoint map (relay)

Related docs

• Agent Orchestration — the hub, nodes, and agents
• Observe orchestration — follow runs in the hub
• CLI reference — the same task views from the terminal