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


---

# 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.bird.com/api/accounts-api/api-reference/organizations/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.