Skip to main content
Set up a new client workspace from your own system, from an empty workspace to a first run, using the REST API. The workspace stays in 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.completed event. Otherwise, poll the run.
  • Enough credits for the first run. Check with Credits.
All values below are synthetic. Every 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

Keep workspace.id as BRAND_ID. The workspace is DRAFT, and the ETag header carries its version.
2

Create topics and tags

Keep topic.id as TOPIC_ID and tag.id as TAG_ID. See Create a topic and Create a tag.
3

Create prompts

Create one prompt per request. Prompts under monitoring add recurring credit use. See Create a prompt.
4

Set monitoring

Read Get monitoring for the selected models and the ETag. Preview the change with dryRun, then save it. When no setting exists yet, the first ETag is "0".
Repeat the request without dryRun to save. See Update monitoring.
5

Subscribe to run.completed

Create an integration webhook endpoint limited to the new workspace. Store the returned secret: it is shown once.
Verify each delivery with Verify signatures.
6

Activate the workspace

Read the workspace again to get its current ETag, then move it to LIVE. This example assumes the ETag you read is "2".
Activation never starts generation. A workspace over the plan limit returns 409 QUOTA_EXCEEDED. See Update a workspace.
7

Estimate, then start the first run

Check 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 run.completed event when the run reaches a final state:
Deduplicate on 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=configuration returns the prompts, their topics and tags.
  • Credits shows what the run reserved.

Limits and rollback

  • Replaying a request with the same Idempotency-Key and 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.
  • 412 means the resource changed since your read. Read it again and reapply your change.
  • A LIVE workspace cannot return to DRAFT. Archive it with status: ARCHIVED if the client leaves.
  • There is no run cancellation in API v1.