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.

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.

Archive

POST /v1/workspaces/{workspace_id}/archive removes a workspace from active access flows while preserving all underlying data. Requires 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

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 - GET /v1/workspaces/{workspace_id}/environment-check?target={environment} returns the current environment, target environment, and a list of compliance warnings that will take effect after conversion. This endpoint does not mutate the workspace.

Convert - POST /v1/workspaces/{workspace_id}/convert-environment performs the conversion. The request body requires a target ("production" or "staging") and a confirm_slug that must match the workspace slug to prevent accidental changes.

Converting to production activates stricter session timeouts, HITRUST compliance controls, and enhanced audit retention. Converting to staging relaxes these controls. The conversion is immediate and affects all active sessions on their next token refresh.

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

Voice Settings

Voice settings control the workspace-level voice pipeline, affecting all voice conversations. Configure them via GET / PUT on the settings/voice endpoint.

GET  /v1/{workspace_id}/settings/voice
PUT  /v1/{workspace_id}/settings/voice

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	Emotional baseline. 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. The tone setting provides the baseline for neutral callers. When the voice agent detects strong caller emotion, it overrides the baseline tone, always in the direction of more empathy. For example, if you set tone: "friendly", neutral callers hear a friendly voice, but an anxious caller still hears sympathetic.

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.

For the authoritative voice settings schema, see the Settings API reference.

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 the baseline experience. The voice agent's emotional intelligence system overrides the baseline only when it detects a strong signal, and always toward more empathy:

Setting	What You Control	What the System Overrides
tone	Baseline voice emotion	Replaced by emotion-derived tone when strong emotion detected
speed	Base speech rate	Never overridden (your choice is respected)
volume	Base volume	Never overridden
voice_id	Voice persona	Per-agent voice_config can override for specific agents
keyterms	Domain vocabulary	Always additive (merged with service-level keyterms)
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.

API Reference

• Workspaces