Dash0 Manage Teams and Members API

openapi: 3.2.0
info:
  title: Dash0 Manage Teams and Members API
  version: 1.0.0
  description: '## Selecting a dataset


    Endpoints that operate on a single dataset take it from the `dataset` query parameter, or from the `Dash0-Dataset` request header when the query parameter is absent. When both are present the query parameter wins.


    If neither is given, the request falls back to the organization''s `default` dataset — a token that is restricted to specific datasets is rejected with `403 Forbidden` in that case, so always select a dataset explicitly when using a dataset-restricted token.


    ## Resource origins


    Most resources take an optional `metadata.labels["dash0.com/origin"]`. It is a stable identifier you choose for a resource you manage as code, so your Terraform configuration, Kubernetes manifests, CLI scripts or your own tooling can address the same resource on every apply without having to store the id Dash0 generated.


    An origin is unique per organization, not per dataset. Two resources of the same type in one organization cannot share an origin, even when they live in different datasets. If you want what is really the same rule in several datasets, put the dataset in the origin, for example `probabilistic-request-sampling-sandbox` and `probabilistic-request-sampling-nonprod`. The Dash0 Kubernetes operator does the same with the origins it generates. A duplicate origin is rejected with `400`.


    You cannot change an origin. Dash0 records it when the resource is created and ignores it on later updates, so you can read a resource, edit it and send it back without stripping the label out first.


    Endpoints with an `{originOrId}` path parameter take either identifier. A value that is not a UUID is read as an origin. A `PUT` to an origin that does not exist yet creates the resource with that origin, so you can apply the same manifest repeatedly.


    ## Request body size limit


    Most API endpoints enforce a maximum request body size of 256KB. Bulk

    endpoints accept a larger body size per request to accommodate batched

    payloads.


    Requests exceeding the applicable limit are rejected with a

    `413 Content Too Large` response.'
servers:
- url: https://api.eu-west-1.aws.dash0.com
  description: API endpoint for AWS region EU (Ireland)
- url: https://api.eu-central-1.aws.dash0.com
  description: API endpoint for AWS region EU (Germany)
- url: https://api.us-east-1.aws.dash0.com
  description: API endpoint for AWS region US (N. Virginia)
- url: https://api.us-west-2.aws.dash0.com
  description: API endpoint for AWS region US (Oregon)
- url: https://api.europe-west4.gcp.dash0.com
  description: API endpoint for GCP region EU (Netherlands)
