HTTP API reference

> For people who script against Agent Taskbay or build on it: every route under /api, with its method, who may call it, what it accepts and what it > returns. Examples marked "Observed" were run against a local development server.

There is no stable API yet. The routes exist to serve the console. They are not versioned (no /api/v1), have no deprecation policy, and may change in any minor release while the project is pre-1.0 (package version 0.2.0). A versioned, token-authenticated client API is proposed in #31. Until then, pin a version if you depend on a route.

The "Use" column in the route index is a reading aid, not a promise: Integration routes are the ones a script is most likely to want and that the console uses as plain request/response APIs; Console routes are UI plumbing (sign-in, live updates, access management) and are the most likely to change.

On this page: Authentication and roles · Conventions · Route index · Sign-in routes · Agents · Sending messages and commands · Tasks · Task workflow · Inbox · Approvals · Notifications · Audit · Access management · Artifacts · Push webhook · Limits

Authentication and rolesCopy Anchor Link

Every route except the three sign-in routes and the push webhook requires a signed-in person.

• Session cookie only. There is no API key, bearer token or service-token authentication for these routes. In oidc mode the session cookie (__Host-a2a-session, HttpOnly, Secure, SameSite=Lax) is issued after browser sign-in. In development mode every request is the local administrator and needs no cookie. See Sign in and roles.

• Roles. Each route is guarded by one of three permissions:

  Permission	Allowed roles	Meaning
  read	admin, operator, viewer	Look at agents, tasks, approvals, inbox, audit for one's own scope
  operate	admin, operator	Send messages, claim and assign work, open and decide approvals
  administer	admin	Register agents, manage teams and grants, escalation policy, notification channel, organization audit

• Per-agent grants. Roles are a ceiling. Administrators see every agent. For operator and viewer, an agent (or one skill of it) is visible only through an enabled grant whose subject is the organization, the person or one of their teams. read needs any grant; operate needs an operate grant and a role that can operate. A resource outside the caller's grants answers as if it does not exist (404), not 403. A skill-scoped grant never authorizes a generic send.

• Order of checks. Sign-in (401), role (403), rate limit (429), then, for non-GET requests, the origin check, then the handler.

Origin check (CSRF)Copy Anchor Link

Requests other than GET, HEAD and OPTIONS are rejected with 403 (This action is not permitted.) when:

• the Sec-Fetch-Site header is cross-site, or
• in oidc mode the Origin header is missing or is not exactly A2A_AUTH_ORIGIN, or
• in development mode an Origin header is present that is neither the request's own origin nor a loopback origin with the same scheme and port.

A script that is not a browser must therefore send an Origin header equal to the configured origin, and it can only do so with a valid session cookie copied from a browser. That is an awkward workflow, and the reason a token API is planned.

ConventionsCopy Anchor Link

Error shapesCopy Anchor Link

Errors use one of these shapes. Messages are written for people and may be reworded; match on the status code.

Common statuses:

Rate limitsCopy Anchor Link

Fixed 60-second windows in the database, so they hold across web replicas.

When a limit is hit the route answers 429. The webhook adds Retry-After: 60. The limits are not configurable.

Route indexCopy Anchor Link

Route handlers run on the Node.js runtime. Task and event content shown here is what Agent Taskbay has stored, not a live read from the agent.

Sign-in routesCopy Anchor Link

GET /api/auth/loginCopy Anchor Link

Public. In development mode it answers 303 to /tasks. In oidc mode it stores encrypted login state for 10 minutes, sets the __Host-a2a-login cookie and answers 303 to the provider. Query returnTo is honored only if it is a relative path starting with a single / (otherwise /tasks). Errors: 429 Too many sign-in requests.; 503 Sign-in service unavailable. (misconfiguration or provider unreachable).

Observed (development mode): 303, location: http://localhost:<port>/tasks.

GET /api/auth/callbackCopy Anchor Link

Public. Completes the authorization-code flow with PKCE, requires an enabled membership for the configured organization, rotates any previous session and answers 303 to the validated returnTo on the configured origin with the session cookie set. Every failure, including an expired or reused attempt, an unknown person and a provider error, is the same 401 Sign-in failed. Start a new sign-in attempt.; provider responses are never reflected. Rate limited (429).

POST /api/auth/logoutCopy Anchor Link

