API reference

Create and start a task

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

POST/v1/tasks

Authorization

Send a personal API key or an OAuth access token as Authorization: Bearer <token>.

OAuth scopes: tasks:write

Parameters

Idempotency-Keystring, headerrequired
Required unique key. For 24 hours, retries with the same key and body replay the original response.

Request body

application/json, required

promptstring
attachmentsobject[]
uploadIdstringrequired
titlestring
modelobjectrequired
slugstringrequired
fastboolean
effort"low" | "medium" | "high" | "xhigh" | "max" | null
projectIdstring (uuid)

Responses

201Success

taskobjectrequired
idstringrequired
titlestringrequired
status"idle" | "queued" | "running" | "awaiting_input" | "completed" | "cancelled" | "failed"required
executionMode"adam" | "external"
projectIdstring | nullrequired
modelobject | nullrequired
slugstring | nullrequired
fastbooleanrequired
effort"low" | "medium" | "high" | "xhigh" | "max" | nullrequired
pendingInteractionobject | nullrequired
idstringrequired
type"question" | "approval"required
promptstring | nullrequired
createdAtstringrequired
updatedAtstringrequired
messagesobject[]required
idstringrequired
role"user" | "assistant"required
partsobject[]required
createdAtstring (date-time)required

400Invalid request

errorobjectrequired
typestringrequired
messagestringrequired
requestIdstring

401Missing or invalid Bearer credential

errorobjectrequired
typestringrequired
messagestringrequired
requestIdstring

402Payment or subscription required

errorobjectrequired
typestringrequired
messagestringrequired
requestIdstring

403Credential is missing a required scope

errorobjectrequired
typestringrequired
messagestringrequired
requestIdstring

404Resource not found

errorobjectrequired
typestringrequired
messagestringrequired
requestIdstring

409Request conflict

errorobjectrequired
typestringrequired
messagestringrequired
requestIdstring

429Rate limit exceeded

errorobjectrequired
typestringrequired
messagestringrequired
requestIdstring

500Internal API error

errorobjectrequired
typestringrequired
messagestringrequired
requestIdstring

curl --request POST \
  --url 'https://api.staging.adam.new/v1/tasks' \
  --header 'Authorization: Bearer <token>' \
  --header 'Idempotency-Key: <Idempotency-Key>' \
  --header 'Content-Type: application/json' \
  --data '{
  "model": {
    "fast": false,
    "slug": "pro",
    "effort": "high"
  },
  "prompt": "Design a printable mounting bracket for a 40 mm stepper motor.",
  "projectId": "PROJECT_ID"
}'

{
  "task": {
    "id": "<string>",
    "title": "<string>",
    "status": "idle",
    "executionMode": "adam",
    "projectId": "<string>",
    "model": {
      "slug": "<string>",
      "fast": true,
      "effort": "low"
    },
    "pendingInteraction": {
      "id": "<string>",
      "type": "question",
      "prompt": "<string>"
    },
    "createdAt": "<string>",
    "updatedAt": "<string>"
  },
  "messages": [
    {
      "id": "<string>",
      "role": "user",
      "parts": [
        {
          "type": "reasoning",
          "text": "<string>"
        }
      ],
      "createdAt": "2026-01-01T00:00:00.000Z"
    }
  ]
}