# Workspaces

## Get a workspace

> Retrieve a workspace by ID. Requires \`Workspace.view\` permission.

```json
{"openapi":"3.1.0","info":{"title":"Platform API","version":"1.0.0"},"servers":[{"url":"https://api.platform.amigo.ai","description":"Production"}],"security":[{"BearerAuth":[]}],"components":{"securitySchemes":{"BearerAuth":{"type":"http","scheme":"bearer","description":"API key issued via `POST /v1/{workspace_id}/api-keys`. Pass the returned `api_key` value as a Bearer token."}},"schemas":{"WorkspaceResponse":{"properties":{"id":{"type":"string","format":"uuid","title":"Id"},"slug":{"type":"string","title":"Slug"},"name":{"type":"string","title":"Name"},"environment":{"type":"string","title":"Environment"},"backend_org_id":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Backend Org Id"},"region":{"type":"string","title":"Region"},"connector_type":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Connector Type"},"provisioned_at":{"anyOf":[{"type":"string","format":"date-time"},{"type":"null"}],"title":"Provisioned At"},"created_at":{"type":"string","format":"date-time","title":"Created At"},"updated_at":{"type":"string","format":"date-time","title":"Updated At"}},"type":"object","required":["id","slug","name","environment","backend_org_id","region","connector_type","provisioned_at","created_at","updated_at"],"title":"WorkspaceResponse"}}},"paths":{"/v1/workspaces/{workspace_id}":{"get":{"tags":["Workspaces"],"summary":"Get a workspace","description":"Retrieve a workspace by ID. Requires `Workspace.view` permission.","operationId":"get-workspace","responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/WorkspaceResponse"}}}},"401":{"description":"Missing or invalid API key."},"403":{"description":"Insufficient permissions."},"404":{"description":"Workspace not found."}},"parameters":[{"name":"workspace_id","in":"path","required":true,"schema":{"type":"string","format":"uuid","title":"Workspace Id"}}]}}}}
```

## Update a workspace

> Update workspace fields. Requires \`Workspace.update\` permission.

```json
{"openapi":"3.1.0","info":{"title":"Platform API","version":"1.0.0"},"servers":[{"url":"https://api.platform.amigo.ai","description":"Production"}],"security":[{"BearerAuth":[]}],"components":{"securitySchemes":{"BearerAuth":{"type":"http","scheme":"bearer","description":"API key issued via `POST /v1/{workspace_id}/api-keys`. Pass the returned `api_key` value as a Bearer token."}},"schemas":{"UpdateWorkspaceRequest":{"properties":{"name":{"anyOf":[{"$ref":"#/components/schemas/StrippedNonemptyString"},{"type":"null"}]},"environment":{"anyOf":[{"type":"string","enum":["production","staging","development"]},{"type":"null"}],"title":"Environment"},"region":{"anyOf":[{"type":"string","enum":["us-east-1","ap-southeast-2","eu-central-1","ca-central-1"]},{"type":"null"}],"title":"Region"},"connector_type":{"anyOf":[{"type":"string","enum":["epic","cerner","allscripts","fhir_store","athenahealth","charmhealth","eclinicalworks","meditab"]},{"type":"null"}],"title":"Connector Type"}},"type":"object","title":"UpdateWorkspaceRequest"},"StrippedNonemptyString":{"type":"string","minLength":1},"WorkspaceResponse":{"properties":{"id":{"type":"string","format":"uuid","title":"Id"},"slug":{"type":"string","title":"Slug"},"name":{"type":"string","title":"Name"},"environment":{"type":"string","title":"Environment"},"backend_org_id":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Backend Org Id"},"region":{"type":"string","title":"Region"},"connector_type":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Connector Type"},"provisioned_at":{"anyOf":[{"type":"string","format":"date-time"},{"type":"null"}],"title":"Provisioned At"},"created_at":{"type":"string","format":"date-time","title":"Created At"},"updated_at":{"type":"string","format":"date-time","title":"Updated At"}},"type":"object","required":["id","slug","name","environment","backend_org_id","region","connector_type","provisioned_at","created_at","updated_at"],"title":"WorkspaceResponse"}}},"paths":{"/v1/workspaces/{workspace_id}":{"patch":{"tags":["Workspaces"],"summary":"Update a workspace","description":"Update workspace fields. Requires `Workspace.update` permission.","operationId":"update-workspace","requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/UpdateWorkspaceRequest"}}},"required":true},"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/WorkspaceResponse"}}}},"401":{"description":"Missing or invalid API key."},"403":{"description":"Insufficient permissions."},"404":{"description":"Workspace not found."},"422":{"description":"Invalid request body."}},"parameters":[{"name":"workspace_id","in":"path","required":true,"schema":{"type":"string","format":"uuid","title":"Workspace Id"}}]}}}}
```

## List workspaces

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

```json
{"openapi":"3.1.0","info":{"title":"Platform API","version":"1.0.0"},"servers":[{"url":"https://api.platform.amigo.ai","description":"Production"}],"security":[{"BearerAuth":[]}],"components":{"securitySchemes":{"BearerAuth":{"type":"http","scheme":"bearer","description":"API key issued via `POST /v1/{workspace_id}/api-keys`. Pass the returned `api_key` value as a Bearer token."}},"schemas":{"PaginatedResponse_WorkspaceResponse_":{"properties":{"items":{"items":{"$ref":"#/components/schemas/WorkspaceResponse"},"type":"array","title":"Items"},"has_more":{"type":"boolean","title":"Has More"},"continuation_token":{"anyOf":[{"type":"integer"},{"type":"null"}],"title":"Continuation Token"},"total":{"anyOf":[{"type":"integer"},{"type":"null"}],"title":"Total"}},"type":"object","required":["items","has_more"],"title":"PaginatedResponse[WorkspaceResponse]"},"WorkspaceResponse":{"properties":{"id":{"type":"string","format":"uuid","title":"Id"},"slug":{"type":"string","title":"Slug"},"name":{"type":"string","title":"Name"},"environment":{"type":"string","title":"Environment"},"backend_org_id":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Backend Org Id"},"region":{"type":"string","title":"Region"},"connector_type":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Connector Type"},"provisioned_at":{"anyOf":[{"type":"string","format":"date-time"},{"type":"null"}],"title":"Provisioned At"},"created_at":{"type":"string","format":"date-time","title":"Created At"},"updated_at":{"type":"string","format":"date-time","title":"Updated At"}},"type":"object","required":["id","slug","name","environment","backend_org_id","region","connector_type","provisioned_at","created_at","updated_at"],"title":"WorkspaceResponse"},"HTTPValidationError":{"properties":{"detail":{"items":{"$ref":"#/components/schemas/ValidationError"},"type":"array","title":"Detail"}},"type":"object","title":"HTTPValidationError"},"ValidationError":{"properties":{"loc":{"items":{"anyOf":[{"type":"string"},{"type":"integer"}]},"type":"array","title":"Location"},"msg":{"type":"string","title":"Message"},"type":{"type":"string","title":"Error Type"},"input":{"title":"Input"},"ctx":{"type":"object","title":"Context"}},"type":"object","required":["loc","msg","type"],"title":"ValidationError"}}},"paths":{"/v1/workspaces":{"get":{"tags":["Workspaces"],"summary":"List workspaces","description":"List workspaces accessible to this API key. Requires `Workspace.view` permission.","operationId":"list-workspaces","parameters":[{"name":"limit","in":"query","required":false,"schema":{"type":"integer","maximum":100,"exclusiveMinimum":0,"default":10,"title":"Limit"}},{"name":"continuation_token","in":"query","required":false,"schema":{"type":"integer","default":0,"title":"Continuation Token"}}],"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/PaginatedResponse_WorkspaceResponse_"}}}},"401":{"description":"Missing or invalid API key."},"403":{"description":"Insufficient permissions."},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}}}}
```

## Provision workspace resources

> Seed default IntegrationConfig and mark workspace as provisioned. Idempotent. Requires \`Workspace.update\` permission.

```json
{"openapi":"3.1.0","info":{"title":"Platform API","version":"1.0.0"},"servers":[{"url":"https://api.platform.amigo.ai","description":"Production"}],"security":[{"BearerAuth":[]}],"components":{"securitySchemes":{"BearerAuth":{"type":"http","scheme":"bearer","description":"API key issued via `POST /v1/{workspace_id}/api-keys`. Pass the returned `api_key` value as a Bearer token."}},"schemas":{"ProvisionResponse":{"properties":{"workspace":{"$ref":"#/components/schemas/WorkspaceResponse"}},"type":"object","required":["workspace"],"title":"ProvisionResponse"},"WorkspaceResponse":{"properties":{"id":{"type":"string","format":"uuid","title":"Id"},"slug":{"type":"string","title":"Slug"},"name":{"type":"string","title":"Name"},"environment":{"type":"string","title":"Environment"},"backend_org_id":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Backend Org Id"},"region":{"type":"string","title":"Region"},"connector_type":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Connector Type"},"provisioned_at":{"anyOf":[{"type":"string","format":"date-time"},{"type":"null"}],"title":"Provisioned At"},"created_at":{"type":"string","format":"date-time","title":"Created At"},"updated_at":{"type":"string","format":"date-time","title":"Updated At"}},"type":"object","required":["id","slug","name","environment","backend_org_id","region","connector_type","provisioned_at","created_at","updated_at"],"title":"WorkspaceResponse"}}},"paths":{"/v1/workspaces/{workspace_id}/provision":{"post":{"tags":["Workspaces"],"summary":"Provision workspace resources","description":"Seed default IntegrationConfig and mark workspace as provisioned. Idempotent. Requires `Workspace.update` permission.","operationId":"provision-workspace","responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ProvisionResponse"}}}},"401":{"description":"Missing or invalid API key."},"403":{"description":"Insufficient permissions."},"404":{"description":"Workspace not found."}},"parameters":[{"name":"workspace_id","in":"path","required":true,"schema":{"type":"string","format":"uuid","title":"Workspace Id"}}]}}}}
```

## Archive a workspace

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

```json
{"openapi":"3.1.0","info":{"title":"Platform API","version":"1.0.0"},"servers":[{"url":"https://api.platform.amigo.ai","description":"Production"}],"security":[{"BearerAuth":[]}],"components":{"securitySchemes":{"BearerAuth":{"type":"http","scheme":"bearer","description":"API key issued via `POST /v1/{workspace_id}/api-keys`. Pass the returned `api_key` value as a Bearer token."}},"schemas":{"ArchiveWorkspaceRequest":{"properties":{"slug":{"$ref":"#/components/schemas/SlugString"}},"type":"object","required":["slug"],"title":"ArchiveWorkspaceRequest"},"SlugString":{"type":"string","maxLength":63,"minLength":2,"pattern":"^[a-z0-9][a-z0-9-]*[a-z0-9]$"},"WorkspaceResponse":{"properties":{"id":{"type":"string","format":"uuid","title":"Id"},"slug":{"type":"string","title":"Slug"},"name":{"type":"string","title":"Name"},"environment":{"type":"string","title":"Environment"},"backend_org_id":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Backend Org Id"},"region":{"type":"string","title":"Region"},"connector_type":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Connector Type"},"provisioned_at":{"anyOf":[{"type":"string","format":"date-time"},{"type":"null"}],"title":"Provisioned At"},"created_at":{"type":"string","format":"date-time","title":"Created At"},"updated_at":{"type":"string","format":"date-time","title":"Updated At"}},"type":"object","required":["id","slug","name","environment","backend_org_id","region","connector_type","provisioned_at","created_at","updated_at"],"title":"WorkspaceResponse"}}},"paths":{"/v1/workspaces/{workspace_id}/archive":{"post":{"tags":["Workspaces"],"summary":"Archive a workspace","description":"Archive a workspace and remove it from active access flows while preserving underlying data. Requires owner access and slug confirmation.","operationId":"archive-workspace","requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ArchiveWorkspaceRequest"}}},"required":true},"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/WorkspaceResponse"}}}},"401":{"description":"Missing or invalid API key."},"403":{"description":"Only owners can archive a workspace."},"404":{"description":"Workspace not found."},"422":{"description":"Workspace slug confirmation did not match."}},"parameters":[{"name":"workspace_id","in":"path","required":true,"schema":{"type":"string","format":"uuid","title":"Workspace Id"}}]}}}}
```

## Pre-check environment conversion

> Returns compliance warnings for converting between staging and production. Does not mutate.

```json
{"openapi":"3.1.0","info":{"title":"Platform API","version":"1.0.0"},"servers":[{"url":"https://api.platform.amigo.ai","description":"Production"}],"security":[{"BearerAuth":[]}],"components":{"securitySchemes":{"BearerAuth":{"type":"http","scheme":"bearer","description":"API key issued via `POST /v1/{workspace_id}/api-keys`. Pass the returned `api_key` value as a Bearer token."}},"schemas":{"EnvironmentCheckResponse":{"properties":{"current":{"type":"string","title":"Current"},"target":{"type":"string","title":"Target"},"warnings":{"items":{"type":"string"},"type":"array","title":"Warnings"}},"type":"object","required":["current","target","warnings"],"title":"EnvironmentCheckResponse"},"HTTPValidationError":{"properties":{"detail":{"items":{"$ref":"#/components/schemas/ValidationError"},"type":"array","title":"Detail"}},"type":"object","title":"HTTPValidationError"},"ValidationError":{"properties":{"loc":{"items":{"anyOf":[{"type":"string"},{"type":"integer"}]},"type":"array","title":"Location"},"msg":{"type":"string","title":"Message"},"type":{"type":"string","title":"Error Type"},"input":{"title":"Input"},"ctx":{"type":"object","title":"Context"}},"type":"object","required":["loc","msg","type"],"title":"ValidationError"}}},"paths":{"/v1/workspaces/{workspace_id}/environment-check":{"get":{"tags":["Workspaces"],"summary":"Pre-check environment conversion","description":"Returns compliance warnings for converting between staging and production. Does not mutate.","operationId":"check-environment-conversion","parameters":[{"name":"workspace_id","in":"path","required":true,"schema":{"type":"string","format":"uuid","title":"Workspace Id"}},{"name":"target","in":"query","required":false,"schema":{"enum":["production","staging"],"type":"string","default":"production","title":"Target"}}],"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/EnvironmentCheckResponse"}}}},"401":{"description":"Missing or invalid API key."},"403":{"description":"Insufficient permissions."},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}}}}
```

## Convert workspace environment

> Convert workspace between staging and production. Requires slug confirmation.

```json
{"openapi":"3.1.0","info":{"title":"Platform API","version":"1.0.0"},"servers":[{"url":"https://api.platform.amigo.ai","description":"Production"}],"security":[{"BearerAuth":[]}],"components":{"securitySchemes":{"BearerAuth":{"type":"http","scheme":"bearer","description":"API key issued via `POST /v1/{workspace_id}/api-keys`. Pass the returned `api_key` value as a Bearer token."}},"schemas":{"ConvertEnvironmentRequest":{"properties":{"target":{"type":"string","enum":["production","staging"],"title":"Target"},"confirm_slug":{"$ref":"#/components/schemas/SlugString"}},"type":"object","required":["target","confirm_slug"],"title":"ConvertEnvironmentRequest"},"SlugString":{"type":"string","maxLength":63,"minLength":2,"pattern":"^[a-z0-9][a-z0-9-]*[a-z0-9]$"},"WorkspaceResponse":{"properties":{"id":{"type":"string","format":"uuid","title":"Id"},"slug":{"type":"string","title":"Slug"},"name":{"type":"string","title":"Name"},"environment":{"type":"string","title":"Environment"},"backend_org_id":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Backend Org Id"},"region":{"type":"string","title":"Region"},"connector_type":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Connector Type"},"provisioned_at":{"anyOf":[{"type":"string","format":"date-time"},{"type":"null"}],"title":"Provisioned At"},"created_at":{"type":"string","format":"date-time","title":"Created At"},"updated_at":{"type":"string","format":"date-time","title":"Updated At"}},"type":"object","required":["id","slug","name","environment","backend_org_id","region","connector_type","provisioned_at","created_at","updated_at"],"title":"WorkspaceResponse"}}},"paths":{"/v1/workspaces/{workspace_id}/convert-environment":{"post":{"tags":["Workspaces"],"summary":"Convert workspace environment","description":"Convert workspace between staging and production. Requires slug confirmation.","operationId":"convert-workspace-environment","requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ConvertEnvironmentRequest"}}},"required":true},"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/WorkspaceResponse"}}}},"401":{"description":"Missing or invalid API key."},"403":{"description":"Insufficient permissions."},"404":{"description":"Workspace not found."},"422":{"description":"Workspace slug confirmation did not match."}},"parameters":[{"name":"workspace_id","in":"path","required":true,"schema":{"type":"string","format":"uuid","title":"Workspace Id"}}]}}}}
```

## Get test caller numbers

> Get phone numbers configured as test callers for this workspace.

```json
{"openapi":"3.1.0","info":{"title":"Platform API","version":"1.0.0"},"servers":[{"url":"https://api.platform.amigo.ai","description":"Production"}],"security":[{"BearerAuth":[]}],"components":{"securitySchemes":{"BearerAuth":{"type":"http","scheme":"bearer","description":"API key issued via `POST /v1/{workspace_id}/api-keys`. Pass the returned `api_key` value as a Bearer token."}},"schemas":{"TestCallerNumbersResponse":{"properties":{"numbers":{"items":{"type":"string"},"type":"array","title":"Numbers"}},"type":"object","required":["numbers"],"title":"TestCallerNumbersResponse"}}},"paths":{"/v1/workspaces/{workspace_id}/test-caller-numbers":{"get":{"tags":["Workspaces"],"summary":"Get test caller numbers","description":"Get phone numbers configured as test callers for this workspace.","operationId":"get-test-caller-numbers","responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/TestCallerNumbersResponse"}}}}},"parameters":[{"name":"workspace_id","in":"path","required":true,"schema":{"type":"string","format":"uuid","title":"Workspace Id"}}]}}}}
```

## Update test caller numbers

> Set phone numbers to be treated as test callers. Calls from these numbers will have direction='test' and be excluded from outbound EHR sync.

```json
{"openapi":"3.1.0","info":{"title":"Platform API","version":"1.0.0"},"servers":[{"url":"https://api.platform.amigo.ai","description":"Production"}],"security":[{"BearerAuth":[]}],"components":{"securitySchemes":{"BearerAuth":{"type":"http","scheme":"bearer","description":"API key issued via `POST /v1/{workspace_id}/api-keys`. Pass the returned `api_key` value as a Bearer token."}},"schemas":{"TestCallerNumbersRequest":{"properties":{"numbers":{"items":{"type":"string"},"type":"array","maxItems":100,"title":"Numbers"}},"type":"object","required":["numbers"],"title":"TestCallerNumbersRequest"},"TestCallerNumbersResponse":{"properties":{"numbers":{"items":{"type":"string"},"type":"array","title":"Numbers"}},"type":"object","required":["numbers"],"title":"TestCallerNumbersResponse"},"HTTPValidationError":{"properties":{"detail":{"items":{"$ref":"#/components/schemas/ValidationError"},"type":"array","title":"Detail"}},"type":"object","title":"HTTPValidationError"},"ValidationError":{"properties":{"loc":{"items":{"anyOf":[{"type":"string"},{"type":"integer"}]},"type":"array","title":"Location"},"msg":{"type":"string","title":"Message"},"type":{"type":"string","title":"Error Type"},"input":{"title":"Input"},"ctx":{"type":"object","title":"Context"}},"type":"object","required":["loc","msg","type"],"title":"ValidationError"}}},"paths":{"/v1/workspaces/{workspace_id}/test-caller-numbers":{"put":{"tags":["Workspaces"],"summary":"Update test caller numbers","description":"Set phone numbers to be treated as test callers. Calls from these numbers will have direction='test' and be excluded from outbound EHR sync.","operationId":"update-test-caller-numbers","requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/TestCallerNumbersRequest"}}},"required":true},"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/TestCallerNumbersResponse"}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}},"parameters":[{"name":"workspace_id","in":"path","required":true,"schema":{"type":"string","format":"uuid","title":"Workspace Id"}}]}}}}
```


---

# Agent Instructions: 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:

```
GET https://docs.amigo.ai/api-reference/readme/platform/workspaces.md?ask=<question>
```

The question should be specific, self-contained, and written in natural language.
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.