Public: Tasks

Start an agent task

Run one autonomous agent turn for this brand.

command: "prompt" takes a free-form prompt, the instruction the agent carries out ("Add an About page with a team section"). command: "build_page" takes an opportunityRef from the page-opportunities list and builds that page.

A task takes about five minutes. Poll the task detail route every 30-60 seconds, or watch the chat thread the response links to.

One task at a time per brand. A second create while one is running answers 409: the agent holds a single workspace per brand, so it runs tasks one after another rather than queuing them. Wait for the running task to settle, then submit the next one.

Idempotent retries. Send an Idempotency-Key header to make a retry safe. For 24 hours, the same key with the same body answers 202 with the task it already started and an Idempotent-Replayed: true header; the same key with a different body answers 422.

post/api/v1/public/brands/{brandSlug}/tasks/

Request

  • Base URL: https://api.iterant.ai
  • URL: https://api.iterant.ai/api/v1/public/brands/{brandSlug}/tasks/
  • Auth: HTTP bearer

Path parameters

brandSlugstring required

Headers

Idempotency-Keystring

A unique value per logical task, 1-255 printable characters (a UUID v4 works). Remembered for 24 hours per organization.

Request body

command'prompt' | 'build_page' required
  • prompt - Prompt
  • build_page - Build page
promptstring

Required when command is "prompt". The instruction for the agent, in plain language.

opportunityRefstring

Required when command is "build_page". The ref of the opportunity to build, from the page-opportunities list.

callbackUrlstring

Optional https:// endpoint to POST the outcome to when the task settles. Polling GET /tasks/{taskId}/ remains the authority.

Response

taskIdstring uuid required

Pass this to the task detail route to poll for the outcome.

command'prompt' | 'build_page' required
  • prompt - Prompt
  • build_page - Build page
status'running' | 'succeeded' | 'failed' required
  • running - Running
  • succeeded - Succeeded
  • failed - Failed
chatUrlstring required

Dashboard deep-link to the chat thread the task runs in. The transcript is the full result.

createdAtstring date-time required

Changes

No recorded changes to this operation across all 1 revision of this API.