Clinical Documentation Workflow API

The Clinical Documentation Workflow API provides a comprehensive solution for managing patient-doctor conversation transcriptions, AI-powered clinical note extraction, and structured clinical documentation.

Workflow Overview

The clinical documentation workflow consists of three main stages:

Create Transcription - Store raw audio-to-text transcription from patient-doctor conversations
Create Thread & Execute Runs - Process transcriptions with AI to extract clinical information
Update Clinical Notes - Store and manage AI-generated clinical documentation

1. Create Transcription

Endpoint

POST https://{your_api_url}/v1/transcriptions/create

Purpose

Creates a new transcription record for audio-to-text conversion from patient-doctor conversations. This is the first step in the clinical documentation workflow - stores the raw transcription before AI processing.

Required headers

Content-Type: application/json
Authorization: Bearer YOUR_API_KEY
x-doctor: dr_123

Optional headers

x-patient: pt_456

Request body

{
  "duration_seconds": 180,
  "original_transcript": "The patient is a 45-year-old male presenting with chest pain radiating to left arm for the past 2 hours. Pain started while climbing stairs. No previous cardiac history. Vital signs: BP 140/90, HR 88, RR 18, O2 sat 98% on room air.",
  "language_used": "en"
}

Request fields

Field	Type	Required	Description
`duration_seconds`	number	Yes	Duration of the recording in seconds (min: 0)
`original_transcript`	string	Yes	The transcribed text from the conversation
`language_used`	string	No	Language code (e.g., ‘en’, ‘es’, ‘fr’)

Success response (HTTP 201)

{
  "message": "Transcription created successfully",
  "transcription": {
    "id": "trans_abc123xyz",
    "user_id": "usr_123456789",
    "group_id": "grp_987654321",
    "duration_seconds": 180,
    "language_used": "en",
    "original_transcript": "The patient is a 45-year-old male...",
    "created_at": "2023-10-09T10:00:00.000Z",
    "updated_at": "2023-10-09T10:00:00.000Z"
  }
}

Example - Python

import requests

url = "https://{your_api_url}/v1/transcriptions/create"
headers = {
    "Authorization": "Bearer YOUR_TOKEN",
    "Content-Type": "application/json",
    "x-doctor": "dr_123",  # REQUIRED
    "x-patient": "pt_456"  # OPTIONAL
}

payload = {
    "duration_seconds": 180,
    "original_transcript": "The patient is a 45-year-old male presenting with chest pain...",
    "language_used": "en"
}

response = requests.post(url, json=payload, headers=headers)
result = response.json()

print(f"Transcription created: {result['transcription']['id']}")

Example - JavaScript

const axios = require('axios');

const url = 'https://{your_api_url}/v1/transcriptions/create';
const headers = {
  'Authorization': 'Bearer YOUR_TOKEN',
  'Content-Type': 'application/json',
  'x-doctor': 'dr_123',   // REQUIRED
  'x-patient': 'pt_456'   // OPTIONAL
};

const payload = {
  duration_seconds: 180,
  original_transcript: 'The patient is a 45-year-old male presenting with chest pain...',
  language_used: 'en'
};

axios.post(url, payload, { headers })
  .then(response => {
    console.log('Transcription created:', response.data.transcription.id);
  })
  .catch(error => {
    console.error('Error:', error.response?.data || error.message);
  });

2. Create Conversation Thread

Endpoint

POST https://{your_api_url}/v1/lang-graph/threads

Purpose

Creates a new conversation thread for AI-powered interactions (chat or clinical extraction). Initializes a stateful conversation session with the AI assistant. The thread maintains context across multiple interactions and is required before executing any conversation runs.

Required headers

Content-Type: application/json
Authorization: Bearer YOUR_API_KEY
x-doctor: dr_123

Optional headers

x-patient: pt_456

Request body

No request body required (empty POST).

{}

Success response (HTTP 201)

{
  "thread_id": "thread-abc123",
  "created_at": "2023-10-09T10:00:00.000Z",
  "status": "active"
}

