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

# Overview

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

The public API lets you create chats, submit a turn, poll a long-running run, and call Crop Image, GPT Image 2, and Merge Videos directly. Use it from backends and scripts. The product UI keeps using the signed-in session.

Base URL: `https://magica-backend-oda9.onrender.com` — public routes are under `/api/v1`.

<Note>
  Every `/api/v1` request needs `Authorization: Bearer gxk_live_…`. Session cookies are not accepted on these routes.
</Note>

## Start here

<Steps>
  <Step title="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.
  </Step>

  <Step title="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`.
  </Step>

  <Step title="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.
  </Step>

  <Step title="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.
  </Step>
</Steps>

<CardGroup cols={2}>
  <Card title="Make the first API call" icon="circle-play" href="/quickstart">
    Shortest path from an API key to a queued run.
  </Card>

  <Card title="Authenticate" icon="key" href="/authentication">
    Create, send, and revoke `gxk_live_…` keys.
  </Card>
</CardGroup>

## What you can do

<CardGroup cols={2}>
  <Card title="Chats" icon="messages" href="/chats">
    Create, list, read, and delete conversations.
  </Card>

  <Card title="Messages and completions" icon="paper-plane" href="/messages">
    Send a message. Omit `chatId` on `/completions` to start a chat. Returns a `runId`.
  </Card>

  <Card title="Runs" icon="clock" href="/runs">
    Poll status, tools, waitpoints, and partial assistant output.
  </Card>

  <Card title="Magica tools" icon="image" href="/magica">
    Crop Image, GPT Image 2, and Merge Videos in one blocking call.
  </Card>

  <Card title="Webhooks" icon="webhook" href="/webhooks">
    Signed lifecycle events. The secret is shown once.
  </Card>

  <Card title="MCP" icon="plug" href="/mcp">
    Connect an assistant to the same chats, runs, and Magica tools.
  </Card>

  <Card title="Errors" icon="triangle-exclamation" href="/errors">
    Status codes, error envelope, and what does not use HTTP 504.
  </Card>
</CardGroup>

## Why this shape

<CardGroup cols={3}>
  <Card title="Turns are durable" icon="database">
    Send and completion return `queued`. Postgres is the source of truth while the agent runs.
  </Card>

  <Card title="One active run" icon="lock">
    A second send in the same chat returns `409 RUN_ACTIVE` instead of starting duplicate work.
  </Card>

  <Card title="Tools you can call directly" icon="cubes">
    The three required Magica models are also `POST /api/v1/tools/…` and wait for the provider.
  </Card>
</CardGroup>

## Next steps

<CardGroup cols={2}>
  <Card title="Quickstart" icon="circle-play" href="/quickstart">
    Create a key, queue a turn, and poll the run.
  </Card>

  <Card title="Run status" icon="code" href="/runs">
    Status enum, waitpoints, partial output, and when to stop polling.
  </Card>
</CardGroup>


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