Chat

Stateless completion with a Mind

Send a conversation to a single Mind and get its next reply without any server-side state: you own the history and resend it every call. Omit messages (or send []) to get the Mind's greeting. Supports OpenAI-style response_format (structured output), user-defined tools / tool_choice (function calling; calls are returned, never executed), file/link attachments via messages[].metadata.attachedFiles, a model/provider override, language, sourcePolicy: "knowledge_only" to retrieve processed Mind knowledge with internal web tools and request attachments disabled (persona fallback is reported when no evidence matches), and citationMarkers to control inline [[CITE:n]] markers. Default responseMode: "sync" returns buffered JSON; responseMode: "stream" returns Server-Sent Events (start, heartbeat comments, then a single result frame with the same payload, then done) to keep the connection active during long generations. JSON is limited to 1 MiB, 100 messages, 128 content parts per message and 100 total attachments; body admission returns HTTP 400/413 before opening a stream. Client disconnects cancel generation and structured extraction where the provider supports cancellation. Access rule: you can chat with Minds you own, Minds shared with you directly or with your team, Minds inside an Audience you own, belong to, or that is shared with your team, and public Minds; anything else returns 403 Access denied. The Mind must be trained (readyToChat: true on GET /v1/minds/{mindId}/training) or you get 409 SPARK_NOT_READY. Each call consumes one synthetic response from your monthly allowance and counts against the 30 completions/minute rate limit.

post/api/v1/minds/{mindId}/completion

Request

  • Base URL: https://api.getminds.ai
  • URL: https://api.getminds.ai/api/v1/minds/{mindId}/completion
  • Auth: HTTP bearer

Path parameters

mindIdstring uuid required

Mind UUID.

Request body

responseMode'sync' | 'stream'

sync buffers the whole reply into one JSON response. stream answers with text/event-stream and delivers the same payload in a terminal result frame; use it whenever generation may exceed ~60 s (web search, large attachments).

modelstring

Model override, e.g. claude-sonnet-5-5, gpt-6.1-sol, gpt-6-luna, gemini-3.8-flash. Provider is auto-detected from the claude-, gemini-, gpt-/o1/o3/o4/chatgpt- prefixes; retired IDs are forwarded to their replacement. Without an override the team's preferred provider (if any) or the product default is used.

provider'openai' | 'anthropic' | 'google'

Provider of model. Required only when the provider cannot be auto-detected from the model name.

language'en' | 'es' | 'fr' | 'de' | 'zh' | 'tr' | 'ar' | 'ja' | 'ko'

Reply language hint. Falls back to the x-locale header, then en. Strong personas may still answer in their native language.

endUserNamestring nullable

Display name of the human end user, normalized and truncated to 120 characters. Omitted/empty means the Mind addresses the user neutrally and never infers the API-key owner's name. Aliases: userDisplayName, userName.

sourcePolicy'auto' | 'knowledge_only' | 'request_only'

auto lets the Mind use its knowledge, web search, link analysis and attachments. knowledge_only is fail-closed: it retrieves the Mind's processed knowledge for the last user message, disables every internal and user tool, rejects attachments and media content parts (including tool results), and answers from persona only when nothing relevant is found (recorded in metadata.knowledgeRetrieval.status: "fallback"). A Mind saved with knowledge_only can never be downgraded per request. request_only is accepted for parity with Study runs and behaves like auto here.

citationMarkers'inline' | 'none'

inline leaves [[CITE:n]] markers (0-based indexes into metadata.ragCitations) after grounded claims in content. none strips them; metadata.ragCitations still lists the sources.

parallel_tool_callsboolean

Accepted for OpenAI compatibility. Advisory only: the runtime does not currently constrain how many tool calls a turn may contain.

participantsstring[]

Names (at most 200 characters each) of other participants when the Mind is one voice in a wider conversation. When non-empty the Mind answers in multi-participant mode instead of 1:1 interview mode.

Response

Reply generated. application/json for responseMode: "sync" (default); text/event-stream for responseMode: "stream", where the result frame carries the identical MindCompletionResponse payload and failures after opening the stream (including 401/403/404/409/429) are reported as an error frame followed by done. Body size/shape failures return HTTP 400/413 before streaming.

messageIdstring required

Opaque per-call ID (msg_ + 32 hex chars). Nothing is persisted; use it for your own correlation.

contentstring required

The Mind's reply. A JSON string when response_format was json_schema/json_object; empty when the turn ended in tool_calls or an image-only result.

Changes

No recorded changes to this operation across all 1 revision of this API.