read. Revokes the session, records session.ended and clears the cookie. Response 200 {"signedOut":true}.

GET /api/auth/sessionCopy Anchor Link

read. Observed (development mode):

{ "user": { "displayName": "Local operator", "role": "admin" }, "mode": "development" }

mode is development or oidc. The launcher polls this route to know the server is up.

AgentsCopy Anchor Link

GET /api/agentsCopy Anchor Link

read. Fetches every visible agent's Agent Card (this makes outbound requests and records a card snapshot per agent) and returns { "agents": [ ... ] }. Each entry has id, cardUrl, source (env or managed) and either name, description, skills, card, trust or, when discovery failed, error. A failing agent stays in the list. trust is unsigned, verified, untrusted or invalid. Non-administrators receive a reduced card for agents they only partly hold (see Authentication and roles).

Calling this route is also what stores the card snapshot that extension negotiation reads; see the note there.

POST /api/agentsCopy Anchor Link

administer. Body { "cardUrl": "<string>" }. Registers the agent; it does not fetch the card. Response 201 { "agent": { "id", "cardUrl", "source": "managed" } }. Registering the same URL again returns the same agent (and re-enables it if it was removed). 400 for a missing cardUrl, a URL that is not http(s), or one with credentials, a query string or a fragment. The network policy (origin allowlist, private addresses) is applied when the card is first fetched, not at registration. The audit trail records agent.registered.

Observed: {"agent":{"id":"e6e890ae-...","cardUrl":"http://127.0.0.1:4011/showcase/card.json","source":"managed"}}.

POST /api/agents/previewCopy Anchor Link

administer. Body { "cardUrl": "<string>" }. Fetches and validates a card without credentials and without registering it. Response { "card", "resolvedCardUrl", "report" } where report is the compliance report (version 1.0, 0.3 or unknown, a score and a list of issues). Does not record a snapshot. The card URL may be the card itself (a path ending in .json) or a base URL, in which case /.well-known/agent-card.json is tried.

GET /api/agents/{agentId}Copy Anchor Link

read. { "id", "cardUrl", "source", "card", "trust", "report" }. 404 if unknown or not visible. Failures talking to the agent surface as 502 (or the status of the underlying error). Records a card snapshot.

DELETE /api/agents/{agentId}Copy Anchor Link

administer. 200 { "removed": true }. 409 with This agent comes from A2A_REGISTERED_AGENTS and can't be removed from the UI. for environment-seeded agents.

Sending messages and commandsCopy Anchor Link

All sends are recorded as a durable command first, then dispatched by a worker. The routes below differ in how long they wait.

Command bodyCopy Anchor Link

POST /api/agents/{agentId}/commands, /messages and /stream accept the same strict object:

Server rules: the console always asks the agent to return immediately and observes progress separately; extensions the agent advertises and Agent Taskbay understands are negotiated automatically; a task's skill and context cannot be changed by a later message; a scoped caller cannot start a send in an existing context.

POST /api/agents/{agentId}/commandsCopy Anchor Link

operate. Requires the Idempotency-Key header (400 An idempotency key of 1–255 characters is required. without it). Returns immediately.

curl -X POST http://127.0.0.1:3002/api/agents/AGENT_ID/commands \
  -H 'Content-Type: application/json' -H 'Idempotency-Key: demo-1' \
  -d '{"text":"hello"}'

Observed: 202 Accepted, header Location: /api/commands/<id>, body:

{ "command": { "id": "69c44ee5-700f-47ab-aafd-193b19fc94d2", "agentId": "e6e890ae-...", "tenant": "", "action": "send",
  "messageId": "27a02477-...", "status": "pending", "result": null, "error": null,
  "createdAt": "2026-10-06T20:04:40.363Z", "updatedAt": "2026-10-06T20:04:40.363Z" } }

Repeating the request with the same key and body returns 202 with the same command and its current state. Same key with different content: 409 This idempotency key already belongs to different command content. Unknown agent: 404 Unknown agent. Unknown keys or an empty send: 400 with the validation message.

Command status values: pending, dispatching, succeeded, failed, uncertain. uncertain means the request may have reached the agent and the result is unknown; Agent Taskbay does not resend automatically. When succeeded, result is { event, localId, taskId, tenant }, where localId is the task's local ID and event is the agent's reply (task or message).

GET /api/commands/{commandId}Copy Anchor Link

