# Workspaces

## List workspaces

> List the workspaces for the organization.

```json
{"openapi":"3.0.3","info":{"title":"Accounts","version":"v1"},"tags":[{"description":"Manage organization workspaces.","name":"organization_workspace"}],"servers":[{"url":"https://api.bird.com","description":"Production API"}],"security":[{"accessKey":[]}],"components":{"securitySchemes":{"accessKey":{"description":"Uses the Authorization header: 'AccessKey ' followed by your access key token (e.g., 'Authorization: AccessKey AbCdEfGhIjKlMnOpQrStUvWxYzAbCdEfGhIj')","scheme":"AccessKey","type":"http"}},"parameters":{"limit":{"name":"limit","description":"Limits the number of results to return","in":"query","schema":{"type":"integer","minimum":1,"maximum":100,"default":10}},"cursor":{"name":"pageToken","description":"Pagination token that keeps of track of the current position in the list","in":"query","schema":{"type":"string"}},"direction":{"name":"reverse","description":"Order in which to retrieve the results","in":"query","schema":{"type":"boolean","default":false}}},"schemas":{"WorkspaceList":{"type":"object","description":"List of workspaces.","properties":{"results":{"type":"array","description":"List of results.","items":{"$ref":"#/components/schemas/Workspace"}}},"required":["results"]},"Workspace":{"title":"Workspace","description":"The workspace record.","type":"object","additionalProperties":false,"properties":{"id":{"type":"string","description":"Workspace ID.","format":"uuid"},"organizationId":{"type":"string","description":"ID of the organization this workspace is part of.","format":"uuid"},"status":{"$ref":"#/components/schemas/WorkspaceStatus"},"statusTransitions":{"type":"array","items":{"$ref":"#/components/schemas/WorkspaceStatusTransition"}},"name":{"$ref":"#/components/schemas/WorkspaceName"},"description":{"$ref":"#/components/schemas/WorkspaceDescription"},"dataPolicy":{"$ref":"#/components/schemas/DataPolicy"},"configuration":{"$ref":"#/components/schemas/WorkspaceConfiguration"},"createdAt":{"type":"string","format":"date-time","description":"When the workspace was created."},"updatedAt":{"type":"string","format":"date-time","description":"When the workspace was last updated."}},"required":["id","organizationId","status","name","dataPolicy","createdAt","updatedAt"]},"WorkspaceStatus":{"type":"string","description":"Status of the workspace","enum":["active","disabled","terminated","deleted"]},"WorkspaceStatusTransition":{"type":"object","description":"Workspace status transition","required":["fromStatus","toStatus","reason","transitionedAt","transitionedBy"],"properties":{"fromStatus":{"$ref":"#/components/schemas/WorkspaceStatus"},"toStatus":{"$ref":"#/components/schemas/WorkspaceStatus"},"reason":{"type":"string","enum":["org-banned","user-initiated","payment-default","inactivity"]},"comment":{"type":"string"},"transitionedAt":{"type":"string","format":"date-time"},"transitionedBy":{"$ref":"#/components/schemas/RequestSubject"}}},"RequestSubject":{"required":["type","id"],"properties":{"type":{"$ref":"#/components/schemas/RequestSubjectType"},"id":{"type":"string","format":"uuid"}}},"RequestSubjectType":{"type":"string","enum":["user","accesskey","contact"]},"WorkspaceName":{"type":"string","description":"The display name for the workspace","minLength":1,"maxLength":256},"WorkspaceDescription":{"type":"string","description":"The description for the workspace","minLength":1,"maxLength":256},"DataPolicy":{"type":"object","title":"DataPolicy","description":"The data storage policy for a resource.","properties":{"group":{"type":"string","description":"The name of the region group used for storage."},"regions":{"type":"array","items":{"type":"object","title":"RegionPriority","properties":{"region":{"type":"string","description":"The name of the AWS region."},"priority":{"type":"integer","minimum":0,"description":"The priority to give to this region when storing data."}},"required":["region","priority"]}},"piiStrategy":{"type":"string","enum":["default","strict"]}},"required":["group","regions","piiStrategy"]},"WorkspaceConfiguration":{"type":"object","additionalProperties":false,"properties":{"domain":{"$ref":"#/components/schemas/DomainName"}}},"DomainName":{"type":"string","description":"Domain name.","format":"domain","pattern":"^(([a-zA-Z0-9]([a-zA-Z0-9\\-]{0,61}[a-zA-Z0-9])?\\.)+[a-zA-Z]{2,})?$","maxLength":253},"responseBody":{"type":"object","title":"PaginatedList","description":"A list of results that supports pagination.","properties":{"nextPageToken":{"type":"string","description":"The token to fetch the next page of results. If empty, there are no more results to fetch."}}},"Error":{"type":"object","required":["code","message"],"properties":{"code":{"type":"string","description":"Unique identifier for the error that occurred"},"message":{"type":"string","description":"Description of the error that occurred, aimed at API consumers"}}}},"responses":{"unauthorized":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}},"description":"unauthorized request"},"notFound":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}},"description":"Resource not found"}}},"paths":{"/organizations/{organizationId}/workspaces":{"get":{"description":"List the workspaces for the organization.","operationId":"listWorkspaces","parameters":[{"$ref":"#/components/parameters/limit"},{"$ref":"#/components/parameters/cursor"},{"$ref":"#/components/parameters/direction"}],"responses":{"200":{"content":{"application/json":{"schema":{"allOf":[{"$ref":"#/components/schemas/WorkspaceList"},{"$ref":"#/components/schemas/responseBody"}]}}},"description":"OK"},"401":{"$ref":"#/components/responses/unauthorized"},"404":{"$ref":"#/components/responses/notFound"}},"summary":"List workspaces","tags":["organization_workspace"]}}}}
```