Example - Python

import requests

url = "https://{your_api_url}/v1/lang-graph/threads"
headers = {
    "Authorization": "Bearer YOUR_TOKEN",
    "Content-Type": "application/json",
    "x-doctor": "dr_123",  # REQUIRED
    "x-patient": "pt_456"  # OPTIONAL
}

response = requests.post(url, json={}, headers=headers)
result = response.json()

print(f"Thread created: {result['thread_id']}")

Example - JavaScript

const axios = require('axios');

const url = 'https://{your_api_url}/v1/lang-graph/threads';
const headers = {
  'Authorization': 'Bearer YOUR_TOKEN',
  'Content-Type': 'application/json',
  'x-doctor': 'dr_123',   // REQUIRED
  'x-patient': 'pt_456'   // OPTIONAL
};

axios.post(url, {}, { headers })
  .then(response => {
    console.log('Thread created:', response.data.thread_id);
  })
  .catch(error => {
    console.error('Error:', error.response?.data || error.message);
  });

3. Execute Conversation Run

Endpoint

POST https://{your_api_url}/v1/lang-graph/threads/{threadId}/runs

Purpose

Executes a conversation run within an existing thread to process AI interactions. This is the core AI processing endpoint - sends messages to the AI assistant and initiates processing. Used for both real-time chat interactions and clinical note extraction from transcriptions. The run executes asynchronously and can be monitored via the join endpoint.

Required headers

Content-Type: application/json
Authorization: Bearer YOUR_API_KEY
x-doctor: dr_123

Optional headers

x-is-chat: true      (Boolean flag: true = chat/scribe, false = extraction)
x-patient: pt_456    (Patient identifier for tracking and auditing)

Path parameters

Parameter	Type	Required	Description
`threadId`	string	Yes	The thread identifier to execute the run in

Request body

{
  "input": {
    "messages": [
      {
        "role": "user",
        "content": "Hello, how can you help me today?"
      }
    ]
  },
  "config": {
    "configurable": {
      "thread_id": "thread-abc123"
    }
  }
}

Request fields

Field	Type	Required	Description
`input.messages`	array	Yes	Array of conversation messages
`input.messages[].role`	string	Yes	Role of message sender (user, assistant, system)
`input.messages[].content`	string	Yes	Message content
`config.configurable.thread_id`	string	Yes	Thread identifier for this run

Success response (HTTP 201)

{
  "run_id": "run-xyz789",
  "thread_id": "thread-abc123",
  "status": "pending",
  "created_at": "2023-10-09T10:00:00.000Z"
}

Example - Clinical extraction

import requests

base_headers = {
    "Authorization": "Bearer YOUR_TOKEN",
    "Content-Type": "application/json",
    "x-doctor": "dr_123",  # REQUIRED
    "x-patient": "pt_456"  # OPTIONAL
}

# First, create a thread
thread_url = "https://{your_api_url}/v1/lang-graph/threads"
thread_response = requests.post(thread_url, json={}, headers=base_headers)
thread_id = thread_response.json()['thread_id']

# Execute a run for clinical extraction (x-is-chat: false)
run_url = f"https://{your_api_url}/v1/lang-graph/threads/{thread_id}/runs"
run_headers = {
    **base_headers,
    "x-is-chat": "false"  # false = clinical extraction
}

payload = {
    "input": {
        "messages": [
            {
                "role": "user",
                "content": "Extract clinical information from: Patient reports chest pain radiating to left arm..."
            }
        ]
    },
    "config": {
        "configurable": {
            "thread_id": thread_id
        }
    }
}

response = requests.post(run_url, json=payload, headers=run_headers)
result = response.json()

print(f"Run created: {result['run_id']}")
print(f"Status: {result['status']}")

Example - Chat interaction

const axios = require('axios');

// Create thread first
const threadUrl = 'https://{your_api_url}/v1/lang-graph/threads';

const baseHeaders = {
  'Authorization': 'Bearer YOUR_TOKEN',
  'Content-Type': 'application/json',
  'x-doctor': 'dr_123',   // REQUIRED
  'x-patient': 'pt_456'   // OPTIONAL
};

