Workspaces

Manage workspaces: tenant isolation, voice settings, speech recognition, and test caller numbers.

Workspaces are the top-level organizational unit in the Platform API. Every resource (agents, services, skills, phone numbers, integrations) belongs to a workspace. Workspaces provide tenant isolation and environment separation.

Key Concepts

• Workspace ID: UUID used in all Platform API request paths
• Slug: URL-friendly name (e.g., acme-production)
• Environment: production, staging, or development
• Backend Org ID: Links to the Classic API organization, bridging the two API surfaces

Workspace vs Organization: The Classic API scopes by organization. The Platform API scopes by workspace. A workspace maps to a Classic API organization via backend_org_id.

Workspace Resource

List Workspaces

List workspaces

get

List workspaces accessible to this API key. Requires Workspace.view permission.

Authorizations

AuthorizationstringRequired

API key issued via POST /v1/{workspace_id}/api-keys. Pass the returned api_key value as a Bearer token.

Query parameters

limitinteger · max: 200OptionalDefault: 50

continuation_tokenanyOptional

Responses

200

Successful Response

application/json

has_morebooleanRequired

continuation_tokenanyOptional

401

Missing or invalid API key.

403

Insufficient permissions.

422

Validation Error

application/json

get/v1/workspaces

GET /v1/workspaces HTTP/1.1
Host: api.platform.amigo.ai
Authorization: Bearer YOUR_SECRET_TOKEN
Accept: */*

{
  "items": [
    {
      "id": "123e4567-e89b-12d3-a456-426614174000",
      "slug": "text",
      "name": "text",
      "backend_org_id": "text",
      "region": "text",
      "connector_type": "text",
      "provisioned_at": "2026-01-01T00:00:00.000Z",
      "created_at": "2026-01-01T00:00:00.000Z",
      "updated_at": "2026-01-01T00:00:00.000Z"
    }
  ],
  "has_more": true,
  "continuation_token": null
}

Get a Workspace

Get a workspace

get

Retrieve a workspace by ID. Requires Workspace.view permission.

Authorizations

AuthorizationstringRequired

API key issued via POST /v1/{workspace_id}/api-keys. Pass the returned api_key value as a Bearer token.

Path parameters

workspace_idstring · uuidRequired

Responses

200

Successful Response

application/json

idstring · uuidRequired

slugstringRequired

namestringRequired

backend_org_idstring · nullableRequired

regionstringRequired

connector_typestring · nullableRequired

provisioned_atstring · date-time · nullableRequired

created_atstring · date-timeRequired

updated_atstring · date-timeRequired

401

Missing or invalid API key.

403

Insufficient permissions.

404

Workspace not found.

get/v1/workspaces/{workspace_id}

GET /v1/workspaces/{workspace_id} HTTP/1.1
Host: api.platform.amigo.ai
Authorization: Bearer YOUR_SECRET_TOKEN
Accept: */*

{
  "id": "123e4567-e89b-12d3-a456-426614174000",
  "slug": "text",
  "name": "text",
  "backend_org_id": "text",
  "region": "text",
  "connector_type": "text",
  "provisioned_at": "2026-01-01T00:00:00.000Z",
  "created_at": "2026-01-01T00:00:00.000Z",
  "updated_at": "2026-01-01T00:00:00.000Z"
}

Update a Workspace

Update a workspace

patch

Update workspace fields. Requires Workspace.update permission.

Authorizations

AuthorizationstringRequired

API key issued via POST /v1/{workspace_id}/api-keys. Pass the returned api_key value as a Bearer token.

Path parameters

workspace_idstring · uuidRequired

Body

namestring · min: 1 · nullableOptional

regionstring · enum · nullableOptionalPossible values:

connector_typestring · enum · nullableOptionalPossible values:

Responses

200

Successful Response

application/json

idstring · uuidRequired

slugstringRequired

namestringRequired

backend_org_idstring · nullableRequired

regionstringRequired

connector_typestring · nullableRequired

provisioned_atstring · date-time · nullableRequired

