DRAFT while you configure it, so nothing is monitored or billed until you activate it and start a run.
Before you start
- A Business, Agency Business or Enterprise plan, and an API token with write access enabled by an Owner or Manager. See Writing data.
- A public HTTPS endpoint if you want to receive the
run.completedevent. Otherwise, poll the run. - Enough credits for the first run. Check with Credits.
POST needs a unique Idempotency-Key, and every PATCH needs If-Match with the ETag you last read.
Steps
1
Create the workspace in DRAFT
workspace.id as BRAND_ID. The workspace is DRAFT, and the ETag header carries its version.2
Create topics and tags
topic.id as TOPIC_ID and tag.id as TAG_ID. See Create a topic and Create a tag.3
Create prompts
4
Set monitoring
Read Get monitoring for the selected models and the Repeat the request without
ETag. Preview the change with dryRun, then save it. When no setting exists yet, the first ETag is "0".dryRun to save. See Update monitoring.5
Subscribe to run.completed
Create an integration webhook endpoint limited to the new workspace. Store the returned Verify each delivery with Verify signatures.
secret: it is shown once.6
Activate the workspace
Read the workspace again to get its current Activation never starts generation. A workspace over the plan limit returns
ETag, then move it to LIVE. This example assumes the ETag you read is "2".409 QUOTA_EXCEEDED. See Update a workspace.7
Estimate, then start the first run
sufficientCredits in the estimate before you start. The start request returns 202 with a Location header and reserves the planned credits. See Estimate a run and Start a run.8
Wait for run.completed
Your endpoint receives a signed Deduplicate on
run.completed event when the run reaches a final state:id: delivery is at least once. A COMPLETED_WITH_WARNINGS status means some answers failed, so read counts. Without a webhook, poll List runs.Verify the result
- Get monitoring returns the saved schedule and models.
- List prompts with
view=configurationreturns the prompts, their topics and tags. - Credits shows what the run reserved.
Limits and rollback
- Replaying a request with the same
Idempotency-Keyand body returns the original response for 24 hours. Use a new key for a new logical operation, and read the state first after an uncertain outcome. 412means the resource changed since your read. Read it again and reapply your change.- A
LIVEworkspace cannot return toDRAFT. Archive it withstatus: ARCHIVEDif the client leaves. - There is no run cancellation in API v1.
Related
- Writing data
- Integration webhook events
- Run write tool for the MCP equivalent of the first run.

