POpoll-the-people
Tasks

Create task.

Changed on

Creates a Plan & Act task and submits its first prompt in one call. Returns 202 Accepted. Sessions can run for minutes or longer, so callers must poll GET /projects/{projectId}/tasks/{taskId} for progress events rather than holding a connection open.

Requires the agent to have use_planner_mode enabled and the team to be on a plan that supports Plan & Act tasks (otherwise 402).

post/api/v1/projects/{projectId}/tasks

Request

Path parameters

projectIdinteger required
Example:1

The unique identifier of the agent.

Request body multipart/form-data

namestring nullable

Task name. Defaults to the truncated prompt if omitted.

promptstring required

The first prompt for this task.

The task runs asynchronously; results stream back via GET /tasks/{taskId} (poll for progress — sessions can run for minutes or longer).

custom_personastring nullable

Custom persona to use for the conversation

chatbot_model'gpt-4-1' | 'gpt-6-sol-none' | 'gpt-5.6-sol-none' | 'gpt-5.6-terra-none' | 'gpt-6-luna-none' | 'gpt-5.6-luna-none' | 'gpt-4-o' | 'gpt-5.1-none' | 'gpt-5.1-low' | 'gpt-5.2-none' | 'gpt-5.2-low' | 'gpt-5.4-low' | 'gpt-4-1-mini' | 'gpt-4o-mini' | 'claude-5.5-opus' | 'claude-5-opus' | 'claude-5-sonnet-thinking' | 'claude-5-sonnet' | 'claude-4.8-opus' | 'claude-4.6-opus' | 'claude-4.5-opus' | 'claude-4.6-sonnet' | 'claude-4.6-sonnet-thinking' | 'claude-4.5-sonnet' | 'claude-4.5-haiku' | 'gpt-o4-mini-low' | 'gpt-o4-mini-medium' | 'gpt-o4-mini-high' | 'gemini-3.1-pro' | 'gemini-3-pro' | 'gemini-3.5-flash' nullable

Agent model to use for the conversation

response_source'default' | 'own_content' | 'openai_content' nullable

Controls which knowledge the agent draws from.

Values:

  • default / own_content — agent answers using only your indexed content (recommended).
  • openai_content — agent supplements your indexed content with general knowledge from the underlying model.
custom_contextstring nullable

Custom context to use for the conversation

child_project_idinteger nullable

Optional child agent id for master agents. Provide it to route the message to a specific child agent. Omit it to let Auto / Smart Routing resolve the child agent when enabled.

filestring binary nullable

File to upload (Allowed types: pdf, docx, doc, odt, txt, jpg, jpeg, png, webp, xlsx, xls, csv, tsv, json, md, html, pptx)

files[]string[] nullable

Multiple files to upload (Allowed types: pdf, docx, doc, odt, txt, jpg, jpeg, png, webp, xlsx, xls, csv, tsv, json, md, html, pptx)

agent_capability'fastest-responses' | 'optimal-choice' | 'advanced-reasoning' | 'complex-tasks' nullable

Agent capability preset.

Values:

  • fastest-responses — prioritises speed; best for simple, high-volume tasks.
  • optimal-choice (default) — balances speed and quality for most tasks.
  • advanced-reasoning — uses extended thinking for multi-step or analytical tasks.
  • complex-tasks — maximum capability for long-horizon, deeply complex tasks; slowest and most resource-intensive.

Ignored when use_planner_mode is enabled.

labels_exclusiveboolean

If true, search only pages with provided labels. If false, search pages with provided labels plus unlabeled pages.

Example request

{
  "name": "Document analysis",
  "prompt": "Analyse the attached document and summarise the key risks.",
  "tools": [
    {
      "function": {
        "name": "track_order",
        "description": "Look up the current status of an order by its ID."
      }
    }
  ],
  "custom_persona": "You are a custom AI Agent called *agent name*, a friendly *agent role* who works for *organization* and answers questions based on the given context. Be as helpful as possible. Always prioritize the customer. Escalate complex issues. Stay on topic. Use appropriate language, Acknowledge limitations.",
  "sub_personas": {
    "persona-summary": "Use a concise analyst tone.",
    "task-planner": "Extract risks first, then summarize."
  },
  "chatbot_model": "gpt-4-1",
  "response_source": "default",
  "custom_context": "User details: Name: John Doe, Role: Software Developer, Organization: CustomGPT.ai",
  "child_project_id": 123,
  "file": "file.pdf",
  "files[]": [
    "file.pdf"
  ],
  "agent_capability": "optimal-choice",
  "labels[]": [
    "27",
    "billing"
  ],
  "action_overrides": {
    "enabled": [
      "file_upload"
    ],
    "disabled": [
      "lead_capture"
    ]
  }
}

Response

Task created and submitted successfully. Poll GET /tasks/{taskId} for progress.

status'error' | 'success'

The status of the response

Example response

{
  "status": "success",
  "data": {
    "id": "f1b9aaf0-5e4e-11eb-ae93-0242ac130002",
    "project_id": 1,
    "name": "Analyse this document",
    "created_at": "Monday, 01-Jan-24 12:00:00 UTC",
    "updated_at": "Monday, 01-Jan-24 12:00:00 UTC"
  }
}

Changes