Documentation Index Fetch the complete documentation index at: https://magica.com/docs/llms.txt
Use this file to discover all available pages before exploring further.
This guide walks you from zero to a successful workflow run. By the end you’ll have an API key, a base URL configured, and a run executing on Magica’s infrastructure.
1. Get your API key
Open API Keys
Go to Settings → API Keys → Manage .
Create a key
Click Create Key , label it (e.g. “Quickstart”), and copy the full gx_…
token immediately — it’s only shown once.
Store the key in an environment variable like MAGICA_API_KEY — never paste
it in committed code or screenshots.
See Authentication for rate limits, key rotation, and revocation.
2. Base URL https://api.magica.com/api
Every endpoint in this reference is relative to that base. The current REST version is /v1.
3. List your workflows A read-only call to verify the key works.
curl https://api.magica.com/api/v1/workflows \ -H "Authorization: Bearer $MAGICA_API_KEY "
const res = await fetch ( "https://api.magica.com/api/v1/workflows" , { headers: { Authorization: `Bearer ${ process . env . MAGICA_API_KEY } ` }, }); const { items } = await res . json (); console . log ( items );
import os, requests res = requests.get( "https://api.magica.com/api/v1/workflows" , headers = { "Authorization" : f "Bearer { os.environ[ 'MAGICA_API_KEY' ] } " }, ) print (res.json()[ "items" ])
A 401 Unauthorized here means the key is missing, malformed, revoked, or expired.
4. Start a run Pick a workflow ID from step 3 (or use a system-workflow template) and kick off a run.
curl -X POST https://api.magica.com/api/v1/runs \ -H "Authorization: Bearer $MAGICA_API_KEY " \ -H "Content-Type: application/json" \ -d '{"workflowId": "wf_abc123"}'
const run = await fetch ( "https://api.magica.com/api/v1/runs" , { method: "POST" , headers: { Authorization: `Bearer ${ process . env . MAGICA_API_KEY } ` , "Content-Type" : "application/json" , }, body: JSON . stringify ({ workflowId: "wf_abc123" }), }). then ( r => r . json ()); console . log ( "runId:" , run . runId );
run = requests.post( "https://api.magica.com/api/v1/runs" , headers = { "Authorization" : f "Bearer { os.environ[ 'MAGICA_API_KEY' ] } " , "Content-Type" : "application/json" , }, json = { "workflowId" : "wf_abc123" }, ).json() print ( "runId:" , run[ "runId" ])
The response includes a runId. Use it to poll status or to register a webhook.
5. Get results You have two options — poll or subscribe .
Poll for status
Subscribe via webhook
Hit GET /v1/runs/{runId} until status becomes COMPLETED, FAILED, or CANCELED. curl https://api.magica.com/api/v1/runs/ $RUN_ID \ -H "Authorization: Bearer $MAGICA_API_KEY "
Good for one-off scripts. For long jobs (video, batch), prefer webhooks. Add a webhook object on the original POST /v1/runs call: curl -X POST https://api.magica.com/api/v1/runs \ -H "Authorization: Bearer $MAGICA_API_KEY " \ -H "Content-Type: application/json" \ -d '{ "workflowId": "wf_abc123", "webhook": { "url": "https://your-app.com/webhooks/magica", "events": ["run.completed", "run.failed"] } }'
Magica POSTs to your URL when the run reaches a terminal state. See Webhooks for signature verification and retry behavior. OpenAPI spec The full OpenAPI 3.1 specification is at:
https://api.magica.com/api/v1/openapi.json
Import it into Postman, Insomnia, or any OpenAPI-compatible client to generate typed SDKs.
Next steps
Concepts Understand workflows, runs, nodes, and request/response scaffolds.
API Reference Browse every endpoint with request/response playground.