tags:
- name: Manage Teams and Members
paths:
  /api/members:
    get:
      summary: Receive a list of organization members
      description: Receive a list of all members in your organization.
      responses:
        '200':
          description: Receive a list of members.
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/MemberDefinition'
        default:
          description: In case any error happens.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
      tags:
      - Manage Teams and Members
      operationId: getApiMembers
      x-operation-id-source: derived
    post:
      summary: Invite a member to the organization
      description: Sends an invitation to join the organization to the given email address.
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/InviteMemberRequest'
      responses:
        '200':
          description: Successfully invited the member.
        default:
          description: In case any error happens.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
      tags:
      - Manage Teams and Members
      operationId: postApiMembers
      x-operation-id-source: derived
  /api/members/invitations:
    get:
      summary: Receive a list of pending member invitations
      description: 'Receive all invitations to your organization that have not been accepted yet. Invitees are

        not listed by `GET /api/members` until they accept, so compare against both lists before

        inviting an address again. Requires the admin role.'
      responses:
        '200':
          description: Receive a list of pending invitations.
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/MemberInvitationDefinition'
        default:
          description: In case any error happens.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
      tags:
      - Manage Teams and Members
      operationId: getApiMembersInvitations
      x-operation-id-source: derived
  /api/members/invitations/{invitationID}:
    delete:
      summary: Revoke a pending member invitation
      description: 'Revokes an invitation to your organization that has not been accepted yet, so it can no

        longer be accepted. Requires the admin role.'
      parameters:
      - in: path
        name: invitationID
        schema:
          type: string
        required: true
        description: 'ID of the invitation to revoke, as returned in `metadata.labels[''dash0.com/id'']` by

          `GET /api/members/invitations`. An invitation that does not exist, or that was already

          accepted, revoked or expired, is rejected with `404`.

          '
      responses:
        '200':
          description: Successfully revoked the invitation.
        default:
          description: In case any error happens.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
      tags:
      - Manage Teams and Members
      operationId: deleteApiMembersInvitationsByInvitationID
      x-operation-id-source: derived
  /api/members/{memberID}:
    delete:
      summary: Remove a member from the organization
      description: Removes the given member from the organization.
      parameters:
      - in: path
        name: memberID
        schema:
          type: string
        required: true
        description: The internal ID of the member to remove.
      responses:
        '200':
          description: Successfully removed the member.
        default:
          description: In case any error happens.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
      tags:
      - Manage Teams and Members
      operationId: deleteApiMembersByMemberID
      x-operation-id-source: derived
  /api/members/{memberID}/role:
    put:
      summary: Change the organization role of a member
      description: Changes the role of a member of your organization.
      parameters:
      - in: path
        name: memberID
        schema:
          type: string
        required: true
        description: The internal ID of the member whose role to change.
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/UpdateMemberRoleRequest'
      responses:
        '200':
          description: Successfully changed the member role.
        default:
          description: In case any error happens.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
      tags:
      - Manage Teams and Members
      operationId: putApiMembersByMemberIDRole
      x-operation-id-source: derived
  /api/teams:
    get:
      summary: Receive a list of teams
      description: Receive a list of your organization teams
      responses:
        '200':
          description: Receive a list of teams.
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/TeamsListItem'
        default:
          description: In case any error happens.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
      tags:
      - Manage Teams and Members
      operationId: getApiTeams
      x-operation-id-source: derived
    post:
      summary: Create a new team
      description: Create a new team in the organization.
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/TeamDefinitionV1Alpha1'
      responses:
        '200':
          description: Successfully created the team.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/TeamDefinitionV1Alpha1'
        default:
          description: In case any error happens.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
      tags:
      - Manage Teams and Members
      operationId: postApiTeams
      x-operation-id-source: derived
  /api/teams/{originOrId}:
    delete:
      summary: Delete a specific team by its origin or id
      description: Delete a specific team by its **origin** or **id**.
      parameters:
      - in: path
        name: originOrId
        schema:
          type: string
        required: true
        description: The **origin** or **id** of the team.
      responses:
        '200':
          description: Team deleted successfully.
        default:
          description: In case any error happens.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
      tags:
      - Manage Teams and Members
      operationId: deleteApiTeamsByOriginOrId
      x-operation-id-source: derived
    get:
      summary: Receive a specific team by its origin or id
      description: Receive a specific team by its **origin** or **id**.
      parameters:
      - in: path
        name: originOrId
        schema:
          type: string
        required: true
        description: The **origin** or **id** of the team.
      responses:
        '200':
          description: Receive a specific team.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/GetTeamResponse'
        default:
          description: In case any error happens.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
      tags:
      - Manage Teams and Members
      operationId: getApiTeamsByOriginOrId
      x-operation-id-source: derived
    put:
      summary: Update or insert a specific team by its origin or id
      description: 'Update or insert a specific team by its **origin** or **id**. In case a team with the given **origin** or **id** is found it will be updated. If there is no team found a new team will be created and the given `originOrId` is used as **origin**.


        `spec.display` fully replaces the existing display values. `spec.members` is reconciled declaratively — the resulting membership is exactly the set given in the request body (adds and removes are computed against the current membership).'
      parameters:
      - in: path
        name: originOrId
        schema:
          type: string
        required: true
        description: The **origin** or **id** of the team.
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/TeamDefinitionV1Alpha1'
      responses:
        '200':
          description: The updated or created team.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/TeamDefinitionV1Alpha1'
        default:
          description: In case any error happens.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
      tags:
      - Manage Teams and Members
      operationId: putApiTeamsByOriginOrId
      x-operation-id-source: derived
  /api/teams/{originOrId}/display:
    put:
      summary: Update a specific team display option
      description: Update the display name, description, and color of a team.
      parameters:
      - in: path
        name: originOrId
        schema:
          type: string
        required: true
        description: The **origin** or **id** of the team.
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/TeamDisplay'
      responses:
        '204':
          description: Successfully updated team display.
        default:
          description: In case any error happens.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
      tags:
      - Manage Teams and Members
      operationId: putApiTeamsByOriginOrIdDisplay
      x-operation-id-source: derived
  /api/teams/{originOrId}/members:
    post:
      summary: Add members to a team
      description: Adds the given members to the team.
      parameters:
      - in: path
        name: originOrId
        schema:
          type: string
        required: true
        description: The **origin** or **id** of the team.
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/AddTeamMembersRequest'
      responses:
        '201':
          description: The members are added.
        default:
          description: In case any error happens.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
      tags:
      - Manage Teams and Members
      operationId: postApiTeamsByOriginOrIdMembers
      x-operation-id-source: derived
  /api/teams/{originOrId}/members/{memberID}:
    delete:
      summary: Remove a member from a team
      description: Removes the given member from the team.
      parameters:
      - in: path
        name: originOrId
        schema:
          type: string
        required: true
        description: The **origin** or **id** of the team.
      - in: path
        name: memberID
        schema:
          type: string
        required: true
        description: The **id** of the member.
      responses:
        '204':
          description: The member is removed.
        default:
          description: In case any error happens.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
      tags:
      - Manage Teams and Members
      operationId: deleteApiTeamsByOriginOrIdMembersByMemberID
      x-operation-id-source: derived
