Skip to main content
POST
This endpoint allows you to send messages to an AI agent and receive responses. It supports:
  • Simple text queries
  • File attachments (documents, images, audio)
  • Real-time response streaming
  • Continuation of existing conversations
  • Contact association (CRM)
  • Per-request overrides of the agent’s prompt, model and reasoning level

Path

string
required
The ID of the agent you want to query (CUID format).

Body

Required

string
required
The user’s message or question.

Optional - Basic Configuration

boolean
default:"false"
If true, responds with Server-Sent Events in real-time.
string
ID to continue an existing conversation. Auto-generated if not provided.
string
Unique ID of the visitor/user. Auto-generated if not provided.
string
default:"api"
Source channel for the message. Valid values: api, dashboard, website, form, whatsapp, telegram, slack, meta, crisp, zapier, mail, mercadolibre, agent_builder, chatwoot, crmchatsappai.
string
Additional context for the AI (e.g., specific instructions).
string
Overrides the agent’s system prompt for this request only. The agent’s saved configuration in the database is not modified.Use this to test different prompt variants, run evaluations, or inject custom instructions without editing the agent from the dashboard.
An empty string "" is treated as no override — the agent’s saved system prompt is used instead. If both systemPrompt and promptType: "raw" are provided, promptType: "raw" takes precedence.

Optional - Model & Reasoning Overrides

string
Overrides the agent’s model for this request only. The agent’s saved configuration in the database is not modified.Use the identifier form used by the agent configuration, with underscores — for example gpt_5_6_sol, gemini_3_8_flash, claude_5_sonnet, gpt_6_luna, glm_5_3.
These identifiers are not the same as the provider-facing model names used by the Increment Agent Queries endpoint. Here it is gpt_5_6_sol, there it is gpt-5.6-sol.
string
Controls how much internal reasoning the model does before answering, for this request only. The agent’s saved reasoning level is not modified.Valid values: off, low, medium, high, max. Always send one of these five — Laburen translates them to whatever each provider expects, so you never send provider-native values such as none or a thinking budget.Which of the five a model accepts depends on the model. Sending a level the model does not support returns 400.The exceptions worth remembering: most Gemini models cannot turn reasoning off — gemini_3_5_flash_lite is the only one that accepts off, and there off means Google’s lowest level rather than reasoning fully disabled. glm_5_3, glm_5_3_flash, claude_5_5_opus and gpt_6_astra cannot turn it off either: reasoning is mandatory on those models. The DeepSeek models (deepseek_r1, deepseek_v4_pro, deepseek_v4_flash) always reason at a fixed level, so they reject every value.
On gemini_3_8_flash, low produces little or no reasoning in practice, even on complex prompts. If you need the model to actually reason, start at medium.
Any model not listed in the table has no configurable reasoning. Sending reasoningEffort to one of those returns 400.
The level is validated against the model that will actually run the request: the modelName you send in this same body, or the agent’s saved model when you omit it.When you omit reasoningEffort, the agent’s saved level is used. If the agent has none saved, the model’s default from the table applies. The override works with conversational mode on or off.

Optional - Webhook (Conversational Mode)

string
URL to receive the AI response asynchronously. Required when the agent has conversational mode enabled and channel is api.The webhook URL must:
  • Be a valid URL format
  • Use http:// or https:// protocol
  • Be reachable (the server validates connectivity)
  • Not point to localhost or private IPs in production (SSRF protection)

Optional - File Attachments

array
List of file attachments.

Optional - Contact (CRM)

object
Contact data to associate with the conversation.

Response (without streaming)

string
The agent’s response.
array
Sources used to generate the response.
string
ID of the response message.
string
ID of the conversation (save this to continue the conversation).
string
ID of the visitor.
boolean
Whether the agent requested human intervention.
string
Conversation status (e.g., UNRESOLVED, RESOLVED).
object
Token usage and cost information.
array
List of approvals for tool executions (if any).

Response (Conversational Mode with Webhook)

When the agent has conversational mode enabled and you provide a webhookUrl, the endpoint returns immediately with a queued status:
string
Always "queued" for webhook mode.
string
ID of the conversation.
string
ID of the visitor.
string
ID of the user’s input message.
string
Confirmation message indicating the request was queued.
string
The webhook URL where the response will be sent.

Webhook Payload

After processing (typically 8 seconds delay to batch multiple messages), a POST request is sent to your webhookUrl with the following payload:
Webhook Headers:
  • Content-Type: application/json
  • X-Laburen-Event: agent.response
In conversational mode, long responses are automatically split into multiple messages (maximum 3 for most channels, up to 10 for Instagram/Meta).

Streaming Response

When streaming: true, the endpoint responds with Server-Sent Events:
Events:
  • answer: Partial response text (concatenate to build the full answer)
  • endpoint_response: Full response object (JSON) with all metadata

Error Responses

Model and Reasoning Override Example

Run a single request on a different model and reasoning level without changing the agent. Useful for A/B testing prompts, evaluations, or spending more reasoning on a hard question while the agent stays cheap by default.
cURL
To make the same agent answer as fast and cheap as possible, send the opposite:
cURL
If the model rejects the level, the response is a 400:
Neither override is persisted. The agent keeps the model and reasoning level saved from the dashboard, so the next request without these fields behaves exactly as before.

Streaming Example (JavaScript)

Webhook Example (Conversational Mode)

When your agent has conversational mode enabled, use webhookUrl to receive the AI response asynchronously:
cURL
Immediate Response:
Webhook Receiver Example (Node.js/Express):