---
title: "Create Run"
method: POST
path: "/v1/runs"
tags: ["runs"]
---

# Create Run

`POST /v1/runs`

## Request

- Base URL: `https://api.theagentc.io` (the document declares no server; this is the origin it was published from)
- URL: `https://api.theagentc.io/v1/runs`
- Auth: HTTP bearer

Create a new one-off pipeline run.

This is what the `/content/new` dashboard form calls. It validates the
request, verifies the brand belongs to the caller's workspace, pre-checks
credits and the monthly video cap, creates a Run row, and enqueues a
Job for the worker to pick up.

We do NOT deduct credits here — the worker does that when the run
actually executes. This prevents charging for queued-but-never-run
jobs (e.g., the worker dies before dequeue) and matches the pattern
used by `coo_engine.dispatch_run`. The pre-check below is just a
fast-fail so the UI can tell the customer "you don't have enough
credits" before filling out a form.

Returns the persisted Run so the dashboard can redirect to
`/content/runs/{id}` and start polling progress immediately.

## Request body

- RunCreateInput: Payload for POST /v1/runs — mirrors `RunCreateInput` in src/lib/api.ts. Kept intentionally loose at the Pydantic layer (strings + lists) so validation errors surface through `validate_run_request` with the same field names the frontend form uses. That way the UI can highlight the right field without a translation table.
  - `brand_id` string, uuid, required
  - `mode` integer, required: Content mode: 1, 2, or 3
  - `idea` string, nullable
  - `video_url` string, nullable
  - `strategy` string, nullable
  - `platforms` string[]
  - `formats` string[]

## Response `201`

Successful Response

- RunListItem
  - `id` string, uuid, required
  - `brand_id` string, uuid, nullable
  - `campaign_id` string, uuid, nullable
  - `mode` integer, nullable
  - `status` string, required
  - `credits_used` integer
  - `created_at` string, required
  - `started_at` string, nullable
  - `completed_at` string, nullable
  - `error` object, nullable

## Other responses

- `422`: Validation Error

---

[API](https://skmtc.dev/theagentc/apis/the-agent-c-api.md) · [All operations](https://skmtc.dev/theagentc/apis/the-agent-c-api/llms.txt) · [OpenAPI document](https://skmtc.dev/theagentc/apis/the-agent-c-api/revisions/1c9868b44584?raw)