> ## Documentation Index > Fetch the complete documentation index at: https://docs.getbindu.com/llms.txt > Use this file to discover all available pages before exploring further. # Liveness and basic configuration probe. > Unauthenticated, cheap, returns immediately. Does NOT verify downstream connectivity (Supabase, OpenRouter, Hydra) — it only reports whether the gateway process has booted with the expected config. Use this for container liveness checks; for readiness probes that include downstream health, build a higher-level check. ## OpenAPI ````yaml /gateway-openapi.yaml get /health openapi: 3.1.0 info: title: Bindu Gateway API version: 1.0.0 summary: >- External HTTP surface of the Bindu Gateway — a task-first orchestrator that plans over a caller-supplied catalog of A2A agents. description: > # Bindu Gateway API The **Bindu Gateway** sits between an external system (your app, a custom frontend, another service) and one or more **Bindu A2A agents**. It takes a user question + an agent catalog and returns a streaming plan: the gateway's planner LLM decomposes the request, invokes A2A agents via the polling protocol, and emits Server-Sent Events in real time. Distinct from the per-agent **Bindu Agent API** (see the repo-root `openapi.yaml`), which describes what a single `bindufy()`-built agent exposes. This spec documents the **gateway** — the orchestrator sitting one layer up. --- ## Mental model: one endpoint, many turns Every orchestration goes through `POST /plan`. Inside, the planner LLM runs an agentic loop — it calls A2A agents as tools, the results feed back into the LLM, and the loop continues up to `max_steps` or until the plan resolves. Two auxiliary endpoints support health probing and DID-based peer authentication: | Path | Purpose | |---|---| | `POST /plan` | Open a new plan or resume an existing session. Streams SSE. | | `GET /health` | Liveness + cheap config probe. | | `GET /.well-known/did.json` | The gateway's own DID document (only when a DID identity is configured via env). | --- ## Request shape A `/plan` request carries three things: 1. **`question`** — the user's natural-language input. 2. **`agents[]`** — the catalog of A2A peers the planner may call, each with an endpoint, authentication descriptor, and list of skills. The gateway does **not** host agents; the caller is always the source of truth for "what can we reach." 3. **`preferences`** and **`session_id`** (both optional) — caps and continuation handles. The shape is stable and additive; unknown top-level keys are accepted (forward-compatible `.passthrough()`), but `preferences` keys are strict snake_case. Clients sending camelCase preferences will have them silently dropped — match the schema below. --- ## Response shape — Server-Sent Events The happy path returns `200 OK` with `Content-Type: text/event-stream`. Errors surface in three ways depending on when they occur: - **Before streaming starts** (auth failure, invalid JSON, malformed request, session creation failure): `401`/`400`/`500` with a JSON `{ error, detail? }` body. - **During streaming** (planner or tool failure): a single `event: error` SSE frame, followed by `event: done`. - **Never silent** — every successful plan closes with `event: done` (empty payload). Consumers should treat the absence of `done` as an incomplete stream. SSE events emitted during a plan, in typical order: | Event | When | Purpose | |---|---|---| | `session` | Once, before the plan starts | Carries session identifiers so clients can correlate. | | `plan` | Once, when the planner starts its first turn | Announces plan_id. | | `text.delta` | Many (streaming planner output) | Incremental text chunks for the final assistant message. | | `task.started` | Per A2A tool call | The planner decided to call a peer agent. | | `task.artifact` | Per A2A tool call | The peer returned an artifact, wrapped in a `` envelope. | | `task.finished` | Per A2A tool call | Terminal state of the peer call. | | `final` | Once, at the end | Stop reason + usage counters. | | `error` | Only on failure during streaming | Human-readable message. | | `done` | Always last | Empty marker so clients can close cleanly. | --- ## Recipes (internal) The gateway supports **progressive-disclosure recipes** — markdown playbooks the planner lazy-loads when a task matches (e.g., "multi-agent research", "payment-required flow"). Recipes are operator- authored and not part of this HTTP API surface: they live in `gateway/recipes/` and are injected automatically into the planner's system prompt as metadata, with the body fetched on demand via an internal `load_recipe` tool. You cannot upload, list, or invoke recipes via the HTTP API; they influence the planner's behavior transparently. See the gateway README §Recipes for authoring details. --- ## A2A protocol pass-through The gateway speaks A2A (JSON-RPC 2.0 over HTTP) to every peer in `agents[]` — `message/send` + `tasks/get` polling, with DID signature verification when configured. A2A task states (`submitted`, `working`, `input-required`, `auth-required`, `payment-required`, `completed`, `failed`, `canceled`) flow through to the planner; terminal states become `task.finished` events, non-terminal states can surface as planner text or trigger recipe-based handling (e.g., surfacing a `payment-required` URL to the user). See the Bindu Agent API spec (`openapi.yaml` at the repo root) for the full A2A protocol surface. contact: name: Bindu Team url: https://docs.getbindu.com/ license: name: Apache-2.0 servers: - url: http://localhost:3774 description: Local development (default port) - url: https://gateway.example.com description: Production deployment (replace with your host) security: [] tags: - name: Plan description: | Open a new plan or resume an existing session. Server-Sent Events stream back the planner's turn-by-turn output, tool calls, and final answer. - name: Health description: Liveness and basic configuration probes. - name: Identity description: | The gateway's self-published DID document, for A2A peers that need to verify `did_signed` outbound calls. Only exposed when the gateway has a DID identity configured via env. paths: /health: get: tags: - Health summary: Liveness and basic configuration probe. description: | Unauthenticated, cheap, returns immediately. Does NOT verify downstream connectivity (Supabase, OpenRouter, Hydra) — it only reports whether the gateway process has booted with the expected config. Use this for container liveness checks; for readiness probes that include downstream health, build a higher-level check. operationId: getHealth responses: '200': description: | Gateway is up. Response body describes the process — version, identity, configured planner model, recipe count, uptime. The 200 status is informational, not a health gate: read `status` and `ready` in the body to distinguish healthy from degraded. content: application/json: schema: $ref: '#/components/schemas/HealthResponse' example: ok: true name: '@bindu/gateway' session: stateful supabase: true security: [] components: schemas: HealthResponse: type: object required: - ok - name - session - supabase description: > Simplified gateway health payload providing essential status information. properties: ok: type: boolean description: Overall health status - true when healthy, false when unhealthy. example: true name: type: string description: Gateway service name identifier. example: '@bindu/gateway' session: type: string enum: - stateful - stateless description: Session persistence mode configuration. example: stateful supabase: type: boolean description: Whether Supabase storage backend is connected and healthy. example: true ````