Create a chat

The primary endpoint. Sends `message` to the AI in the context of chat `{ref}` and returns the assistant's response when complete. ### Tools Tools listed in `tools` are made available to the AI. Names come from `GET /ai/tools`. Omit `tools` to use the default set (search + document reading). Send `tools: []` to disable all tools. ### Images attached by the caller Pass base64-encoded images in `attachedImages`. Vision-capable models (GPT 5.x, Claude Sonnet/Opus, Gemini Pro) read them. With `tools: ["image_generation"]` they're also used as edit/composition inputs ("change the background", "combine these two", etc.). ### Images generated by the AI Generated images are returned in the `images` array as `{path, url}` pairs. The `url` is a 1-hour signed URL that any browser `<img src>` can fetch — no api-key header needed. ### Streaming For long responses you can pre-create a stream via `POST /ai/streams/init`, pass `streamId` here, and poll `GET /ai/streams/{streamId}` from a separate connection while this POST blocks. ### Resource grounding Pass `resourceRefs: [123, 456]` to attach catalogue resources as chat documents. Combined with `tools: ["document_reading"]` (auto-on when documents are present) the AI can read them via the `document_read` tool. ### Idempotency Pass an `Idempotency-Key` header (a unique random string per logical send, e.g. a UUID) to make retries safe. The first successful response with a given key is cached for 24 hours; replays return the same body byte-for-byte with `Idempotent-Replayed: true`. Reusing the key with a different request body returns 422 `IDEMPOTENCY_KEY_CONFLICT`.