Dash0 Manage Time Series Aggregations (Private BETA) API

openapi: 3.1.0
info:
  title: Dash0 Edge Collectors Manage Time Series Aggregations (Private BETA) API
  version: 1.0.0
  description: '## 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-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 Time Series Aggregations (Private BETA)
paths:
  /api/time-series-aggregations/{originOrId}:
    delete:
      summary: Delete a time series aggregation by origin or ID
      description: Deletes a specific time series aggregation identified by its origin label or UUID.
      tags:
      - Manage Time Series Aggregations (Private BETA)
      parameters:
      - in: path
        name: originOrId
        schema:
          type: string
        required: true
        description: Time series aggregation origin or UUID
      - in: query
        name: dataset
        schema:
          $ref: '#/components/schemas/Dataset'
      responses:
        '200':
          description: Successfully deleted
        '403':
          description: Forbidden - Admin access required
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        default:
          description: In case any error happens.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
      operationId: delete_api-time-series-aggregations-originorid
    get:
      summary: Get a specific time series aggregation by origin or ID
      description: Returns a specific time series aggregation identified by its origin label or UUID.
      tags:
      - Manage Time Series Aggregations (Private BETA)
      parameters:
      - in: path
        name: originOrId
        schema:
          type: string
        required: true
        description: Time series aggregation origin or UUID
      - in: query
        name: dataset
        schema:
          $ref: '#/components/schemas/Dataset'
      responses:
        '200':
          description: The requested time series aggregation
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/TimeSeriesAggregationDefinition'
        default:
          description: In case any error happens.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
      operationId: get_api-time-series-aggregations-originorid
    put:
      summary: Update or create a time series aggregation by origin or ID
      description: 'Updates an existing time series aggregation or creates a new one if it doesn''t exist.

        Useful for Infrastructure-as-Code workflows.

        '
      tags:
      - Manage Time Series Aggregations (Private BETA)
      parameters:
      - in: path
        name: originOrId
        schema:
          type: string
        required: true
        description: Time series aggregation origin or UUID
      - in: query
        name: dataset
        schema:
          $ref: '#/components/schemas/Dataset'
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/TimeSeriesAggregationDefinition'
      responses:
        '200':
          description: The updated or created time series aggregation
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/TimeSeriesAggregationDefinition'
        '403':
          description: Forbidden - Admin access required
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        default:
          description: In case any error happens.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
      operationId: put_api-time-series-aggregations-originorid
  /api/time-series-aggregations:
    get:
      summary: List all time series aggregations for the organization
      description: Returns all time series aggregation rules configured for your organization.
      tags:
      - Manage Time Series Aggregations (Private BETA)
      parameters:
      - in: query
        name: dataset
        schema:
          $ref: '#/components/schemas/Dataset'
      responses:
        '200':
          description: List of time series aggregations
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/TimeSeriesAggregationListResponse'
        default:
          description: In case any error happens.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
      operationId: get_api-time-series-aggregations
    post:
      summary: Create a new time series aggregation
      description: 'Create a new time series aggregation rule for your organization. If

        `metadata.labels["dash0.com/origin"]` is provided, it must be unique within the

        organization and dataset; a request with a duplicate origin returns 400. If no

        origin is provided, the server auto-generates one.

        '
      tags:
      - Manage Time Series Aggregations (Private BETA)
      parameters:
      - in: query
        name: dataset
        schema:
          $ref: '#/components/schemas/Dataset'
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/TimeSeriesAggregationDefinition'
      responses:
        '200':
          description: The created time series aggregation
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/TimeSeriesAggregationDefinition'
        '403':
          description: Forbidden - Admin access required
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        default:
          description: In case any error happens.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
      operationId: post_api-time-series-aggregations
