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

# Create a message

> Create a user message for a session and submit it to the session agent.



## OpenAPI

````yaml https://api.tembo.io/public-api/openapi/public post /v1/messages
openapi: 3.1.0
info:
  title: Tembo Public API
  description: Public API Endpoints for Tembo
  version: 1.0.0
servers:
  - url: https://api.tembo.io
    description: Tembo API
  - url: https://{deployment-origin}/api/public-api
    description: Self-hosted Tembo
    variables:
      deployment-origin:
        default: tembo.example.com
        description: Hostname of your self-hosted Tembo deployment
security: []
paths:
  /v1/messages:
    post:
      tags:
        - Messages
      summary: Create a message
      description: Create a user message for a session and submit it to the session agent.
      operationId: createMessage
      parameters: []
      requestBody:
        content:
          application/json:
            schema:
              type: object
              properties:
                artifactId:
                  type: string
                  format: uuid
                content:
                  type: string
                  minLength: 1
                  maxLength: 1000000
                mcpServers:
                  type: array
                  items:
                    type: string
                    minLength: 1
                    maxLength: 200
                  maxItems: 100
                pullRequestId:
                  type: string
                  format: uuid
                sessionId:
                  type: string
                  format: uuid
                agentOptions:
                  type: object
                  additionalProperties: {}
                  description: >-
                    Agent-specific options. Options are normalized and validated
                    after the session agent is selected.
                deliveryMode:
                  type: string
                  enum:
                    - queue
                    - steer
                jsonContent:
                  type: string
                  description: >-
                    JSON-encoded TipTap document, normally rooted at { "type":
                    "doc", "content": [...] }.
                  example: >-
                    {"type":"doc","content":[{"type":"paragraph","content":[{"type":"text","text":"Hello"}]}]}
                slashCommand:
                  type: object
                  properties:
                    command:
                      type: string
                      minLength: 1
                      maxLength: 200
                    arguments:
                      type: string
                      maxLength: 100000
                  required:
                    - command
                  additionalProperties: false
              required:
                - content
                - sessionId
              additionalProperties: false
      responses:
        '201':
          description: Create a message
          content:
            application/json:
              schema:
                type: object
                properties:
                  hotPath:
                    type:
                      - object
                      - 'null'
                    properties:
                      activeProviderTurnId:
                        type:
                          - string
                          - 'null'
                      mode:
                        type: string
                        enum:
                          - started
                          - steered
                          - queued
                      providerSessionId:
                        type:
                          - string
                          - 'null'
                      queuedTurnId:
                        type:
                          - string
                          - 'null'
                      transport:
                        type: string
                    additionalProperties: false
                  job:
                    type:
                      - object
                      - 'null'
                    properties:
                      id:
                        type: string
                        format: uuid
                      task:
                        type: string
                    required:
                      - id
                      - task
                    additionalProperties: false
                  message:
                    type: object
                    properties:
                      artifactId:
                        type:
                          - string
                          - 'null'
                        format: uuid
                      content:
                        type: string
                      createdAt:
                        type: string
                        format: date-time
                      createdBy:
                        type:
                          - string
                          - 'null'
                      externalAvatarUrl:
                        type:
                          - string
                          - 'null'
                      externalUrl:
                        type:
                          - string
                          - 'null'
                      id:
                        type: string
                        format: uuid
                      parentMessageId:
                        type:
                          - string
                          - 'null'
                        format: uuid
                      pullRequestId:
                        type:
                          - string
                          - 'null'
                        format: uuid
                      role:
                        type: string
                        enum:
                          - user
                          - assistant
                          - system
                      sessionId:
                        type:
                          - string
                          - 'null'
                        format: uuid
                      type:
                        type: string
                      updatedAt:
                        type: string
                        format: date-time
                      jsonContent:
                        allOf:
                          - 5906b0ed-29b0-4dca-b623-539756d1931f
                        description: >-
                          Raw JSON value stored for the message, including
                          legacy strings and unknown TipTap nodes or attributes.
                        example:
                          type: doc
                          content:
                            - type: paragraph
                      slashCommand:
                        type:
                          - object
                          - 'null'
                        properties:
                          command:
                            type: string
                            minLength: 1
                            maxLength: 200
                          arguments:
                            type: string
                            maxLength: 100000
                        required:
                          - command
                        additionalProperties: false
                      source:
                        type:
                          - string
                          - 'null'
                        maxLength: 100
                      isQueued:
                        type: boolean
                    required:
                      - artifactId
                      - content
                      - createdAt
                      - createdBy
                      - externalAvatarUrl
                      - externalUrl
                      - id
                      - parentMessageId
                      - pullRequestId
                      - role
                      - sessionId
                      - type
                      - updatedAt
                      - jsonContent
                      - slashCommand
                      - source
                      - isQueued
                    additionalProperties: false
                  session:
                    type: object
                    properties:
                      id:
                        type: string
                        format: uuid
                      title:
                        type: string
                    required:
                      - id
                      - title
                    additionalProperties: false
                required:
                  - hotPath
                  - job
                  - message
                  - session
                additionalProperties: false
        '400':
          description: Validation error or missing resource scope
          content:
            application/json:
              schema:
                type: object
                properties:
                  error:
                    type: string
                required:
                  - error
                additionalProperties: false
        '403':
          description: A user-backed credential is required to create a message
          content:
            application/json:
              schema:
                type: object
                properties:
                  error:
                    type: string
                required:
                  - error
                additionalProperties: false
        '404':
          description: Message or session not found
          content:
            application/json:
              schema:
                type: object
                properties:
                  error:
                    type: string
                required:
                  - error
                additionalProperties: false
        '409':
          description: Message operation conflicts with its current state
          content:
            application/json:
              schema:
                type: object
                properties:
                  error:
                    type: string
                required:
                  - error
                additionalProperties: false
        '500':
          description: Message operation failed
          content:
            application/json:
              schema:
                type: object
                properties:
                  error:
                    type: string
                required:
                  - error
                additionalProperties: false
      security:
        - apiKey: []
components:
  securitySchemes:
    apiKey:
      type: http
      scheme: bearer

````