Chat & AI Agents (1.0.0)

Start a new AI-powered conversation session for a client. Sessions are the container for all messages exchanged between a client and Kana's AI companion. Each session maintains clinical context and generates a session summary when closed.

Use this when:

• A client starts a new interaction with Kana's AI companion
• Initiating a clinical conversation that should be tracked and summarized
• Building an integration where each interaction maps to a distinct session

Returns: sessionid of the new session (HTTP 201). Pass this sessionid when sending messages via the conversation message endpoint.

Start a new AI-powered conversation session for a client. Sessions are the container for all messages exchanged between a client and Kana's AI companion. Each session maintains clinical context and generates a session summary when closed.

Use this when:

• A client starts a new interaction with Kana's AI companion
• Initiating a clinical conversation that should be tracked and summarized
• Building an integration where each interaction maps to a distinct session

Returns: sessionid of the new session (HTTP 201). Pass this sessionid when sending messages via the conversation message endpoint.

Close an active AI conversation session for a client. When closed, Kana automatically generates an AI session summary and title from the conversation history, which is stored and can be used for clinical review or follow-up.

Use this when:

• A client ends their interaction with Kana's AI companion
• You want to finalize a session and trigger AI summarization
• Closing out a clinical conversation to prepare for the next one

PUT /{id}/ — Marks the session closed and triggers AI session summary generation.

Returns: The closed sessionid (HTTP 200).

Retrieve all AI conversation sessions for a client, ordered by most recent first. Each session contains a title (AI-generated summary) and timestamps. Use this to display a client's full conversation history or build a session timeline in your application.

Use this when:

• Displaying a client's session history in your interface
• Auditing all AI interactions for a client
• Fetching session titles and dates for a care timeline view

GET /{userid}/ — Returns all sessions for the client, sorted by most recent first.

Retrieve all AI conversation sessions for a client, ordered by most recent first. Each session contains a title (AI-generated summary) and timestamps. Use this to display a client's full conversation history or build a session timeline in your application.

Use this when:

• Displaying a client's session history in your interface
• Auditing all AI interactions for a client
• Fetching session titles and dates for a care timeline view

GET /{userid}/ — Returns all sessions for the client, sorted by most recent first.

Send or update a message in a client-therapist chat session. Kana automatically delivers real-time push notifications to the recipient — an FCM push to the client's device when the AI responds, or a web push to the therapist when the client sends a query.

Use this when:

• Building an in-app messaging channel between clients and therapists
• Integrating clinical chat into your telehealth platform
• Storing conversation content for clinical documentation and audit

POST — Send a new message (or update an existing one). Triggers real-time notifications automatically. PUT /{interactionid}/ — Update message content or submit like/dislike feedback. GET / GET /{interactionid}/ — Retrieve messages for display.

Returns: interactionid (HTTP 201 for create, HTTP 200 for update).

Send or update a message in a client-therapist chat session. Kana automatically delivers real-time push notifications to the recipient — an FCM push to the client's device when the AI responds, or a web push to the therapist when the client sends a query.

Use this when:

• Building an in-app messaging channel between clients and therapists
• Integrating clinical chat into your telehealth platform
• Storing conversation content for clinical documentation and audit

POST — Send a new message (or update an existing one). Triggers real-time notifications automatically. PUT /{interactionid}/ — Update message content or submit like/dislike feedback. GET / GET /{interactionid}/ — Retrieve messages for display.

Returns: interactionid (HTTP 201 for create, HTTP 200 for update).

Send or update a message in a client-therapist chat session. Kana automatically delivers real-time push notifications to the recipient — an FCM push to the client's device when the AI responds, or a web push to the therapist when the client sends a query.

Use this when:

• Building an in-app messaging channel between clients and therapists
• Integrating clinical chat into your telehealth platform
• Storing conversation content for clinical documentation and audit

POST — Send a new message (or update an existing one). Triggers real-time notifications automatically. PUT /{interactionid}/ — Update message content or submit like/dislike feedback. GET / GET /{interactionid}/ — Retrieve messages for display.

Returns: interactionid (HTTP 201 for create, HTTP 200 for update).

Send or update a message in a client-therapist chat session. Kana automatically delivers real-time push notifications to the recipient — an FCM push to the client's device when the AI responds, or a web push to the therapist when the client sends a query.

Use this when:

• Building an in-app messaging channel between clients and therapists
• Integrating clinical chat into your telehealth platform
• Storing conversation content for clinical documentation and audit

POST — Send a new message (or update an existing one). Triggers real-time notifications automatically. PUT /{interactionid}/ — Update message content or submit like/dislike feedback. GET / GET /{interactionid}/ — Retrieve messages for display.