created_atstring · date-timeRequired

updated_atstring · date-timeRequired

401

Missing or invalid API key.

403

Insufficient permissions.

404

Workspace not found.

422

Invalid request body.

patch/v1/workspaces/{workspace_id}

PATCH /v1/workspaces/{workspace_id} HTTP/1.1
Host: api.platform.amigo.ai
Authorization: Bearer YOUR_SECRET_TOKEN
Content-Type: application/json
Accept: */*
Content-Length: 60

{
  "name": "text",
  "region": "us-east-1",
  "connector_type": "epic"
}

{
  "id": "123e4567-e89b-12d3-a456-426614174000",
  "slug": "text",
  "name": "text",
  "backend_org_id": "text",
  "region": "text",
  "connector_type": "text",
  "provisioned_at": "2026-01-01T00:00:00.000Z",
  "created_at": "2026-01-01T00:00:00.000Z",
  "updated_at": "2026-01-01T00:00:00.000Z"
}

Provisioning

After creating a workspace, call the provision endpoint to seed default integrations and mark the workspace as provisioned. This is idempotent: safe to call multiple times. Requires Workspace.update permission.

Provision workspace resources

post

Seed default integrations and mark workspace as provisioned. Idempotent. Requires Workspace.update permission.

Authorizations

AuthorizationstringRequired

API key issued via POST /v1/{workspace_id}/api-keys. Pass the returned api_key value as a Bearer token.

Path parameters

workspace_idstring · uuidRequired

Responses

200

Successful Response

application/json

401

Missing or invalid API key.

403

Insufficient permissions.

404

Workspace not found.

post/v1/workspaces/{workspace_id}/provision

POST /v1/workspaces/{workspace_id}/provision HTTP/1.1
Host: api.platform.amigo.ai
Authorization: Bearer YOUR_SECRET_TOKEN
Accept: */*

{
  "workspace": {
    "id": "123e4567-e89b-12d3-a456-426614174000",
    "slug": "text",
    "name": "text",
    "backend_org_id": "text",
    "region": "text",
    "connector_type": "text",
    "provisioned_at": "2026-01-01T00:00:00.000Z",
    "created_at": "2026-01-01T00:00:00.000Z",
    "updated_at": "2026-01-01T00:00:00.000Z"
  }
}

Archive

Archive a workspace

post

Archive a workspace and remove it from active access flows while preserving underlying data. Requires owner access and slug confirmation.

Authorizations

AuthorizationstringRequired

API key issued via POST /v1/{workspace_id}/api-keys. Pass the returned api_key value as a Bearer token.

Path parameters

workspace_idstring · uuidRequired

Body

slugstring · min: 2 · max: 63RequiredPattern: ^[a-z0-9][a-z0-9-]*[a-z0-9]$

Responses

200

Successful Response

application/json

idstring · uuidRequired

slugstringRequired

namestringRequired

backend_org_idstring · nullableRequired

regionstringRequired

connector_typestring · nullableRequired

provisioned_atstring · date-time · nullableRequired

created_atstring · date-timeRequired

updated_atstring · date-timeRequired

401

Missing or invalid API key.

403

Only owners can archive a workspace.

404

Workspace not found.

422

Workspace slug confirmation did not match.

post/v1/workspaces/{workspace_id}/archive

