Astronomer Team API

openapi: 3.2.0
info:
  contact: {}
  description: Astro Platform API
  title: Astro Platform AgentToken Team API
  version: v1.0
servers:
- url: https://api.astronomer.io/v1
security:
- JWT: []
tags:
- 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
paths:
  /organizations/{organizationId}/teams:
    get:
      description: List all Teams in an Organization. Optionally filter by Workspace or Deployment membership.
      operationId: ListTeams
      parameters:
      - description: ID of the Organization to list Teams for.
        in: path
        name: organizationId
        required: true
        schema:
          type: string
      - description: A list of names for Teams to filter by. The API returns details only for the specified Teams.
        in: query
        name: names
        schema:
          items:
            type: string
          type: array
      - description: The ID of the Workspace to filter the list of Teams for. When specified, the API returns only Teams with a role in the specified Workspace.
        in: query
        name: workspaceId
        schema:
          type: string
      - description: The ID of the Deployment to filter the list of Teams for. When specified, the API returns only Teams with a role in the specified Deployment.
        in: query
        name: deploymentId
        schema:
          type: string
      - description: Offset for pagination
        in: query
        name: offset
        schema:
          default: 0
          minimum: 0
          type: integer
      - description: Limit for pagination
        in: query
        name: limit
        schema:
          default: 20
          maximum: 1000
          minimum: 0
          type: integer
      - description: Sorting criteria, each criterion should conform to format 'fieldName:asc' or 'fieldName:desc'
        in: query
        name: sorts
        schema:
          items:
            enum:
            - name:asc
            - name:desc
            - description:asc
            - description:desc
            - createdAt:asc
            - createdAt:desc
            - updatedAt:asc
            - updatedAt:desc
            type: string
          type: array
      responses:
        '200':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/TeamsPaginated'
          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
        '404':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
          description: Not Found
        '500':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
          description: Internal Server Error
      security:
      - JWT: []
      summary: List Teams
      tags:
      - Team
      x-permission:
      - action: organization.teams.get
    post:
      description: Create a Team in an Organization. A Team is a group of users that have the same set of permissions in an Organization or Workspace.
      operationId: CreateTeam
      parameters:
      - description: The ID of the Organization where the Team is created.
        in: path
        name: organizationId
        required: true
        schema:
          type: string
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/CreateTeamRequest'
        description: The request body for creating a Team.
        required: true
        x-originalParamName: body
      responses:
        '200':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Team'
          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
        '404':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
          description: Not Found
        '500':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
          description: Internal Server Error
      security:
      - JWT: []
      summary: Create a Team
      tags:
      - Team
      x-permission:
      - action: organization.teams.create
  /organizations/{organizationId}/teams/{teamId}:
    delete:
      description: Delete a Team. Deleting a Team will remove all permissions associated with the Team. Users that previously belonged to the Team will no longer have these permissions.
      operationId: DeleteTeam
      parameters:
      - description: The ID of the Organization to delete the Team from.
        in: path
        name: organizationId
        required: true
        schema:
          type: string
      - description: The ID of the Team to delete.
        in: path
        name: teamId
        required: true
        schema:
          type: string
      responses:
        '204':
          description: ''
        '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
        '404':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
          description: Not Found
        '500':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
          description: Internal Server Error
      security:
      - JWT: []
      summary: Delete a Team
      tags:
      - Team
      x-permission:
      - action: organization.teams.delete
    get:
      description: Retrieve details about a specific Team.
      operationId: GetTeam
      parameters:
      - description: The ID of the Organization to which the Team belongs.
        in: path
        name: organizationId
        required: true
        schema:
          type: string
      - description: The ID of the Team to retrieve data for.
        in: path
        name: teamId
        required: true
        schema:
          type: string
      responses:
        '200':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Team'
          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
        '404':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
          description: Not Found
        '500':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
          description: Internal Server Error
      security:
      - JWT: []
      summary: Get a Team
      tags:
      - Team
      x-permission:
      - action: organization.teams.get
    post:
      description: Update a Team's details.
      operationId: UpdateTeam
      parameters:
      - description: The ID of the Organization to which the Team belongs.
        in: path
        name: organizationId
        required: true
        schema:
          type: string
      - description: The ID of the Team to update.
        in: path
        name: teamId
        required: true
        schema:
          type: string
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/UpdateTeamRequest'
        description: The request body for updating the Team.
        required: true
        x-originalParamName: body
      responses:
        '200':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Team'
          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
        '404':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
          description: Not Found
        '500':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
          description: Internal Server Error
      security:
      - JWT: []
      summary: Update a Team
      tags:
      - Team
      x-permission:
      - action: organization.teams.update
  /organizations/{organizationId}/teams/{teamId}/members:
    get:
      description: List the details about all users that belong to a specific Team.
      operationId: ListTeamMembers
      parameters:
      - description: The ID of the Organization to which the Team belongs.
        in: path
        name: organizationId
        required: true
        schema:
          type: string
      - description: The ID of the Team to retrieve member information for.
        in: path
        name: teamId
        required: true
        schema:
          type: string
      - description: Offset for pagination
        in: query
        name: offset
        schema:
          default: 0
          minimum: 0
          type: integer
      - description: Limit for pagination
        in: query
        name: limit
        schema:
          default: 20
          minimum: 0
          type: integer
      - description: Sorting criteria, each criterion should conform to format 'fieldName:asc' or 'fieldName:desc'
        in: query
        name: sorts
        schema:
          items:
            enum:
            - userId:asc
            - userId:desc
            - fullName:asc
            - fullName:desc
            - username:asc
            - username:desc
            - createdAt:asc
            - createdAt:desc
            type: string
          type: array
      responses:
        '200':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/TeamMembersPaginated'
          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
        '404':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
          description: Not Found
        '500':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
          description: Internal Server Error
      security:
      - JWT: []
      summary: List Team members
      tags:
      - Team
      x-permission:
      - action: organization.teams.get
    post:
      description: Add members to a team
      operationId: AddTeamMembers
      parameters:
      - description: organization ID
        in: path
        name: organizationId
        required: true
        schema:
          type: string
      - description: team ID
        in: path
        name: teamId
        required: true
        schema:
          type: string
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/AddTeamMembersRequest'
        description: request body for adding members to a team
        required: true
        x-originalParamName: body
      responses:
        '204':
          description: ''
        '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
        '404':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
          description: Not Found
        '500':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
          description: Internal Server Error
      security:
      - JWT: []
      summary: Add members to a team
      tags:
      - Team
      x-permission:
      - action: organization.teams.update
  /organizations/{organizationId}/teams/{teamId}/members/{memberId}:
    delete:
      description: Remove a user from a Team. The user loses all permissions associated with the Team.
      operationId: RemoveTeamMember
      parameters:
      - description: The ID of the Organization to which the user belongs.
        in: path
        name: organizationId
        required: true
        schema:
          type: string
      - description: The ID of the Team to remove the user from.
        in: path
        name: teamId
        required: true
        schema:
          type: string
      - description: The ID of the user to remove.
        in: path
        name: memberId
        required: true
        schema:
          type: string
      responses:
        '204':
          description: ''
        '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
        '404':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
          description: Not Found
        '500':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
          description: Internal Server Error
      security:
      - JWT: []
      summary: Remove Team member
      tags:
      - Team
      x-permission:
      - action: organization.teams.update
  /organizations/{organizationId}/teams/{teamId}/roles:
    post:
      description: Update Organization and Workspace roles for a Team.
      operationId: UpdateTeamRoles
      parameters:
      - description: The ID of the Organization to which the Team belongs.
        in: path
        name: organizationId
        required: true
        schema:
          type: string
      - description: The ID of the Team to update roles for.
        in: path
        name: teamId
        required: true
        schema:
          type: string
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/UpdateTeamRolesRequest'
        description: The request body for updating the Team's roles
        required: true
        x-originalParamName: body
      responses:
        '200':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/SubjectRoles'
          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
        '404':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
          description: Not Found
        '500':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
          description: Internal Server Error
      security:
      - JWT: []
      summary: Update Team roles
      tags:
      - Team
      x-permission:
      - action: organization.teamRoles.access
