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

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

## 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, environment conversion, 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 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

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

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

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

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

{% 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.amigo.ai/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.