Sessions

Trigger agent generation

Triggers the agent to generate a response based on the current conversation. Background by default: returns 202 Accepted immediately while the generation runs. Pass ?wait=true to block and receive the assistant reply (or a requires_action status if the agent needs client tool outputs) in the response.

post/v1/projects/{project_id}/sessions/{session_id}/generate

Request

  • Base URL: https://api.naturali.ai
  • URL: https://api.naturali.ai/v1/projects/{project_id}/sessions/{session_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

session_idstring required
Example:sess_V1StGXR8Z5jdHi6B

Session public ID

Query parameters

waitboolean

When omitted or false (default), 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

modelstring

Optional model override

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. Keys are never case-converted — they round-trip exactly as sent. An invalid or colliding key is rejected with 400 INVALID_TOOL_CONTEXT_KEY.

Example request

{
  "model": "gpt-4o"
}

Response

Agent reply 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.