Chat completion

post

https://api.agent700.ai/api/chat

Processes a chat request to the LLM using the caller's active agent
configuration. Returns a non-streaming JSON response by default, or an SSE stream
if streamingEnabled is set to true in the request body.

Model catalog integration (recommended)

GET /api/models?category=text — choose models[].name (not displayName).
Optionally persist on the agent: PUT /api/agents/{agentId} with { "model": "<name>" }, or POST /api/agents when creating an agent.
Call this endpoint with a saved agent's agentId (model from the agent revision), or include "model": "<name>" to override for a single request. Create the agent first via POST /api/agents if you do not have one yet.

Request examples prefixed with catalog_flow_ all include agentId (except step 1, which lists models).

Recent Requests

Time	Status	User Agent
Retrieving recent requests…

Loading…

Body Params

Chat completion request. messages is required. Provide agentId to use a
persisted agent revision, or omit agentId for a phantom agent built from
request overrides and defaults (caller billing). Optional agentRevisionId
selects a specific revision when agentId is set. Set streamingEnabled to
true for SSE instead of JSON. Requires a valid paid account for the caller
(phantom) or agent owner (persisted agent).

messages

array of objects

required

Ordered list of chat messages forming the conversation. The first
message is typically a system prompt injected from the agent, the
rest are user/assistant turns.

messages*

agentId

string

Optional UUID of a persisted agent. When omitted, a phantom in-memory
agent revision is built from request fields and platform defaults; the
caller's organization is billed. Include model (and optionally
masterPrompt, temperature, etc.) for phantom requests.

agentRevisionId

integer | null

Optional specific agent revision ID to use instead of the agent's
current_revision.

masterPrompt

string

Optional per-request override of the agent revision master prompt
(agent owner only). When omitted, the revision's stored masterPrompt is used.

introductoryText

string

Optional override of the agent revision introductory text for this
request (agent owner only). Does not replace creating or updating an agent.

imageDimensions

string

Image size/format hint for models that can generate images
(implementation‑specific, e.g. "1024x1024").

model

string

Model identifier to use for this request (overrides the agent's
configured model when provided).

temperature

float

Sampling temperature for the model.

topP

float

Nucleus sampling parameter (top_p).

maxTokens

integer

Maximum number of tokens for the completion. Subject to global
model limits.

reasoningEffort

string | null

Reasoning effort hint for models that support explicit reasoning
modes.

thinkingEnabled

boolean | null

Enables extended "thinking" for models that support it (model‑
specific feature).

thinkingBudgetTokens

integer | null

Token budget reserved for thinking when thinkingEnabled is true.

promptCachingEnabled

boolean | null

Defaults to true

When true, enables automatic prompt caching for models that support it.
Anthropic receives top-level cache_control; OpenAI/Mistral receive
prompt_cache_key and xAI receives x-grok-conv-id when the model
supports a cache ID. Defaults to true for new agents.

promptCacheKey

string | null

Optional cache routing key override for keyed providers. Blank/omitted
uses agentId automatically. Do not put secrets or PII in this value.

scrubPii

boolean

When true, scrubs PII from messages based on piiThreshold before
sending to the model.

piiThreshold

float

PII detection confidence threshold used when scrubPii is enabled.

smartDocEvaluation

boolean

When true, uses smart document evaluation with embeddings for
alignment data placeholders.

smartDocChunkSize

integer

Chunk size (in characters) for smart document evaluation.

smartDocChunkOverlap

integer

Overlap (in characters) between chunks for smart document
evaluation.

smartDocEmbeddingModel

string

Embedding model name used for smart document evaluation.

smartDocTopK

integer

Number of top relevant chunks to retrieve during smart document
evaluation.

fullDocAnalysis

boolean

When true, performs full document analysis over alignment data
placeholders without streaming.

fullDocChunkSize

integer

Chunk size (in characters) for full document analysis.

fullDocChunkOverlap

integer

Overlap (in characters) between chunks for full document analysis.

