> ## Documentation Index
> Fetch the complete documentation index at: https://docs.agntix.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# Send Message

> Send a user message and receive the agent's reply, optionally as a streaming SSE response.

<Note>
  Every endpoint on this page requires either a Clerk-issued JWT (`Authorization: Bearer <token>`) or
  an organization API key (`x-api-key: pk_…`). Anonymous calls return `401 Unauthorized`. See
  [Authentication](/authentication) for the full setup.
</Note>

## Streaming vs. non-streaming

By default (`"stream": true`), the agent's reply is delivered as a [Server-Sent Events](https://developer.mozilla.org/en-US/docs/Web/API/Server-sent_events) stream. Set `"stream": false` to receive a single JSON response when you don't need incremental rendering.

## Code examples

<CodeGroup>
  ```bash curl (streaming) theme={null}
  curl -X POST https://api.agntix.ai/v1/chat/chat/sessions/ses_01j3m8xkqp8v2nw4f7g9hk0r/messages \
    -H "x-api-key: pk_live_••••" \
    -H "Content-Type: application/json" \
    --no-buffer \
    -d '{ "content": "What is my current subscription plan?", "stream": true }'
  ```

  ```bash curl (non-streaming) theme={null}
  curl -X POST https://api.agntix.ai/v1/chat/chat/sessions/ses_01j3m8xkqp8v2nw4f7g9hk0r/messages \
    -H "x-api-key: pk_live_••••" \
    -H "Content-Type: application/json" \
    -d '{ "content": "What is my current subscription plan?", "stream": false }'
  ```

  ```javascript Node.js (streaming) theme={null}
  const sessionId = 'ses_01j3m8xkqp8v2nw4f7g9hk0r';

  const res = await fetch(
    `https://api.agntix.ai/v1/chat/chat/sessions/${sessionId}/messages`,
    {
      method: 'POST',
      headers: {
        'x-api-key': 'pk_live_••••',
        'Content-Type': 'application/json',
      },
      body: JSON.stringify({
        content: 'What is my current subscription plan?',
        stream: true,
      }),
    },
  );

  const reader = res.body.getReader();
  const decoder = new TextDecoder();
  let fullReply = '';

  while (true) {
    const { done, value } = await reader.read();
    if (done) break;

    const chunk = decoder.decode(value);
    for (const line of chunk.split('\n')) {
      if (line.startsWith('data: ') && line !== 'data: [DONE]') {
        const event = JSON.parse(line.slice(6));
        fullReply += event.delta ?? '';
        process.stdout.write(event.delta ?? '');
      }
    }
  }
  console.log('\nFull reply:', fullReply);
  ```

  ```javascript Node.js (non-streaming) theme={null}
  const message = await fetch(
    `https://api.agntix.ai/v1/chat/chat/sessions/${sessionId}/messages`,
    {
      method: 'POST',
      headers: {
        'x-api-key': 'pk_live_••••',
        'Content-Type': 'application/json',
      },
      body: JSON.stringify({ content: 'What is my plan?', stream: false }),
    },
  ).then(r => r.json());

  console.log('Reply:', message.content);
  ```

  ```python Python (streaming) theme={null}
  import httpx

  session_id = "ses_01j3m8xkqp8v2nw4f7g9hk0r"

  with httpx.stream(
      "POST",
      f"https://api.agntix.ai/v1/chat/chat/sessions/{session_id}/messages",
      headers={"x-api-key": "pk_live_••••"},
      json={"content": "What is my current subscription plan?", "stream": True},
  ) as r:
      for line in r.iter_lines():
          if line.startswith("data: ") and line != "data: [DONE]":
              import json
              event = json.loads(line[6:])
              print(event.get("delta", ""), end="", flush=True)
  ```

  ```python Python (non-streaming) theme={null}
  import httpx

  session_id = "ses_01j3m8xkqp8v2nw4f7g9hk0r"

  message = httpx.post(
      f"https://api.agntix.ai/v1/chat/chat/sessions/{session_id}/messages",
      headers={"x-api-key": "pk_live_••••"},
      json={"content": "What is my current subscription plan?", "stream": False},
  ).json()

  print("Reply:", message["content"])
  ```
</CodeGroup>

## SSE stream format

When `stream: true`, the response is `Content-Type: text/event-stream`. Each event:

```
data: {"id":"msg_01j3m","delta":"Your "}

data: {"id":"msg_01j3m","delta":"plan is Pro."}

data: [DONE]
```

The stream ends with the literal `data: [DONE]` sentinel.

## Non-streaming response

```json theme={null}
{
  "id": "msg_01j3m...",
  "content": "Your current plan is Pro.",
  "role": "ASSISTANT",
  "createdAt": "2026-04-29T09:10:00Z"
}
```


## OpenAPI

````yaml POST /v1/chat/chat/sessions/{sessionId}/messages
openapi: 3.0.3
info:
  title: Agntix API
  version: 1.0.0
  description: >-
    The Agntix API lets you build, deploy, and operate AI chat and voice agents.
    All requests are sent to `https://api.agntix.ai`. Authenticate with an API
    key (`x-api-key`) or a Clerk-issued JWT (`Authorization: Bearer <token>`).


    Base URL: `https://api.agntix.ai`
