POpoll-the-people
Task Messages

Send follow-up message.

Changed on

Submits a follow-up prompt to an existing task. The task must not currently be processing a previous message. Returns 202 Accepted; poll the task for progress.

Returns 409 if the task is locked by an active session.

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

Request

Path parameters

projectIdinteger required

The unique identifier of the agent.

taskIdstring required

The task ID.

Request body multipart/form-data

promptstring required

Prompt to send to the agent

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 task

custom_personastring nullable

Custom persona to use for the task

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 task

child_project_idinteger nullable

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

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)

labels_exclusiveboolean

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

Example request

{
  "prompt": "Can you expand on the third section?",
  "chatbot_model": "gpt-4-1",
  "custom_persona": "You are a helpful assistant specialised in document analysis.",
  "sub_personas": {
    "persona-summary": "Use a concise analyst tone.",
    "task-planner": "Extract risks first."
  },
  "response_source": "default",
  "custom_context": "User details: Name: John Doe, Role: Software Developer",
  "child_project_id": 123,
  "files[]": [
    "document.pdf"
  ],
  "labels[]": [
    "27",
    "billing"
  ],
  "tools": [
    {
      "function": {
        "name": "track_order",
        "description": "Look up the current status of an order by its ID."
      }
    }
  ]
}

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