components:
  schemas:
    Error:
      properties:
        code:
          type: integer
          description: 'HTTP status code.

            '
        type:
          type: string
          description: 'Stable `snake_case` identifier for the kind of error, safe for clients to branch on. Not

            an enum: treat an unrecognized value the same as an absent one and fall back to `message`,

            so a new error kind never breaks the contract. Optional — absent means unclassified, not

            success.

            '
        message:
          type: string
          description: 'Human-readable description of the error. Safe to display.

            '
        traceId:
          type: string
          description: 'Trace ID for the request that produced the error, for correlating with logs and traces.

            '
      required:
      - code
      - message
    TeamAnnotations:
      description: 'Key/value annotations on the team. Arbitrary keys are accepted on

        write (the request is not rejected), but the server only interprets

        and persists the reserved `dash0.com/*` keys documented below. Any

        other key supplied by the client is silently dropped and will not

        appear on the response or on subsequent reads.

        '
      type: object
      additionalProperties:
        type: string
      properties:
        dash0.com/created-at:
          description: Timestamp when the team was created. Set by the server; read-only.
          type: string
          format: date-time
        dash0.com/updated-at:
          description: Timestamp of the last update to the team. Set by the server; read-only.
          type: string
          format: date-time
    GetTeamResponse:
      properties:
        team:
          $ref: '#/components/schemas/TeamDefinitionV1Alpha1'
        members:
          type: array
          items:
            $ref: '#/components/schemas/MemberDefinition'
        dashboards:
          type: array
          items:
            $ref: '#/components/schemas/AccessibleAsset'
        checkRules:
          type: array
          items:
            $ref: '#/components/schemas/AccessibleAsset'
        syntheticChecks:
          type: array
          items:
            $ref: '#/components/schemas/AccessibleAsset'
        views:
          type: array
          items:
            $ref: '#/components/schemas/AccessibleAsset'
        datasets:
          type: array
          items:
            $ref: '#/components/schemas/AccessibleAsset'
        agenticWorkflows:
          type: array
          items:
            $ref: '#/components/schemas/AccessibleAsset'
      required:
      - team
      - members
      - dashboards
      - checkRules
      - syntheticChecks
      - views
      - datasets
      - agenticWorkflows
    ErrorResponse:
      type: object
      properties:
        error:
          $ref: '#/components/schemas/Error'
      required:
      - error
    UpdateMemberRoleRequest:
      properties:
        role:
          type: string
          description: The member's role in the organization
      required:
      - role
    MemberMetadata:
      properties:
        name:
          type: string
        labels:
          $ref: '#/components/schemas/MemberLabels'
      required:
      - name
    TeamDisplay:
      properties:
        name:
          description: Human-facing name of the team, used in the UI.
          type: string
        description:
          type: string
        color:
          $ref: '#/components/schemas/Gradient'
      required:
      - name
      - color
    TeamsListItem:
      properties:
        id:
          type: string
        origin:
          type: string
        source:
          $ref: '#/components/schemas/CrdSource'
        name:
          type: string
        color:
          $ref: '#/components/schemas/Gradient'
        members:
          description: 'A sample of five members. You can inspect the total member count via `totalMemberCount`. This array

            is restricted to at most five members, because this could otherwise be too much data.

            '
          type: array
          maxItems: 5
          items:
            $ref: '#/components/schemas/MemberDefinition'
        totalMemberCount:
          type: integer
      required:
      - id
      - name
      - color
      - members
      - totalMemberCount
    Dataset:
      type: string
      pattern: ^[a-zA-Z0-9_-]{3,26}$
      description: Optional dataset to query across. Defaults to whatever is configured to be the default dataset for the organization.
    MemberDisplay:
      properties:
        email:
          type: string
        firstName:
          type: string
        lastName:
          type: string
        imageUrl:
          type: string
    FixedTime:
      type: string
      format: date-time
      description: 'A fixed point in time represented as an RFC 3339 date-time string.


        **Format**: `YYYY-MM-DDTHH:MM:SSZ` (UTC) or `YYYY-MM-DDTHH:MM:SS±HH:MM` (with timezone offset)


        **Examples**:

        - `2024-01-15T14:30:00Z`

        - `2024-01-15T14:30:00+08:00`

        '
    TeamDefinitionV1Alpha1:
      description: 'v1alpha1 team definition. `metadata.name` is the team''s technical name

        (used e.g. as the CRD name in an operator manifest or a Terraform

        resource ID), `spec.display` carries the human-facing attributes

        (name, description, color) and `spec.members` is the declarative list

        of member IDs that make up the team. `metadata.name` and

        `spec.display.name` are persisted independently.

        '
      properties:
        apiVersion:
          $ref: '#/components/schemas/TeamApiVersion'
          description: 'Optional on write requests for backwards compatibility: defaults to

            `dash0.com/v1alpha1` when omitted. Always populated on read responses.

            '
        kind:
          type: string
          enum:
          - Dash0Team
        metadata:
          $ref: '#/components/schemas/TeamMetadata'
        spec:
          $ref: '#/components/schemas/TeamSpec'
      required:
      - kind
      - metadata
      - spec
    MemberLabels:
      properties:
        dash0.com/id:
          description: The member's ID, used to address the member in the members and teams endpoints.
          type: string
        dash0.com/userId:
          description: The member's Dash0 user ID. Use it wherever another endpoint asks for a user ID, such as the `userId` of a custom skill permission.
          type: string
        dash0.com/joinedAt:
          type: string
          format: date-time
        dash0.com/role:
          description: The member's role in the organization
          type: string
    MemberSpec:
      properties:
        display:
          $ref: '#/components/schemas/MemberDisplay'
      required:
      - display
    TeamLabels:
      description: 'Key/value labels on the team. Arbitrary keys are accepted on write

        (the request is not rejected), but the server only interprets and

        persists the reserved `dash0.com/*` keys documented below. Any

        other key supplied by the client is silently dropped and will not

        appear on the response or on subsequent reads.

        '
      type: object
      additionalProperties:
        type: string
      properties:
        dash0.com/id:
          description: 'Unique internal ID of the team. Server-set on creation and

            stable for the lifetime of the team; ignored if supplied on

            POST and PUT request bodies.

            '
          type: string
        dash0.com/origin:
          description: 'External identifier for API-managed teams (e.g. the CRD name

            from an operator manifest or a Terraform resource ID).

            Client-settable on create only — a team''s origin cannot be

            changed once it exists. Empty for teams created via the UI;

            non-empty for teams created via the internal API or reconciled

            by an operator. Uniquely identifies a team within its

            organization when present.

            '
          type: string
        dash0.com/source:
          $ref: '#/components/schemas/CrdSource'
          description: 'Origin source derived by the server from the request context.

            Read-only.

            '
    MemberDefinition:
      properties:
        kind:
          type: string
          enum:
          - Dash0Member
        metadata:
          $ref: '#/components/schemas/MemberMetadata'
        spec:
          $ref: '#/components/schemas/MemberSpec'
      required:
      - kind
      - metadata
      - spec
    TeamMetadata:
      properties:
        name:
          description: 'Technical name of the team (e.g. `platform-team`). Distinct from

            `spec.display.name`, which carries the human-facing name. Persisted

            verbatim and echoed on read responses.

            '
          type: string
        labels:
          $ref: '#/components/schemas/TeamLabels'
        annotations:
          $ref: '#/components/schemas/TeamAnnotations'
      required:
      - name
    CrdSource:
      description: "Origin of a Dash0 resource, derived from `dash0.com/origin` on read.\n- `ui`: created interactively in the Dash0 UI.\n- `terraform`: managed via the Dash0 Terraform provider.\n- `operator`: managed via the Dash0 Kubernetes operator.\n- `dash0-cli`: managed via the Dash0 CLI.\n- `platform`: owned by Dash0 rather than by anyone in your organization. Covers both\n  resources Dash0 generates from another resource you own (the recording rules an SLO\n  produces) and resources Dash0 ships with the product (the built-in views).\n- `identity-provider`: a team whose membership Dash0 keeps in sync with a directory\n  group from the organization's identity provider. Membership edits made by hand\n  revert on the next reconcile.\n- `api`: created directly through the API, and the fallback for any origin whose\n  prefix is not recognized.\n\nNew values may be added over time. Treat an unrecognized value as `api`\nrather than rejecting the response.\n"
      type: string
      enum:
      - ui
      - terraform
      - operator
      - dash0-cli
      - platform
      - identity-provider
      - api
    MemberInvitationDefinition:
      description: 'An invitation to join the organization that has not been accepted yet. Once accepted, the

        invitee is listed as a member instead.

        '
      properties:
        kind:
          type: string
          enum:
          - Dash0MemberInvitation
        metadata:
          $ref: '#/components/schemas/MemberInvitationMetadata'
        spec:
          $ref: '#/components/schemas/MemberInvitationSpec'
      required:
      - kind
      - metadata
      - spec
    AccessibleAsset:
      properties:
        id:
          type: string
        name:
          type: string
        type:
          description: returns for views the information which type of view it is
          type: string
        permittedActions:
          type: array
          items:
            $ref: '#/components/schemas/Action'
        createdAt:
          $ref: '#/components/schemas/FixedTime'
        creator:
          $ref: '#/components/schemas/MemberDefinition'
        dataset:
          $ref: '#/components/schemas/Dataset'
        hasAccess:
          description: returns the information if the logged-in user has access to this asset
          type: boolean
      required:
      - id
      - name
      - permittedActions
      - createdAt
      - dataset
      - hasAccess
    MemberInvitationLabels:
      properties:
        dash0.com/id:
          description: 'ID of the invitation, for `DELETE /api/members/invitations/{invitationID}`. It

            identifies the invitation, not a member: it cannot be passed where a member ID is

            expected.

            '
          type: string
        dash0.com/role:
          description: The role the invitee receives on accepting.
          type: string
        dash0.com/invited-at:
          type: string
          format: date-time
        dash0.com/expires-at:
          description: When the invitation stops being valid. Absent if it does not expire.
          type: string
          format: date-time
      required:
      - dash0.com/id
      - dash0.com/role
      - dash0.com/invited-at
    TeamSpec:
      properties:
        display:
          $ref: '#/components/schemas/TeamDisplay'
        members:
          description: 'The declarative membership of the team. Each entry is either a

            member''s internal ID (the `dash0.com/id` label value returned

            for the member, e.g. `user_01ABC...`) or an email address.

            Emails are matched case-insensitively against the

            organization''s members and translated to internal IDs during

            reconciliation, so callers can author teams with

            human-readable references. An empty array clears the team''s

            membership; a `null`/missing value is rejected with 400.

            Unresolvable email addresses cause the entire request to fail

            with 400 listing every offender. Responses always echo the

            resolved internal IDs.

            '
          type: array
          items:
            type: string
      required:
      - display
      - members
    Action:
      type: string
      description: 'Not defined as an enum, because we will eventually support wildcards like `ingest:*`.

        '
    AddTeamMembersRequest:
      properties:
        memberIds:
          description: 'Add an existing organization member to this team.

            '
          type: array
          items:
            type: string
      required:
      - memberIds
    InviteMemberRequest:
      properties:
        emailAddress:
          type: string
          description: 'The address the invitation is sent to. An address that the organization''s sign-up

            restrictions do not permit is rejected with `403`, and an address that already belongs

            to the organization, or already has a pending invitation, with `409`.

            '
        role:
          type: string
          description: 'The role the invited member receives. The built-in roles are `admin` and

            `basic_member`; an organization with custom roles configured may use those instead.

            An unknown role is rejected with `400`.

            '
      required:
      - emailAddress
      - role
    MemberInvitationMetadata:
      properties:
        name:
          description: The address the invitation was sent to.
          type: string
        labels:
          $ref: '#/components/schemas/MemberInvitationLabels'
      required:
      - name
      - labels
    TeamApiVersion:
      description: 'API version of the team CRD. Currently only `dash0.com/v1alpha1` is

        supported.

        '
      type: string
      enum:
      - dash0.com/v1alpha1
    MemberInvitationSpec:
      properties:
        emailAddress:
          description: The address the invitation was sent to.
          type: string
      required:
      - emailAddress
    Gradient:
      description: A color gradient from one color to another.
      properties:
        from:
          type: string
        to:
          type: string
      required:
      - from
      - to
x-provenance:
  method: harvested
  publisher: Dash0
  source: https://api.eu-central-1.aws.dash0.com/openapi.json
  note: split by refine-openapis from the provider's own published document, verified by fetch (openapi/_original/*.fetch.json);
    stamped by stamp-openapi-provenance.py (roadmap#793)