const threadResponse = await axios.post(threadUrl, {}, { headers: baseHeaders });
const threadId = threadResponse.data.thread_id;

// Execute a chat run (x-is-chat: true)
const runUrl = `https://{your_api_url}/v1/lang-graph/threads/${threadId}/runs`;
const runHeaders = {
  ...baseHeaders,
  'x-is-chat': 'true'  // true = chat/scribe mode
};

const payload = {
  input: {
    messages: [
      {
        role: 'user',
        content: 'Hello, how can you help me today?'
      }
    ]
  },
  config: {
    configurable: {
      thread_id: threadId
    }
  }
};

axios.post(runUrl, payload, { headers: runHeaders })
  .then(response => {
    console.log('Run created:', response.data.run_id);
    console.log('Status:', response.data.status);
  })
  .catch(error => {
    console.error('Error:', error.response?.data || error.message);
  });

4. Update Clinical Note

Endpoint

PATCH https://{your_api_url}/v1/clinical-notes/{id}

Purpose

Updates an existing clinical note with AI-generated content, feedback, or metadata. Used to store AI-generated clinical documentation, link to conversation threads, and capture user feedback for quality improvement.

Required headers

Content-Type: application/json
Authorization: Bearer YOUR_API_KEY
x-doctor: dr_123

Optional headers

x-patient: pt_456

Path parameters

Parameter	Type	Required	Description
`id`	string (UUID)	Yes	The clinical note UUID

Request body

All fields are optional - update only what’s needed:

{
  "template": "SOAP",
  "ai_generated_content": {
    "subjective": "Patient reports chest pain radiating to left arm",
    "objective": "BP 140/90, HR 88, RR 18, O2 sat 98% on RA",
    "assessment": "R/O myocardial infarction",
    "plan": "Admit to CCU, serial troponins, cardiology consult"
  },
  "feedback": "Well structured note",
  "report_thread_id": "thread_xyz789",
  "report_run_id": ["run_001", "run_002"]
}

Request fields

Field	Type	Required	Description
`template`	string	No	Clinical note format (SOAP, BIRP, DAP, GIRP)
`ai_generated_content`	object	No	Structured clinical data (schema varies by template)
`feedback`	string	No	User comments or feedback on the note
`report_thread_id`	string	No	Thread ID that generated this content
`report_run_id`	array	No	Array of run IDs involved in generating content

Success response (HTTP 200)

{
  "id": "note_def456ghi",
  "user_id": "usr_123456789",
  "group_id": "grp_987654321",
  "transcription_id": "trans_abc123xyz",
  "template": "SOAP",
  "ai_generated_content": {
    "subjective": "Patient reports chest pain radiating to left arm",
    "objective": "BP 140/90, HR 88, RR 18, O2 sat 98% on RA",
    "assessment": "R/O myocardial infarction",
    "plan": "Admit to CCU, serial troponins, cardiology consult"
  },
  "feedback": "Well structured note",
  "report_thread_id": "thread_xyz789",
  "report_run_id": ["run_001", "run_002"],
  "created_at": "2023-10-09T10:00:00.000Z",
  "updated_at": "2023-10-09T10:05:00.000Z"
}

Example - Python

import requests

note_id = "note_def456ghi"
url = f"https://{your_api_url}/v1/clinical-notes/{note_id}"
headers = {
    "Authorization": "Bearer YOUR_TOKEN",
    "Content-Type": "application/json",
    "x-doctor": "dr_123",  # REQUIRED
    "x-patient": "pt_456"  # OPTIONAL
}

payload = {
    "template": "SOAP",
    "ai_generated_content": {
        "subjective": "Patient reports chest pain radiating to left arm",
        "objective": "BP 140/90, HR 88, RR 18, O2 sat 98% on RA",
        "assessment": "R/O myocardial infarction",
        "plan": "Admit to CCU, serial troponins, cardiology consult"
    },
    "feedback": "Well structured note",
    "report_thread_id": "thread_xyz789",
    "report_run_id": ["run_001", "run_002"]
}

