> ## 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.

# Messages and completions

> Submit a durable agent turn. The HTTP call returns as soon as the run is queued.

There is one send route: `POST /api/v1/completions`. Omit `chatId` to create a chat and queue the turn. Pass `chatId` to continue an existing chat. `POST /api/v1/chats` is optional when you want an empty chat or a title first.

Send **text and an image in one request**. Use `multipart/form-data` with `text` + `file`. JSON is for text, or text plus a public `image_urls` if the file is already hosted.

## Request

<ParamField body="text" type="string" required>
  The message to send, up to 8192 characters.
</ParamField>

<ParamField body="file" type="file">
  Multipart. Upload an image (or video/audio) in the same request as `text`. Repeat `file` or use `files` for more than one. See [Upload files](/uploads).
</ParamField>

<ParamField body="image_urls" type="string[]">
  JSON only. Public `http(s)` URLs when the file is already hosted.
</ParamField>

<ParamField body="attachmentIds" type="string[]">
  IDs from `POST /uploads` or files already in the product.
</ParamField>

<ParamField body="planMode" type="boolean">
  When true, the agent pauses for plan approval before tools.
</ParamField>

<ParamField body="chatId" type="string">
  **Omit it to send a first message** (a chat is created). Pass it to continue an existing chat.
</ParamField>

```bash theme={null}
curl -X POST "$BASE/api/v1/completions" \
  -H "Authorization: Bearer $GALAXY_API_KEY" \
  -F "text=What is in this photo?" \
  -F "file=@./photo.jpg;type=image/jpeg"
```

```bash theme={null}
curl -X POST "$BASE/api/v1/completions" \
  -H "Authorization: Bearer $GALAXY_API_KEY" \
  -F "chatId=$CHAT_ID" \
  -F "text=What is in this photo?" \
  -F "file=@./photo.jpg;type=image/jpeg"
```

## Response

`POST /completions` returns `202`.

<ResponseField name="chatId" type="string" />

<ResponseField name="messageId" type="string" />

<ResponseField name="runId" type="string">
  Poll this on the runs route.
</ResponseField>

<ResponseField name="triggerRunId" type="string">
  Orchestrator id. Nullable if dispatch has not attached yet.
</ResponseField>

<ResponseField name="status" type="string">
  Always `queued` at admission. Later states are on the run snapshot.
</ResponseField>

## Routes

| Method | Path | When |
| - | - | - |
| POST | `/api/v1/completions` | Send. Omit `chatId` to start a chat, or pass it to continue |
| GET | `/api/v1/chats/{chatId}/messages` | List history, newest first |

`GET` supports `limit` and `cursor`. Each message includes `contentBlocks` and `attachments`. If the message has files, `attachments[].id` is the attachment id (uploads on the user turn, generated images on the assistant turn).

<Note>
  One active run per chat. A second send before the run reaches `COMPLETE`, `FAILED`, or `CANCELLED` returns `409 RUN_ACTIVE`.
</Note>


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