Create Cycle Api V1 Workstreams Cycles Post

post/api/v1/workstreams/cycles

Start new cycle

Manually start a new execution cycle for a blueprint. Creates a new cycle and queues it for execution. **Authentication Required:** JWT Bearer token

Request bodyapplication/json

Field	Type	Description
`blueprint_id`required	`string (uuid)`	Workplan UUID
`input_data`	`object`	Input data for the cycle show nested Empty object.
`priority`	`integer`	Execution priority (1=highest)
`topic_id`	`string (uuid) \| null`	Optional Topic UUID this cycle belongs to. Stamped onto workstreams.cycle.topic_id so topic→run linkage resolves (the reverse link of platform.topics.workstream_id). NULL for cycles launched outside a topic context — no behaviour change.

Responses

201Cycle started successfully

Field	Type	Description
`id`required	`string (uuid)`	Cycle UUID
`permakey`	`string \| null`	Stable human-readable cycle key for the deep-link URL /workstreams/{ws}/cycles/{permakey}/instance/{task}. Null on legacy rows.
`workstream_id`	`string (uuid) \| null`	Parent workstream UUID. Populated for every cycle launched against a workstream definition; only null for legacy agentic/v2 cycles that have no workstream parent.
`workstream_permakey`	`string \| null`	Parent workstream's stable human-readable key (workstreams.workstream.permakey), resolved by joining on the same COALESCE(cycle.workstream_id, blueprint.workstream_id) that backs workstream_id. Lets the list/detail surfaces build the permakey-prefixed deep link /workstreams/{workstream_permakey}/cycles/{permakey} without a second fetch. Null when no workstream parent resolves (legacy agentic/v2 cycles, or a workstream that no longer exists).
`workstream_slug`	`string \| null`	Parent workstream's URL slug (workstreams.workstream.slug), resolved via the same join as workstream_permakey. Null when no workstream parent resolves.
`blueprint_id`	`string (uuid) \| null`	Workplan UUID (null for agentic cycles)
`blueprint_name`	`string \| null`	Workplan name (from join)
`client_id`	`string (uuid) \| null`	Client UUID (from workplan join)
`client_name`	`string \| null`	Client name (from workplan join)
`status`required	`"created" \| "planning" \| "queued" \| "running" \| "paused" \| "blocked" \| "completed" \| "failed" \| "cancelled" \| "skipped"`	Status for execution cycles - matches DB check constraint. `createdplanningqueuedrunningpausedblockedcompletedfailedcancelledskipped`
`progress_pct`	`number`	Progress percentage (computed)
`blueprint_snapshot`	`object`	Workplan snapshot at cycle start show nested Empty object.
`error_context`	`object \| null`	Error context if failed
`started_at`	`string (date-time) \| null`	Start timestamp
`completed_at`	`string (date-time) \| null`	Completion timestamp
`started_by`	`string (uuid) \| null`	Initiator user ID (started_by in DB)
`created_at`required	`string (date-time)`	Creation timestamp
`updated_at`required	`string (date-time)`	Last update timestamp
`current_step_name`	`string \| null`	Name of the currently active or next pending step
`completed_steps`	`integer`	Number of completed/approved/skipped steps
`total_steps`	`integer`	Total number of steps in cycle
`customer_cost_gbp`	`number \| null`	Customer-facing cost in GBP: £19/hr x elapsed time since cycle start. NULL when the cycle has not yet started. Uses completed_at if available, otherwise current wall-clock time. Distinct from cost_cents_total which tracks REAL compute token cost.
`cost_cents_total`	`integer \| null`	Real total compute (token) cost across all steps, in pence (SUM of workstreams.task.cost_cents). NULL when no step recorded a cost. Distinct from the hourly customer_cost_gbp price field.
`cost_gbp_total`	`number \| null`	Real total compute cost across all steps in GBP (cost_cents_total / 100).
`tokens_total_input`	`integer \| null`	Total input tokens across all steps. NULL when none recorded.
`tokens_total_output`	`integer \| null`	Total output tokens across all steps. NULL when none recorded.
`artifacts`	`CycleArtifactSummary[]`	Artifacts produced by this cycle (workstreams.cycle_artifact, non-deleted), newest first, each with a download_url. Surfaced at CYCLE level — step→artifact attribution is a follow-up. Empty when the cycle produced no artifacts. item shape CycleArtifactSummary
`input_data`	`object`	Launch inputs the cycle was started with (period, file refs, run_mode, etc.), read from workstreams.cycle.runtime_vars — the canonical input dict written verbatim on both the inline and containerized launch paths. Empty when the cycle has no recorded launch inputs. Within-workspace only (the endpoint is FGA- + workspace-scoped); redact file names / conversation_id before surfacing this on any cross-org surface. show nested Empty object.

400Invalid request or blueprint not found

401Unauthorized

422Validation Error

Field	Type	Description
`detail`	`ValidationError[]`	— item shape ValidationError

curl https://api.dev.arch.ie/api/v1/workstreams/cycles \
  -X POST \
  -H "Authorization: Bearer sk_..." \
  -H "Content-Type: application/json" \
  -d '{
       "blueprint_id": "550e8400-e29b-41d4-a716-446655440000",
       "input_data": {
         "account_ids": [
           "1001",
           "1002"
         ],
         "period": "2025-01"
       },
       "priority": 5
     }'