POST /v1/workspaces/{workspace_id}/archive HTTP/1.1
Host: api.platform.amigo.ai
Authorization: Bearer YOUR_SECRET_TOKEN
Content-Type: application/json
Accept: */*
Content-Length: 15

{
  "slug": "text"
}

{
  "id": "123e4567-e89b-12d3-a456-426614174000",
  "slug": "text",
  "name": "text",
  "backend_org_id": "text",
  "region": "text",
  "connector_type": "text",
  "provisioned_at": "2026-01-01T00:00:00.000Z",
  "created_at": "2026-01-01T00:00:00.000Z",
  "updated_at": "2026-01-01T00:00:00.000Z"
}

Archiving removes a workspace from active access flows while preserving all underlying data. It requires the owner role and a slug confirmation in the request body to prevent accidental archival. Archived workspaces no longer appear in workspace listings and reject new API requests.

Invitations

Invitation creation and preview are Identity API operations and are not represented in the Platform API OpenAPI document. The embedded Platform operations on this page remain the source of truth for workspace resources, archiving, environment conversion, settings, and test configuration.

Workspace invitations let you invite users by email before they have an account.

• Create: POST /workspaces/{workspace_id}/invitations sends an invitation with a specified role and 7-day expiry. Resending to the same email reactivates the existing invitation.
• Preview: GET /workspaces/invitations/{invitation_id}/preview returns a safe public view of the invitation (workspace name, role, expiry, status) without requiring authentication. Used to render invitation landing pages before sign-in.
• Accept or decline: the invited user can accept or decline from their pending invitations list.
• Revoke: workspace admins can revoke pending invitations.

When a workspace admin creates or resends an invitation, an email notification is sent to the invited user with the workspace name, assigned role, and an accept link. Email delivery is asynchronous and fail-open - if delivery fails, the invitation is still created and returned to the admin for manual sharing.

Invited users who do not belong to an auto-provisioning domain can log in through Google OAuth. If pending invitations exist for their verified email, they receive a bootstrap token with no workspace scopes. The user must accept a specific invitation through the Developer Console before receiving a workspace-scoped token.

Access Audit Logging

All workspace membership and invitation operations emit audit events:

Event	When
workspace.member_added	Member created or reactivated
workspace.member_removed	Member deactivated
workspace.member_role_updated	Member role changed
workspace.invitation_sent	Invitation created or resent
workspace.invitation_accepted	Invitation accepted
workspace.invitation_declined	Invitation declined
workspace.invitation_revoked	Invitation revoked by admin

Each event records the actor, target, role, and relevant metadata. These events are available through the audit log endpoints and the compliance export.

Environment Conversion

Workspaces can be converted between staging and production environments. This supports the workflow where teams build and test in a staging workspace, then promote it to production when ready.

Pre-Check an Environment Conversion

The pre-check returns the current environment, target environment, and a list of operational and compliance warnings associated with the requested conversion. It does not mutate the workspace.

Convert a Workspace Environment

Conversion requires a target environment and a slug confirmation that matches the workspace slug to prevent accidental changes.

The conversion endpoint updates the workspace environment and records conversion metadata. Treat the pre-check warnings as considerations for dependent services and credentials; the endpoint does not itself guarantee migration of resources or a specific transition time for already-active sessions.

Requires Workspace.update permission (admin or owner role).

Voice Settings

Voice settings control the workspace-level voice pipeline, affecting all voice conversations.

Get Voice Settings

Get voice settings

get

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).

Authorizations

AuthorizationstringRequired

API key issued via POST /v1/{workspace_id}/api-keys. Pass the returned api_key value as a Bearer token.

Path parameters

workspace_idstring · uuidRequired

Responses

200

Successful Response

application/json

Voice experience state — what the PM configured.

voice_idstring · nullableRequired

tonestring · nullableRequired

speednumber · nullableRequired

volumenumber · nullableRequired

languagestringRequired

keytermsstring[]Required

pronunciation_dict_idstring · nullableRequired

sensitive_topicsstring[]Required

post_call_analysis_enabledbooleanRequired

transcript_correction_enabledbooleanRequired

stt_providerstring · enum · nullableRequiredPossible values:

tts_providerstring · enum · nullableRequiredPossible values:

429

Rate limited

get/v1/{workspace_id}/settings/voice

GET /v1/{workspace_id}/settings/voice HTTP/1.1
Host: api.platform.amigo.ai
Authorization: Bearer YOUR_SECRET_TOKEN
Accept: */*