servers:
  - url: https://api.agntix.ai
    description: Production
security:
  - ApiKeyAuth: []
  - BearerAuth: []
tags:
  - name: Agents
    description: >-
      Create and manage AI agents — the core building block of Agntix. An agent
      encapsulates a system prompt, LLM, tools, knowledge store, and voice
      configuration.
  - name: Chat
    description: >-
      Open chat sessions with an agent and exchange messages. Supports streaming
      responses over SSE.
  - name: Voice
    description: >-
      List available voices and TTS/STT models, and create real-time voice
      sessions.
  - name: Tools
    description: >-
      Extend agent capabilities with API tools (webhook calls) or function tools
      (server-side logic).
  - name: Phone Numbers
    description: >-
      Provision and manage telephony numbers for inbound and outbound voice
      calls.
  - name: Models
    description: Browse available LLM, STT, and TTS models supported by Agntix.
  - name: Analytics
    description: Query call and agent-level performance metrics.
  - name: API Keys
    description: Create and manage organization-scoped API keys.
  - name: Contacts
    description: Manage customer contacts that can be linked to chat sessions.
  - name: Call Campaigns
    description: Launch and manage outbound call campaigns against a list of contacts.
  - name: Subscriptions
    description: View billing plans, usage quotas, and manage Stripe subscriptions.
paths:
  /v1/chat/chat/sessions/{sessionId}/messages:
    post:
      tags:
        - Chat
      summary: Send message
      description: >-
        Sends a user message to the agent and returns the assistant's reply. Set
        `stream: true` (the default) to receive the reply as a Server-Sent
        Events stream. Set `stream: false` for a single JSON response.
      operationId: sendMessage
      parameters:
        - name: sessionId
          in: path
          required: true
          schema:
            type: string
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/SendMessageRequest'
            example:
              content: What is my current subscription plan?
              stream: true
      responses:
        '200':
          description: >-
            Assistant reply (SSE stream when `stream: true`, JSON object when
            `stream: false`).
          content:
            text/event-stream:
              schema:
                type: string
              example: |+
                data: {"id":"msg_01j3m","delta":"Your current plan is"}

                data: {"id":"msg_01j3m","delta":" Pro."}

                data: [DONE]

            application/json:
              schema:
                $ref: '#/components/schemas/ChatMessage'
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '404':
          $ref: '#/components/responses/NotFound'
components:
  schemas:
    SendMessageRequest:
      type: object
      required:
        - content
      properties:
        content:
          type: string
          description: The user's message.
          example: What is my current subscription plan?
        stream:
          type: boolean
          default: true
          description: >-
            Stream the response over SSE. Set `false` for a single JSON
            response.
    ChatMessage:
      type: object
      properties:
        id:
          type: string
          example: msg_01j3m...
        content:
          type: string
          example: Your current plan is Pro.
        role:
          type: string
          enum:
            - USER
            - ASSISTANT
            - SYSTEM
          example: ASSISTANT
        createdAt:
          type: string
          format: date-time
        images:
          type: array
          items:
            type: string
          nullable: true
        metadata:
          type: object
          nullable: true
    Error:
      type: object
      properties:
        error:
          type: object
          properties:
            code:
              type: string
              example: NOT_FOUND
            message:
              type: string
              example: Resource not found.
            status:
              type: integer
              example: 404
        meta:
          type: object
          properties:
            requestId:
              type: string
            timestamp:
              type: string
              format: date-time
  responses:
    BadRequest:
      description: Invalid request body or parameters.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
          example:
            error:
              code: VALIDATION_ERROR
              message: fullName should not be empty
              status: 400
            meta:
              requestId: req_01j3m...
              timestamp: '2026-04-29T10:00:00Z'
    Unauthorized:
      description: Missing or invalid authentication credentials.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
          example:
            error:
              code: UNAUTHORIZED
              message: Authentication required.
              status: 401
            meta:
              requestId: req_01j3m...
              timestamp: '2026-04-29T10:00:00Z'
    NotFound:
      description: Resource not found.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
          example:
            error:
              code: NOT_FOUND
              message: Agent not found.
              status: 404
            meta:
              requestId: req_01j3m...
              timestamp: '2026-04-29T10:00:00Z'
  securitySchemes:
    ApiKeyAuth:
      type: apiKey
      in: header
      name: x-api-key
      description: >-
        Organization API key. Obtain from the
        [dashboard](https://app.agntix.ai/settings/api-keys). Format:
        `pk_live_…`
    BearerAuth:
      type: http
      scheme: bearer
      bearerFormat: JWT
      description: 'Clerk-issued JWT. Use `Authorization: Bearer <token>`.'

````