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

text · string · required

The message to send, up to 8192 characters.

file · 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.

image_urls · string[]

JSON only. Public http(s) URLs when the file is already hosted.

attachmentIds · string[]

IDs from POST /uploads or files already in the product.

planMode · boolean

When true, the agent pauses for plan approval before tools.

chatId · string

Omit it to send a first message (a chat is created). Pass it to continue an existing chat.

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"

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.

chatId · string

messageId · string

runId · string

Poll this on the runs route.

triggerRunId · string

Orchestrator id. Nullable if dispatch has not attached yet.

status · string

Always queued at admission. Later states are on the run snapshot.

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

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