{
  "voice_id": "text",
  "tone": "text",
  "speed": 1,
  "volume": 1,
  "language": "text",
  "keyterms": [
    "text"
  ],
  "pronunciation_dict_id": "text",
  "sensitive_topics": [
    "text"
  ],
  "post_call_analysis_enabled": true,
  "transcript_correction_enabled": true,
  "stt_provider": "deepgram",
  "tts_provider": "cartesia",
  "tts_config": {
    "ANY_ADDITIONAL_PROPERTY": "anything"
  },
  "language_providers": {
    "ANY_ADDITIONAL_PROPERTY": {
      "provider": "cartesia",
      "config": {
        "ANY_ADDITIONAL_PROPERTY": "anything"
      }
    }
  }
}

Update Voice Settings

Update voice settings

put

Update the voice experience settings for a workspace.

Only provided fields are updated; omitted fields retain their current values. Set a field to null to reset it to default.

Voice Identity & Style

• voice_id: Voice identity UUID — determines the agent's voice persona
• tone: Emotional baseline (calm, sympathetic, enthusiastic, content, curious, cheerful, serious, friendly). The system also adapts tone dynamically based on real-time caller emotion analysis; this setting provides the baseline when no strong emotional signal is detected.
• speed: Speech rate multiplier (0.5-2.0)
• volume: Volume multiplier (0.0-1.0)
• language: BCP-47 language tag (default en)

Speech Recognition Boost

• keyterms: Exact words the speech recognition engine should prioritize. Use for specific names, drug names, and org jargon. Example: ["Dr. Ramirez", "metformin", "HIPAA"]

Post-Call Intelligence

• post_call_analysis_enabled: Run automated quality scoring after each call ends (default true)
• transcript_correction_enabled: Re-verify transcripts with a high-accuracy batch model after call ends (default true)

Permissions

• Requires admin or owner role.

Authorizations

AuthorizationstringRequired

API key issued via POST /v1/{workspace_id}/api-keys. Pass the returned api_key value as a Bearer token.

Path parameters

workspace_idstring · uuidRequired

Body

Voice experience control plane — PM-facing, high-level controls.

Controls the caller experience without exposing engineering internals. Emotion detection, filler speech, model selection, and buffer tuning are always-on internals managed by engineering.

voice_idstring · max: 128 · nullableOptional

tonestring · max: 2000 · nullableOptional

speednumber · nullableOptional

volumenumber · nullableOptional

languagestring · max: 32 · nullableOptional

keytermsstring[] · max: 200 · nullableOptional

pronunciation_dict_idstring · max: 128 · nullableOptional

sensitive_topicsstring[] · max: 50 · nullableOptional

post_call_analysis_enabledboolean · nullableOptional

transcript_correction_enabledboolean · nullableOptional

stt_providerstring · enum · nullableOptionalPossible values:

tts_providerstring · enum · nullableOptionalPossible values:

Responses

200

Successful Response

application/json

Voice experience state — what the PM configured.

voice_idstring · nullableRequired

tonestring · nullableRequired

speednumber · nullableRequired

volumenumber · nullableRequired

languagestringRequired

keytermsstring[]Required

pronunciation_dict_idstring · nullableRequired

sensitive_topicsstring[]Required

post_call_analysis_enabledbooleanRequired

transcript_correction_enabledbooleanRequired

stt_providerstring · enum · nullableRequiredPossible values:

tts_providerstring · enum · nullableRequiredPossible values:

404

Workspace not found

422

Validation error

429

Rate limited

put/v1/{workspace_id}/settings/voice