components:
  schemas:
    AnyValue:
      description: AnyValue is used to represent any type of attribute value. AnyValue may contain a primitive value such as a string or integer or it may contain an arbitrary nested object containing arrays, key-value lists and primitives.
      type: object
      properties:
        stringValue:
          type: string
        boolValue:
          type: boolean
        intValue:
          type: string
          format: int64
        doubleValue:
          type: number
          format: double
        bytesValue:
          type: string
          format: byte
    AttributeFilterAnyValue:
      description: AttributeFilterAnyValue may contain any AnyValue value.
      $ref: '#/components/schemas/AnyValue'
    ErrorResponse:
      type: object
      properties:
        error:
          $ref: '#/components/schemas/Error'
      required:
      - error
    TimeSeriesAggregationMetricNameMatch:
      properties:
        metricNameMatcher:
          $ref: '#/components/schemas/Matcher'
        otherFilters:
          $ref: '#/components/schemas/FilterCriteria'
          x-go-type-skip-optional-pointer: true
      required:
      - metricNameMatcher
    TimeSeriesAggregationListResponse:
      type: object
      properties:
        timeSeriesAggregations:
          type: array
          items:
            $ref: '#/components/schemas/TimeSeriesAggregationDefinition'
      required:
      - timeSeriesAggregations
    AttributeFilterStringValue:
      description: AttributeFilterStringValue may contain a primitive value such as a regex pattern or string.
      type: string
    TimeSeriesAggregationAttributeModificationContext:
      type: string
      enum:
      - resource
      - scope
      - datapoint
    TimeSeriesAggregationDisplay:
      properties:
        name:
          description: 'Short-form name for the view to be shown prominently within the view list and atop

            the screen when the view is selected.

            '
          type: string
      required:
      - name
    Error:
      properties:
        code:
          type: integer
        message:
          type: string
        traceId:
          type: string
      required:
      - code
      - message
    CrdSource:
      description: 'Origin of a Dash0 resource.

        - `ui`: created interactively in the Dash0 UI.

        - `terraform`: managed via the Dash0 Terraform provider.

        - `operator`: managed via the Dash0 Kubernetes operator.

        - `api`: created directly through the internal API.

        '
      type: string
      enum:
      - ui
      - terraform
      - operator
      - api
    AttributeFilterKey:
      type: string
      description: The attribute key to be filtered.
    AttributeFilterOperator:
      type: string
      enum:
      - is
      - is_not
      - is_set
      - is_not_set
      - is_one_of
      - is_not_one_of
      - gt
      - lt
      - gte
      - lte
      - matches
      - does_not_match
      - contains
      - does_not_contain
      - starts_with
      - does_not_start_with
      - ends_with
      - does_not_end_with
      - is_any
      description: 'The match operation for filtering attributes.


        #### Equality Operators

        - `is` - equals (attribute exists and has a matching value)

        - `is_not` - not equals (attribute exists and has a different value)


        #### Existence Operators

        - `is_set` - is set (attribute exists)

        - `is_not_set` - is not set (attribute does not exist)


        #### Multiple Value Operators

        - `is_one_of` - is any of (attribute exists and has a value that is in the specified values)

        - `is_not_one_of` - is not any of (attribute exists and has a value that is not in the specified values)


        #### Comparison Operators

        - `gt` - greater than

        - `lt` - less than

        - `gte` - greater than or equal

        - `lte` - less than or equal


        #### Pattern Matching Operators

        - `matches` - match regex expression (attribute exists and matches the regular expression)

        - `does_not_match` - does not match regex expression (attribute exists and does not match the regular expression)


        #### String Operators

        - `contains` - contains (attribute exists and contains the specified value)

        - `does_not_contain` - does not contain (attribute exists and does not contain the specified value)

        - `starts_with` - starts with (attribute exists and starts with the specified value)

        - `does_not_start_with` - does not start with (attribute exists and does not start with the specified value)

        - `ends_with` - ends with (attribute exists and ends with the specified value)

        - `does_not_end_with` - does not end with (attribute exists and does not end with the specified value)


        #### Special Operators

        - `is_any` - matches any value, ignoring whether the key exists or not

        '
    TimeSeriesAggregationAttributeModification:
      properties:
        kind:
          type: string
          enum:
          - drop_attributes
          - keep_attributes
        spec:
          $ref: '#/components/schemas/TimeSeriesAggregationAttributeModificationSpec'
      required:
      - kind
      - spec
    Matcher:
      type: object
      properties:
        operator:
          $ref: '#/components/schemas/AttributeFilterOperator'
        value:
          oneOf:
          - $ref: '#/components/schemas/AttributeFilterStringValue'
          - $ref: '#/components/schemas/AttributeFilterAnyValue'
        values:
          type: array
          description: 'List of values to match against. This parameter is mandatory for the is_one_of and is_not_one_of operators.

            '
          items:
            oneOf:
            - $ref: '#/components/schemas/AttributeFilterStringValue'
            - $ref: '#/components/schemas/AttributeFilterAnyValue'
      required:
      - operator
    AttributeFilter:
      type: object
      properties:
        key:
          $ref: '#/components/schemas/AttributeFilterKey'
        operator:
          $ref: '#/components/schemas/AttributeFilterOperator'
        value:
          oneOf:
          - $ref: '#/components/schemas/AttributeFilterStringValue'
          - $ref: '#/components/schemas/AttributeFilterAnyValue'
        values:
          type: array
          description: 'List of values to match against. This parameter is mandatory for the is_one_of and is_not_one_of operators.

            '
          items:
            oneOf:
            - $ref: '#/components/schemas/AttributeFilterStringValue'
            - $ref: '#/components/schemas/AttributeFilterAnyValue'
      required:
      - key
      - operator
    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.
    FilterCriteria:
      type: array
      items:
        $ref: '#/components/schemas/AttributeFilter'
      example:
      - key: service.name
        operator: is
        value: foo
    TimeSeriesAggregationSample:
      properties:
        interval:
          description: 'The frequency at which metric data points are aggregated via these rules. This is a required parameter.

            If you don''t which to downsample your metrics, then set this to the scrape/export interval of your

            metrics. Otherwise, use a larger number to reduce the granularity of your metrics.

            '
          $ref: '#/components/schemas/Duration'
        delay:
          description: 'The amount of time to account for delays in scraping, exporting, and data arrival. We suggest to always

            add a little bit of a delay to account for this. But you can increase it in case you have larger delays in

            your scrape and export processes.

            '
          $ref: '#/components/schemas/Duration'
          default: 20s
        staleAfter:
          description: 'Duration after which a time series with no new data is considered stale and removed from memory.

            When a stale time series is removed and new data arrives later, it is treated as a fresh start:

            for cumulative metrics, no delta is computed against the old baseline, and the new value is

            exported as-is. This prevents incorrect delta calculations after long gaps in data.

            Default is 5 times the interval.

            '
          $ref: '#/components/schemas/Duration'
      required:
      - interval
    Duration:
      type: string
      pattern: (\d+(ms|s|m|h|d|w|M|Q|y))+
    TimeSeriesAggregationDefinition:
      properties:
        kind:
          type: string
          enum:
          - Dash0TimeSeriesAggregation
        metadata:
          $ref: '#/components/schemas/TimeSeriesAggregationMetadata'
        spec:
          $ref: '#/components/schemas/TimeSeriesAggregationSpec'
      required:
      - kind
      - metadata
      - spec
    TimeSeriesAggregationSpec:
      properties:
        enabled:
          type: boolean
        priority:
          description: 'Precedence when more than one rule matches a metric. Lower values are evaluated first

            (higher precedence). Defaults to 0. Rules with equal priority are ordered deterministically

            by creation time, then by id.

            '
          type: integer
        display:
          $ref: '#/components/schemas/TimeSeriesAggregationDisplay'
        match:
          $ref: '#/components/schemas/TimeSeriesAggregationMetricNameMatch'
        sample:
          $ref: '#/components/schemas/TimeSeriesAggregationSample'
        attributeModifications:
          type: array
          items:
            $ref: '#/components/schemas/TimeSeriesAggregationAttributeModification'
      required:
      - enabled
      - match
      - sample
    TimeSeriesAggregationAttributeModificationSpec:
      properties:
        context:
          $ref: '#/components/schemas/TimeSeriesAggregationAttributeModificationContext'
        keyMatcher:
          $ref: '#/components/schemas/Matcher'
      required:
      - keyMatcher
    TimeSeriesAggregationAnnotations:
      properties:
        dash0.com/created-at:
          description: Timestamp when the aggregation was created. Set by the server; read-only.
          type: string
          format: date-time
        dash0.com/updated-at:
          description: Timestamp of the last update. Set by the server; read-only.
          type: string
          format: date-time
        dash0.com/deleted-at:
          description: Timestamp when the aggregation was soft-deleted. Set by the server; read-only. Absent unless the aggregation is deleted.
          type: string
          format: date-time
    TimeSeriesAggregationMetadata:
      properties:
        name:
          type: string
        labels:
          $ref: '#/components/schemas/TimeSeriesAggregationLabels'
        annotations:
          $ref: '#/components/schemas/TimeSeriesAggregationAnnotations'
      required:
      - name
    TimeSeriesAggregationLabels:
      properties:
        dash0.com/id:
          type: string
        dash0.com/origin:
          type: string
        dash0.com/version:
          type: string
        dash0.com/dataset:
          type: string
        dash0.com/source:
          $ref: '#/components/schemas/CrdSource'
        custom:
          type: object
          additionalProperties:
            type: string