> For the complete documentation index, see [llms.txt](https://docs.concurrence.com/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.concurrence.com/developer-guide/platform-api/workspaces.md).

# 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`)
* **Regional endpoint**: responses report the deployment serving the request; region is not an editable workspace placement policy
* **Backend Org ID**: Links to the Classic API organization, bridging the two API surfaces

{% hint style="info" %}
**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`.
{% endhint %}

## Workspace Resource

### List Workspaces

{% openapi src="<https://api.platform.amigo.ai/v1/openapi.json>" path="/v1/workspaces" method="get" %}
<https://api.platform.amigo.ai/v1/openapi.json>
{% endopenapi %}

### Get a Workspace

{% openapi src="<https://api.platform.amigo.ai/v1/openapi.json>" path="/v1/workspaces/{workspace\_id}" method="get" %}
<https://api.platform.amigo.ai/v1/openapi.json>
{% endopenapi %}

### Update a Workspace

{% openapi src="<https://api.platform.amigo.ai/v1/openapi.json>" path="/v1/workspaces/{workspace\_id}" method="patch" %}
<https://api.platform.amigo.ai/v1/openapi.json>
{% endopenapi %}

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

{% openapi src="<https://api.platform.amigo.ai/v1/openapi.json>" path="/v1/workspaces/{workspace\_id}/provision" method="post" %}
<https://api.platform.amigo.ai/v1/openapi.json>
{% endopenapi %}

## Archive

{% openapi src="<https://api.platform.amigo.ai/v1/openapi.json>" path="/v1/workspaces/{workspace\_id}/archive" method="post" %}
<https://api.platform.amigo.ai/v1/openapi.json>
{% endopenapi %}

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

{% hint style="info" %}
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, settings, and test configuration.
{% endhint %}

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 Separation

The former environment-check and staging/production conversion routes have been removed. The current workspace update contract does not include an environment label. Use separately provisioned workspaces for development, testing, and production, with the appropriate access, integration, and retention policies.

The legacy region update field is accepted but ignored. Its presence in a request does not move data or change the serving deployment's reported region. See [Regions and Endpoints](/developer-guide/getting-started/regions-and-endpoints.md).

## Optional Data Exposure

Topic modeling and Delta Sharing are separate opt-in settings, disabled by default. Delta Sharing supports open sharing and a recipient identified by a sharing identifier. Use the embedded workspace update schema for the mode and identifier requirements.

Saving a setting and applying its data grants are separate steps. Enabling a capability can require asynchronous provisioning. Disabling exposure or changing an active recipient requests reconciliation; if it cannot be queued, the request reports failure after the setting has been saved. Retry and verify actual access rather than treating the stored setting alone as proof of revocation.

## Voice Settings

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

### Get Voice Settings

{% openapi src="<https://api.platform.amigo.ai/v1/openapi.json>" path="/v1/{workspace\_id}/settings/voice" method="get" %}
<https://api.platform.amigo.ai/v1/openapi.json>
{% endopenapi %}

### Update Voice Settings

{% openapi src="<https://api.platform.amigo.ai/v1/openapi.json>" path="/v1/{workspace\_id}/settings/voice" method="put" %}
<https://api.platform.amigo.ai/v1/openapi.json>
{% endopenapi %}

{% hint style="info" %}
**Partial updates.** The `PUT` endpoint supports partial updates: omitted fields stay unchanged. You only need to send the fields you want to modify.
{% endhint %}

### 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` |

{% hint style="info" %}
**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.
{% endhint %}

### 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](/developer-guide/platform-api/conversations/voice-agent.md#layer-5-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

{% openapi src="<https://api.platform.amigo.ai/v1/openapi.json>" path="/v1/workspaces/{workspace\_id}/test-caller-numbers" method="get" %}
<https://api.platform.amigo.ai/v1/openapi.json>
{% endopenapi %}

### Update Test Caller Numbers

{% openapi src="<https://api.platform.amigo.ai/v1/openapi.json>" path="/v1/workspaces/{workspace\_id}/test-caller-numbers" method="put" %}
<https://api.platform.amigo.ai/v1/openapi.json>
{% endopenapi %}

## Test Credential IDs

Manage which credentials are authorized for workspace test flows.

### Get Test Credential IDs

{% openapi src="<https://api.platform.amigo.ai/v1/openapi.json>" path="/v1/workspaces/{workspace\_id}/test-credential-ids" method="get" %}
<https://api.platform.amigo.ai/v1/openapi.json>
{% endopenapi %}

### Update Test Credential IDs

{% openapi src="<https://api.platform.amigo.ai/v1/openapi.json>" path="/v1/workspaces/{workspace\_id}/test-credential-ids" method="put" %}
<https://api.platform.amigo.ai/v1/openapi.json>
{% endopenapi %}


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter, and the optional `goal` query parameter:

```
GET https://docs.concurrence.com/developer-guide/platform-api/workspaces.md?ask=<question>&goal=<endgoal>
```

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is optional and describes the broader end goal you are ultimately trying to accomplish on behalf of the user. GitBook uses it to tailor the answer towards what is most useful for that goal.

The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.