Returns: interactionid (HTTP 201 for create, HTTP 200 for update).

Retrieves video content URLs grouped by topic and content category. Content is filtered by user role and organized into a nested structure.

Used when:

• Loading the content library for a client or therapist
• Displaying educational video resources

Input:

• role (query parameter, optional): User role filter, defaults to "User"

Returns: Content grouped by content_group and topic_group

Common errors:

• 200: Returns empty groups if no content matches

Send a message within an active AI conversation session. Each message represents one turn in the conversation — either from the client or from Kana's AI. Messages are the raw conversation data that Kana uses to generate session summaries and clinical insights.

Use this when:

• Logging client or AI messages in a session for clinical audit purposes
• Storing conversation content that will feed into AI session summaries
• Building an integration that records clinical conversations in Kana

POST — Send a new message (omit id) or update an existing one (include id). PUT /{id}/ — Submit feedback (like/dislike) on an AI response.

Returns: Message id (HTTP 201 for new, HTTP 200 for update).

Send a message within an active AI conversation session. Each message represents one turn in the conversation — either from the client or from Kana's AI. Messages are the raw conversation data that Kana uses to generate session summaries and clinical insights.

Use this when:

• Logging client or AI messages in a session for clinical audit purposes
• Storing conversation content that will feed into AI session summaries
• Building an integration that records clinical conversations in Kana

POST — Send a new message (omit id) or update an existing one (include id). PUT /{id}/ — Submit feedback (like/dislike) on an AI response.

Returns: Message id (HTTP 201 for new, HTTP 200 for update).

Send a message within an active AI conversation session. Each message represents one turn in the conversation — either from the client or from Kana's AI. Messages are the raw conversation data that Kana uses to generate session summaries and clinical insights.

Use this when:

• Logging client or AI messages in a session for clinical audit purposes
• Storing conversation content that will feed into AI session summaries
• Building an integration that records clinical conversations in Kana

POST — Send a new message (omit id) or update an existing one (include id). PUT /{id}/ — Submit feedback (like/dislike) on an AI response.

Returns: Message id (HTTP 201 for new, HTTP 200 for update).

Send a message within an active AI conversation session. Each message represents one turn in the conversation — either from the client or from Kana's AI. Messages are the raw conversation data that Kana uses to generate session summaries and clinical insights.

Use this when:

• Logging client or AI messages in a session for clinical audit purposes
• Storing conversation content that will feed into AI session summaries
• Building an integration that records clinical conversations in Kana

POST — Send a new message (omit id) or update an existing one (include id). PUT /{id}/ — Submit feedback (like/dislike) on an AI response.

Returns: Message id (HTTP 201 for new, HTTP 200 for update).

Send a message within an active AI conversation session. Each message represents one turn in the conversation — either from the client or from Kana's AI. Messages are the raw conversation data that Kana uses to generate session summaries and clinical insights.

Use this when:

• Logging client or AI messages in a session for clinical audit purposes
• Storing conversation content that will feed into AI session summaries
• Building an integration that records clinical conversations in Kana

POST — Send a new message (omit id) or update an existing one (include id). PUT /{id}/ — Submit feedback (like/dislike) on an AI response.

Returns: Message id (HTTP 201 for new, HTTP 200 for update).

Retrieve the full chronological message history for a specific conversation session. Returns all client and AI messages in order — useful for displaying session transcripts, clinical review, or feeding session content into downstream workflows.

Use this when:

• Displaying the full conversation transcript for a session in your application
• Reviewing AI-client interactions for quality or safety monitoring
• Extracting session content for clinical documentation or reporting

GET /{sessionid}/ — Returns all messages in chronological order. HTTP 204 if no messages exist. GET /{sessionid}/count/ — Returns the message count for the session.

Retrieve the full chronological message history for a specific conversation session. Returns all client and AI messages in order — useful for displaying session transcripts, clinical review, or feeding session content into downstream workflows.

Use this when:

• Displaying the full conversation transcript for a session in your application
• Reviewing AI-client interactions for quality or safety monitoring
• Extracting session content for clinical documentation or reporting

GET /{sessionid}/ — Returns all messages in chronological order. HTTP 204 if no messages exist. GET /{sessionid}/count/ — Returns the message count for the session.

Retrieve the full chronological message history for a specific conversation session. Returns all client and AI messages in order — useful for displaying session transcripts, clinical review, or feeding session content into downstream workflows.

Use this when:

• Displaying the full conversation transcript for a session in your application
• Reviewing AI-client interactions for quality or safety monitoring
• Extracting session content for clinical documentation or reporting

GET /{sessionid}/ — Returns all messages in chronological order. HTTP 204 if no messages exist. GET /{sessionid}/count/ — Returns the message count for the session.

