The agent API.Four calls.

Authentication and errors

Every call carries the agent’s ingest key as a bearer token. Errors share one shape across the whole API.

{ "error": { "code": "invalid_request", "message": "send between 1 and 500 messages" } }

Send conversation messages

POST /api/agent/v1/conversations/{conversation_id}/messages. The conversation_id is your own identifier, 1 to 200 characters. The response is the internal conversation id and how many messages were inserted.

{
  "title": "Optional; defaults to the first user message",
  "user_ref": "optional end-user reference",
  "messages": [
    { "id": "m1", "role": "user", "content": "Where is my order?",
      "timestamp": "2026-01-02T10:00:00Z" },
    { "id": "m2", "role": "assistant", "content": "It ships tomorrow.", "latency_ms": 820,
      "usage": { "input_tokens": 1200, "output_tokens": 300, "cost": 0.0042, "model": "…" },
      "sources": [{ "title": "Shipping times", "excerpt": "…" }] }
  ]
}

Check the connection

GET /api/agent/v1/ping returns ok, the agent and a list of problems. A wrong or rotated key answers 401.

python -m blue_falnoa doctor https://YOUR-INSTANCE bfa_…
# or: curl -H "Authorization: Bearer bfa_…" https://YOUR-INSTANCE/api/agent/v1/ping

Search published knowledge

GET /api/agent/v1/knowledge/search?q=refund+window&limit=5 returns document id, title and excerpt. Only the published version of each document is searchable.

Workflow agents (A2A)

For A2A agents Blue Falnoa reads the agent card, picks protocol 1.0 or 0.3, and sends one message per workflow step. It polls the task with backoff, or accepts a push callback at POST /api/agent/v1/step-runs/{step_run_id}/callback.

A completed task becomes the step’s outputs. input-required waits for a person, canceled cancels the execution, and failed is an error a person can retry or solve by hand. A step waiting on an outside system is released with POST /api/agent/v1/step-runs/{step_run_id}/unlock.

Verified against the official A2A SDK reference servers only. Not yet run against a third-party production agent.

All guides