Create agent

post

https://api.agent700.ai/api/agents

Creates a new agent for the current user in the specified organization.
Also creates the first agent revision.

Revision fields match AgentCreateRequest / AgentRevisionConfigBase (model,
prompts, temperature, PII scrubbing, smart/full document settings, MCP, JSON
structured output, promptCachingEnabled, promptCacheKey). Fields in
AgentRevisionConfigUpdateOnly (reasoningEffort, thinkingEnabled,
thinkingBudgetTokens, searchDomainFilter, searchRecencyFilter)
are not accepted on create; use PUT /api/agents/{agentId} to set them.

Supports optional JSON Structured Output: set jsonOutputEnabled: true and
provide a valid jsonSchema (JSON Schema Draft 7, object or string) to force
the agent's responses into a predefined JSON format. Not available for image
generation models.

Set model to a name from GET /api/models (see example catalog_flow_create_agent).
Then call POST /api/chat with the returned agent id as agentId.

Recent Requests

Time	Status	User Agent
Retrieving recent requests…

Loading…

Body Params

Agent creation data. Organization ID is required. All other fields are optional and use
defaults from configuration. Creates a new agent with its first revision. Requires
a valid paid account (payment_required middleware).

Body for POST /api/agents. Creates the agent and its first revision.
All fields except organizationId are optional and use server defaults.
promptCachingEnabled (default true) and promptCacheKey are accepted on
create. Reasoning, thinking, and search filters are not; set them with
PUT /api/agents/{agentId} after creation.

organizationId

uuid

required

Organization that owns the new agent.

name

string

Display name for this revision.

masterPrompt

string | null

System prompt sent to the model for this agent revision.

introductoryText

string | null

User-facing greeting or intro shown before the first turn.

imageDimensions

string

Image size hint for image-generation models (e.g. 1024x1024).

model

string

Model name from GET /api/models. Deprecated or inactive models are
rejected with 400.

temperature

float

Sampling temperature for the model.

topP

float | null

Nucleus sampling parameter (top_p).

maxTokens

integer

Maximum completion tokens (subject to model limits).

scrubPii

boolean

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

piiThreshold

float

PII detection confidence threshold when scrubPii is enabled.

smartDocEvaluation

boolean

When true, uses embedding-based smart document evaluation for alignment
placeholders in prompts.

smartDocChunkSize

integer

Chunk size (characters) for smart document evaluation.

smartDocChunkOverlap

integer

Overlap (characters) between smart-doc chunks.

smartDocEmbeddingModel

string

Embedding model name for smart document evaluation.

smartDocTopK

integer

Top-K relevant chunks retrieved during smart document evaluation.

fullDocAnalysis

boolean

When true, runs full-document analysis over alignment placeholders.

fullDocChunkSize

integer

Chunk size (characters) for full document analysis.

fullDocChunkOverlap

integer

Overlap (characters) between full-doc chunks.

fullDocMaxLength

integer

Maximum total text length considered during full document analysis.

enableMcp

boolean

Enables MCP (Model Context Protocol) tools for this agent when the
selected model supports MCP.

mcpServerNames

array of strings

MCP server names this agent may use.

mcpServerNames

mcpAutoApprove

boolean

When true, MCP tool calls are approved automatically without user confirmation.

promptCachingEnabled

boolean | null

Defaults to true

When true, enables automatic prompt caching for models that support it
(supportsPromptCaching on GET /api/models). Anthropic requests receive
top-level cache_control; OpenAI/Mistral receive prompt_cache_key and
xAI receives x-grok-conv-id when supportsPromptCacheId is true.
Cache token usage is always billed correctly when the provider reports it.
Defaults to true for new agents. Set on POST /api/agents or
PUT /api/agents/{agentId}.

promptCacheKey

string | null

Optional cache routing key for providers that accept one
(supportsPromptCacheId). When blank/omitted and caching is enabled,
agentId is used automatically. Do not put secrets or PII in this value.
Ignored for Claude and Gemini (no provider routing-key parameter).

jsonOutputEnabled

boolean

Defaults to false

Enables JSON Structured Output, forcing responses to conform to jsonSchema.
Not available for image generation models (names starting with img).
Requires a valid schema when enabled.

jsonSchema

JSON Schema (Draft 7) for structured output. Responses return a parsed object;
requests accept a JSON object or a JSON-encoded string.

Responses

200Agent created

400Missing organizationId