API Reference

Create task.

post
https://app.customgpt.ai/api/v1/projects//tasks

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).

Recent Requests
Log in to see full request history
TimeStatusUser Agent
Retrieving recent requests…
LoadingLoading…
Path Params
integer
required

The unique identifier of the agent.

Body Params

Create a Plan & Act task and submit its first prompt in one call. Poll GET /tasks/{taskId} for progress.

string | null

Task name. Defaults to the truncated prompt if omitted.

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).

string | null

Custom persona to use for the conversation

string | null
enum

Agent model to use for the conversation

string | null
enum
Defaults to default

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.
Allowed:
string | null

Custom context to use for the conversation

file | null

File to upload (Allowed types: pdf, docx, doc, odt, txt, jpg, jpeg, png, webp)

files[]
array of files | null

Multiple files to upload (Allowed types: pdf, docx, doc, odt, txt, jpg, jpeg, png, webp)

string | null
enum
Defaults to optimal-choice

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.
Allowed:
labels[]
array | null

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.

labels[]
boolean
Defaults to false

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

action_overrides
object | null

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.

Responses

Updated about 2 months ago

Language
Credentials
Bearer
JWT
LoadingLoading…
Response
Click Try It! to start a request and see the response here! Or choose an example:
application/json

Updated about 2 months ago