--- title: "Create task." method: POST path: "/api/v1/projects/{projectId}/tasks" tags: ["Tasks"] --- # Create task. `POST /api/v1/projects/{projectId}/tasks` ## Request - Base URL: `https://app.customgpt.ai` - URL: `https://app.customgpt.ai/api/v1/projects/{projectId}/tasks` - Auth: HTTP bearer - TypeScript: (a function with typed inputs; its response is checked against the schema) 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). ## Path parameters - `projectId` integer, required ## Request body `multipart/form-data` - object - `name` string, nullable: Task name. Defaults to the truncated prompt if omitted. - `prompt` string, 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). - `tools` object[], nullable: Functions the agent may call during this task (OpenAI tools format, max 10). When the agent decides to call one, polling returns `status: awaiting_tool_results` with `result.tool_calls`; execute the functions and submit results via `POST /tasks/{taskId}/tool-outputs`. On multipart requests, pass this field as a JSON-encoded string. - `type` 'function', required - `function` object, required - `name` string, required: Function name (letters, numbers, underscores and dashes; max 64 chars; unique per request). - `description` string: What the function does — used by the agent to decide when to call it. Max 512 chars. - `parameters` object: JSON Schema describing the function arguments (free-form). - `custom_persona` string, nullable: Custom persona to use for the conversation - `sub_personas` object, nullable: Request-only sub-persona overrides keyed by sub-persona slug. Omitted keys use the saved generated/project value. For multipart/form-data, send bracket notation like sub_personas[persona-summary]=... - `persona-summary` string, nullable - `task-planner` string, nullable - `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_context` string, nullable: Custom context to use for the conversation - `child_project_id` integer, 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. - `file` string, 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[]` union[], nullable: Optional source-label filter (IDs or names). - Single group (OR): `labels[0][]=A&labels[0][]=B` - Multiple groups (AND-of-ORs, inner OR / outer AND): `labels[0][]=A&labels[0][]=B&labels[1][]=C&labels[1][]=D` → (A OR B) AND (C OR D) Limits: max 20 groups, 50 per group, 500 total. Unknown labels are dropped; a group emptied by dropping matches nothing. - union - string - string[] - `labels_exclusive` boolean: If true, search only pages with provided labels. If false, search pages with provided labels plus unlabeled pages. - `action_overrides` object, nullable: Override agent actions for this query only. Provide enabled and disabled action IDs. When using multipart/form-data, send action_overrides as a JSON-encoded object. - `enabled` string[]: Action IDs to enable for this request (built-in tool keys or custom tool keys). - `disabled` string[]: Action IDs to disable for this request (built-in tool keys or custom tool keys). ## Response `202` Task created and submitted successfully. Poll GET /tasks/{taskId} for progress. - object - `status` 'error' | 'success': The status of the response - `data` Task - `id` string: Task ID - `project_id` integer: Agent ID this task belongs to - `name` string: Task name - `created_at` string, date-time: When the task was created - `updated_at` string, date-time: When the task was last updated ## Other responses - `400`: Bad Argument - `401`: API Token is either missing or invalid - `402`: This feature is not available on your current plan. Upgrade your subscription or enable the required setting to use this endpoint. - `422`: Unsupported Argument - `429`: Resource Exhausted when sending a message to a conversation - `500`: Internal Server Error ## Changes - **2026-11-03** `77aab4354382`: 1 info - endpoint added [Operation history](https://skmtc.dev/poll-the-people/apis/customgpt-ai/changes/api/v1/projects/:projectId/tasks/post.md) --- [API](https://skmtc.dev/poll-the-people/apis/customgpt-ai.md) - [All operations](https://skmtc.dev/poll-the-people/apis/customgpt-ai/llms.txt) - [OpenAPI document](https://skmtc.dev/poll-the-people/apis/customgpt-ai/revisions/77aab4354382?raw)