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

# Create a conversation thread by resolving a user and invoking an AI agent



## OpenAPI

````yaml /deploy/api/openapi.json post /api/v1/appuid/{appUid}/threads
openapi: 3.0.1
info:
  title: Mindset API Gateway
  version: 1.2.0
servers:
  - url: https://a.api.mindset.ai
  - url: https://b.api.mindset.ai
  - url: https://c.api.mindset.ai
  - url: https://d.api.mindset.ai
security: []
tags:
  - name: Agent Configuration
  - name: Agent Sessions
  - name: AppStatus
  - name: Context Files
  - name: Contexts
  - name: DynamicComponents
  - name: Labels
  - name: SDK Users
  - name: Threads
  - name: Webhooks
  - name: Agent Management (deprecated)
paths:
  /api/v1/appuid/{appUid}/threads:
    post:
      tags:
        - Threads
      summary: >-
        Create a conversation thread by resolving a user and invoking an AI
        agent
      operationId: createThread
      parameters:
        - name: appUid
          in: path
          description: Your application's uid
          required: true
          schema:
            minLength: 1
            type: string
      requestBody:
        content:
          application/json:
            schema:
              required:
                - agentUid
                - message
              type: object
              properties:
                agentUid:
                  type: string
                  description: >-
                    Agent UID to invoke. Can be a plain agentUid or composite
                    agentUid::sessionUid.
                message:
                  type: string
                  description: >-
                    Message to send to the agent. When messageType is 'user'
                    (default), appears as a visible user message in the
                    conversation. When messageType is 'system', used as an
                    invisible prompt that triggers the agent without appearing
                    in the conversation.
                messageType:
                  type: string
                  description: >-
                    Message type. 'user' (default) sends a visible user message.
                    'system' sends an invisible prompt (like an icebreaker) that
                    triggers the agent without appearing in the conversation.
                  default: user
                  enum:
                    - user
                    - system
                humanUid:
                  type: string
                  description: >-
                    Direct Firestore human UID. Mutually exclusive with other
                    user identifiers.
                externalUserId:
                  maxLength: 100
                  type: string
                  description: >-
                    External system user identifier. Valid characters are
                    A-Za-z0-9_-. Mutually exclusive with other user identifiers.
                sdkUserEmail:
                  maxLength: 100
                  type: string
                  description: >-
                    SDK user email address. Mutually exclusive with other user
                    identifiers.
                realEmailAddress:
                  maxLength: 100
                  type: string
                  description: >-
                    User's actual email address for SSO or email-based auth.
                    Mutually exclusive with other user identifiers.
        required: true
      responses:
        '201':
          description: Thread created successfully
          content:
            application/json:
              schema:
                type: object
                properties:
                  threadUid:
                    type: string
                    description: UID of the created conversation thread
                  humanUid:
                    type: string
                    description: Resolved human UID
                  agentUid:
                    type: string
                    description: Agent UID that was invoked
        '400':
          description: Bad Request
          content: {}
        '401':
          description: Unauthorized
          content: {}
        '403':
          description: Forbidden - API key does not match appUid
          content: {}
        '404':
          description: Agent not found
          content: {}
        '422':
          description: >-
            Validation error (missing/invalid fields, identity resolution
            failure, or user not permitted)
          content: {}
        '502':
          description: Agent service returned an error
          content: {}
        '503':
          description: Agent service unavailable
          content: {}
        '504':
          description: Agent service did not respond in time
          content: {}
      security:
        - APIKeyHeader: []
components:
  securitySchemes:
    APIKeyHeader:
      type: apiKey
      name: x-api-key
      in: header

````