Copilot Settings

Per-workspace configuration for the clinical copilot - specialty, SOAP style, safety alerts, CDS, post-encounter automation, tool selection, and medical vocabulary.

Copilot settings control how the clinical copilot behaves within a workspace. Configuration covers language, specialty focus, documentation style, safety alerting, clinical decision support, post-encounter automation, tool selection, and medical vocabulary for transcription accuracy.

Settings are stored at the workspace level and apply to all new copilot sessions in that workspace.

These settings are the public configuration hook for language, keyterms, specialty, SOAP style, enabled tools, safety, CDS, post-encounter behavior, voice authentication, and clinician access. Only documented fields are part of the public settings contract.

Endpoints

Method	Path	Description
GET	/v1/{workspace_id}/settings/scribe	Get copilot settings
PUT	/v1/{workspace_id}/settings/scribe	Update copilot settings

Get Copilot Settings

Returns the current copilot configuration for the workspace, merged with defaults for any fields not explicitly set.

Operation ID: get-scribe-settings

Response Body

Field	Type	Default	Description
enabled	boolean	false	Whether the copilot is active for this workspace
language	string	"en"	BCP-47 language tag for transcription and note generation (e.g., en, es, auto)
specialty	string or null	null	Clinical specialty (e.g., "cardiology", "orthopedics"). Shapes which findings the copilot prioritizes
custom_instructions	string or null	null	Free-text directives for workspace-specific copilot behavior (max 4000 characters)
soap_style	string	"concise"	Documentation format: concise, detailed, or structured
tools_enabled	array of strings or null	null (all tools)	Which copilot tools are active. Null enables all. Options: soap_update, icd10_suggest, clinical_alert, encounter_entity, polish_note, prepare_orders, learn_style
safety	object	All enabled	Safety alert configuration (see below)
cds	object	See defaults below	Clinical decision support configuration (see below)
post_encounter	object	See defaults below	Post-encounter automation configuration (see below)
keyterms	array of strings	[]	Workspace-level medical terms for transcription vocabulary boosting (max 100 terms, max 80 characters each)
voice_auth_enabled	boolean	false	Whether voice authentication is enabled for clinicians in this workspace
authorized_clinicians	array of objects	[]	List of authorized clinicians (see Clinician Object below)

Safety Configuration

Field	Type	Default	Description
drug_interaction_checking	boolean	true	Detect drug-drug interactions
allergy_cross_reference	boolean	true	Detect drug-allergy conflicts including cross-class reactions
crisis_detection	boolean	true	Detect crisis indicators (suicidality, abuse, homicidal ideation)
vital_range_alerting	boolean	true	Alert on dangerous vital sign values

Clinical Decision Support (CDS) Configuration

Field	Type	Default	Description
care_gap_surfacing	boolean	true	Identify overdue screenings, labs, and preventive care during encounters
icd10_auto_suggest	boolean	true	Suggest ICD-10 codes as diagnoses emerge in the conversation
guideline_matching	boolean	false	Evaluate encounters against evidence-based practice guidelines
documentation_completeness	boolean	true	Score encounters for missing SOAP sections and uncoded diagnoses

Post-Encounter Configuration

Field	Type	Default	Description
auto_polish_note	boolean	true	Rewrite accumulated SOAP sections as coherent medical prose
order_preparation	boolean	false	Structure lab orders, imaging requests, and referrals for one-click approval
education_materials	boolean	false	Match patient education materials to encounter diagnoses
follow_up_surface	boolean	false	Queue follow-up surfaces for delivery after the encounter

Example Response

{
  "enabled": false,
  "language": "en",
  "specialty": "cardiology",
  "custom_instructions": "Always note ejection fraction when mentioned.",
  "soap_style": "detailed",
  "tools_enabled": ["soap_update", "icd10_suggest", "clinical_alert", "encounter_entity", "polish_note", "learn_style"],
  "safety": {
    "drug_interaction_checking": true,
    "allergy_cross_reference": true,
    "crisis_detection": true,
    "vital_range_alerting": true
  },
  "cds": {
    "care_gap_surfacing": true,
    "icd10_auto_suggest": true,
    "guideline_matching": false,
    "documentation_completeness": true
  },
  "post_encounter": {
    "auto_polish_note": true,
    "order_preparation": false,
    "education_materials": false,
    "follow_up_surface": false
  },
  "keyterms": ["metoprolol", "echocardiogram", "troponin"],
  "voice_auth_enabled": false,
  "authorized_clinicians": [
    {
      "email": "[email protected]",
      "name": "Dr. Sarah Jones",
      "role": "physician"
    }
  ]
}

Update Copilot Settings

Update copilot configuration for the workspace. Only include the fields you want to change - unspecified fields retain their current values.

Operation ID: update-scribe-settings

Permissions: Requires workspace admin or owner role.

Request Body

All fields are optional. Only fields included in the request are updated.

Field	Type	Description
enabled	boolean	Enable or disable the copilot
language	string	BCP-47 language tag (normalized to lowercase). Use auto for automatic language detection
specialty	string or null	Clinical specialty (max 120 characters). Set to null to clear
custom_instructions	string or null	Free-text directives (max 4000 characters). Set to null to clear
soap_style	string	concise, detailed, or structured
tools_enabled	array of strings or null	Tools to enable. Set to null to enable all. Options: soap_update, icd10_suggest, clinical_alert, encounter_entity, polish_note, prepare_orders, learn_style
safety	object	Safety alert toggles (see Safety Configuration above)
cds	object	Clinical decision support toggles (see CDS Configuration above)
post_encounter	object	Post-encounter automation toggles (see Post-Encounter Configuration above)
keyterms	array of strings	Medical vocabulary terms (max 100 terms, max 80 characters each)
voice_auth_enabled	boolean	Enable or disable voice authentication for clinicians

Example Request

{
  "specialty": "orthopedics",
  "soap_style": "structured",
  "safety": {
    "drug_interaction_checking": true,
    "allergy_cross_reference": true,
    "vital_range_alerting": true,
    "crisis_detection": false
  },
  "cds": {
    "care_gap_surfacing": true,
    "icd10_auto_suggest": true,
    "guideline_matching": true,
    "documentation_completeness": true
  },
  "post_encounter": {
    "auto_polish_note": true,
    "order_preparation": true,
    "education_materials": false,
    "follow_up_surface": true
  },
  "authorized_clinicians": [
    {
      "email": "[email protected]",
      "name": "Dr. Sarah Jones",
      "role": "physician"
    }
  ],
  "keyterms": ["arthroscopy", "meniscus", "ACL reconstruction"]
}

Response

Returns the full merged settings after the update, using the same schema as the GET response.

Error Responses

Status	Condition
404	Workspace not found
422	Invalid tool name, invalid field value, or validation error
429	Rate limit exceeded

Audit

All updates are logged in the workspace audit trail with the list of fields that were changed.

SOAP Styles

Style	Behavior
concise	One sentence per finding. Minimal clinical prose
detailed	Full context and reasoning for each documented item
structured	Bullet points with labeled subsections

Vocabulary Boosting

Workspace-level keyterms improve transcription accuracy for domain-specific medical terminology. Terms defined in the copilot settings are combined with relevant encounter context when the session starts.

During a session, the copilot can also dynamically boost additional terms it encounters in the transcript. These session-level terms are added automatically and do not modify the workspace settings.