Conversations

Create a conversation

Creates a new conversation in the project named in the path.

post/v1/projects/{project_id}/conversations

Request

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

Request body

status'open' | 'closed'

Initial conversation status

namestring nullable

Optional name for the conversation

actor_idstring nullable

Actor ID to associate with this conversation

retrieval'embed' | 'none' | 'null' nullable

Whether this conversation's turns are embedded for vector retrieval. Turns are stored and chunked either way, so none leaves them readable and reachable by full-text search without paying for an embedding. null (the default) inherits the project's default_conversation_retrieval.

Example request

{
  "actor_id": "actor_V1StGXR8Z5jdHi6B"
}

Response

Conversation created

idstring

Conversation ID

project_idstring

Project ID

namestring nullable

Optional human-readable name for the conversation.

status'open' | 'closed'

Conversation status

created_atstring date-time

Creation timestamp

updated_atstring date-time

Last update timestamp

actor_idstring nullable

Actor ID associated with this conversation

retrieval'embed' | 'none' | 'null' nullable

Whether this conversation's turns are embedded for vector retrieval. Turns are stored and chunked either way, so none leaves them readable and reachable by full-text search without paying for an embedding. null (the default) inherits the project's default_conversation_retrieval.

Example response

{
  "id": "conv_V1StGXR8Z5jdHi6B",
  "project_id": "proj_V1StGXR8Z5jdHi6B",
  "status": "open",
  "actor_id": "actor_V1StGXR8Z5jdHi6B"
}

Changes

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