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

# Append thread messages

> Appends messages to a thread **without running an agent** — to record a message that arrived on an external channel, or to create a thread (any id you choose) before anyone has spoken on it. The thread is created when it does not exist, for the calling user: a session token writes as its own user; an organization API key names the user with `user_id`. An existing thread must belong to that user (`403` otherwise). Each message is `{ role, content, metadata?, created_at?, id? }` where `content` is a text or an array of message parts; up to 50 per call. The rows are ordinary thread messages: `GET /v1/messages` returns them and the next `POST /v1/chat` turn on the thread reads them as history.



## OpenAPI

````yaml /api-reference/openapi.json post /v1/threads/{id}/messages
openapi: 3.1.0
info:
  title: Sidenet API
  version: 1.0.0
  description: >-
    Sidenet HTTP endpoints exposed by the Sidenet Studio. All routes require an
    api key that can be generated through the studio in studio.sidenet.ai.
servers:
  - url: https://api.sidenet.ai
security:
  - bearerAuth: []
paths:
  /v1/threads/{id}/messages:
    post:
      tags:
        - Chat
      summary: Append thread messages
      description: >-
        Appends messages to a thread **without running an agent** — to record a
        message that arrived on an external channel, or to create a thread (any
        id you choose) before anyone has spoken on it. The thread is created
        when it does not exist, for the calling user: a session token writes as
        its own user; an organization API key names the user with `user_id`. An
        existing thread must belong to that user (`403` otherwise). Each message
        is `{ role, content, metadata?, created_at?, id? }` where `content` is a
        text or an array of message parts; up to 50 per call. The rows are
        ordinary thread messages: `GET /v1/messages` returns them and the next
        `POST /v1/chat` turn on the thread reads them as history.
      parameters:
        - name: id
          in: path
          required: true
          schema:
            type: string
            example: wa:prop_12:guest:34600000000
          description: The thread id — yours to choose when creating.
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required:
                - messages
              properties:
                user_id:
                  type: string
                  example: user_4821
                  description: >-
                    The user the thread belongs to. Required with an API key; a
                    session token writes as its own user.
                title:
                  type: string
                  example: WhatsApp · +34 600 000 000
                  description: >-
                    Used when the thread is created; defaults to the first text
                    sent.
                metadata:
                  type: object
                  description: Thread metadata, used when the thread is created.
                messages:
                  type: array
                  minItems: 1
                  maxItems: 50
                  items:
                    type: object
                    required:
                      - role
                      - content
                    properties:
                      id:
                        type: string
                        description: 'Your id for the message (default: a uuid).'
                      role:
                        type: string
                        enum:
                          - user
                          - assistant
                          - system
                      content:
                        oneOf:
                          - type: string
                          - type: array
                            items:
                              type: object
                        description: >-
                          A text, or message parts (`[{ "type": "text", "text":
                          "…" }]`).
                      metadata:
                        type: object
                        description: >-
                          Stored on the message (e.g. the channel, the external
                          message id).
                      created_at:
                        type: string
                        format: date-time
                        description: >-
                          When the message happened (default: now, in the order
                          sent).
                  example:
                    - role: user
                      content: Hi, can I check in at 2pm?
                      metadata:
                        channel: whatsapp
                        wa_message_id: wamid.HBg…
      responses:
        '201':
          description: The messages were saved
          content:
            application/json:
              schema:
                type: object
                properties:
                  thread_id:
                    type: string
                  created:
                    type: boolean
                    description: True when the thread was created by this call.
                  message_ids:
                    type: array
                    items:
                      type: string
        '400':
          description: Invalid body, or no user (an API key must send `user_id`)
        '403':
          description: The thread belongs to another user
        '404':
          description: The thread exists in another organization
      security:
        - bearerAuth: []
        - sessionToken: []
components:
  securitySchemes:
    bearerAuth:
      type: http
      scheme: bearer
      description: >-
        Organization API key, generated in studio.sidenet.ai. Backend only —
        never in a browser.
    sessionToken:
      type: http
      scheme: bearer
      description: >-
        Session token (`snat_…`) minted by POST /v1/token. Carries the
        organization and the end user; safe in a browser.

````

This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.