PUT /v1/{workspace_id}/settings/voice HTTP/1.1
Host: api.platform.amigo.ai
Authorization: Bearer YOUR_SECRET_TOKEN
Content-Type: application/json
Accept: */*
Content-Length: 447

{
  "voice_id": "text",
  "tone": "text",
  "speed": 1,
  "volume": 1,
  "language": "text",
  "keyterms": [
    "text"
  ],
  "pronunciation_dict_id": "text",
  "sensitive_topics": [
    "text"
  ],
  "post_call_analysis_enabled": true,
  "transcript_correction_enabled": true,
  "stt_provider": "deepgram",
  "tts_provider": "cartesia",
  "tts_config": {
    "ANY_ADDITIONAL_PROPERTY": "anything"
  },
  "language_providers": {
    "ANY_ADDITIONAL_PROPERTY": {
      "provider": "cartesia",
      "config": {
        "ANY_ADDITIONAL_PROPERTY": "anything"
      }
    }
  }
}

{
  "voice_id": "text",
  "tone": "text",
  "speed": 1,
  "volume": 1,
  "language": "text",
  "keyterms": [
    "text"
  ],
  "pronunciation_dict_id": "text",
  "sensitive_topics": [
    "text"
  ],
  "post_call_analysis_enabled": true,
  "transcript_correction_enabled": true,
  "stt_provider": "deepgram",
  "tts_provider": "cartesia",
  "tts_config": {
    "ANY_ADDITIONAL_PROPERTY": "anything"
  },
  "language_providers": {
    "ANY_ADDITIONAL_PROPERTY": {
      "provider": "cartesia",
      "config": {
        "ANY_ADDITIONAL_PROPERTY": "anything"
      }
    }
  }
}

Partial updates. The PUT endpoint supports partial updates: omitted fields stay unchanged. You only need to send the fields you want to modify.

Voice Identity & Style

Field	Type	Description
voice_id	string	Voice persona identifier (max 128 chars)
tone	string	Explicit TTS tone override. Typical values: calm, sympathetic, enthusiastic, content, curious, cheerful, serious, friendly
speed	float	Speech rate (0.5-2.0, default 1.0)
volume	float	Volume level (0.0-1.0)
language	string	BCP-47 language tag (default en)

Providers

Field	Type	Description
stt_provider	string	Speech-to-text provider: deepgram, openai, or cartesia
tts_provider	string	Text-to-speech provider: cartesia, elevenlabs, or groq
tts_config	object	Provider-specific TTS configuration; keys depend on tts_provider
language_providers	object	Per-language TTS provider map. Keys are BCP-47 language codes or multilingual

Tone vs emotional adaptation. In the standard voice-context path, an explicit workspace tone overrides the tone computed from acoustic emotion, tone momentum, or sensitive-topic matching. Omit tone if you want the runtime to select a supported tone from those signals. Provider and runtime support still determine how a selected tone is rendered.

Speech Recognition

Field	Type	Description
keyterms	list[string]	Exact words for STT boost, up to 200 entries: ["Dr. Ramirez", "metformin", "amlodipine"]

Keyterms are merged with service-level keyterms and deduplicated. They improve recognition of domain-specific vocabulary: drug names, doctor names, insurance carriers, medical abbreviations. Keyterms are the recommended way to improve transcription accuracy for domain-specific terms.

Pronunciation

Field	Type	Description
pronunciation_dict_id	string	Pronunciation dictionary identifier for domain-specific term pronunciation

Links to a pronunciation dictionary for the voice engine. Use this when the TTS engine mispronounces domain-specific terms (drug names, medical procedures, proper nouns).

Proactive Intelligence

Field	Type	Description
sensitive_topics	list[string]	Topics that trigger preemptive tone softening, up to 50 entries: ["test results", "billing", "surgery"]

When the voice agent's current action matches a sensitive topic, the voice tone preemptively shifts to sympathetic, before the caller shows distress. Falls back to healthcare defaults when not configured.

Post-Call Intelligence

Field	Type	Description
post_call_analysis_enabled	bool	Quality scoring after each call (default true)
transcript_correction_enabled	bool	AI re-transcription for ground-truth accuracy (default true)

See Voice Agent, Post-Call Intelligence for details on what these enable.

How Settings Interact with Emotional Adaptation

Voice settings define workspace-level defaults and overrides. In the standard voice-context path, explicit tone wins over computed emotion tone, while other settings can still be adapted where noted:

Setting	What You Control	What the System Overrides
tone	Explicit workspace TTS tone	Overrides acoustic, momentum, and sensitive-topic tone selection when set
speed	Base speech rate	Can be reduced by supported empathy pacing logic, subject to configured floors
volume	Base volume	Passed through when supported by the selected TTS provider
voice_id	Voice persona	Per-agent voice_config can override for specific agents
keyterms	Domain vocabulary	Merged with service-level keyterms and deduplicated
sensitive_topics	Proactive tone softening	Falls back to defaults when not set

Test Caller Numbers

Manage which phone numbers are authorized for test calls in the workspace. Useful for restricting test/playground calls to known numbers.

Get Test Caller Numbers

Get test caller numbers

get

Get phone numbers configured as test callers for this workspace.

Authorizations

AuthorizationstringRequired

API key issued via POST /v1/{workspace_id}/api-keys. Pass the returned api_key value as a Bearer token.

Path parameters

workspace_idstring · uuidRequired

Responses

200

Successful Response

application/json

numbersstring[]Required

get/v1/workspaces/{workspace_id}/test-caller-numbers

GET /v1/workspaces/{workspace_id}/test-caller-numbers HTTP/1.1
Host: api.platform.amigo.ai
Authorization: Bearer YOUR_SECRET_TOKEN
Accept: */*

