---
title: "Send Message"
method: POST
path: "/v1/agents/sessions/{session_id}/messages"
tags: ["Agent Sessions"]
---

# Send Message

`POST /v1/agents/sessions/{session_id}/messages`

Send a message to the agent and stream the response.

This endpoint streams Server-Sent Events (SSE) back to the client as
the agent processes the message through its workflow.

## SSE Event Types

**Core Events:**
- `intent`: Intent classification result (emitted first)
    - `{intent, confidence, category, reasoning, context_scope}`
- `thinking`: Agent is analyzing/planning
    - `{step, message}`
- `tool_call`: Agent is calling a tool
    - `{tool_name, tool_call_id, inputs}`
- `tool_result`: Tool execution completed
    - `{tool_name, tool_call_id, success, output, latency_ms}`
- `token`: Response token (streaming)
    - `{content}`
- `message`: Final response content
    - `{content, message_id, is_final}`
- `session_name`: Auto-generated session name (first message only)
    - `{session_name}`
- `done`: Processing complete
    - `{latency_ms, tool_calls_made, message_id, retriever_summary, data_accessed_via_retriever}`
- `error`: Error occurred
    - `{message, recoverable}`

**Retriever Events (IMPORTANT - Primary Data Pathway):**
- `retriever_execution`: Retriever was used for data access
    - `{tool_name, execution_id, retriever_id, is_adhoc, documents_returned, latency_ms, message}`
    - Emitted whenever data is accessed via retriever (saved or ad-hoc)
- `pipeline_config`: Ad-hoc retriever configuration
    - `{tool_name, config, message}`
    - Contains the exact pipeline config users can save as a named retriever

**Retriever Summary in `done` Event:**
```json
{
  "retriever_summary": {
    "used_retrievers": true,
    "retriever_count": 2,
    "saved_retrievers": 1,
    "adhoc_retrievers": 1,
    "total_documents": 25,
    "executions": [...]
  },
  "data_accessed_via_retriever": true
}
```

Args:
    request: FastAPI request with tenant context
    session_id: Session identifier
    payload: Message request

Returns:
    StreamingResponse with SSE events

Raises:
    NotFoundError: If session not found

Example:
    ```bash
    curl -N -X POST http://localhost:8000/v1/agents/sessions/ses_abc123/messages \
      -H "Authorization: Bearer {api_key}" \
      -H "X-Namespace: {namespace_id}" \
      -H "Content-Type: application/json" \
      -d '{
        "content": "Find videos about machine learning",
        "stream": true
      }'

    # SSE Output:
    event: intent
    data: {"intent": "retriever_search", "confidence": 0.92, "category": "retriever"}

    event: thinking
    data: {"step": "processing", "message": "Analyzing your request..."}

    event: tool_call
    data: {"tool_name": "execute_retriever", "tool_call_id": "run_abc", "inputs": {...}}

    event: tool_result
    data: {"tool_name": "execute_retriever", "success": true, "output": {...}}

    event: retriever_execution
    data: {"tool_name": "execute_retriever", "is_adhoc": false, "documents_returned": 5}

    event: message
    data: {"content": "I found 5 videos about machine learning...", "is_final": true}

    event: done
    data: {"latency_ms": 1250.5, "data_accessed_via_retriever": true, "retriever_summary": {...}}
    ```

## Path parameters

- `session_id` string, required — Session ID

## Request body

- SendMessageRequest — Request payload for sending a message to the agent. Attributes: content: Message text content metadata: Optional message metadata stream: Whether to stream response as SSE (default: True) Note: When stream=True, the response will be Server-Sent Events (SSE). When stream=False, the response will be a MessageResponse object. Example: ```python # Streaming request (SSE) request = SendMessageRequest( content="Find videos about machine learning", stream=True ) # Non-streaming request request = SendMessageRequest( content="Find videos about machine learning", stream=False ) ```
  - `content` string, required — Message text content (REQUIRED)
  - `metadata` object — Message metadata (OPTIONAL)
  - `stream` boolean — Stream response as SSE (default: True)

## Response `200`

Successful Response

- unknown

## Other responses

- `400` — Bad Request
- `401` — Unauthorized
- `403` — Forbidden
- `404` — Not Found
- `422` — Validation Error
- `500` — Internal Server Error

---

[API](https://skmtc.net/mixpeek/apis/mixpeek-api.md) · [All operations](https://skmtc.net/mixpeek/apis/mixpeek-api/llms.txt) · [OpenAPI document](https://skmtc-service-staging.skmtc.workers.dev/v1/apis/mixpeek/mixpeek-api/revisions/04b379bdbb7c/schema)