Skip to main content
POST
OpenAI Chat Completion

Authorizations

Authorization
string
header
required

Bearer authentication header of the form Bearer <token>, where <token> is your auth token.

Headers

x-space-id
string

Space ID to run the completion in. Used as a fallback when space_id is not set in the request body.

Body

application/json
messages
object[]
required

Ordered chat messages that make up the conversation history. Always include the user’s latest turn; prepend prior turns when you want additional context.

Minimum array length: 1
space_id
required

Unique identifier of the space the completion should be run in.

Required string length: 2 - 6
model
string | null

Use this in the API call to specify the model to use for the completion request. Is generally the model ID from the LLM provider (e.g., "gpt-4o", "o1").

imageGenerationModel
enum<string>

User-selected image generation model id. Overrides the workspace default when present. Validated server-side against the AI_ENABLED_IMAGE_MODELS feature flag.

Available options:
gemini-2.5-flash-image,
gemini-3-pro-image,
gemini-3.1-flash-image,
imagen,
imagen-fast,
gpt-image-2,
gpt-image-2.5-sunburst,
flux-1-1-pro-ultra,
flux-1-kontext-pro,
flux-2-pro,
gemini-3-pro-image-preview,
gemini-3.1-flash-image-preview
temperature
number

Sampling temperature. Higher values make responses more adventurous; lower values keep them conservative.

top_p
number

Nucleus sampling parameter. Use this instead of temperature when you want to strictly cap how much of the probability mass is considered.

agentId
string<uuid> | null

Unique ID of the agent to use for the completion request. Used to load the agent's full configuration (system prompt, knowledge sources, etc.). NB: Agent must already be created in the database and available for the space.

agentPublished
boolean

Which version of the agent to use: true (default) = published version, false = draft. Useful to test an agent that has not been published yet.

voiceId
string<uuid> | null

UUID of the Voice to use for the completion request. NB: Voice must already be created in the database and available for the space.

taskId
string<uuid> | null

ID of the Task to use for the completion request. Used to tie the completion back to a workflow step or scheduled job. NB: Task must already be created in the database and available for the space.

capabilities
object

Provide an object of capabilities to enable the LLM perform specific tasks better (e.g., web search, internal KB, canvas, etc.).

attachmentIds
string<uuid>[]

Array of asset IDs (files, snippets, etc.) that should be injected into the completion request as supporting context.

contentIds
string<uuid>[]

Array of Content document IDs to include in the RAG context. Used to pass relevant document IDs so their content is included as additional background information for the completion request.

folderIds
string<uuid>[]

Array of Folder IDs to include in the RAG context. When provided, the LLM will use assets/documents within these folders as additional background information for the completion request.

toolOptions
object

User preferences for AI behavior including language, audience, and image generation style. These options are injected into the system prompt.

toolGroups
object[]

Grouped tool configurations keyed by provider context (nuwacom, paragon integration type, or MCP client). Backend expands these groups into per-tool configs.

skillIds
string<uuid>[]

Skill IDs explicitly selected by the user from the skills dropdown. When present without an agent, only these skills are loaded.

workflowContext
object
stream
boolean

When true the API sends partial chunks as the model generates them (ideal for typing indicators). Set to false to receive a single response payload.

parent_message_id
number | null

Internal reference to the last assistant message in the thread. Include this when you need the completion to “continue” an earlier answer.

conversation_id
string<uuid> | null

Conversation UUID tying multiple completions together. Provide it to append to an existing thread; leave empty to start fresh.

Response

200

Successful completion response (see OpenAI Completions Object)