# Workspaces

## 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","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":20,"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"}}}}}}}}}
```

## Create a workspace

> Bootstrap a new workspace. No authentication required.

```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":{"CreateWorkspaceRequest":{"properties":{"slug":{"$ref":"#/components/schemas/SlugString"},"name":{"$ref":"#/components/schemas/StrippedNonemptyString"},"environment":{"type":"string","enum":["production","staging","development"],"title":"Environment"},"region":{"type":"string","enum":["us-east-1","ap-southeast-2","eu-central-1","ca-central-1"],"title":"Region","default":"us-east-1"},"backend_org_id":{"anyOf":[{"$ref":"#/components/schemas/StrippedNonemptyString"},{"type":"null"}]}},"type":"object","required":["slug","name","environment"],"title":"CreateWorkspaceRequest"},"SlugString":{"type":"string","maxLength":63,"minLength":2,"pattern":"^[a-z0-9][a-z0-9-]*[a-z0-9]$"},"StrippedNonemptyString":{"type":"string","minLength":1},"WorkspaceResponse":{"properties":{"id":{"type":"string","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":{"post":{"tags":["Workspaces"],"summary":"Create a workspace","description":"Bootstrap a new workspace. No authentication required.","operationId":"create-workspace","requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/CreateWorkspaceRequest"}}}},"responses":{"201":{"description":"Successful Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/WorkspaceResponse"}}}},"409":{"description":"Workspace slug already taken."},"422":{"description":"Invalid request body."}}}}}}
```

## Create a workspace for the authenticated user

> Create a new workspace and attach the authenticated caller as the owner.

```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":{"CreateWorkspaceRequest":{"properties":{"slug":{"$ref":"#/components/schemas/SlugString"},"name":{"$ref":"#/components/schemas/StrippedNonemptyString"},"environment":{"type":"string","enum":["production","staging","development"],"title":"Environment"},"region":{"type":"string","enum":["us-east-1","ap-southeast-2","eu-central-1","ca-central-1"],"title":"Region","default":"us-east-1"},"backend_org_id":{"anyOf":[{"$ref":"#/components/schemas/StrippedNonemptyString"},{"type":"null"}]}},"type":"object","required":["slug","name","environment"],"title":"CreateWorkspaceRequest"},"SlugString":{"type":"string","maxLength":63,"minLength":2,"pattern":"^[a-z0-9][a-z0-9-]*[a-z0-9]$"},"StrippedNonemptyString":{"type":"string","minLength":1},"WorkspaceResponse":{"properties":{"id":{"type":"string","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/self-service":{"post":{"tags":["Workspaces"],"summary":"Create a workspace for the authenticated user","description":"Create a new workspace and attach the authenticated caller as the owner.","operationId":"create-self-service-workspace","requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/CreateWorkspaceRequest"}}},"required":true},"responses":{"201":{"description":"Successful Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/WorkspaceResponse"}}}},"403":{"description":"Insufficient permissions or unsupported principal type."},"409":{"description":"Workspace slug already taken."},"422":{"description":"Invalid request body."},"503":{"description":"Identity service unavailable."}}}}}}
```

## 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","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."}}}}}}
```

## 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":["revolution","epic","cerner","allscripts","fhir_store","hubspot","athenahealth","charmhealth","eclinicalworks","meditab"]},{"type":"null"}],"title":"Connector Type"}},"type":"object","title":"UpdateWorkspaceRequest"},"StrippedNonemptyString":{"type":"string","minLength":1},"WorkspaceResponse":{"properties":{"id":{"type":"string","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."}}}}}}
```

## 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","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."}}}}}}
```

## 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","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."}}}}}}
```

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

## 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":20,"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"}}}}}}}}}
```