components:
  schemas:
    UpdateTeamRolesRequest:
      properties:
        dagRoles:
          description: The Team's updated DAG roles.
          items:
            $ref: '#/components/schemas/DagRole'
          type: array
        deploymentRoles:
          description: The user's updated Deployment roles. The Deployments you specify must belong to the Team's Organization.
          items:
            $ref: '#/components/schemas/DeploymentRole'
          type: array
        organizationRole:
          description: The Team's Organization roles.
          example: ORGANIZATION_OWNER,ORGANIZATION_OBSERVE_ADMIN,ORGANIZATION_OBSERVE_MEMBER,ORGANIZATION_BILLING_ADMIN,ORGANIZATION_MEMBER
          type: string
        workspaceRoles:
          description: The Team's updated Workspace roles. The Workspaces you specify must belong to the Team's Organization.
          items:
            $ref: '#/components/schemas/WorkspaceRole'
          type: array
      required:
      - organizationRole
      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
    DeploymentRole:
      properties:
        deploymentId:
          description: The Deployment ID.
          example: clm8t5u4q000008jq4qoc3031
          type: string
        role:
          description: The name of the role for the subject in the Deployment.
          example: DEPLOYMENT_ADMIN
          type: string
      required:
      - deploymentId
      - role
      type: object
    UpdateTeamRequest:
      properties:
        description:
          description: The Team's description.
          example: My Team Description
          type: string
        name:
          description: The Team's name.
          example: My Team
          type: string
      required:
      - name
      type: object
    TeamsPaginated:
      properties:
        limit:
          description: The maximum number of Teams in one page.
          example: 10
          type: integer
        offset:
          description: The offset of the current page of Teams.
          example: 0
          type: integer
        teams:
          description: The list of Teams in the current page.
          items:
            $ref: '#/components/schemas/Team'
          type: array
        totalCount:
          description: The total number of Teams.
          example: 100
          type: integer
      required:
      - limit
      - offset
      - teams
      - totalCount
      type: object
    Team:
      properties:
        createdAt:
          description: The time when the Team was created in UTC, formatted as `YYYY-MM-DDTHH:MM:SSZ`.
          example: '2022-11-22T04:37:12Z'
          format: date-time
          type: string
        createdBy:
          $ref: '#/components/schemas/BasicSubjectProfile'
        dagRoles:
          description: The Team's role in each DAG it belongs to.
          items:
            $ref: '#/components/schemas/DagRole'
          type: array
        deploymentRoles:
          description: The Team's role in each Deployment it belongs to.
          items:
            $ref: '#/components/schemas/DeploymentRole'
          type: array
        description:
          description: The Team's description.
          example: My Team description
          type: string
        id:
          description: The Team's ID.
          example: clma5ftgk000008mhgev00k7d
          type: string
        isIdpManaged:
          description: Whether the Team is managed by an identity provider (IdP).
          example: false
          type: boolean
        name:
          description: The Team's name.
          example: My Team
          type: string
        organizationId:
          description: The ID of the Organization to which the Team belongs.
          example: clma5g8q6000108mh88g27k1y
          type: string
        organizationRole:
          description: The Team's Organization role.
          enum:
          - ORGANIZATION_OWNER
          - ORGANIZATION_OBSERVE_ADMIN
          - ORGANIZATION_OBSERVE_MEMBER
          - ORGANIZATION_BILLING_ADMIN
          - ORGANIZATION_MEMBER
          example: ORGANIZATION_MEMBER
          type: string
        rolesCount:
          description: The number of roles the Team has.
          example: 1
          type: integer
        updatedAt:
          description: The time when the Team was last updated in UTC, formatted as `YYYY-MM-DDTHH:MM:SSZ`.
          example: '2022-11-22T04:37:12Z'
          format: date-time
          type: string
        updatedBy:
          $ref: '#/components/schemas/BasicSubjectProfile'
        workspaceRoles:
          description: The Team's role in each Workspace it belongs to.
          items:
            $ref: '#/components/schemas/WorkspaceRole'
          type: array
      required:
      - createdAt
      - id
      - isIdpManaged
      - name
      - organizationId
      - organizationRole
      - updatedAt
      type: object
    FieldValidationError:
      properties:
        code:
          type: string
        field:
          type: string
        message:
          type: string
      required:
      - code
      - field
      - message
      type: object
    TeamMembersPaginated:
      properties:
        limit:
          description: The maximum number of Team members in one page.
          example: 10
          type: integer
        offset:
          description: The offset of the current page of Team members.
          example: 0
          type: integer
        teamMembers:
          description: The list of Team members in the current page.
          items:
            $ref: '#/components/schemas/TeamMember'
          type: array
        totalCount:
          description: The total number of Team members.
          example: 100
          type: integer
      required:
      - limit
      - offset
      - teamMembers
      - totalCount
      type: object
    SubjectRoles:
      properties:
        dagRoles:
          description: A list of the subject's DAG roles.
          items:
            $ref: '#/components/schemas/DagRole'
          type: array
        deploymentRoles:
          description: A list of the subject's Deployment roles. Currently only for API tokens.
          items:
            $ref: '#/components/schemas/DeploymentRole'
          type: array
        organizationRole:
          description: The subject's Organization role.
          example: ORGANIZATION_OWNER,ORGANIZATION_OBSERVE_ADMIN,ORGANIZATION_OBSERVE_MEMBER,ORGANIZATION_BILLING_ADMIN,ORGANIZATION_MEMBER
          type: string
        workspaceRoles:
          description: A list of the subject's Workspace roles.
          items:
            $ref: '#/components/schemas/WorkspaceRole'
          type: array
      type: object
    CreateTeamRequest:
      properties:
        description:
          description: The Team's description.
          example: My Team description
          type: string
        memberIds:
          description: The list of IDs for users to add to the Team.
          example:
          - clma67byh000008md1gr995ez
          items:
            type: string
          type: array
        name:
          description: The Team's name.
          example: My Team
          type: string
        organizationRole:
          description: The Team's Organization role.
          enum:
          - ORGANIZATION_OWNER
          - ORGANIZATION_OBSERVE_ADMIN
          - ORGANIZATION_OBSERVE_MEMBER
          - ORGANIZATION_BILLING_ADMIN
          - ORGANIZATION_MEMBER
          example: ORGANIZATION_MEMBER
          type: string
      required:
      - name
      type: object
    WorkspaceRole:
      properties:
        role:
          description: The role of the subject in the Workspace.
          enum:
          - WORKSPACE_OWNER
          - WORKSPACE_OPERATOR
          - WORKSPACE_AUTHOR
          - WORKSPACE_MEMBER
          - WORKSPACE_ACCESSOR
          example: WORKSPACE_MEMBER
          type: string
        workspaceId:
          description: The Workspace ID.
          example: clm8t5u4q000008jq4qoc3036
          type: string
      required:
      - role
      - workspaceId
      type: object
    AddTeamMembersRequest:
      properties:
        memberIds:
          description: The list of IDs for users to add to the Team.
          example:
          - clma5y9hu000208k2aumf7pbd
          items:
            type: string
          minItems: 1
          type: array
      required:
      - memberIds
      type: object
    DagRole:
      properties:
        dagId:
          description: The DAG ID. Required if Tag is not specified.
          example: my_dag
          type: string
        dagTag:
          description: The DAG tag. Required if DagId is not specified.
          example: team-a
          type: string
        deploymentId:
          description: The Deployment ID containing the DAG.
          example: clm8t5u4q000008jq4qoc3031
          type: string
        role:
          description: The role name (DAG_VIEWER, DAG_AUTHOR, or custom DAG role).
          example: DAG_VIEWER
          type: string
      required:
      - deploymentId
      - role
      type: object
    TeamMember:
      properties:
        avatarUrl:
          description: The URL for the Team member's profile image.
          example: https://avatar.url
          type: string
        createdAt:
          description: The time when the Team member was added in UTC, formatted as `YYYY-MM-DDTHH:MM:SSZ`.
          example: '2022-11-22T04:37:12Z'
          format: date-time
          type: string
        fullName:
          description: The Team member's full name.
          example: Jane Doe
          type: string
        userId:
          description: The Team member's ID.
          example: clma5vzk2000108k20jhq3f7n
          type: string
        username:
          description: The Team member's username.
          example: user1@company.com
          type: string
      required:
      - userId
      - username
      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