## Create workspace

> Create a workspace for the organization.

```json
{"openapi":"3.0.3","info":{"title":"Accounts","version":"v1"},"tags":[{"description":"Manage organization workspaces.","name":"organization_workspace"}],"servers":[{"url":"https://api.bird.com","description":"Production API"}],"security":[{"accessKey":[]}],"components":{"securitySchemes":{"accessKey":{"description":"Uses the Authorization header: 'AccessKey ' followed by your access key token (e.g., 'Authorization: AccessKey AbCdEfGhIjKlMnOpQrStUvWxYzAbCdEfGhIj')","scheme":"AccessKey","type":"http"}},"schemas":{"CreateWorkspace":{"type":"object","additionalProperties":false,"properties":{"name":{"$ref":"#/components/schemas/WorkspaceName"},"description":{"$ref":"#/components/schemas/WorkspaceDescription"},"dataPolicy":{"$ref":"#/components/schemas/DataPolicyCreate"},"configuration":{"nullable":true,"$ref":"#/components/schemas/WorkspaceConfiguration"},"userUsername":{"nullable":true,"description":"The username of the user that is creating the workspace.","$ref":"#/components/schemas/WorkspaceIdentifier"},"flavors":{"nullable":true,"type":"array","items":{"type":"string"}}},"required":["name","dataPolicy"]},"WorkspaceName":{"type":"string","description":"The display name for the workspace","minLength":1,"maxLength":256},"WorkspaceDescription":{"type":"string","description":"The description for the workspace","minLength":1,"maxLength":256},"DataPolicyCreate":{"type":"object","title":"DataPolicy","description":"The data storage policy for a resource.","properties":{"group":{"type":"string","description":"The name of the region group used for storage. Must be one of `us-west-2`, `eu-west-1`, or `ap-south-1`."},"regions":{"type":"array","items":{"type":"object","title":"RegionPriority","properties":{"region":{"type":"string","description":"The name of the AWS region. Must be one of `us-west-2`, `eu-west-1`, or `ap-south-1`."},"priority":{"type":"integer","minimum":0,"description":"The priority to give to this region when storing data."}},"required":["region","priority"]}}},"required":["group","regions"]},"WorkspaceConfiguration":{"type":"object","additionalProperties":false,"properties":{"domain":{"$ref":"#/components/schemas/DomainName"}}},"DomainName":{"type":"string","description":"Domain name.","format":"domain","pattern":"^(([a-zA-Z0-9]([a-zA-Z0-9\\-]{0,61}[a-zA-Z0-9])?\\.)+[a-zA-Z]{2,})?$","maxLength":253},"WorkspaceIdentifier":{"type":"string","pattern":"^[a-z0-9._-]+$","description":"The identifier of the resource inside the workspace.  Takes the form of the user component of an email address.\n"},"Workspace":{"title":"Workspace","description":"The workspace record.","type":"object","additionalProperties":false,"properties":{"id":{"type":"string","description":"Workspace ID.","format":"uuid"},"organizationId":{"type":"string","description":"ID of the organization this workspace is part of.","format":"uuid"},"status":{"$ref":"#/components/schemas/WorkspaceStatus"},"statusTransitions":{"type":"array","items":{"$ref":"#/components/schemas/WorkspaceStatusTransition"}},"name":{"$ref":"#/components/schemas/WorkspaceName"},"description":{"$ref":"#/components/schemas/WorkspaceDescription"},"dataPolicy":{"$ref":"#/components/schemas/DataPolicy"},"configuration":{"$ref":"#/components/schemas/WorkspaceConfiguration"},"createdAt":{"type":"string","format":"date-time","description":"When the workspace was created."},"updatedAt":{"type":"string","format":"date-time","description":"When the workspace was last updated."}},"required":["id","organizationId","status","name","dataPolicy","createdAt","updatedAt"]},"WorkspaceStatus":{"type":"string","description":"Status of the workspace","enum":["active","disabled","terminated","deleted"]},"WorkspaceStatusTransition":{"type":"object","description":"Workspace status transition","required":["fromStatus","toStatus","reason","transitionedAt","transitionedBy"],"properties":{"fromStatus":{"$ref":"#/components/schemas/WorkspaceStatus"},"toStatus":{"$ref":"#/components/schemas/WorkspaceStatus"},"reason":{"type":"string","enum":["org-banned","user-initiated","payment-default","inactivity"]},"comment":{"type":"string"},"transitionedAt":{"type":"string","format":"date-time"},"transitionedBy":{"$ref":"#/components/schemas/RequestSubject"}}},"RequestSubject":{"required":["type","id"],"properties":{"type":{"$ref":"#/components/schemas/RequestSubjectType"},"id":{"type":"string","format":"uuid"}}},"RequestSubjectType":{"type":"string","enum":["user","accesskey","contact"]},"DataPolicy":{"type":"object","title":"DataPolicy","description":"The data storage policy for a resource.","properties":{"group":{"type":"string","description":"The name of the region group used for storage."},"regions":{"type":"array","items":{"type":"object","title":"RegionPriority","properties":{"region":{"type":"string","description":"The name of the AWS region."},"priority":{"type":"integer","minimum":0,"description":"The priority to give to this region when storing data."}},"required":["region","priority"]}},"piiStrategy":{"type":"string","enum":["default","strict"]}},"required":["group","regions","piiStrategy"]},"Error":{"type":"object","required":["code","message"],"properties":{"code":{"type":"string","description":"Unique identifier for the error that occurred"},"message":{"type":"string","description":"Description of the error that occurred, aimed at API consumers"}}},"DetailedError":{"type":"object","required":["code","message"],"properties":{"code":{"type":"string","description":"Unique identifier for the error that occurred"},"message":{"type":"string","description":"Description of the error that occurred, aimed at API consumers"},"details":{"type":"object","description":"Detailed information on where the error exists, usually the field name on the request payload","additionalProperties":{"type":"array","description":"The error description for the specific detail","items":{"type":"string"}}}}}},"responses":{"notFound":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}},"description":"Resource not found"},"invalidRequest":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/DetailedError"}}},"description":"Request validation failed"}}},"paths":{"/organizations/{organizationId}/workspaces":{"post":{"description":"Create a workspace for the organization.","operationId":"createWorkspace","requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/CreateWorkspace"}}}},"responses":{"201":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Workspace"}}},"description":"Created"},"404":{"$ref":"#/components/responses/notFound"},"422":{"$ref":"#/components/responses/invalidRequest"}},"summary":"Create workspace","tags":["organization_workspace"]}}}}
```

