# Workspaces

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

{% 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 %}

## Provisioning

After creating a workspace, call the provision endpoint to set up default resources (telephony account, initial configuration). This is idempotent - safe to call multiple times.

## 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 /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 / Decline** - The invited user can accept or decline from their pending invitations list.
* **Revoke** - Workspace admins can revoke pending invitations.

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

## Voice Settings

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

```
GET  /v1/workspaces/{workspace_id}/voice-settings
PUT  /v1/workspaces/{workspace_id}/voice-settings
```

{% hint style="info" %}
**Partial updates**: The `PUT` endpoint supports partial updates - omitted fields remain 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                                                                                           |
| `tone`     | string | Emotional baseline: `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`)                                                                                 |

{% hint style="info" %}
**Tone vs emotional adaptation**: The `tone` setting provides the baseline for neutral callers. When the [voice agent](https://docs.amigo.ai/developer-guide/platform-api/voice-agent#emotional-adaptation) 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`.
{% endhint %}

### Speech Recognition

| Field      | Type          | Description                                                             |
| ---------- | ------------- | ----------------------------------------------------------------------- |
| `keyterms` | list\[string] | Exact words for STT boost: `["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.

### Audio Correction

| Field                   | Type          | Description                                                                              |
| ----------------------- | ------------- | ---------------------------------------------------------------------------------------- |
| `correction_categories` | list\[string] | Broad domain hints: `["medication names", "insurance carriers", "patient demographics"]` |

Correction categories are injected into the AI audio correction system as domain context. Unlike keyterms (exact word matches), these are broad hints that tell the correction model what types of words to pay extra attention to.

{% hint style="info" %}
**Keyterms vs Correction Categories**: `keyterms` boost exact words in the speech-to-text engine (e.g., `"metformin"`). `correction_categories` are broad domain hints for AI audio correction (e.g., `"medication names"`). They serve different purposes and are not interchangeable.
{% endhint %}

### 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: `["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](https://docs.amigo.ai/developer-guide/platform-api/voice-agent#layer-5-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](https://docs.amigo.ai/api-reference/readme/platform/workspaces)