> ## Documentation Index > Fetch the complete documentation index at: https://docs.neoagent.io/llms.txt > Use this file to discover all available pages before exploring further. # Append a user message + enqueue a chat turn > Persists the user message and enqueues a `ChatTurnWorkflow`. Returns 202 Accepted with the persisted message id + the Temporal workflow id. The agent's streamed response is consumed via `GET /chat/sessions//events`. Pass `client_message_id` for idempotent retries — a duplicate returns 409 with the original message id and no new turn is enqueued. The response also includes `since_cursor`: the SSE stream id snapshotted right before this turn was enqueued. Pass it as `?since=` on the very next call to `/chat/sessions//events` so the tail skips envelopes from prior turns on this session — skipping the cursor on a 2nd+ turn against the same session causes the tail to return the previous turn's final state. To include images, first upload each via `POST /chat/sessions//attachments/upload-url`, then pass the returned `blob_path` values in `attachments`. `message` may be empty when at least one attachment is provided. Images are surfaced on later `GET .../messages` replays. ## OpenAPI ````yaml https://api.neoagent.io/public-api/openapi.json post /public-api/chat/sessions/{session_id}/messages openapi: 3.1.0 info: description: >- Neo's public contract for the dashboard ChatAgent, partner integrations, and MSP automation. Every response is wrapped in a `{data, meta}` envelope; errors use `{error: {code, message, details?}, meta: {request_id}}`. Authenticate with a `Bearer neo_sk__` API key (service account) or a Microsoft Entra ID JWT (dashboard user). Signed-URL endpoints (end-user feedback links) take a `signature` query parameter instead. title: Neo Public API version: 1.0.0 servers: - url: https://api.neoagent.io security: [] tags: - description: Service metadata — health, OpenAPI. name: Meta - description: Agents and workflows — read, version history, delete, stats. name: Agents - description: Agent/workflow execution history, sub-resources, retry/cancel. name: Executions - description: PSA webhook events and their workflow-match results. name: Callbacks - description: Technician-in-the-loop approval requests. name: TIL requests - description: RMM script executions triggered by agents. name: RMM scripts - description: Dispatch-agent field-update decisions. name: Dispatch - description: The authenticated tenant. name: Tenant - description: Agent-builder schema catalogs (raw JSON payloads). name: Schemas - description: Escalate to the Neo team (HubSpot ticket). name: Escalation - description: Tenant settings. name: Settings - description: Tenant API-key management (dashboard JWT only). name: API keys - description: End-user feedback links (signed-URL auth). name: Feedback - description: End-client companies (CRUD + bulk-update). name: End companies - description: Channels — bind a CONVERSATIONAL agent to a transport (Teams). name: Channels - description: PSA/RMM/M365 integration status and connection management. name: Integrations - description: Technician roster (controls TIL routing and paging). name: Technicians - description: Future runs queued for TRIGGERED agents. name: Scheduled work - description: Subscription state and customer-facing credit usage (no provider $). name: Billing - description: Inbox messages and announcements. name: Inbox & Comms - description: Tenant-authored agent skills (CRUD) and the built-in skill catalog. name: Skills paths: /public-api/chat/sessions/{session_id}/messages: post: tags: - Chat summary: Append a user message + enqueue a chat turn description: >- Persists the user message and enqueues a `ChatTurnWorkflow`. Returns 202 Accepted with the persisted message id + the Temporal workflow id. The agent's streamed response is consumed via `GET /chat/sessions//events`. Pass `client_message_id` for idempotent retries — a duplicate returns 409 with the original message id and no new turn is enqueued. The response also includes `since_cursor`: the SSE stream id snapshotted right before this turn was enqueued. Pass it as `?since=` on the very next call to `/chat/sessions//events` so the tail skips envelopes from prior turns on this session — skipping the cursor on a 2nd+ turn against the same session causes the tail to return the previous turn's final state. To include images, first upload each via `POST /chat/sessions//attachments/upload-url`, then pass the returned `blob_path` values in `attachments`. `message` may be empty when at least one attachment is provided. Images are surfaced on later `GET .../messages` replays. operationId: public_api.chat_session_post_message_post parameters: - in: path name: session_id required: true schema: type: string requestBody: content: application/json: schema: $ref: '#/components/schemas/PostMessageRequest' required: true responses: '200': content: application/json: schema: properties: data: $ref: '#/components/schemas/PostMessageResponse' meta: $ref: '#/components/schemas/SuccessMeta' required: - data - meta type: object description: Success. '400': content: application/json: schema: $ref: '#/components/schemas/ErrorEnvelope' description: Bad request — malformed input. '401': content: application/json: schema: $ref: '#/components/schemas/ErrorEnvelope' description: Unauthenticated — missing or invalid credentials. '403': content: application/json: schema: $ref: '#/components/schemas/ErrorEnvelope' description: Forbidden — authenticated but not allowed. '404': content: application/json: schema: $ref: '#/components/schemas/ErrorEnvelope' description: Not found. '409': content: application/json: schema: $ref: '#/components/schemas/ErrorEnvelope' description: Conflict — the resource is in a state that blocks this operation. '422': content: application/json: schema: $ref: '#/components/schemas/ErrorEnvelope' description: Request validation failed. '429': content: application/json: schema: $ref: '#/components/schemas/ErrorEnvelope' description: Rate limited — see Retry-After. '500': content: application/json: schema: $ref: '#/components/schemas/ErrorEnvelope' description: Internal server error. security: - bearerAuth: [] components: schemas: PostMessageRequest: properties: attachments: description: >- Images to include with this turn. Each must first be uploaded via `POST /chat/sessions//attachments/upload-url`. At most 6 per turn. items: $ref: '#/components/schemas/PublicChatAttachment' title: Attachments type: array client_message_id: anyOf: - type: string - type: 'null' default: null title: Client Message Id message: default: '' title: Message type: string model_tier: $ref: '#/components/schemas/ChatModelTier' default: FAST description: >- Speed/quality tier for this turn (ENG-5851): FAST keeps the agent's configured model; SMART escalates a single turn to a stronger model. May be flipped per turn to switch mid-conversation. Defaults to FAST. title: PostMessageRequest type: object PostMessageResponse: description: >- 202 Accepted body — the turn is enqueued, the agent's response streams via SSE. `since_cursor` is the Redis-stream event id snapshotted right before this turn was enqueued. Callers tailing `/chat/sessions//events` should pass it as `?since=` (or `Last-Event-Id: `) so the SSE tail starts strictly after the previous turn's terminal envelopes. Skipping this on a 2nd+ turn against the same session causes the tail to return the previous turn's final state. May be `None` on the first turn of a fresh session or under Redis failure; consumers treat `None` as "tail from beginning." properties: chat_turn_id: title: Chat Turn Id type: string show_agent_progress_steps: anyOf: - type: boolean - type: 'null' default: null title: Show Agent Progress Steps since_cursor: anyOf: - type: string - type: 'null' title: Since Cursor user_message_id: title: User Message Id type: string required: - user_message_id - chat_turn_id - since_cursor title: PostMessageResponse type: object SuccessMeta: properties: pagination: $ref: '#/components/schemas/Pagination' request_id: format: uuid type: string timings_ms: additionalProperties: type: number type: object warnings: description: >- Non-fatal warnings about the created/updated resource (e.g. an unhealthy PSA callback). items: type: string type: array required: - request_id - timings_ms type: object ErrorEnvelope: properties: error: properties: code: description: Stable machine-readable error code. type: string details: additionalProperties: true type: object message: type: string required: - code - message type: object meta: properties: request_id: format: uuid type: - string - 'null' type: object required: - error - meta type: object PublicChatAttachment: description: >- An image attached to a chat turn. `blob_path` is the value returned by the `attachments/upload-url` endpoint for THIS session — the backend re-validates it sits under the session's prefix, so a client can't reference another session's or tenant's blob. properties: alt: anyOf: - type: string - type: 'null' default: null description: Optional alt text / description for the image. title: Alt blob_path: description: The `blob_path` returned by `attachments/upload-url`. title: Blob Path type: string filename: anyOf: - type: string - type: 'null' default: null description: Optional original filename, for display. title: Filename mime: description: >- Image MIME type — one of image/png, image/jpeg, image/gif, image/webp. title: Mime type: string required: - blob_path - mime title: PublicChatAttachment type: object ChatModelTier: description: >- User-selectable speed/quality tier for a single chat turn (ENG-5851). The Neo Support chat surfaces a Fast/Smart toggle that the user can flip at any point in a conversation. The toggle rides each turn (not the session), so switching mid-chat just changes the next turn — `previous_response_id` continuity is preserved across the swap because it is bound to provider+region, not to the model. The frontend sends only this enum, never a model id: the FAST→model / SMART→model mapping is owned by the backend (`resolve_chat_model_override` in `chat_agent.py`). FAST keeps the agent's configured model (the Neo Support floor: GPT5_4_MINI + HIGH); SMART escalates the turn to a stronger model. FAST is the default so every pre-toggle caller (and the entire historical signal/activity corpus) deserializes unchanged. enum: - FAST - SMART title: ChatModelTier type: string Pagination: properties: has_more: type: boolean next_cursor: type: - string - 'null' required: - next_cursor - has_more type: object securitySchemes: bearerAuth: description: >- `Authorization: Bearer ` where `` is either a `neo_sk__` API key (service account) or a Microsoft Entra ID access token (dashboard user). scheme: bearer type: http ````