## Get workspace

> Get the workspace instance.

```json
{"openapi":"3.0.3","info":{"title":"Accounts","version":"v1"},"tags":[{"description":"Manage organization workspaces.","name":"organization_workspace"}],"servers":[{"url":"https://api.bird.com","description":"Production API"}],"security":[{"accessKey":[]}],"components":{"securitySchemes":{"accessKey":{"description":"Uses the Authorization header: 'AccessKey ' followed by your access key token (e.g., 'Authorization: AccessKey AbCdEfGhIjKlMnOpQrStUvWxYzAbCdEfGhIj')","scheme":"AccessKey","type":"http"}},"schemas":{"Workspace":{"title":"Workspace","description":"The workspace record.","type":"object","additionalProperties":false,"properties":{"id":{"type":"string","description":"Workspace ID.","format":"uuid"},"organizationId":{"type":"string","description":"ID of the organization this workspace is part of.","format":"uuid"},"status":{"$ref":"#/components/schemas/WorkspaceStatus"},"statusTransitions":{"type":"array","items":{"$ref":"#/components/schemas/WorkspaceStatusTransition"}},"name":{"$ref":"#/components/schemas/WorkspaceName"},"description":{"$ref":"#/components/schemas/WorkspaceDescription"},"dataPolicy":{"$ref":"#/components/schemas/DataPolicy"},"configuration":{"$ref":"#/components/schemas/WorkspaceConfiguration"},"createdAt":{"type":"string","format":"date-time","description":"When the workspace was created."},"updatedAt":{"type":"string","format":"date-time","description":"When the workspace was last updated."}},"required":["id","organizationId","status","name","dataPolicy","createdAt","updatedAt"]},"WorkspaceStatus":{"type":"string","description":"Status of the workspace","enum":["active","disabled","terminated","deleted"]},"WorkspaceStatusTransition":{"type":"object","description":"Workspace status transition","required":["fromStatus","toStatus","reason","transitionedAt","transitionedBy"],"properties":{"fromStatus":{"$ref":"#/components/schemas/WorkspaceStatus"},"toStatus":{"$ref":"#/components/schemas/WorkspaceStatus"},"reason":{"type":"string","enum":["org-banned","user-initiated","payment-default","inactivity"]},"comment":{"type":"string"},"transitionedAt":{"type":"string","format":"date-time"},"transitionedBy":{"$ref":"#/components/schemas/RequestSubject"}}},"RequestSubject":{"required":["type","id"],"properties":{"type":{"$ref":"#/components/schemas/RequestSubjectType"},"id":{"type":"string","format":"uuid"}}},"RequestSubjectType":{"type":"string","enum":["user","accesskey","contact"]},"WorkspaceName":{"type":"string","description":"The display name for the workspace","minLength":1,"maxLength":256},"WorkspaceDescription":{"type":"string","description":"The description for the workspace","minLength":1,"maxLength":256},"DataPolicy":{"type":"object","title":"DataPolicy","description":"The data storage policy for a resource.","properties":{"group":{"type":"string","description":"The name of the region group used for storage."},"regions":{"type":"array","items":{"type":"object","title":"RegionPriority","properties":{"region":{"type":"string","description":"The name of the AWS region."},"priority":{"type":"integer","minimum":0,"description":"The priority to give to this region when storing data."}},"required":["region","priority"]}},"piiStrategy":{"type":"string","enum":["default","strict"]}},"required":["group","regions","piiStrategy"]},"WorkspaceConfiguration":{"type":"object","additionalProperties":false,"properties":{"domain":{"$ref":"#/components/schemas/DomainName"}}},"DomainName":{"type":"string","description":"Domain name.","format":"domain","pattern":"^(([a-zA-Z0-9]([a-zA-Z0-9\\-]{0,61}[a-zA-Z0-9])?\\.)+[a-zA-Z]{2,})?$","maxLength":253},"Error":{"type":"object","required":["code","message"],"properties":{"code":{"type":"string","description":"Unique identifier for the error that occurred"},"message":{"type":"string","description":"Description of the error that occurred, aimed at API consumers"}}}},"responses":{"notFound":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}},"description":"Resource not found"}}},"paths":{"/organizations/{organizationId}/workspaces/{workspaceId}":{"get":{"description":"Get the workspace instance.","operationId":"getWorkspace","responses":{"200":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Workspace"}}},"description":"OK"},"404":{"$ref":"#/components/responses/notFound"}},"summary":"Get workspace","tags":["organization_workspace"]}}}}
```

