API Reference

Send message.

post
https://app.customgpt.ai/api/v1/projects//conversations//messages

Sends a user message to an agent and returns the agent's response. Supports streaming for real-time display, file attachments for document analysis, and persona overrides for dynamic behavior. This is the primary endpoint for chat interactions.

Notes: Add ?stream=true to receive the response in real-time chunks.

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

The ID of the agent to get the messages for

string
required

The session ID of the converstaions to get the messages for

Query Params
boolean
Defaults to false

When true, the response is sent as a stream of data-only server-sent events (SSE) as tokens are generated, terminated by a status: "finish" event. When false, the full response is returned in a single JSON object. See the streaming guide for client implementation examples.

string
Defaults to en

The ISO 639-1 language code for the response language. Examples: es - Spanish, fr - French, de - German, ja - Japanese. The agent will attempt to respond in this language regardless of the query language.

string
length ≤ 128

The external ID of the prompt history.

Body Params

Send a message to a conversation.

string

Prompt to send to the agent

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)

files[]
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 10 days 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 10 days ago