Retrieve all conversation messages across all sessions for a specific client. Returns the complete message history in chronological order — useful for building a full longitudinal view of a client's AI interactions or for clinical audit.

Use this when:

• Auditing all AI conversations for a client across sessions
• Building a complete interaction history for clinical review

GET /{userid}/ — Returns all messages for the client in chronological order. HTTP 204 if no messages exist.

Retrieve all conversation messages across all sessions for a specific client. Returns the complete message history in chronological order — useful for building a full longitudinal view of a client's AI interactions or for clinical audit.

Use this when:

• Auditing all AI conversations for a client across sessions
• Building a complete interaction history for clinical review

GET /{userid}/ — Returns all messages for the client in chronological order. HTTP 204 if no messages exist.

Queries the GraphRAG knowledge index for DSM diagnosis-related information. Uses graph-based retrieval augmented generation to provide clinically relevant answers.

Used when:

• Therapist needs DSM diagnostic criteria or guidance
• Looking up differential diagnosis information
• Clinical decision support queries

Input:

• query_text (required): The clinical query
• method (optional): Query method to use
• default_response_type (optional): Response format preference

Returns: GraphRagResponse with the answer and any error messages

Common errors:

• 500: GraphRAG service not initialized or query failure

Generates structured therapy goals from a treatment plan using AI. Supports two modes: 'llm' (default) uses a language model for direct generation, 'agent' uses an AI agent workflow for more detailed goal creation.

Used when:

• Therapist wants to auto-generate goals from a treatment plan
• Creating structured, trackable goals from clinical documentation

Input:

• treatment_plan (required): Treatment plan content as JSON
• mode (optional): 'llm' (default) or 'agent'

Returns: Generated goals structured for the Kana goal tracking system

Common errors:

• 500: AI service error during goal generation

Send a clinical question to Kana's AI assistant powered by the DSM knowledge base. Kana synthesizes the client's full clinical context — diagnosis, treatment history, session notes, mood logs, and goals — to provide clinically grounded, real-time streaming responses. Supports file attachments for in-context document analysis.

Use this when:

• A clinician wants AI-assisted answers to clinical questions during or between sessions
• You want to query Kana's AI with a DSM-informed question about a specific client
• You are building a clinical decision support feature in your application

Input:

• data (required, form field): JSON string with user_query, session_id, user_id, model_provider (optional)
• files (optional): PDF or document attachments for context-aware responses

Returns: Streaming text response (Server-Sent Events format)

Send a message to Kana's AI mental health companion on behalf of a client. The AI maintains full conversational context across the session and responds with empathetic, evidence-based mental health support grounded in the client's clinical history, goals, mood trends, and past interactions.

Use this when:

• You are building a patient-facing mental health companion experience
• A client is engaging with Kana's AI between therapy sessions
• You want Kana's AI to provide context-aware support based on the client's clinical data

Input:

• user_query (required): The client's message or question
• session_id (required): Active session ID
• user_id (required): Client's Kana user ID
• model_provider (optional): AI model to use (default: groq)

Returns: {"response": "<AI response text>"}

Submit client clinical data and receive AI-powered recommendations for Measurement-Based Care (MBC) assessment tools. Kana's AI analyzes the clinical presentation and recommends the most appropriate standardized instruments (e.g. PHQ-9, GAD-7, PCL-5) across relevant clinical domains, along with safety flag indicators.

Use this when:

• You want Kana to recommend which clinical assessments to assign to a client
• Building intake or assessment workflows that auto-select the right screening tools
• You want AI-driven MBC tool selection based on a client's clinical presentation

Input:

• client_data (required): Clinical summary or structured data describing the client's presentation, symptoms, and history

Returns: Recommended MBC tools with clinical domains, tool names, safety flags, and a recommendation summary

Execute an AI-powered clinical documentation task using Kana's large language model pipeline. Provide clinical data and a task type, and Kana returns structured, AI-generated clinical output — such as progress notes, safety plans, treatment summaries, or risk assessments.

Use this when:

• You want to auto-generate clinical documentation from raw session or client data
• Building AI-assisted note writing, safety planning, or treatment summary workflows
• You need Kana's AI to process clinical data and return structured documentation

Supported task types include:

• clinical_notes: Generate structured progress notes from session data
• safety_plan: Generate a client safety plan
• Other task types as configured in your Kana deployment

Input:

• task_type (required): The documentation task to execute
• clinical_data (required): Raw clinical content (notes, transcript, client data)
• user_id (optional): Client's Kana user ID for personalized context
• additional_params (optional): Extra parameters for the task

Returns: AI-generated clinical documentation output for the specified task