## Delete workspace

> Delete a workspace from the organization.

```json
{"openapi":"3.0.3","info":{"title":"Accounts","version":"v1"},"tags":[{"description":"Manage organization workspaces.","name":"organization_workspace"}],"servers":[{"url":"https://api.bird.com","description":"Production API"}],"security":[{"accessKey":[]}],"components":{"securitySchemes":{"accessKey":{"description":"Uses the Authorization header: 'AccessKey ' followed by your access key token (e.g., 'Authorization: AccessKey AbCdEfGhIjKlMnOpQrStUvWxYzAbCdEfGhIj')","scheme":"AccessKey","type":"http"}},"responses":{"forbidden":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}},"description":"Forbidden operation"},"notFound":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}},"description":"Resource not found"}},"schemas":{"Error":{"type":"object","required":["code","message"],"properties":{"code":{"type":"string","description":"Unique identifier for the error that occurred"},"message":{"type":"string","description":"Description of the error that occurred, aimed at API consumers"}}}}},"paths":{"/organizations/{organizationId}/workspaces/{workspaceId}":{"delete":{"description":"Delete a workspace from the organization.","operationId":"deleteWorkspace","responses":{"204":{"description":"Delete successful"},"403":{"$ref":"#/components/responses/forbidden"},"404":{"$ref":"#/components/responses/notFound"},"410":{"description":"Does not exist or already deleted"}},"summary":"Delete workspace","tags":["organization_workspace"]}}}}
```