read. { "command": { ... } } as above. 404 for an unknown or invisible command. Poll this after a 202.

POST /api/agents/{agentId}/messagesCopy Anchor Link

operate. Compatibility route: submits the command, waits up to 50 seconds, and returns the result. The idempotency key defaults to the messageId when the body has one (so retries are safe), otherwise to a random value (retries are not safe).

Success 200: { "result": <task or message>, "localId", "commandId", "sessionId", "requestId", "telemetry": [] }. 409 when the command failed or ended uncertain (the message carries the reason). 504 when still pending after 50 seconds: Command accepted; waiting stopped. Query /api/commands/<id> for its outcome before submitting again. The command continues; do not resubmit.

POST /api/agents/{agentId}/tasks/{taskId}/cancelCopy Anchor Link

operate. {taskId} here is the remote task ID. Optional query ?tenant=. Optional Idempotency-Key (random if absent, so a retry is not de-duplicated). Waits like /messages and returns the same shape; the result is the agent's updated task.

POST /api/agents/{agentId}/streamCopy Anchor Link

operate. Server-sent events (Content-Type: text/event-stream, Cache-Control: no-store, no-transform). Body is a command body, or { "resubscribe": true, "taskId": "<remote id>", "tenant": "" } to follow an existing task. Events come from committed state, not from the agent's own stream, so a dropped browser connection never loses or repeats work.

The stream ends with end when the task is paused (input required, auth required) or finished, after about 50 seconds, or on error. The task keeps running; reconnect with resubscribe. Pre-stream problems are ordinary HTTP errors (400, 403, 404). Observed event order for a new send: accepted, persisted, snapshot.

TasksCopy Anchor Link

GET /api/tasksCopy Anchor Link

read. Query:

Response { "tasks": [ ... ] }, newest first. Rows carry localId, taskId, tenant, agentId, agentName, state (TASK_STATE_*), kind, title, contextId, createdAt, updatedAt, referenceLinks, workflow (null or { assigneeMembershipId, assigneeName, dueAt, escalationLevel }), and empty messages and artifacts arrays; use the detail route for content. Observed: {"tasks":[{"localId":"7470c984-...","taskId":"form-task-0","state":"TASK_STATE_INPUT_REQUIRED","kind":"task","title":"hello", ...,"workflow":null}]}. Bad filter: 400 Invalid task filter.

GET /api/tasks/{taskId}Copy Anchor Link

