Clinical Workflows (1.0.0)

Retrieve all clinical notes for a client, filtered by note type. Use this to read back documentation that has been submitted to Kana — useful for syncing notes back into your EHR, building client care timelines, or auditing what clinical documentation exists for a given client.

Use this when:

• You want to pull client notes from Kana into your own system
• You are building a client care summary in your application
• You need to verify that notes were successfully received and stored

Request fields:

• record_type_id (required): The note type identifier.
• client_user_id (required): The client's Kana user ID.

Returns: Array of clinical note objects (HTTP 200). HTTP 204 if none found.

Retrieve the 10 most recent clinical note history entries for a client by note type. Use this to build a longitudinal view of a client's documentation, track how notes have evolved, or sync historical records into your system.

Use this when:

• Building a timeline of a client's clinical documentation in your application
• Checking the note revision history before a session
• Auditing changes to clinical notes over time

Request fields:

• record_type_id (required): The note type identifier.
• client_user_id (required): The client's Kana user ID.

Returns: Array of up to 10 note history records (HTTP 200). HTTP 204 if no history found.

Submit clinical notes — including session summaries, psychotherapy notes, and other structured documentation — into Kana's clinical data platform. Notes can include file attachments (e.g. session recordings, documents) which Kana automatically processes to extract and incorporate text content. Once submitted, Kana triggers AI-powered de-identification and clinical documentation workflows in the background.

Use this when:

• Your system captures session notes and you want Kana's AI to process them
• You are sending clinical documentation from an EHR into Kana for AI augmentation
• You want to attach documents (transcripts, referrals) to a client's note record

Typical workflow:

1. Submit clinical notes via this endpoint (with optional file attachments)
2. Kana processes and de-identifies the note asynchronously
3. Trigger SOAP note generation via the AI SOAP trigger endpoint
4. Retrieve the AI-generated SOAP note for clinician review

Request (multipart/form-data):

• metadata (required): JSON string containing:
  • id (optional): ID of an existing note to update; omit to create.
  • data (required): Note content fields.
  • record_type (required): Note type identifier.
  • client_user_id (required): Client's Kana user ID.
  • therapist_user_id (required): Therapist's Kana user ID.
  • therapist_client_id (required): Therapist-client relationship ID.
  • therapist_session_id (optional): Associated session ID.
• files (optional): File attachments (transcripts, documents, etc.).

Returns: ID of the created or updated note record (HTTP 201).

Soft-delete a therapist note. The record is retained for audit purposes but will no longer appear in active queries or be included in AI processing.

Path parameter:

• id (required): Primary key of the note to delete.

Returns: ID of the deleted note (HTTP 204), or HTTP 404 if not found.

Retrieve all SOAP notes for a client, filtered by note type. Returns both AI-generated drafts and therapist-approved notes, allowing partner systems to read back structured clinical documentation from Kana and sync it into their own EHR or reporting systems.

Use this when:

• You want to pull completed SOAP notes back into your system after Kana generates them
• You need to display structured clinical notes in your own interface
• You are auditing or archiving session documentation

Request fields:

• record_type_id (required): The note type identifier.
• client_user_id (required): The client's Kana user ID.

Returns: Array of SOAP note objects with note content, approval status, signature, and session ID (HTTP 200). HTTP 204 if no notes found.

Retrieve the 10 most recent SOAP note history entries for a client by note type. Useful for tracking how a client's clinical documentation has evolved over time and for pre-session preparation.

Use this when:

• Building a longitudinal view of a client's clinical progress
• Populating a pre-session brief with historical notes in your EHR
• Auditing the history of note revisions for a client

Request fields:

• record_type_id (required): The note type identifier.
• client_user_id (required): The client's Kana user ID.

Returns: Array of up to 10 SOAP note history records (HTTP 200). HTTP 204 if no history found.

Returns a clinically relevant snapshot of SOAP note history: the latest draft plus all approved notes from the most recent 30 entries. This is more useful than full history when you want approved documentation without noise from unapproved revisions.

Use this when:

• Displaying a clean audit trail of approved session notes in your EHR
• Fetching the latest AI-generated note plus confirmed historical records
• Building a session preparation view with recent approved notes

Request fields:

• record_type_id (required): The note type identifier.
• client_user_id (required): The client's Kana user ID.

Returns: Array of SOAP note history objects with note content, approval status, signature, and session timestamps (HTTP 200). HTTP 204 if none found.

Submit or update a structured SOAP (Subjective, Objective, Assessment, Plan) note for a therapy session. Partner systems — such as EHRs or telehealth platforms — can push session notes directly into Kana. When a therapist approves the note (is_approved=true), Kana automatically triggers AI-powered clinical documentation workflows including de-identification and audit trail updates.

Use this when:

• Your system captures session notes and wants to sync them into Kana
• You want Kana to store clinician-reviewed SOAP notes for a client
• You need to update a previously submitted note after therapist review

Request fields:

• id (optional): ID of an existing note to update; omit to create a new one.
• data (required): SOAP note content fields.
• sender_role (required): "ml" (system-generated) or "therapist" (clinician-reviewed).
• record_type (required): Note type identifier.
• client_user_id (required): Client's Kana user ID.
• therapist_user_id (required): Therapist's Kana user ID.
• therapist_client_id (required): Therapist-client relationship ID.
• is_approved (required): Set to true to trigger downstream clinical workflows.
• signature (optional): Therapist digital signature (Base64-encoded).
• therapist_session_id (optional): Associated session ID.

Returns: ID of the created or updated SOAP note record (HTTP 201).

Trigger Kana's AI to automatically generate a structured SOAP note for a therapy session. Kana synthesizes all available clinical context — session transcripts, prior notes, client history, and diagnosis — to produce a clinician-ready SOAP (Subjective, Objective, Assessment, Plan) note. The request returns immediately and generation runs asynchronously in the background.

Use this when:

• You want Kana to auto-generate a SOAP note after a session completes
• Your clinicians want AI-drafted notes to review and approve rather than writing from scratch
• You are integrating session-end workflows where documentation is triggered automatically

Typical workflow:

1. Session ends in your system
2. Call this endpoint with the session and client identifiers
3. Kana generates the SOAP note asynchronously
4. Clinician reviews and approves via the Kana therapist app
5. Retrieve the approved note via the SOAP notes retrieval endpoint

Request fields:

• client_user_id (required): Client's Kana user ID.
• therapist_user_id (required): Therapist's Kana user ID.
• therapist_client_id (required): Therapist-client relationship ID.
• record_type (required): Note type identifier.
• therapist_session_id (optional): Associated session ID.

Returns: {"detail": "Processing"} immediately (HTTP 200). Generation continues in the background.