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

# Create thread

> Creates a new thread and sends the first message. Supports both direct
(single agent_id) and group (agent_ids array) creation. For group threads,
dispatches to all running agents and returns three-array response
(dispatched/skipped/failed). Max 8 agents per group.




## OpenAPI

````yaml /ai-app/openapi.yaml post /chat/threads
openapi: 3.0.3
info:
  title: Hill90 API
  description: Hill90 platform API — agent management and lifecycle operations.
  version: 0.1.0
servers:
  - url: /
    description: Relative (behind Traefik reverse proxy)
security: []
paths:
  /chat/threads:
    post:
      summary: Create thread
      description: >
        Creates a new thread and sends the first message. Supports both direct

        (single agent_id) and group (agent_ids array) creation. For group
        threads,

        dispatches to all running agents and returns three-array response

        (dispatched/skipped/failed). Max 8 agents per group.
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                agent_id:
                  type: string
                  format: uuid
                  description: Single agent UUID (creates direct thread)
                agent_ids:
                  type: array
                  items:
                    type: string
                    format: uuid
                  description: Multiple agent UUIDs (creates group thread)
                  maxItems: 8
                message:
                  type: string
                title:
                  type: string
                  nullable: true
                lead_agent_id:
                  type: string
                  format: uuid
                  nullable: true
                  description: |
                    Designate a lead agent for collaborative group threads.
                    Must be one of the agent_ids. When set, only the lead agent
                    receives dispatch with collaborator context. Other agents
                    serve as queryable collaborators.
                idempotency_key:
                  type: string
                  nullable: true
              required:
                - message
      responses:
        '201':
          description: Thread created and message dispatched
          content:
            application/json:
              schema:
                type: object
                properties:
                  thread:
                    type: object
                  message_id:
                    type: string
                    format: uuid
                    description: Placeholder ID (direct thread)
                  user_message:
                    type: object
                    description: User message info (group thread)
                  dispatched:
                    type: array
                    description: Agents dispatched (group thread)
                  skipped:
                    type: array
                    description: Agents skipped (group thread)
                  failed:
                    type: array
                    description: Agents failed (group thread)
        '400':
          description: Missing or invalid fields, or exceeds max agents
        '403':
          description: Elevated scope requires admin role
        '404':
          description: Agent not found
        '409':
          description: Agent not running or duplicate idempotency key
      security:
        - bearerAuth: []
components:
  securitySchemes:
    bearerAuth:
      type: http
      scheme: bearer
      bearerFormat: JWT

````