https://magica-backend-oda9.onrender.com — public routes are under /api/v1.
Every
/api/v1 request needs Authorization: Bearer gxk_live_…. Session cookies are not accepted on these routes.Start here
1
Create an API key
Sign in to the product and create a key on API / MCP. The full
gxk_live_… value is shown once. Send it as Authorization: Bearer $GALAXY_API_KEY on every public request.2
Submit a turn
POST /api/v1/completions — omit chatId to start a new chat. Send JSON, or multipart/form-data with file to upload an image. The HTTP call returns immediately with runId.3
Poll until the run finishes
GET /api/v1/chats/{chatId}/runs/{runId} until status is COMPLETE, FAILED, or CANCELLED. Partial text, tool outcomes, and the error message are on that snapshot.4
Subscribe to webhooks
Register an HTTPS endpoint for
agent.started, agent.completed, agent.failed, and tool.completed. Verify X-Galaxy-Signature with the signing secret.Make the first API call
Shortest path from an API key to a queued run.
Authenticate
Create, send, and revoke
gxk_live_… keys.What you can do
Chats
Create, list, read, and delete conversations.
Messages and completions
Send a message. Omit
chatId on /completions to start a chat. Returns a runId.Runs
Poll status, tools, waitpoints, and partial assistant output.
Magica tools
Crop Image, GPT Image 2, and Merge Videos in one blocking call.
Webhooks
Signed lifecycle events. The secret is shown once.
MCP
Connect an assistant to the same chats, runs, and Magica tools.
Errors
Status codes, error envelope, and what does not use HTTP 504.
Why this shape
Turns are durable
Send and completion return
queued. Postgres is the source of truth while the agent runs.One active run
A second send in the same chat returns
409 RUN_ACTIVE instead of starting duplicate work.Tools you can call directly
The three required Magica models are also
POST /api/v1/tools/… and wait for the provider.Next steps
Quickstart
Create a key, queue a turn, and poll the run.
Run status
Status enum, waitpoints, partial output, and when to stop polling.