# Create and start a task

`POST /v1/tasks`

Starts asynchronous work. Supplying attachments additionally requires files:write; each uploadId must come from POST /v1/uploads.

Required OAuth scopes: `tasks:write`

## Parameters

- `Idempotency-Key` (header, string, required): Required unique key. For 24 hours, retries with the same key and body replay the original response.

## Request body

- `prompt` (string)
- `attachments` (object[])
  - `uploadId` (string, required)
- `title` (string)
- `model` (object, required)
  - `slug` (string, required)
  - `fast` (boolean)
  - `effort` ("low" | "medium" | "high" | "xhigh" | "max" | null)
- `projectId` (string (uuid))

```json
{
  "model": {
    "fast": false,
    "slug": "pro",
    "effort": "high"
  },
  "prompt": "Design a printable mounting bracket for a 40 mm stepper motor.",
  "projectId": "PROJECT_ID"
}
```

## Responses

- `201`
  - `task` (object, required)
    - `id` (string, required)
    - `title` (string, required)
    - `status` ("idle" | "queued" | "running" | "awaiting_input" | "completed" | "cancelled" | "failed", required)
    - `executionMode` ("adam" | "external")
    - `projectId` (string | null, required)
    - `model` (object | null, required)
    - `pendingInteraction` (object | null, required)
    - `createdAt` (string, required)
    - `updatedAt` (string, required)
  - `messages` (object[], required)
    - `id` (string, required)
    - `role` ("user" | "assistant", required)
    - `parts` (object[], required)
    - `createdAt` (string (date-time), required)
- `400`: Invalid request
- `401`: Missing or invalid Bearer credential
- `402`: Payment or subscription required
- `403`: Credential is missing a required scope
- `404`: Resource not found
- `409`: Request conflict
- `429`: Rate limit exceeded
- `500`: Internal API error