## Update workspace

> Update a workspace's properties.

```json
{"openapi":"3.0.3","info":{"title":"Accounts","version":"v1"},"tags":[{"description":"Manage organization workspaces.","name":"organization_workspace"}],"servers":[{"url":"https://api.bird.com","description":"Production API"}],"security":[{"accessKey":[]}],"components":{"securitySchemes":{"accessKey":{"description":"Uses the Authorization header: 'AccessKey ' followed by your access key token (e.g., 'Authorization: AccessKey AbCdEfGhIjKlMnOpQrStUvWxYzAbCdEfGhIj')","scheme":"AccessKey","type":"http"}},"schemas":{"UpdateWorkspace":{"type":"object","additionalProperties":false,"properties":{"name":{"$ref":"#/components/schemas/WorkspaceName"},"description":{"$ref":"#/components/schemas/WorkspaceDescription"}}},"WorkspaceName":{"type":"string","description":"The display name for the workspace","minLength":1,"maxLength":256},"WorkspaceDescription":{"type":"string","description":"The description for the workspace","minLength":1,"maxLength":256},"Workspace":{"title":"Workspace","description":"The workspace record.","type":"object","additionalProperties":false,"properties":{"id":{"type":"string","description":"Workspace ID.","format":"uuid"},"organizationId":{"type":"string","description":"ID of the organization this workspace is part of.","format":"uuid"},"status":{"$ref":"#/components/schemas/WorkspaceStatus"},"statusTransitions":{"type":"array","items":{"$ref":"#/components/schemas/WorkspaceStatusTransition"}},"name":{"$ref":"#/components/schemas/WorkspaceName"},"description":{"$ref":"#/components/schemas/WorkspaceDescription"},"dataPolicy":{"$ref":"#/components/schemas/DataPolicy"},"configuration":{"$ref":"#/components/schemas/WorkspaceConfiguration"},"createdAt":{"type":"string","format":"date-time","description":"When the workspace was created."},"updatedAt":{"type":"string","format":"date-time","description":"When the workspace was last updated."}},"required":["id","organizationId","status","name","dataPolicy","createdAt","updatedAt"]},"WorkspaceStatus":{"type":"string","description":"Status of the workspace","enum":["active","disabled","terminated","deleted"]},"WorkspaceStatusTransition":{"type":"object","description":"Workspace status transition","required":["fromStatus","toStatus","reason","transitionedAt","transitionedBy"],"properties":{"fromStatus":{"$ref":"#/components/schemas/WorkspaceStatus"},"toStatus":{"$ref":"#/components/schemas/WorkspaceStatus"},"reason":{"type":"string","enum":["org-banned","user-initiated","payment-default","inactivity"]},"comment":{"type":"string"},"transitionedAt":{"type":"string","format":"date-time"},"transitionedBy":{"$ref":"#/components/schemas/RequestSubject"}}},"RequestSubject":{"required":["type","id"],"properties":{"type":{"$ref":"#/components/schemas/RequestSubjectType"},"id":{"type":"string","format":"uuid"}}},"RequestSubjectType":{"type":"string","enum":["user","accesskey","contact"]},"DataPolicy":{"type":"object","title":"DataPolicy","description":"The data storage policy for a resource.","properties":{"group":{"type":"string","description":"The name of the region group used for storage."},"regions":{"type":"array","items":{"type":"object","title":"RegionPriority","properties":{"region":{"type":"string","description":"The name of the AWS region."},"priority":{"type":"integer","minimum":0,"description":"The priority to give to this region when storing data."}},"required":["region","priority"]}},"piiStrategy":{"type":"string","enum":["default","strict"]}},"required":["group","regions","piiStrategy"]},"WorkspaceConfiguration":{"type":"object","additionalProperties":false,"properties":{"domain":{"$ref":"#/components/schemas/DomainName"}}},"DomainName":{"type":"string","description":"Domain name.","format":"domain","pattern":"^(([a-zA-Z0-9]([a-zA-Z0-9\\-]{0,61}[a-zA-Z0-9])?\\.)+[a-zA-Z]{2,})?$","maxLength":253},"Error":{"type":"object","required":["code","message"],"properties":{"code":{"type":"string","description":"Unique identifier for the error that occurred"},"message":{"type":"string","description":"Description of the error that occurred, aimed at API consumers"}}},"DetailedError":{"type":"object","required":["code","message"],"properties":{"code":{"type":"string","description":"Unique identifier for the error that occurred"},"message":{"type":"string","description":"Description of the error that occurred, aimed at API consumers"},"details":{"type":"object","description":"Detailed information on where the error exists, usually the field name on the request payload","additionalProperties":{"type":"array","description":"The error description for the specific detail","items":{"type":"string"}}}}}},"responses":{"notFound":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}},"description":"Resource not found"},"invalidRequest":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/DetailedError"}}},"description":"Request validation failed"}}},"paths":{"/organizations/{organizationId}/workspaces/{workspaceId}":{"patch":{"description":"Update a workspace's properties.","operationId":"updateWorkspace","requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/UpdateWorkspace"}}}},"responses":{"200":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Workspace"}}},"description":"OK"},"404":{"$ref":"#/components/responses/notFound"},"422":{"$ref":"#/components/responses/invalidRequest"}},"summary":"Update workspace","tags":["organization_workspace"]}}}}
```