200

Successful Response

{
  "numbers": [
    "text"
  ]
}

Update Test Caller Numbers

Update test caller numbers

put

Set phone numbers to be treated as test callers. Calls from these numbers are tagged source='test' and excluded from billing, scores, analytics, outbound EHR sync, and entity views.

Authorizations

AuthorizationstringRequired

API key issued via POST /v1/{workspace_id}/api-keys. Pass the returned api_key value as a Bearer token.

Path parameters

workspace_idstring · uuidRequired

Body

numbersstring[] · max: 100Required

Responses

200

Successful Response

application/json

numbersstring[]Required

422

Validation Error

application/json

put/v1/workspaces/{workspace_id}/test-caller-numbers

PUT /v1/workspaces/{workspace_id}/test-caller-numbers HTTP/1.1
Host: api.platform.amigo.ai
Authorization: Bearer YOUR_SECRET_TOKEN
Content-Type: application/json
Accept: */*
Content-Length: 20

{
  "numbers": [
    "text"
  ]
}

{
  "numbers": [
    "text"
  ]
}

Test Credential IDs

Manage which credentials are authorized for workspace test flows.

Get Test Credential IDs

Get test credential IDs

get

Get the credential IDs configured as test principals for this workspace's text channel.

Authorizations

AuthorizationstringRequired

API key issued via POST /v1/{workspace_id}/api-keys. Pass the returned api_key value as a Bearer token.

Path parameters

workspace_idstring · uuidRequired

Responses

200

Successful Response

application/json

credential_idsstring · uuid[]Required

get/v1/workspaces/{workspace_id}/test-credential-ids

GET /v1/workspaces/{workspace_id}/test-credential-ids HTTP/1.1
Host: api.platform.amigo.ai
Authorization: Bearer YOUR_SECRET_TOKEN
Accept: */*

200

Successful Response

{
  "credential_ids": [
    "123e4567-e89b-12d3-a456-426614174000"
  ]
}

Update Test Credential IDs

Update test credential IDs

put

Set credential IDs to be treated as test principals. Text turns from these credentials are tagged source='test' and excluded from billing, scores, analytics, outbound EHR sync, and entity views.

Authorizations

AuthorizationstringRequired

API key issued via POST /v1/{workspace_id}/api-keys. Pass the returned api_key value as a Bearer token.

Path parameters

workspace_idstring · uuidRequired

Body

credential_idsstring · uuid[] · max: 100Required

Responses

200

Successful Response

application/json

credential_idsstring · uuid[]Required

422

Validation Error

application/json

put/v1/workspaces/{workspace_id}/test-credential-ids

PUT /v1/workspaces/{workspace_id}/test-credential-ids HTTP/1.1
Host: api.platform.amigo.ai
Authorization: Bearer YOUR_SECRET_TOKEN
Content-Type: application/json
Accept: */*
Content-Length: 59

{
  "credential_ids": [
    "123e4567-e89b-12d3-a456-426614174000"
  ]
}

{
  "credential_ids": [
    "123e4567-e89b-12d3-a456-426614174000"
  ]
}