---
title: "Start an agent task"
method: POST
path: "/api/v1/public/brands/{brandSlug}/tasks/"
tags: ["Public: Tasks"]
---

# Start an agent task

`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

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.

## Path parameters

- `brandSlug` string, required

## Headers

- `Idempotency-Key` string

## Request body

- PublicAgentTaskCreate
  - `command` 'prompt' | 'build_page', required: * `prompt` - Prompt * `build_page` - Build page
  - `prompt` string: Required when `command` is "prompt". The instruction for the agent, in plain language.
  - `opportunityRef` string: Required when `command` is "build_page". The `ref` of the opportunity to build, from the page-opportunities list.
  - `callbackUrl` string: Optional https:// endpoint to POST the outcome to when the task settles. Polling `GET /tasks/{taskId}/` remains the authority.

## Response `202`

- PublicAgentTaskCreated: The 202 body: the handle, what it is doing, and where to watch it.
  - `taskId` string, 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
  - `chatUrl` string, required: Dashboard deep-link to the chat thread the task runs in. The transcript is the full result.
  - `createdAt` string, date-time, required

## Other responses

- `400`
- `401`
- `403`
- `404`
- `405`
- `406`
- `415`
- `429`
- `500`

---

[API](https://skmtc.dev/iterant/apis/iterant-public-api.md) · [All operations](https://skmtc.dev/iterant/apis/iterant-public-api/llms.txt) · [OpenAPI document](https://skmtc.dev/iterant/apis/iterant-public-api/revisions/8d62f6ac9cbd?raw)