Conversations

Generate the next message in a conversation

Generates the next message using the specified actor's linked agent or chat. Background by default: returns 202 Accepted immediately and the reply lands as a new ConversationMessage when it completes — poll GET /v1/projects/{project_id}/conversations/{conversation_id}/messages for it. Pass ?wait=true to block and receive the result inline. On completed, the reply is persisted as a new ConversationMessage authored by that actor. On requires_action, nothing is persisted; the caller must submit tool outputs via the Agents module and re-invoke generate — so a flow using client tools should pass ?wait=true.

post/v1/projects/{project_id}/conversations/{conversation_id}/generate

Request

  • Base URL: https://api.naturali.ai
  • URL: https://api.naturali.ai/v1/projects/{project_id}/conversations/{conversation_id}/generate
  • Auth: one of:
    • HTTP bearer
    • OAuth 2 (authorization code, authorization URL https://api.naturali.ai/authorize, token URL https://api.naturali.ai/token, scopes: mcp:access)

Path parameters

conversation_idstring required

Query parameters

waitboolean

When omitted or false (default), the generation runs in the background and 202 Accepted is returned immediately. Pass true to block until the generation settles and receive the result. An MCP tool call always waits.

Request body

agent_idstring required

ID of the agent that will produce the next message.

modelstring

Optional model override.

streamboolean

If true, stream tokens via SSE. NOT IMPLEMENTED in v1 — returns 501.

tool_contextobject nullable

Key-value pairs forwarded as X-Naturali-Context-<key> headers on every http and mcp tool call in this generation. The header name is the deployment's configured context prefix (X-Naturali-Context- by default) plus the key verbatim — no character is re-cased and keys are never case-converted, so they round-trip exactly as sent. An invalid or colliding key is rejected with 400 INVALID_TOOL_CONTEXT_KEY.

Response

Generation completed or requires action (only when ?wait=true)

OR

Example response

{
  "content": "Hello! How can I help you today?",
  "message": {
    "document_id": "doc_V1StGXR8Z5jdHi6B",
    "role": "user",
    "actor_id": "actor_V1StGXR8Z5jdHi6B",
    "agent_id": "agent_V1StGXR8Z5jdHi6B",
    "metadata": {
      "author": "John",
      "revision": 2
    },
    "idempotency_key": "wamid.HBgLNTUxMTk4..."
  },
  "generation_id": "gen_V1StGXR8Z5jdHi6B",
  "trace_id": "trace_V1StGXR8Z5jdHi6B",
  "model": "gpt-4o"
}

Changes

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