# Galaxy Agent API

> Versioned public REST for agent chats, Magica tools, run polling, and signed webhooks.

- [Overview](https://magica-adi.mintlify.app/index.md): REST API for agent chats, Magica tools, run polling, and signed webhooks.
- [Quickstart](https://magica-adi.mintlify.app/quickstart.md): Create a key, queue a turn, and poll until the run finishes.
- [Authentication](https://magica-adi.mintlify.app/authentication.md): Bearer API keys for /api/v1. The full key is shown once.
- [Errors](https://magica-adi.mintlify.app/errors.md): JSON error envelope, status codes, and which failures stay on the run.
- [Chats](https://magica-adi.mintlify.app/chats.md): Create, list, read, and delete conversations.
- [Messages and completions](https://magica-adi.mintlify.app/messages.md): Submit a durable agent turn. The HTTP call returns as soon as the run is queued.
- [Upload files](https://magica-adi.mintlify.app/uploads.md): Send an image or video as a file. You do not need a public URL.
- [Runs](https://magica-adi.mintlify.app/runs.md): Poll the durable agent turn. Postgres is the source of truth.
- [Magica tools](https://magica-adi.mintlify.app/magica.md): Direct Crop Image, GPT Image 2, and Merge Videos execution.
- [Webhooks](https://magica-adi.mintlify.app/webhooks.md): Signed outbound events for agent and tool lifecycle.
- [MCP server](https://magica-adi.mintlify.app/mcp.md): Connect an assistant to chats, runs, and Magica tools with the same API key.
- [List chats](https://magica-adi.mintlify.app/api-reference/chats/list-chats.md)
- [Create an empty chat](https://magica-adi.mintlify.app/api-reference/chats/create-an-empty-chat.md): Optional. To send a first message without this step, use `POST /completions` and omit `chatId`.
- [Get a chat](https://magica-adi.mintlify.app/api-reference/chats/get-a-chat.md)
- [Delete a chat](https://magica-adi.mintlify.app/api-reference/chats/delete-a-chat.md)
- [List messages](https://magica-adi.mintlify.app/api-reference/messages/list-messages.md)
- [Send a message (creates a chat if needed)](https://magica-adi.mintlify.app/api-reference/messages/send-a-message-creates-a-chat-if-needed.md): 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.
- [Upload a file](https://magica-adi.mintlify.app/api-reference/messages/upload-a-file.md): Multipart upload. Stores the file and returns an attachment id. Pass `chatId` only to attach it to an existing chat. Omitting `chatId` does not create a chat — use `attachmentIds` on send, or upload in the same request on `/completions`. Images, video, and audio. 20 MB per file, 8 files.
- [Get run status](https://magica-adi.mintlify.app/api-reference/runs/get-run-status.md): Poll until status is COMPLETE, FAILED, or CANCELLED. The public snapshot does not mint a realtime token.
- [Crop an image](https://magica-adi.mintlify.app/api-reference/magica/crop-an-image.md): Blocks until Magica finishes. Exactly one crop rectangle.
- [Generate or edit an image](https://magica-adi.mintlify.app/api-reference/magica/generate-or-edit-an-image.md)
- [Merge videos](https://magica-adi.mintlify.app/api-reference/magica/merge-videos.md)

## OpenAPI Specs

- [openapi](/openapi.yaml)


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