Amigo Settings API
The Settings API from Amigo — 9 operation(s) for settings.
OpenAPI Specification
openapi: 3.1.0
info:
title: Amigo Account Settings API
version: 0.1.0
servers:
- url: https://api.amigo.ai
- url: https://internal-api.amigo.ai
- url: https://api-eu-central-1.amigo.ai
- url: https://api-ap-southeast-2.amigo.ai
- url: https://api-ca-central-1.amigo.ai
security:
- Bearer-Authorization: []
Bearer-Authorization-Organization: []
Basic: []
tags:
- name: Settings
paths:
/v1/{workspace_id}/settings/retention:
get:
tags:
- Settings
summary: Get retention policy
description: 'Get the workspace retention policy.
Returns HIPAA-compliant defaults (2190 days / 6 years) for any field
not explicitly configured. Advisory in v1 — no automated deletion.
Permissions: authenticated (any role).'
operationId: get-retention-policy
responses:
'200':
description: Successful Response
content:
application/json:
schema:
$ref: '#/components/schemas/RetentionPolicyResponse'
'429':
description: Rate limited
parameters:
- name: workspace_id
in: path
required: true
schema:
type: string
format: uuid
title: Workspace Id
put:
tags:
- Settings
summary: Update retention policy
description: 'Update the workspace retention policy.
Partial updates supported — only provided fields are changed.
Advisory in v1: policy is stored and displayed but no automated
deletion is performed. Legal hold overrides all retention.
Permissions: admin, owner (``Workspace.update``).'
operationId: update-retention-policy
requestBody:
content:
application/json:
schema:
$ref: '#/components/schemas/RetentionPolicyRequest'
required: true
responses:
'200':
description: Successful Response
content:
application/json:
schema:
$ref: '#/components/schemas/RetentionPolicyResponse'
'404':
description: Workspace not found
'422':
description: Validation error
'429':
description: Rate limited
parameters:
- name: workspace_id
in: path
required: true
schema:
type: string
format: uuid
title: Workspace Id
/v1/{workspace_id}/settings/gap-scanner:
get:
tags:
- Settings
summary: Get gap scanner settings
description: 'Get the workspace gap scanner settings.
Returns defaults when not configured. Gap scanner is disabled by default.
Permissions: authenticated (any role).'
operationId: get-gap-scanner-settings
responses:
'200':
description: Successful Response
content:
application/json:
schema:
$ref: '#/components/schemas/GapScannerSettingsResponse'
'429':
description: Rate limited
parameters:
- name: workspace_id
in: path
required: true
schema:
type: string
format: uuid
title: Workspace Id
put:
tags:
- Settings
summary: Update gap scanner settings
description: 'Update the workspace gap scanner settings.
Partial updates supported — only provided fields are changed.
Requirements list is replaced entirely when provided (not merged).
Permissions: admin, owner (enforced via ``Workspace.update``, matching
the outreach-settings sibling).'
operationId: update-gap-scanner-settings
requestBody:
content:
application/json:
schema:
$ref: '#/components/schemas/GapScannerSettingsRequest'
required: true
responses:
'200':
description: Successful Response
content:
application/json:
schema:
$ref: '#/components/schemas/GapScannerSettingsResponse'
'404':
description: Workspace not found
'422':
description: Validation error
'429':
description: Rate limited
parameters:
- name: workspace_id
in: path
required: true
schema:
type: string
format: uuid
title: Workspace Id
/v1/{workspace_id}/settings/gap-scanner/preview:
post:
tags:
- Settings
summary: Preview gap detection (dry run)
description: 'Dry-run gap detection — returns entities with missing fields without creating surfaces.
Proxies to connector-runner /internal/gap-scanner/preview.
Permissions: admin, owner (enforced via ``Workspace.update``).'
operationId: gap-scanner-preview
requestBody:
content:
application/json:
schema:
anyOf:
- $ref: '#/components/schemas/GapScannerPreviewRequest'
- type: 'null'
title: Body
responses:
'200':
description: Successful Response
content:
application/json:
schema:
additionalProperties: true
type: object
title: Response Gap-Scanner-Preview
'429':
description: Rate limited
'503':
description: Connector runner unavailable
'422':
description: Validation Error
content:
application/json:
schema:
$ref: '#/components/schemas/HTTPValidationError'
parameters:
- name: workspace_id
in: path
required: true
schema:
type: string
format: uuid
title: Workspace Id
/v1/{workspace_id}/settings/gap-scanner/scan:
post:
tags:
- Settings
summary: Trigger one scan tick
description: 'Trigger one scan tick immediately — creates surfaces for detected gaps.
Proxies to connector-runner /internal/gap-scanner/scan.
Permissions: admin, owner (enforced via ``Workspace.update`` — this
creates patient-facing surfaces, so it must not be reachable below
admin tier).'
operationId: gap-scanner-scan
responses:
'200':
description: Successful Response
content:
application/json:
schema:
additionalProperties: true
type: object
title: Response Gap-Scanner-Scan
'429':
description: Rate limited
'503':
description: Connector runner unavailable
parameters:
- name: workspace_id
in: path
required: true
schema:
type: string
format: uuid
title: Workspace Id
/v1/{workspace_id}/settings/metrics:
get:
tags:
- Settings
summary: Get metric definitions
description: 'Get the workspace metric definitions.
Returns built-in defaults when not configured.
Permissions: authenticated (any role).'
operationId: get-metric-settings
responses:
'200':
description: Successful Response
content:
application/json:
schema:
$ref: '#/components/schemas/MetricSettingsResponse'
'429':
description: Rate limited
parameters:
- name: workspace_id
in: path
required: true
schema:
type: string
format: uuid
title: Workspace Id
put:
tags:
- Settings
summary: Update metric definitions
description: 'Update the workspace metric definitions.
Partial updates supported — only provided fields are changed.
The definitions list is replaced entirely when provided.
Permissions: admin, owner.'
operationId: update-metric-settings
requestBody:
content:
application/json:
schema:
$ref: '#/components/schemas/MetricSettingsRequest'
required: true
responses:
'200':
description: Successful Response
content:
application/json:
schema:
$ref: '#/components/schemas/MetricSettingsResponse'
'404':
description: Workspace not found
'422':
description: Validation error
'429':
description: Rate limited
parameters:
- name: workspace_id
in: path
required: true
schema:
type: string
format: uuid
title: Workspace Id
/v1/{workspace_id}/settings/outreach:
get:
tags:
- Settings
summary: Get outreach settings
description: 'Get the workspace outreach settings.
Returns empty rules and templates when not configured.
Permissions: authenticated (any role).'
operationId: get-outreach-settings
responses:
'200':
description: Successful Response
content:
application/json:
schema:
$ref: '#/components/schemas/OutreachSettingsResponse'
'429':
description: Rate limited
parameters:
- name: workspace_id
in: path
required: true
schema:
type: string
format: uuid
title: Workspace Id
put:
tags:
- Settings
summary: Update outreach settings
description: 'Update the workspace outreach settings.
Partial updates supported — only provided fields are changed.
Rules and data_templates lists are replaced entirely when provided.
Validates that data_template_id references in rules point to
templates that exist in the same payload or current settings.
Permissions: admin, owner.'
operationId: update-outreach-settings
requestBody:
content:
application/json:
schema:
$ref: '#/components/schemas/OutreachSettingsRequest'
required: true
responses:
'200':
description: Successful Response
content:
application/json:
schema:
$ref: '#/components/schemas/OutreachSettingsResponse'
'404':
description: Workspace not found
'422':
description: Validation error
'429':
description: Rate limited
parameters:
- name: workspace_id
in: path
required: true
schema:
type: string
format: uuid
title: Workspace Id
/v1/{workspace_id}/settings/branding:
get:
tags:
- Settings
summary: Get workspace branding
description: 'Get the workspace default branding for surfaces.
Returns empty branding when not configured.
Permissions: authenticated (any role).'
operationId: get-branding-settings
responses:
'200':
description: Successful Response
content:
application/json:
schema:
$ref: '#/components/schemas/BrandingSettingsResponse'
'429':
description: Rate limited
parameters:
- name: workspace_id
in: path
required: true
schema:
type: string
format: uuid
title: Workspace Id
put:
tags:
- Settings
summary: Update workspace branding
description: 'Update the workspace default branding for surfaces.
Surface-level branding takes precedence over workspace-level branding.
Permissions: admin, owner.'
operationId: update-branding-settings
requestBody:
content:
application/json:
schema:
$ref: '#/components/schemas/BrandingSettingsRequest'
required: true
responses:
'200':
description: Successful Response
content:
application/json:
schema:
$ref: '#/components/schemas/BrandingSettingsResponse'
'404':
description: Workspace not found
'422':
description: Validation error
'429':
description: Rate limited
parameters:
- name: workspace_id
in: path
required: true
schema:
type: string
format: uuid
title: Workspace Id
/v1/{workspace_id}/settings/environments:
get:
tags:
- Settings
summary: Get environment overrides
description: 'Get per-environment config overrides.
Returns empty environments when not configured.
Permissions: authenticated (any role).'
operationId: get-environment-settings
responses:
'200':
description: Successful Response
content:
application/json:
schema:
$ref: '#/components/schemas/EnvironmentSettingsResponse'
'429':
description: Rate limited
parameters:
- name: workspace_id
in: path
required: true
schema:
type: string
format: uuid
title: Workspace Id
put:
tags:
- Settings
summary: Update environment overrides
description: 'Update per-environment config overrides.
Permissions: admin, owner.'
operationId: update-environment-settings
requestBody:
content:
application/json:
schema:
$ref: '#/components/schemas/EnvironmentSettingsRequest'
required: true
responses:
'200':
description: Successful Response
content:
application/json:
schema:
$ref: '#/components/schemas/EnvironmentSettingsResponse'
'404':
description: Workspace not found
'422':
description: Validation error
'429':
description: Rate limited
parameters:
- name: workspace_id
in: path
required: true
schema:
type: string
format: uuid
title: Workspace Id
/v1/{workspace_id}/settings/voice:
get:
tags:
- Settings
summary: Get voice settings
description: 'Get the voice experience settings for a workspace.
Returns voice identity, domain vocabulary, and post-call intelligence
configuration. These settings shape how the AI agent sounds and what
domain-specific terms it recognizes accurately.
#### Permissions
* Requires authenticated API key (any role).'
operationId: get-voice-settings
responses:
'200':
description: Successful Response
content:
application/json:
schema:
$ref: '#/components/schemas/VoiceSettingsResponse'
'429':
description: Rate limited
parameters:
- name: workspace_id
in: path
required: true
schema:
type: string
format: uuid
title: Workspace Id
put:
tags:
- Settings
summary: Update voice settings
description: "Update the voice experience settings for a workspace.\n\nOnly provided fields are updated; omitted fields retain their current\nvalues. Set a field to ``null`` to reset it to default.\n\n**Voice Identity & Style**\n- **voice_id**: Voice identity UUID — determines the agent's voice persona\n- **tone**: Emotional baseline (``calm``, ``sympathetic``,\n ``enthusiastic``, ``content``, ``curious``, ``cheerful``,\n ``serious``, ``friendly``). The system also adapts tone dynamically\n based on real-time caller emotion analysis; this setting provides\n the baseline when no strong emotional signal is detected.\n- **speed**: Speech rate multiplier (0.5-2.0)\n- **volume**: Volume multiplier (0.0-1.0)\n- **language**: BCP-47 language tag (default ``en``)\n\n**Speech Recognition Boost**\n- **keyterms**: Exact words the speech recognition engine should\n prioritize. Use for specific names, drug names, and org jargon.\n Example: ``[\"Dr. Ramirez\", \"metformin\", \"HIPAA\"]``\n\n**Post-Call Intelligence**\n- **post_call_analysis_enabled**: Run automated quality scoring after\n each call ends (default ``true``)\n- **transcript_correction_enabled**: Re-verify transcripts with a\n high-accuracy batch model after call ends (default ``true``)\n\n#### Permissions\n* Requires admin or owner role."
operationId: update-voice-settings
requestBody:
content:
application/json:
schema:
$ref: '#/components/schemas/VoiceSettingsRequest'
required: true
responses:
'200':
description: Successful Response
content:
application/json:
schema:
$ref: '#/components/schemas/VoiceSettingsResponse'
'404':
description: Workspace not found
'422':
description: Validation error
'429':
description: Rate limited
parameters:
- name: workspace_id
in: path
required: true
schema:
type: string
format: uuid
title: Workspace Id
components:
schemas:
ChannelType:
type: string
enum:
- email
- web
- sms
title: ChannelType
description: Delivery channels for surfaces.
DataTemplate-Input:
properties:
id:
type: string
format: uuid
title: Id
name:
$ref: '#/components/schemas/NameString'
fields:
items:
$ref: '#/components/schemas/DataTemplateField'
type: array
maxItems: 50
minItems: 1
title: Fields
type: object
required:
- name
- fields
title: DataTemplate
description: Named field template — reusable across multiple outreach rules.
EnvironmentOverrides:
properties:
data_source_id:
anyOf:
- type: string
format: uuid
- type: 'null'
title: Data Source Id
tool_overrides:
additionalProperties: true
type: object
title: Tool Overrides
data_source_overrides:
additionalProperties: true
type: object
title: Data Source Overrides
type: object
title: EnvironmentOverrides
description: Per-environment config overrides merged at runtime.
GapScannerPreviewRequest:
properties:
limit:
type: integer
maximum: 200.0
minimum: 1.0
title: Limit
default: 50
type: object
title: GapScannerPreviewRequest
ValidationError:
properties:
loc:
items:
anyOf:
- type: string
- type: integer
type: array
title: Location
msg:
type: string
title: Message
type:
type: string
title: Error Type
input:
title: Input
ctx:
type: object
title: Context
type: object
required:
- loc
- msg
- type
title: ValidationError
DataTemplateField:
properties:
key:
type: string
maxLength: 128
minLength: 1
title: Key
label:
$ref: '#/components/schemas/NameString'
field_type:
$ref: '#/components/schemas/FieldType'
default: text
required:
type: boolean
title: Required
default: true
sensitive:
type: boolean
title: Sensitive
default: false
path:
type: string
maxLength: 256
minLength: 1
title: Path
description: Dot-notation path into entity state (e.g. demographics.date_of_birth)
type: object
required:
- key
- label
- path
title: DataTemplateField
description: A field in a data template — maps to entity state path for gap detection.
BrandingSettingsResponse:
properties:
branding:
$ref: '#/components/schemas/BrandingConfig'
type: object
required:
- branding
title: BrandingSettingsResponse
MetricSettingsResponse:
properties:
definitions:
items:
$ref: '#/components/schemas/MetricDefinition'
type: array
title: Definitions
type: object
required:
- definitions
title: MetricSettingsResponse
GapRequirement-Output:
properties:
name:
$ref: '#/components/schemas/NameString'
entity_type:
type: string
const: person
title: Entity Type
default: person
trigger:
type: string
enum:
- upcoming_appointment
- recent_interaction
title: Trigger
default: upcoming_appointment
required_fields:
items:
$ref: '#/components/schemas/GapRequiredField'
type: array
maxItems: 50
minItems: 1
title: Required Fields
channel:
$ref: '#/components/schemas/ChannelType'
default: email
priority:
type: string
enum:
- low
- normal
- high
title: Priority
default: normal
surface_title:
anyOf:
- $ref: '#/components/schemas/NameString'
- type: 'null'
description: Title for generated surfaces. Defaults to requirement name.
surface_description:
anyOf:
- $ref: '#/components/schemas/DescriptionString'
- type: 'null'
type: object
required:
- name
- required_fields
title: GapRequirement
description: A named gap detection rule.
OutreachRule:
properties:
id:
type: string
format: uuid
title: Id
name:
$ref: '#/components/schemas/NameString'
trigger:
type: string
enum:
- appointment_window
- post_visit
- gap_detected
- form_intake
- manual
title: Trigger
default: appointment_window
trigger_config:
additionalProperties: true
type: object
title: Trigger Config
description: Trigger-specific config (hours_before, hours_after, etc.)
channel:
$ref: '#/components/schemas/ChannelType'
default: email
consent_required:
type: boolean
title: Consent Required
default: true
quiet_hours:
$ref: '#/components/schemas/QuietHours'
review_required:
type: boolean
title: Review Required
default: false
message_template:
type: string
maxLength: 1600
title: Message Template
default: 'Hi {first_name}, please complete your form: {surface_url}'
data_template_id:
anyOf:
- type: string
format: uuid
- type: 'null'
title: Data Template Id
form_template_id:
anyOf:
- type: string
format: uuid
- type: 'null'
title: Form Template Id
active:
type: boolean
title: Active
default: true
type: object
required:
- name
title: OutreachRule
description: A single outreach rule — defines WHEN, WHAT, and HOW to reach a patient.
EnvironmentSettingsRequest:
properties:
environments:
additionalProperties:
$ref: '#/components/schemas/EnvironmentOverrides'
type: object
title: Environments
type: object
required:
- environments
title: EnvironmentSettingsRequest
BrandingSettingsRequest:
properties:
branding:
$ref: '#/components/schemas/BrandingConfig'
type: object
required:
- branding
title: BrandingSettingsRequest
description: 'Update workspace branding. All fields are optional — only provided
fields are changed.'
GapScannerSettingsResponse:
properties:
enabled:
type: boolean
title: Enabled
scan_interval_seconds:
type: integer
title: Scan Interval Seconds
appointment_lookahead_hours:
type: integer
title: Appointment Lookahead Hours
cooldown_hours:
type: integer
title: Cooldown Hours
max_surfaces_per_tick:
type: integer
title: Max Surfaces Per Tick
max_pending_surfaces:
type: integer
title: Max Pending Surfaces
min_completion_rate:
type: number
title: Min Completion Rate
channel_optimization:
type: boolean
title: Channel Optimization
requirements:
items:
$ref: '#/components/schemas/GapRequirement-Output'
type: array
title: Requirements
type: object
required:
- enabled
- scan_interval_seconds
- appointment_lookahead_hours
- cooldown_hours
- max_surfaces_per_tick
- max_pending_surfaces
- min_completion_rate
- channel_optimization
- requirements
title: GapScannerSettingsResponse
VoiceSettingsResponse:
properties:
voice_id:
anyOf:
- type: string
- type: 'null'
title: Voice Id
tone:
anyOf:
- type: string
- type: 'null'
title: Tone
speed:
anyOf:
- type: number
- type: 'null'
title: Speed
volume:
anyOf:
- type: number
- type: 'null'
title: Volume
language:
type: string
title: Language
keyterms:
items:
type: string
type: array
title: Keyterms
pronunciation_dict_id:
anyOf:
- type: string
- type: 'null'
title: Pronunciation Dict Id
sensitive_topics:
items:
type: string
type: array
title: Sensitive Topics
post_call_analysis_enabled:
type: boolean
title: Post Call Analysis Enabled
transcript_correction_enabled:
type: boolean
title: Transcript Correction Enabled
stt_provider:
anyOf:
- type: string
enum:
- deepgram
- openai
- cartesia
- type: 'null'
title: Stt Provider
tts_provider:
anyOf:
- type: string
enum:
- cartesia
- elevenlabs
- groq
- type: 'null'
title: Tts Provider
tts_config:
anyOf:
- additionalProperties: true
type: object
- type: 'null'
title: Tts Config
language_providers:
anyOf:
- additionalProperties:
$ref: '#/components/schemas/LanguageProviderEntry'
type: object
- type: 'null'
title: Language Providers
type: object
required:
- voice_id
- tone
- speed
- volume
- language
- keyterms
- pronunciation_dict_id
- sensitive_topics
- post_call_analysis_enabled
- transcript_correction_enabled
- stt_provider
- tts_provider
- tts_config
title: VoiceSettingsResponse
description: Voice experience state — what the PM configured.
FieldType:
type: string
enum:
- text
- textarea
- date
- phone
- email
- number
- select
- multiselect
- checkbox
- photo
- signature
- file
- heading
- info
title: FieldType
description: Input field types for surface data collection.
GapRequirement-Input:
properties:
name:
$ref: '#/components/schemas/NameString'
entity_type:
type: string
const: person
title: Entity Type
default: person
trigger:
type: string
enum:
- upcoming_appointment
- recent_interaction
title: Trigger
default: upcoming_appointment
required_fields:
items:
$ref: '#/components/schemas/GapRequiredField'
type: array
maxItems: 50
minItems: 1
title: Required Fields
channel:
$ref: '#/components/schemas/ChannelType'
default: email
priority:
type: string
enum:
- low
- normal
- high
title: Priority
default: normal
surface_title:
anyOf:
- $ref: '#/components/schemas/NameString'
- type: 'null'
description: Title for generated surfaces. Defaults to requirement name.
surface_description:
anyOf:
- $ref: '#/components/schemas/DescriptionString'
- type: 'null'
type: object
required:
- name
- required_fields
title: GapRequirement
description: A named gap detection rule.
EnvironmentSettingsResponse:
properties:
environments:
additionalProperties:
$ref: '#/components/schemas/EnvironmentOverrides'
type: object
title: Environments
type: object
title: EnvironmentSettingsResponse
QuietHours:
properties:
enabled:
type: boolean
title: Enabled
default: false
start_hour:
type: integer
maximum: 23.0
minimum: 0.0
title: Start Hour
default: 21
end_hour:
type: integer
maximum: 23.0
minimum: 0.0
title: End Hour
default: 8
timezone:
type: string
maxLength: 64
title: Timezone
default: America/New_York
type: object
title: QuietHours
description: Quiet hours — no outbound outreach during this window.
HTTPValidationError:
properties:
detail:
items:
$ref: '#/components/schemas/ValidationError'
type: array
title: Detail
type: object
title: HTTPValidationError
GapRequiredField:
properties:
path:
type: string
maxLength: 256
minLength: 1
title: Path
description: Dot-notation path into entity state
label:
$ref: '#/components/schemas/NameString'
field_type:
$ref: '#/components/schemas/FieldType'
default: text
min_items:
anyOf:
- type: integer
maximum: 100.0
minimum: 0.0
- type: 'null'
title: Min Items
description: For list fields, minimum items required
type: object
required:
- path
- label
title: GapRequiredField
description: A field that must be present in entity state.
RetentionPolicyRequest:
properties:
call_recordings_days:
anyOf:
- type: integer
maximum: 36500.0
minimum: 365.0
- type: 'null'
title: Call Recordings Days
call_transcripts_days:
anyOf:
- type: integer
maximum: 36500.0
minimum: 365.0
- type: 'null'
title: Call Transcripts Days
audit_log_days:
anyOf:
- type: integer
maximum: 36500.0
minimum: 365.0
- type: 'null'
title: Audit Log Days
world_events_days:
anyOf:
- type: integer
maximum: 36500.0
minimum: 365.0
- type: 'null'
title: World Events Days
phi_data_days:
anyOf:
- type: integer
maximum: 36500.0
minimum: 365.0
- type: 'null'
title: Phi Da
# --- truncated at 32 KB (53 KB total) ---
# Full source: https://raw.githubusercontent.com/api-evangelist/amigo/refs/heads/main/openapi/amigo-settings-api-openapi.yml