read. {taskId} is the local ID. { "task": <view> } with messages (each with id, role user or agent, normalized parts, timestamp, fromStatus for the agent's question), artifacts, transitions, version and the fields above. 404 Task not found.

GET /api/task-viewsCopy Anchor Link

read. Pages durable content by local task ID, for chat and flow views. limit 1 to 100 (default 100) and after (a local UUID) are validated: 400 limit must be 1–100 and after must be a local UUID. Response { "tasks": [ <view> ], "next": "<local id>" | null }.

GET /api/tasks/eventsCopy Anchor Link

read. A long-lived SSE signal that "something changed for this organization". Frames carry no task data (data: {}); clients re-query. Event names: ready (first frame), freshness (a change was committed), resync (sent after 15 seconds of silence so clients refresh anyway). Each frame is preceded by retry: 1000. The server closes the stream after 55 seconds; reconnect.

Task workflowCopy Anchor Link

Ownership is local to Agent Taskbay and independent of the remote task state. All routes need operate on the task's agent and skill, and apply only to A2A tasks (not direct-message threads: 409 Only A2A tasks can be assigned.). Responses are { "assignment": { assigneeMembershipId, claimedAt, dueAt, escalationLevel, escalatedAt, updatedAt } } (or null fields). Rules: anyone with access may claim an unowned task; only the owner or an administrator may release, reassign or change the due time of an owned task (403); a claim on a task owned by someone else is 409 This task is already owned by someone else.; claiming, assigning and setting a due time need an unfinished task (409 The task is already finished.).

Every change is recorded in the audit trail. Observed: claim returned {"assignment":{"assigneeMembershipId":"89254850-...","claimedAt":"...","dueAt":null,"escalationLevel":0,"escalatedAt":null,"updatedAt":"..."}}.

Escalation policyCopy Anchor Link

GET /api/escalation-policies (administer) returns { "policies": [ { id, agentId, targetMembershipId, enabled, updatedAt } ], "people": { ... } }. PUT takes { "agentId": "<uuid>" or null, "targetMembershipId": "<uuid>", "enabled": true|false } (agentId: null applies to every agent) and answers { "policy": { ... } }. The target must be an active operator or administrator (422). When a task passes its due time and a policy exists, a worker reassigns it to the target once per due time. With no policy it only shows as overdue.

InboxCopy Anchor Link

GET /api/inboxCopy Anchor Link

read. One page of tasks and approval requests the caller may read, newest update first.

Response { "items": [ ... ], "next": "<cursor>" | null }. Each item: kind, id (task local ID or request ID), taskId, agentId, agentName, skillId, status, open, title, risk, assigneeMembershipId, assigneeName, dueAt, expiresAt, escalationLevel, updatedAt. Errors are 400 (Unknown inbox view., Invalid cursor., ...). No event payloads are read, so the route stays cheap on large histories.

ApprovalsCopy Anchor Link

An approval request asks a reviewer to approve one exact action on a task. The decision is bound to the revision the reviewer saw. Concepts: Human in the loop.

GET /api/decisionsCopy Anchor Link

read. Query status (pending, approved, rejected, changes_requested, expired, superseded; else 400 Unknown status.), taskId, and assigned=me. Returns up to 100 requests, { "decisions": [ <request> ] }, each with the agent and task context (agentName, taskTitle, taskState). There is no paging.

A request has id, requesterUserId (null when the agent asked), taskId, agentId, tenant, skillId, kind (send_message or send_data), status, title, summary, risk, policy ({ allowedOutcomes, separationOfDuties }), assignedMembershipId, currentRevision, expiresAt, createdAt, updatedAt.

POST /api/decisionsCopy Anchor Link

operate. Opens a request (a person proposing an action for review).

Opening a request marks any older open request on the same task superseded: one approval is live per task. Response 201 { "decision": <request> } with Location: /api/decisions/<id>; 200 when the same key and content already created it. Errors: 404 unknown task, 409 task finished or not an A2A task or key reused for a different request, 422 assignee. Observed: a minimal body (taskId, title, expiresAt, action) produced status: "pending", risk: "medium", currentRevision: 1 and the default policy.

GET /api/decisions/{decisionId}Copy Anchor Link

read. { "request", "revisions", "decisions", "executions", "people", "viewer" }. Revisions carry number, action, digest, authorType (agent, user, system). Decisions carry outcome, rationale, revisionId, revisionDigest, reviewer and delegate IDs. Executions correlate each approval with the command it produced (status, observedTaskState). Reading refreshes execution status from the task. A non-UUID or invisible ID is 404 Decision request not found.

POST /api/decisions/{decisionId}/revisionsCopy Anchor Link

operate. { "action": <action>, "expectedRevision": <int >= 1> }. Adds a revision (same action kind), resets the request to pending and voids earlier reviews. 201 { "decision": <request>, "revision": { id, number, action, digest, authorType, authorUserId, createdAt } }. 409 when closed, expired or expectedRevision is stale; 422 for a different kind.

POST /api/decisions/{decisionId}/decisionsCopy Anchor Link

operate. Records one decision. Requires Idempotency-Key. Body:

Rules: the request must be pending and unexpired; the policy must allow the outcome (403); with separationOfDuties the requester cannot decide (403 The requester cannot decide their own request.); an assigned request can be decided only by the assignee or an administrator. approve and edit send the exact revision to the agent once, as a command with metadata.approval (requestId, decisionId, revision, revisionDigest); reject and request_changes send nothing. Approving a request whose task has finished, or deciding after expiry, closes it (superseded or expired) and answers 409 This request is <reason> and can no longer authorize an action.

Response 201 { "decision", "request", "execution", "replay": false }; a replay of the same key returns 200 with "replay": true. A key reused with a different decision is 409. Observed: self-deciding with the default policy returned 403, and a reject without a rationale returned 400 A rationale is required for this decision.

GET /api/reviewersCopy Anchor Link

operate. Query taskId (local UUID). { "reviewers": [ { membershipId, displayName, role, self } ] }: active admins and operators who may operate that task's agent and skill. 404 Task not found.

NotificationsCopy Anchor Link

GET /api/notificationsCopy Anchor Link

read. The caller's own notifications. Query unread (true/false, default false), limit (1 to 100, default 30), cursor. Response { "items": [ { id, kind, title, body, link, taskId, createdAt, readAt } ], "next", "unread" }. Items about tasks the person can no longer read are hidden. Kinds: approval.requested, approval.revised, approval.assigned, approval.decided, approval.expiring, approval.expired, approval.superseded, task.assigned, task.escalated, task.needs_input, task.finished, task.failed, test. Unknown query keys are 400.

POST /api/notifications/readCopy Anchor Link

read. Body { "ids": [ "<uuid>", ... ] } (1 to 100) or { "all": true }, not both (400 Provide either ids or all.). Response { "updated": <count> }. Only the caller's own rows are affected.

GET /api/notifications/channelCopy Anchor Link

administer. Webhook status: { configured, enabledForOrganization, host, counts: { pending, processing, delivered, failed }, lastFailure: { at, message } | null }. Observed with no webhook set: configured: false.

POST /api/notifications/testCopy Anchor Link

administer. Queues a test notification through the real pipeline, including the webhook. 202 { "queued": true }.

AuditCopy Anchor Link

GET /api/auditCopy Anchor Link

read. Query taskId (UUID), group (all, approvals, ownership, commands, access), actor (user UUID), since and until (ISO datetimes), cursor, limit (1 to 200, default 50). Without taskId the caller must be an administrator (403). With taskId any member who can read that task's agent sees that task's trail, without identity and access events (404 if not visible). Response { entries: [ { key, at, kind, actorUserId, taskId, subjectId, data } ], people, context, next, viewer }. since after until is 400. Unknown query keys are 400.

GET /api/audit/exportCopy Anchor Link

administer. Same query; limit defaults to 200. Returns text/csv with columns time, kind, actor, task, subject, detail as an attachment named audit-trail.csv. When more rows exist the header X-Next-Cursor carries the cursor to pass as cursor. Cells that start with =, +, -, @, tab or carriage return are prefixed with ' so spreadsheets do not execute them. The audit trail is append-only: database triggers reject updates and deletes.

Access managementCopy Anchor Link

GET /api/admin/securityCopy Anchor Link

administer. { organizationId, teams, memberships, teamMembers, grants, credentials }. Credential entries show only agentId, kind, enabled and updatedAt; secrets are never returned.

POST /api/admin/securityCopy Anchor Link

administer. A strict, discriminated body on action; success is { "updated": true }, a malformed body is 400 Invalid access management request., and other failures are 400 with a message.

All changes are audited. Credential values are managed with npm run security:credentials, not through the API.

ArtifactsCopy Anchor Link

GET /api/artifacts/{digest}Copy Anchor Link

read. {digest} is a 64-character lowercase hex SHA-256. Returns the stored bytes only if the caller can read a task that references that artifact; otherwise 404 Not found (plain text). The response is always application/octet-stream with Content-Disposition: attachment; filename="artifact", X-Content-Type-Options: nosniff and Content-Security-Policy: default-src 'none'; sandbox, so stored content is never rendered by the browser from this route. Objects are limited to 16 MiB each.

Push webhook (agents only)Copy Anchor Link

POST /api/webhooks/a2a/{registrationId}Copy Anchor Link

Not for people. This is the callback that Agent Taskbay registers with agents that support A2A push notifications when A2A_PUSH_CALLBACK_ORIGIN is set. It does not use a session. The caller must send Authorization: Bearer <token> where the token is the 43-character value Agent Taskbay derived for that registration. The body must be JSON with content type application/json or application/a2a+json. An optional X-A2A-Delivery-Id header (printable ASCII, at most 255 characters) de-duplicates repeats.

LimitsCopy Anchor Link

• No versioning, deprecation policy, OpenAPI document or typed client. See #31.
• Session-cookie authentication only; scripts need a browser-issued cookie and a matching Origin. User-delegated and service-token access: #1, #31.
• No search, saved views or bulk actions on lists (#5). Approval lists are capped at 100 and are not paged.
• Task content is what Agent Taskbay has observed. It can lag the agent by the worker's polling interval when streaming and push are unavailable.
• Real-time updates are a "something changed" signal followed by a re-query, not a data stream.

RelatedCopy Anchor Link

• Configuration reference
• Data model
• Durable tasks
• Human in the loop
• AG-UI adapter