> ## Documentation Index
> Fetch the complete documentation index at: https://magica-adi.mintlify.site/llms.txt
> Use this file to discover all available pages before exploring further.

# Send a message (creates a chat if needed)

> One-call send. Omit `chatId` to create a chat and queue the turn.
Pass `chatId` to continue an existing chat.
Upload an image with multipart `text` + `file` in the same request,
or pass `image_urls` in JSON if the file is already hosted.




## OpenAPI

````yaml /openapi.yaml post /completions
openapi: 3.1.0
info:
  title: Galaxy Agent API
  version: 1.0.0
  description: |
    Public REST for agent chats, Magica tools, and run status.
    Authenticate with `Authorization: Bearer gxk_live_…`.
servers:
  - url: https://magica-backend-oda9.onrender.com/api/v1
    description: Production
  - url: http://localhost:4000/api/v1
    description: Local
security:
  - bearerAuth: []
tags:
  - name: Chats
  - name: Messages
  - name: Runs
  - name: Magica
paths:
  /completions:
    post:
      tags:
        - Messages
      summary: Send a message (creates a chat if needed)
      description: |
        One-call send. Omit `chatId` to create a chat and queue the turn.
        Pass `chatId` to continue an existing chat.
        Upload an image with multipart `text` + `file` in the same request,
        or pass `image_urls` in JSON if the file is already hosted.
      operationId: completion
      requestBody:
        required: true
        content:
          multipart/form-data:
            schema:
              $ref: '#/components/schemas/MultipartCompletion'
            examples:
              withFile:
                summary: Text plus an uploaded image
                value:
                  text: What is in this photo?
                  file: (binary)
          application/json:
            schema:
              $ref: '#/components/schemas/CompletionBody'
            examples:
              newChat:
                summary: Text plus an image URL
                value:
                  text: What is in this photo?
                  image_urls:
                    - https://cdn.example.com/photo.jpg
              existingChat:
                summary: Send into an existing chat
                value:
                  chatId: 11111111-1111-4111-8111-111111111111
                  text: Continue from here
              textOnly:
                summary: Text only, new chat
                value:
                  text: Summarize what this agent can do
      responses:
        '202':
          description: Turn queued
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/QueuedTurn'
        '409':
          description: A turn is already running
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '429':
          description: Send rate limit
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
components:
  schemas:
    MultipartCompletion:
      allOf:
        - $ref: '#/components/schemas/MultipartSend'
        - type: object
          properties:
            chatId:
              type: string
              format: uuid
              description: Existing chat. Omit to create one.
    CompletionBody:
      allOf:
        - $ref: '#/components/schemas/SendBody'
        - type: object
          properties:
            chatId:
              type: string
              format: uuid
              description: >-
                Existing chat. Omit this field to create a chat and send in one
                call.
    QueuedTurn:
      type: object
      required:
        - chatId
        - messageId
        - runId
        - triggerRunId
        - status
      properties:
        chatId:
          type: string
          format: uuid
        messageId:
          type: string
          format: uuid
        runId:
          type: string
          format: uuid
        triggerRunId:
          type: string
          nullable: true
        status:
          type: string
          enum:
            - queued
    Error:
      type: object
      required:
        - error
      properties:
        error:
          type: string
        code:
          type: string
          examples:
            - UNAUTHORIZED
            - CHAT_NOT_FOUND
            - RUN_ACTIVE
    MultipartSend:
      type: object
      required:
        - text
      properties:
        text:
          type: string
          maxLength: 8192
          description: The message to send.
        file:
          type: string
          format: binary
          description: >-
            Image or video to send with this message. Repeat the field or use
            `files` for more than one. Max 20 MB each, 8 files.
        files:
          type: array
          items:
            type: string
            format: binary
        planMode:
          type: boolean
    SendBody:
      type: object
      required:
        - text
      properties:
        text:
          type: string
          maxLength: 8192
          description: The message to send.
        image_urls:
          type: array
          description: >-
            Public http(s) image URLs to attach. Optional if you upload `file`
            or pass `attachmentIds`.
          items:
            type: string
            format: uri
          maxItems: 8
        attachmentIds:
          type: array
          description: IDs from `POST /uploads` or files already in the product.
          items:
            type: string
            format: uuid
        planMode:
          type: boolean
  securitySchemes:
    bearerAuth:
      type: http
      scheme: bearer
      description: API key created in the product. Shown once, prefix `gxk_live_`.

````

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