response = requests.patch(url, json=payload, headers=headers)
result = response.json()

print(f"Clinical note updated: {result['id']}")
print(f"Template: {result['template']}")

Example - JavaScript

const axios = require('axios');

const noteId = 'note_def456ghi';
const url = `https://{your_api_url}/v1/clinical-notes/${noteId}`;
const headers = {
  'Authorization': 'Bearer YOUR_TOKEN',
  'Content-Type': 'application/json',
  'x-doctor': 'dr_123',   // REQUIRED
  'x-patient': 'pt_456'   // OPTIONAL
};

const payload = {
  template: 'SOAP',
  ai_generated_content: {
    subjective: 'Patient reports chest pain radiating to left arm',
    objective: 'BP 140/90, HR 88, RR 18, O2 sat 98% on RA',
    assessment: 'R/O myocardial infarction',
    plan: 'Admit to CCU, serial troponins, cardiology consult'
  },
  feedback: 'Well structured note',
  report_thread_id: 'thread_xyz789',
  report_run_id: ['run_001', 'run_002']
};

axios.patch(url, payload, { headers })
  .then(response => {
    console.log('Clinical note updated:', response.data.id);
    console.log('Template:', response.data.template);
  })
  .catch(error => {
    console.error('Error:', error.response?.data || error.message);
  });

Complete Workflow Example

Here’s a complete example of the entire clinical documentation workflow:

Python - Complete workflow

import requests

BASE_URL = "https://{your_api_url}"
headers = {
    "Authorization": "Bearer YOUR_TOKEN",
    "Content-Type": "application/json",
    "x-doctor": "dr_123",  # REQUIRED
    "x-patient": "pt_456"  # OPTIONAL
}

# Step 1: Create transcription
transcription_data = {
    "duration_seconds": 180,
    "original_transcript": "The patient is a 45-year-old male presenting with chest pain...",
    "language_used": "en"
}

transcription_response = requests.post(
    f"{BASE_URL}/v1/transcriptions/create",
    json=transcription_data,
    headers=headers
)
transcription = transcription_response.json()
transcription_id = transcription['transcription']['id']
print(f"✅ Step 1: Transcription created: {transcription_id}")

# Step 2: Create thread
thread_response = requests.post(
    f"{BASE_URL}/v1/lang-graph/threads",
    json={},
    headers=headers
)
thread = thread_response.json()
thread_id = thread['thread_id']
print(f"✅ Step 2: Thread created: {thread_id}")

# Step 3: Execute run for clinical extraction
run_headers = {
    **headers,
    "x-is-chat": "false"  # Clinical extraction mode
}

run_data = {
    "input": {
        "messages": [
            {
                "role": "user",
                "content": f"Extract clinical information: {transcription_data['original_transcript']}"
            }
        ]
    },
    "config": {
        "configurable": {
            "thread_id": thread_id
        }
    }
}

run_response = requests.post(
    f"{BASE_URL}/v1/lang-graph/threads/{thread_id}/runs",
    json=run_data,
    headers=run_headers
)
run = run_response.json()
run_id = run['run_id']
print(f"✅ Step 3: Run executed: {run_id}")

# Step 4: Update clinical note (assuming note_id exists)
note_id = "note_def456ghi"  # This would be created elsewhere
note_data = {
    "template": "SOAP",
    "ai_generated_content": {
        "subjective": "Patient reports chest pain radiating to left arm",
        "objective": "BP 140/90, HR 88, RR 18, O2 sat 98% on RA",
        "assessment": "R/O myocardial infarction",
        "plan": "Admit to CCU, serial troponins, cardiology consult"
    },
    "report_thread_id": thread_id,
    "report_run_id": [run_id]
}

note_response = requests.patch(
    f"{BASE_URL}/v1/clinical-notes/{note_id}",
    json=note_data,
    headers=headers
)
note = note_response.json()
print(f"✅ Step 4: Clinical note updated: {note['id']}")
print(f"\n🎉 Workflow complete!")

