Wire protocol (version 1)

This is how the askdare server streams a chat turn to its clients: the embed iframe app now, @boldare/askdare/react later. The protocol belongs to askdare; raw OpenAI stream events are never forwarded (ADR-0002).

Source of truth: packages/askdare/src/protocol/.

Endpoints

Every path sits under the route's base path: /api/chat by default, or basePath in createChatHandler. Any other path or method answers 404.

• POST /messages takes { "botId", "text", "resumeToken"?, "attachments"?, "context"?, "locale"? }. Without resumeToken, the server starts a new conversation and sends conversation.created. locale is the visitor's language tag, passed to the bot's instructions.
• POST /history takes { "botId", "resumeToken" } and answers { "messages": [{ "id", "role", "text", "citations", "attachments" }] }, where attachments is a count.
• DELETE /conversation takes the same body and answers 204 with no body.
• Same origin only. Every POST and DELETE except /doctor refuses cross-site requests with 401. The API serves the chat's own iframe, which runs on the same origin.

Transport

• Request: POST with a JSON body and a Bearer access token. No cookies.
• Response: Server-Sent Events. Clients read them with fetch and a ReadableStream, because EventSource can't send a POST body.
• Response headers:
  • Content-Type: text/event-stream; charset=utf-8
  • Cache-Control: no-cache, no-transform
  • X-Accel-Buffering: no
  • x-askdare-protocol: 1
• Framing: one event per frame, event: <type> followed by data: <json> and a blank line. The JSON always repeats type.
• First byte: the server sends a comment (: ok) before contacting OpenAI. Heroku requires a first byte within 30 s.
• Heartbeat: a : ping comment every 15 s, on a timer that is independent of model output. Heroku closes connections after 55 s without bytes.

Events

Attachments

When a bot has attachments enabled, files travel separately from the message:

1. POST /attachments with the raw file as the body (Content-Type: application/octet-stream), the Bearer token, and two headers: x-askdare-bot (bot ID) and x-askdare-filename (URL-encoded name). The server detects the type from the bytes, uploads the file to OpenAI and answers { "attachment": { "id", "kind": "image" | "pdf", "name", "size" } }.
2. POST /messages with "attachments": ["<id>", …] next to text. text may be empty when files are attached.

id is an encrypted handle bound to the bot and the visitor, valid for 1 hour. OpenAI file IDs never reach clients, and the server refuses raw file IDs. History (POST /history) reports only how many files a message had.

Dictation

When a bot has voice enabled, POST /transcriptions takes a recording as the raw body (Content-Type: application/octet-stream) with the Bearer token and two headers: x-askdare-bot (bot ID) and x-askdare-languages (comma-separated language tags, used as hints). It answers { "text": "…" }. Clients put the text in the message field for the visitor to check; nothing is sent to the model.

Identity

POST /session takes an optional identityToken: the JWT from askdare('identify'), or null to sign out. Without it, a renewal keeps the identity the previous access token had. Widgets send the page's latest token with every session request. The answer adds identified (boolean), identityKey (an HMAC that tells users apart without revealing them; widgets keep one conversation handle per key), resumeToken when signing in adopted an anonymous conversation, and identityProblem when a token was refused. A signed-in access token expires with the identity token. Identities travel inside the encrypted access token; clients never see the claims (ADR-0009).

Diagnostics

POST /doctor serves npx @boldare/askdare doctor. It takes a 2-minute token that the CLI encrypts with CHAT_SECRET and answers with a report on each bot: whether the server's key, models, vector store and permissions work. The report format is internal and may change in any release.

Error codes

These codes are stable and safe to branch on in the UI:

Error keys and parameters

Next to code and message, an error event can carry:

message is the English text. The widget looks key up in the bot's texts, overrides included, fills in params, and shows message when it has no text for the key.

key is absent in two cases:

• Explained in development. When NODE_ENV is development, as under next dev, a bot_unavailable error caused by the setup carries a description for you in message instead of a key: a missing or weak secret, a missing OPENAI_API_KEY, a key OpenAI rejects, a model the project can't use. The widget shows that description as it is. In production, the server never sends one.
• Messages for developers. Some refusals carry only a plain English message, such as Expected an application/json body., Malformed JSON., Request body is too large. and Cross-origin requests are not allowed.

Error responses outside the stream have the same fields, inside error:

{
  "error": {
    "code": "invalid_input",
    "message": "Messages must be between 1 and 4000 characters.",
    "key": "error.messageLength",
    "params": { "max": 4000 }
  }
}

HTTP status codes

An error response with retryAfterMs also has a Retry-After header, in whole seconds rounded up. For budget_exceeded, it lasts until the next midnight UTC.

Any endpoint can also answer 500.

Protocol version

PROTOCOL_VERSION, exported from @boldare/askdare, is the version of this protocol: 1. Every event stream (POST /messages answered with 200) carries it in the x-askdare-protocol response header. Other responses don't have this header.

The widget compares the header with the version it was built with. On a mismatch, it doesn't read the stream and shows error.updated ("The assistant was updated. Please reload the page.").

Client rules

• Tolerate the unknown. Ignore unknown event types and unknown fields. Newer servers may add them within the same protocol version.
• Check the version. Compare x-askdare-protocol with the version the client supports. On a mismatch, show a "please reload" state.
• Run a watchdog. If no bytes (events or comments) arrive for 45 s, abort and re-fetch the conversation history.
• Render text safely. Treat text.delta content as untrusted markdown and sanitize it before rendering.

Versioning

• Adding an event type or an optional field is not breaking.
• Removing or renaming an event or field, or changing a field's meaning, is breaking. It bumps the protocol version and requires a minor release of @boldare/askdare (ADR-0006).