This CoreReflex API quickstart gets you from zero to a finished, graded cut in four moves: create a key, post a JSON recipe, poll the job, and pull the result. The API wraps the same agentic Director you use in the app, it plans, produces, critiques, and assembles, so automating creative in code gives you the identical quality gates and provenance you'd get by hand, just without the clicking. By the end of this guide you'll have the request shapes and the polling loop you need to wire CoreReflex into any pipeline.
The endpoint paths and field names below illustrate the request pattern. Treat the documentation as the canonical reference for exact routes, field names, and current parameters before you ship.
Before you start: what the API actually does
The CoreReflex API is a thin, programmable surface over the platform's JSON engine, you describe what you want as a recipe, submit it as a job, and the Director runs its loop on your behalf. The same rules that govern the interactive editor apply here: planning and scoring are free, and you only spend credits when a shot generates. That means you can submit a plan-only request to inspect the shot list and projected cost before committing to production.
If you want the conceptual model underneath the API before you write code, our overview of the programmable JSON engine, explained covers how editor state maps to a recipe you can post.
Step 1: Create an API key
Generate a key from your account settings. Treat it like a password, it authorizes generation, which spends credits, so it should live in an environment variable or a secrets manager, never in source control or client-side code.
Every request authenticates with a bearer token in the Authorization header:
- Header:
Authorization: Bearer YOUR_API_KEY - Store the key as an env var, e.g.
COREREFLEX_API_KEY - Scope keys per environment so you can rotate a staging key without touching production
For a deeper treatment of key scoping, rotation, and least-privilege patterns, see our guide to API keys and auth for automated creative.
Step 2: Post a JSON recipe
A recipe is the JSON description of what you want made. At its simplest it's a brief plus output settings; the Director fills in the shot plan, you submit it with a POST to the jobs endpoint.
Conceptually, a minimal request body carries:
prompt, the one-sentence description of the film or assetformat, aspect ratio and target durationmode,planto board for free, orproduceto generatebudget, an optional credit cap the job must respect
A representative call looks like POST /v1/jobs with that JSON body and your bearer token. The response returns a job identifier, capture it, because every subsequent step keys off it.
Plan first, then produce
Because planning is free, the efficient pattern is two calls. First submit with mode: "plan" and read back the boarded shot list, each shot's role, camera move, and prompt, along with the projected cost. Inspect it, and if it's right, submit the same recipe with mode: "produce" to commit. This is the API equivalent of reviewing the storyboard before spending, and it's the single best habit for keeping automated spend predictable.
Step 3: Poll the job to completion
Generation is asynchronous. The Director runs PLAN, PRODUCE, CRITIQUE, and ASSEMBLE in sequence, regenerating any shot that fails its quality gate, so a job moves through states rather than returning instantly. You poll the job endpoint until it reaches a terminal state.
The loop is straightforward:
GET /v1/jobs/{id}to read the current status.- Inspect the
statusfield, typically values likeplanning,producing,assembling,succeeded, orfailed. - If the status is non-terminal, wait a few seconds and poll again. Use a backoff interval rather than a tight loop so you're not hammering the endpoint.
- Stop when status is
succeededorfailed.
While producing, the job exposes per-shot progress and quality-gate scores, so you can surface real status in your own dashboard instead of a spinner. If you'd rather receive a callback than poll, the docs cover webhook delivery as an alternative to the loop above.
Step 4: Pull the finished, graded cut
When the job reaches succeeded, the response carries the output: a URL to the rendered asset and the asset metadata. The render came off the deterministic render path, a real render-worker that claims the job, renders, uploads to storage, and writes an asset row, so the file you pull is the same cut the manifest describes, with faststart muxing already applied for fast playback.
Alongside the asset you get the provenance trace: the model, prompt, parameters, and score behind every shot. Persist that trace with your asset record. It's what makes the result auditable and reproducible, submit the same manifest later and you get the same cut.
Going further: schedule, govern, and connect agents
A single quickstart job is the foundation; the platform is built for running this at scale.
- Schedule it. Wrap the recipe in an Autopilot workflow and the automation scheduler runs it hands-off, nightly product videos, weekly social cuts, on-publish asset generation. Our guide to scheduling hands-off content generation shows the pattern.
- Govern the spend. Set budget caps and approval checkpoints so an unattended pipeline can't overspend. See checkpoint approvals in automated content for where to place the gates.
- Work in code, not raw HTTP. The SDK wraps these calls with typed helpers and built-in polling, covered in the CoreReflex SDK: automate creative in code.
- Drive it from an AI agent. The MCP server exposes the same capabilities to assistants, so a model can plan and produce a cut as a tool call, see connect Claude to CoreReflex with MCP.
All of this lives in the broader automation toolkit, which turns one quickstart job into a programmable content operation.
Frequently asked questions
How do I get a CoreReflex API key?
Generate one from your account settings, then store it as an environment variable and pass it as a bearer token in the Authorization header of each request. Scope keys per environment so you can rotate staging credentials independently of production, and never embed a key in client-side or committed code, since it authorizes credit-spending generation.
What does a minimal API request look like?
A POST to the jobs endpoint with a JSON body carrying a prompt, an output format, and a mode of either plan or produce, authenticated with your bearer token. Sending mode: "plan" boards the shot list for free so you can review it and the projected cost before you submit the same recipe with mode: "produce". Check the docs for the exact route and current field names.
How do I poll a generation job to completion?
Capture the job id from the submission response, then GET the job endpoint on a backoff interval and read the status field. Keep polling while the status is non-terminal, for example planning, producing, or assembling, and stop when it reaches succeeded or failed. If you prefer not to poll, configure a webhook to receive the completion callback instead.
Does using the API skip the quality gates?
No. The API runs the same agentic Director loop as the app, so every shot is scored on the same concrete checks and any failure regenerates selectively. You also get the same portable provenance trace with each result, which keeps API-generated work just as auditable and reproducible as work made by hand.
Ship your first automated cut
You now have the full path: create a key, post a recipe, poll the job, and pull a graded cut with its provenance trace. The same loop scales from one request to a scheduled pipeline, and it never trades away the quality gates or reproducibility that make the output trustworthy. Read the full reference in the documentation, then start free with no credit card and post your first job today.