Supported Clinical Templates

The template field in clinical notes supports multiple formats:

SOAP (Subjective, Objective, Assessment, Plan)

{
  "subjective": "Patient's reported symptoms and history",
  "objective": "Physical examination findings and vital signs",
  "assessment": "Clinical diagnosis or impression",
  "plan": "Treatment plan and follow-up"
}

BIRP (Behavior, Intervention, Response, Plan)

{
  "behavior": "Observed patient behaviors",
  "intervention": "Actions taken by healthcare provider",
  "response": "Patient's response to intervention",
  "plan": "Future treatment plan"
}

DAP (Data, Assessment, Plan)

{
  "data": "Objective and subjective data gathered",
  "assessment": "Clinical assessment and diagnosis",
  "plan": "Treatment and follow-up plan"
}

Custom Templates

You can also use custom templates based on your organization’s requirements. The ai_generated_content field accepts any valid JSON object structure.

Error Handling

Common errors

Code	Error	Description	Solution
400	Bad Request	Missing required fields or invalid data	Verify all required fields are provided
401	Unauthorized	Invalid or expired token	Check your Bearer token
404	Not Found	Thread or clinical note not found	Verify the ID exists
500	Internal Server Error	Server error	Retry with exponential backoff

Error response format

{
  "success": false,
  "error": "Bad Request",
  "details": "duration_seconds and original_transcript are required"
}

Next steps

View Codify API

ICD-10 medical coding API

Error handling

Error responses and retry strategies

Authentication

API authentication and headers

OpenAPI Reference

Complete API specification

Overview

Configuration

Usage and Examples

API Reference

​Workflow Overview

​1. Create Transcription

​Endpoint

​Purpose

​Required headers

​Optional headers

​Request body

​Request fields

​Success response (HTTP 201)

​Example - Python

​Example - JavaScript

​2. Create Conversation Thread

​Endpoint

​Purpose

​Required headers

​Optional headers

​Request body

​Success response (HTTP 201)

​Example - Python

​Example - JavaScript

​3. Execute Conversation Run

​Endpoint

​Purpose

​Required headers

​Optional headers

​Path parameters

​Request body

​Request fields

​Success response (HTTP 201)

​Example - Clinical extraction

​Example - Chat interaction

​4. Update Clinical Note

​Endpoint

​Purpose

​Required headers

​Optional headers

​Path parameters

​Request body

​Request fields

​Success response (HTTP 200)

​Example - Python

​Example - JavaScript

​Complete Workflow Example

​Python - Complete workflow

​Supported Clinical Templates

​SOAP (Subjective, Objective, Assessment, Plan)

​BIRP (Behavior, Intervention, Response, Plan)

​DAP (Data, Assessment, Plan)

​Custom Templates

​Error Handling

​Common errors

​Error response format

​Next steps

View Codify API

Error handling

Authentication

OpenAPI Reference

Workflow Overview

1. Create Transcription

Endpoint

Purpose

Required headers

Optional headers

Request body

Request fields

Success response (HTTP 201)

Example - Python

Example - JavaScript

2. Create Conversation Thread

Endpoint

Purpose

Required headers

Optional headers

Request body

Success response (HTTP 201)

Example - Python

Example - JavaScript

3. Execute Conversation Run

Endpoint

Purpose

Required headers

Optional headers

Path parameters

Request body

Request fields

Success response (HTTP 201)

Example - Clinical extraction

Example - Chat interaction

4. Update Clinical Note

Endpoint

Purpose

Required headers

Optional headers

Path parameters

Request body

Request fields

Success response (HTTP 200)

Example - Python

Example - JavaScript

Complete Workflow Example

Python - Complete workflow

Supported Clinical Templates

SOAP (Subjective, Objective, Assessment, Plan)

BIRP (Behavior, Intervention, Response, Plan)

DAP (Data, Assessment, Plan)

Custom Templates

Error Handling

Common errors

Error response format

Next steps