> ## Documentation Index
> Fetch the complete documentation index at: https://astronomer.io/docs/llms.txt
> Use this file to discover all available pages before exploring further.
# List Workspaces
> List Workspaces in an Organization
To list multiple Workspaces, string together the `workspaceIds` parameter. For example, `workspaces?workspaceIds=workspaceId1&workspaceIds=workspaceId2`.
## OpenAPI
````yaml astro/api/v-1/openapi.yaml GET /organizations/{organizationId}/workspaces
openapi: 3.0.3
info:
contact: {}
description: Astro Platform API
title: Astro Platform API
version: v1.0
servers:
- url: https://api.astronomer.io/v1
security:
- JWT: []
tags:
- description: >-
The `organization` object contains the metadata and configurations of an
Astro Organization. It does not include objects within the Organization,
such as users and clusters. Make requests to `organization` endpoints to
view and update high level settings for your Organization, including
settings related to authentication and billing. To manage resources within
an Organization, make requests to the endpoints related to those
resources, such as `users`. See
[Billing](https://astronomer.io/docs/astro/manage-billing), [Set up single
sign-on](https://astronomer.io/docs/astro/configure-idp), and [Manage
domains](https://astronomer.io/docs/astro/manage-domains).
name: Organization
- description: >-
The `deployment` object represents an Astro Deployment, which is a hosted
Airflow environment that is powered by all core Airflow components,
including schedulers and workers. Make requests to the `deployment` object
to create, update, or delete a Deployment or its computational resources.
See [Deployment
settings](https://astronomer.io/docs/astro/deployment-settings).
name: Deployment
- description: >-
A `cluster` object represents an Astro cluster, which is a Kubernetes
cluster that hosts the infrastructure required to run Deployments. Make
requests to `cluster` endpoints to manage your standard and dedicated
clusters. See [Create a dedicated
cluster](https://astronomer.io/docs/astro/create-dedicated-cluster).
name: Cluster
- description: >-
The `workspace` object represents an Astro Workspace, which is a
collection of Deployments that can be accessed by a specific group of
users. It contains metadata about a Workspace, but does not contain
objects within the Workspace such as users and Deployments. Make requests
to `workspace` endpoints to manage high level details about your
Workspace. To manage resources within a Workspace, make requests to the
endpoints related to those resources, such as `users`, and use the
`workspaceIds` parameter to filter results by Workspace. See [Configure
Workspaces](https://astronomer.io/docs/astro/manage-workspaces).
name: Workspace
- description: >-
The `user` object represents a user account in your Astro Organization.
Astro creates a new `user` object whenever you invite a user by email or
add a user to Astro through an identity provider. The object contains all
information about a user, including their personal information, roles, and
login attempts. It doesn't include attributes for actions that the user
completes after they log in, such as updating a Deployment. Make requests
to `user` endpoints to manage permissions for existing users both at the
Organization and Workspace level. To create new users, make requests to
`invite` endpoints instead.
name: User
- description: >-
The `team` object represents an Astro Team, which is a group of users that
share the same permissions across your Organization and Workspaces. Make
requests to `team` endpoints to create, update, and delete Teams across an
Organization. See [Configure Teams on
Astro](https://astronomer.io/docs/astro/manage-teams).
name: Team
- description: >-
The `apitoken` object represents a single API token within your
Organization. API tokens are used to authenticate automated tools and
processes to your Organization. They have varying levels of access to your
resources based on their Organization, Workspace, and Deployment roles.
See [Workspace API tokens](workspace-api-tokens.md) and [Organization API
tokens](organization-api-tokens.md).
name: api-token
x-group: API Token
- name: allowed-ip-address-range
x-group: Allowed IP Address Range
- name: agent-token
x-group: Agent Token
paths:
/organizations/{organizationId}/workspaces:
get:
tags:
- Workspace
summary: List Workspaces
description: List Workspaces in an Organization
operationId: ListWorkspaces
parameters:
- description: The ID of the Organization to list Workspaces for.
in: path
name: organizationId
required: true
schema:
type: string
- description: >-
A list of IDs for specific Workspaces to list. The API will list
information only for Workspaces which have been specified in this
list.
in: query
name: workspaceIds
schema:
items:
type: string
type: array
- description: >-
A list of names for specific Workspaces to filter by. The API will
list information only for Workspaces which have been specified in
this list.
in: query
name: names
schema:
items:
type: string
type: array
- description: The number of results to skip before returning values.
in: query
name: offset
schema:
default: 0
minimum: 0
type: integer
- description: The maximum number of results to return.
in: query
name: limit
schema:
default: 20
maximum: 1000
minimum: 0
type: integer
- description: >-
A list of field names to sort by, and whether to show results as
ascending or descending. Formatted as `:asc` or
`:desc`.
in: query
name: sorts
schema:
items:
enum:
- name:asc
- name:desc
- createdAt:asc
- createdAt:desc
- updatedAt:asc
- updatedAt:desc
type: string
type: array
responses:
'200':
content:
application/json:
schema:
$ref: '#/components/schemas/WorkspacesPaginated'
description: OK
'400':
content:
application/json:
schema:
$ref: '#/components/schemas/Error'
description: Bad Request
'401':
content:
application/json:
schema:
$ref: '#/components/schemas/Error'
description: Unauthorized
'403':
content:
application/json:
schema:
$ref: '#/components/schemas/Error'
description: Forbidden
'500':
content:
application/json:
schema:
$ref: '#/components/schemas/Error'
description: Internal Server Error
security:
- JWT: []
components:
schemas:
WorkspacesPaginated:
properties:
limit:
description: The maximum number of workspaces that can be retrieved per page.
example: 0
type: integer
offset:
description: >-
The offset for the current page of workspaces in the complete
result.
example: 0
type: integer
totalCount:
description: The total number of Workspaces in the paginated result.
example: 0
type: integer
workspaces:
description: An array of Workspace objects representing a list of workspaces.
items:
$ref: '#/components/schemas/Workspace'
type: array
required:
- limit
- offset
- totalCount
- workspaces
type: object
Error:
properties:
fieldErrors:
description: >-
FieldErrors carries one entry per failed request-validation
constraint.
Only present on 400 responses caused by request binding/validation.
items:
$ref: '#/components/schemas/FieldValidationError'
type: array
message:
type: string
requestId:
type: string
statusCode:
maximum: 600
minimum: 400
type: integer
required:
- message
- requestId
- statusCode
type: object
Workspace:
properties:
cicdEnforcedDefault:
description: Whether CI/CD deploys are enforced by default.
example: true
type: boolean
createdAt:
description: >-
The time when the Workspace was created in UTC, formatted as
`YYYY-MM-DDTHH:MM:SSZ`
example: '2023-09-08T12:00:00Z'
format: date-time
type: string
createdBy:
$ref: '#/components/schemas/BasicSubjectProfile'
defaultCloudProvider:
description: The default cloud provider for new Deployments.
enum:
- AWS
- AZURE
- GCP
example: AWS
type: string
defaultClusterId:
description: The ID of the default cluster for new Deployments.
example: clmh9g6zj000008mg77if5wa2
type: string
defaultRegion:
description: The default region for new Deployments.
example: us-east-1
type: string
description:
description: The Workspace's description.
example: This is a test workspace
type: string
id:
description: The Workspace's ID.
example: clm8t5u4q000008jq4qoc3036
type: string
name:
description: The Workspace's name.
example: My Workspace
type: string
organizationId:
description: The ID of the organization to which the workspace belongs.
example: clm8t5u4q000008jq4qoc3036
type: string
organizationName:
description: The name of the Organization to which the Workspace belongs.
example: My Organization
type: string
updatedAt:
description: >-
The time when the Workspace was updated in UTC, formatted as
`YYYY-MM-DDTHH:MM:SSZ`
example: '2023-09-08T13:30:00Z'
format: date-time
type: string
updatedBy:
$ref: '#/components/schemas/BasicSubjectProfile'
required:
- cicdEnforcedDefault
- createdAt
- id
- name
- organizationId
- updatedAt
type: object
FieldValidationError:
properties:
code:
type: string
field:
type: string
message:
type: string
required:
- code
- field
- message
type: object
BasicSubjectProfile:
properties:
apiTokenName:
description: >-
The API token's name. Returned only when `SubjectType` is
`SERVICEKEY`.
example: my-token
type: string
avatarUrl:
description: >-
The URL for the user's profile image. Returned only when
`SubjectType` is `USER`.
example: https://avatar.url
type: string
fullName:
description: The subject's full name. Returned only when `SubjectType` is `USER`.
example: Jane Doe
type: string
id:
description: The subject's ID.
example: clm8qv74h000008mlf08scq7k
type: string
subjectType:
description: The subject type.
enum:
- USER
- SERVICEKEY
example: USER
type: string
username:
description: The subject's username. Returned only when `SubjectType` is `USER`.
example: user1@company.com
type: string
required:
- id
type: object
securitySchemes:
JWT:
scheme: bearer
type: http
````