fullDocMaxLength

integer

Maximum total length of text considered during full document
analysis.

enableMcp

boolean

Enables MCP (Model Context Protocol) tools for this request if
supported by the model.

mcpServerNames

array of strings

List of MCP server names that may be used by this agent/request.

mcpServerNames

mcpAutoApprove

boolean

When true, automatically approves MCP tool calls without requiring
explicit user confirmation.

jsonOutputEnabled

boolean | null

Enables structured JSON output for this request. Resolution logic:

true with jsonSchema provided: uses the request schema.
true without jsonSchema: falls back to the agent's stored schema.
true with no schema in request or on agent: returns an error.
false: disables JSON output even if enabled on the agent.
Not sent: uses the agent's own jsonOutputEnabled setting.

jsonSchema

object | null

JSON Schema object defining the structure of the expected response.
Used only when jsonOutputEnabled is true. When omitted, the agent's
stored jsonSchema is used as a fallback.

streamingEnabled

boolean

When true, enables Server-Sent Events (SSE) streaming for this request.
When set to true, the endpoint will return an SSE stream instead of a JSON response.
Defaults to false.

parallelToolCalls

boolean | null

Controls whether the model is allowed to invoke multiple tools in a single
response turn (parallel tool calling).

true – parallel tool calls enabled (default for most models).
false – the model will call at most one tool per turn.

When omitted the server applies a per-model default: gpt-4.1-mini and
gpt-4.1-nano default to false because those models can loop
unexpectedly when parallel tool calls are enabled. All other models
default to true.

Supported providers: OpenAI (Responses API), xAI, Anthropic Claude.

tools

array of objects | null

Optional array of client-provided tool definitions in OpenAI function-calling
format. These tools are passed to the model's native tools parameter alongside
any server-side MCP tools.

When the model calls one of these client tools the server returns
finish_reason: "requires_action" with a tool_calls array instead of
executing the tool server-side.

Parallel tool calling is supported: the model may return multiple
tool calls in a single tool_calls array within one turn.

The client should then:

Execute all tools locally (may be done in parallel).
Send a follow-up /chat request whose messages array contains the
original conversation plus an assistant message with tool_calls
and one tool role message per tool result (OpenAI stateless loop).

tools

Responses

200

Chat response.

Non-streaming: Returns a ChatResponse JSON object.

Streaming (SSE): Returns a Server-Sent Events stream. Each event
has an event: type and a data: JSON payload. Relevant event types:

chat_message_response — partial content chunk, or a finish_reason
completion signal.
tool_calls — emitted before the requires_action finish signal
when the model invokes one or more client-provided tools. The data
payload is {"tool_calls": [...]} using ClientToolCall schema.
Parallel tool calling is supported: the model may invoke multiple
tools in a single turn and all will be included in one tool_calls event.
mcp_tool_complete_in_content — emitted for each server-side MCP tool
that completes within a streaming turn.
mcp_tool_message — emitted for each MCP tool response added to history.
error — stream-level error event.

SSE example (single client tool):

event: chat_message_response
data: {"content": "Let me check the weather."}

event: tool_calls
data: {"tool_calls": [{"id": "call_abc123", "type": "function", "function": {"name": "get_weather", "arguments": "{\"location\":\"San Francisco\"}"}}]}

event: chat_message_response
data: {"finish_reason": "requires_action"}

SSE example (parallel client tools):

event: chat_message_response
data: {"content": "Let me check both locations."}

event: tool_calls
data: {"tool_calls": [{"id": "call_abc123", "type": "function", "function": {"name": "get_weather", "arguments": "{\"location\":\"San Francisco\"}"}}, {"id": "call_def456", "type": "function", "function": {"name": "get_weather", "arguments": "{\"location\":\"New York\"}"}}]}

event: chat_message_response
data: {"finish_reason": "requires_action"}

400Invalid request (e.g. missing agentId)

402Payment required for agent owner

500Error processing chat request