HTTP API

Bot Development Kit (BDK) hosts expose one public HTTP surface. In the default multi-agent layout, each agent uses /<slug>/v1/*; --mode single serves the same routes at /v1/*. Routes use the agent's HTTP auth chain, and session-owned resources return 403 to another principal.

Unless a section says otherwise, the default auth policy is localDevStrict(). --bearer-token replaces it with bearer auth, and --allow-anonymous replaces it with anonymous access. Built-in JSON routes use { ok: false, error: "<code>", message? } for errors, and MCP uses JSON-RPC. Custom channel routes answer hosted callers with an empty 202; see Call custom channel routes.

Host routes

These routes live at the host root in multi-agent mode. The index routes exist only when the playground is enabled.

--no-playground removes the two index routes. --no-docs removes the documentation site.

Start a session

POST /v1/session opens a durable conversation.

curl -X POST http://127.0.0.1:3000/<slug>/v1/session \  -H 'content-type: application/json' \  -d '{"message":"What can you do?"}'# {"ok":true,"sessionId":"ses_…","continuationToken":"http:…",#  "playgroundUrl":"…?sessionId=ses_…","traceUrl":"…/v1/session/ses_…/events"}

Once accepted, the response returns sessionId for inspection and continuationToken for follow-ups; follow the stream for progress.

Send a follow-up

POST /v1/session/:sessionId continues an existing conversation.

curl -X POST http://127.0.0.1:3000/<slug>/v1/session/ses_… \  -H 'content-type: application/json' \  -d '{"continuationToken":"http:…","message":"Make it shorter."}'

The route accepts any chat session, including one created by a custom channel. Each accepted follow-up rotates the continuation token and returns the replacement. A message sent to a busy session interrupts the active turn before starting.

The route returns 409 for a stale token or task session, and 403 when the caller doesn't own the session.

Stream or replay session events

GET /v1/session/:sessionId/stream is the live NDJSON feed.

curl -N 'http://127.0.0.1:3000/<slug>/v1/session/ses_…/stream?startIndex=0'

The route replays one event per line from startIndex, then follows new events. The default 0 replays the full stream. To reconnect without duplicates, pass the last index you received plus one.

GET /v1/session/:sessionId/events returns a one-shot NDJSON dump. Pass ?format=json for { sessionId, events, playgroundUrl }. See Stream events for the event vocabulary.

Manage sessions

On loopback under serve --dev, the session list includes every principal so webhook and schedule sessions appear in the playground. The cost route returns 404 for an unknown session.

Call a tool without a model turn

POST /v1/tools/:toolName runs a server tool with no model turn.

curl -X POST http://127.0.0.1:3000/<slug>/v1/tools/inspect_pr \  -H 'content-type: application/json' \  -d '{"input":{"prUrl":"https://github.com/acme/checkout/pull/42"}}'# {"ok":true,"toolName":"inspect_pr","callId":"tool_inspect_pr_…",#  "isError":false,"result":{…},"durationMs":12}

Omit both identifiers for an unbound call. Agent-execution tools return 400, and an unknown name returns 404 with the available names. See Tools for session binding, busy-session rules, and error codes.

Discovery routes

These read-only routes describe the running agent.

An unknown tool name returns 404 with available names. If an MCP connection can't list its tools, the catalog skips that connection and includes it in connectionErrors.

List and download artifacts

The list follows the same ownership rules as GET /v1/sessions. See Artifacts for tagging and record fields.

Call custom channel routes

Authored routes mount under /v1/channels/<id> with their declared methods and paths, and each channel's auth chain applies. A hosted caller receives 202 Accepted with an empty body, never the handler's response. See Route responses.

MCP endpoint

Both MCP routes use stateless streamable HTTP. Send protocol requests with POST; GET and DELETE return 405.

See MCP connections to connect one agent to another.

Playground eval routes

The playground Evals tab and remote eval commands use these routes:

Poll the run route until its status is completed, failed, or cancelled. Entries within filterIds and tags use OR semantics; when both fields are present, a case must match each group.

Dev-mode routes

These routes exist only under serve --dev.

Schedules and reminders never fire automatically in dev mode. These routes run them manually.

Playground assets

GET /playground and GET /playground/assets/:file serve the playground. --no-playground removes both routes.

Status codes

Built-in routes use these common status codes.

Related

• Sessions
• Channels
• Tools
• Deployment