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

# Chat with agent

> Send a user message to a Pharen Hub AI agent by UUID and stream the model response back over HTTP using a scoped agents:run API key.

Sends a message to an agent. The endpoint streams the model response. API keys must explicitly allow streaming when a streaming response is requested by the client.

<Note>
  Required API key scope: `agents:run`.
</Note>

## Path parameters

<ParamField path="agent_uuid" type="string" required>
  UUID of the agent.
</ParamField>

## Body parameters

<ParamField body="message" type="string" required>
  User message for the agent. Maximum length is `32000` characters.
</ParamField>

<ParamField body="conversation_uuid" type="string">
  Existing conversation UUID. If omitted, Pharen starts a new conversation.
</ParamField>

<ParamField body="model" type="string">
  Optional model override. If omitted, the agent default model is used.
</ParamField>

<ParamField body="enable_thinking" type="boolean">
  Whether to enable model reasoning when supported by the selected model.
</ParamField>

<ParamField body="artifact_mode" type="boolean">
  Whether the agent should produce an artifact-oriented response.
</ParamField>

<ParamField body="artifact_category" type="string">
  Optional artifact category hint.
</ParamField>

<ParamField body="page_context" type="object">
  Optional JSON context from the caller's current page.
</ParamField>

## Example body

```json theme={null}
{
  "message": "Summarize the open tasks for this workspace.",
  "enable_thinking": true
}
```


## OpenAPI

````yaml openapi.json POST /api/agents/{agent_uuid}/chat/
openapi: 3.1.0
info:
  title: Pharen Hub API
  version: 1.0.0
  description: >-
    Scoped REST API for Pharen Hub workspaces, calendars, lists, docs,
    workflows, and agents.
servers:
  - url: '{baseUrl}'
    description: Pharen Hub API base URL
    variables:
      baseUrl:
        default: https://pharen.app
        description: >-
          The Pharen Hub API origin. Keep the default for production, or enter
          another environment such as http://localhost:8000.
security:
  - bearerAuth: []
tags:
  - name: Calendar
    description: Calendar source and event operations.
  - name: Lists
    description: Saved list data and metadata operations.
  - name: Docs
    description: Document and collection operations.
  - name: Workflows
    description: Workflow definition and execution operations.
  - name: Agents
    description: Agent catalog and chat operations.
paths:
  /api/agents/{agent_uuid}/chat/:
    post:
      tags:
        - Agents
      summary: Chat with agent
      description: >-
        Send a message to an agent and receive a response. Requires the
        `agents:run` scope.
      operationId: chatWithAgent
      parameters:
        - name: agent_uuid
          in: path
          required: true
          description: Agent UUID.
          schema:
            type: string
            format: uuid
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/AgentChatRequest'
            examples:
              message:
                summary: Ask an agent
                value:
                  message: Summarize the latest onboarding blockers.
                  conversation_id: conv_123
      responses:
        '200':
          description: Agent response returned.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/AgentChatResponse'
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/Forbidden'
        '404':
          $ref: '#/components/responses/NotFound'
components:
  schemas:
    AgentChatRequest:
      type: object
      required:
        - message
      properties:
        message:
          type: string
          example: Summarize the latest onboarding blockers.
        conversation_id:
          type: string
          description: Optional conversation identifier for continuing a thread.
        context:
          type: object
          additionalProperties: true
          description: Optional structured context for the agent.
    AgentChatResponse:
      type: object
      properties:
        message:
          type: string
        conversation_id:
          type: string
        run_id:
          type: string
    ErrorResponse:
      type: object
      properties:
        error:
          type: object
          properties:
            code:
              type: string
              example: forbidden
            message:
              type: string
              example: This API key does not have the required scope.
            details:
              type: object
              additionalProperties: true
  responses:
    BadRequest:
      description: The request was malformed or missing required fields.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ErrorResponse'
    Unauthorized:
      description: The request did not include a valid API key.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ErrorResponse'
    Forbidden:
      description: >-
        The API key is valid but does not have the required scope or workspace
        access.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ErrorResponse'
    NotFound:
      description: >-
        The requested resource was not found or is outside the key's access
        target.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ErrorResponse'
  securitySchemes:
    bearerAuth:
      type: http
      scheme: bearer
      description: Paste your Pharen API key without the Bearer prefix.
      x-default: phk_your_api_key

````