openapi: 3.0.0
info:
  title: SLO status v2.0
  version: 2.0.0
  description:
    $ref: './md-partials/slo-status-intro.mdx'
servers:
  - url: "https://app.nobl9.com/api/v2"
  - url: "https://us1.nobl9.com/api/v2"
tags:
  - name: SLO status
paths:
  /slos:
    get:
      summary: List SLOs
      tags:
        - SLO status
      description:
        $ref: './md-partials/pagination.mdx'
      security:
        - bearerAuth: [ ]
      parameters:
        - $ref: '#/components/parameters/organization'
        - in: query
          name: limit
          required: false
          description: Specifies the number of returned results (maximum of 500 items).
          schema:
            type: integer
        - in: query
          name: cursor
          description: Specifies the pagination cursor for the next page of results. You can get it through the `next` link property.
          required: false
          schema:
            type: string
      responses:
        200:
          description: Success
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/SLOList'
        401:
          description: Authentication credentials not valid
        429:
          description: API call exceeded the rate limit
  /slos/{sloName}:
    get:
      summary: Find SLO by name
      tags:
        - SLO status
      description: >-
        Returns a specific SLO by name and project.
        <hr/>
        <p/>
        <div class='api-note'><b>AUTHENTICATION REQUIRED</b><br/>Authenticate API requests using an [access token](/api/access-token/generate-access-token). Include it in the Authorization header as <code>Bearer TOKEN</code>.</div>
      security:
        - bearerAuth: [ ]
      parameters:
        - $ref: '#/components/parameters/organization'
        - in: header
          name: project
          description: Filters results by a specific project.
          required: true
          schema:
            type: string
        - in: path
          name: sloName
          description: Name of the SLO to return.
          required: true
          schema:
            type: string
            maxLength: 63
        - in: query
          name: fields
          required: false
          example: counts
          description: |
            Use to request for additional metrics, such as aggregated good and total counts.<br/>
            Currently supported `counts`, which returns the total and good counts for each of the SLO's objective.<br/>
            To specify the range of data to be gathered, use `to` and `from` query parameters (e.g., `from=2021-01-01T00:00:00Z&to=2021-01-02T00:00:00Z`).
          schema:
            type: string
        - in: query
          name: from
          required: false
          example: 2024-01-25T23:00:00Z
          description:
            Specifies the start date and time for the data range (in UTC). Required when using the `fields` and `to` parameter.<br/>
            The API allows to retrieve 7 days of data.
          schema:
            type: string
            format: date-time
        - in: query
          name: to
          required: false
          example: 2024-01-25T23:59:00Z
          description:
            Specifies the end date and time for the data range (in UTC). Required when using the `fields` and `from` parameter.<br/>
            The API allows to retrieve 7 days of data.
          schema:
            type: string
            format: date-time
      responses:
        200:
          description: Success
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/SLO'
        401:
          description: Authentication credentials not valid
        403:
          description: Access to the requested SLO is forbidden
        404:
          description: SLO not found
        429:
          description: API call exceeded the rate limit
components:
  parameters:
    organization:
      in: header
      name: Organization
      description: ID of your organization.
      required: true
      schema:
        type: string
  schemas:
    AccessToken:
      properties:
        access_token:
          type: string
      type: object
    Error:
      type: object
      description: >-
        Error always contains the status code and message.
        Additionally, the detailed description of the problem can be included.
      additionalProperties: true
      properties:
        message:
          type: string
        statusCode:
          type: integer
      required:
        - statusCode
        - message
    SLO:
      type: object
      properties:
        name:
          type: string
          example: sample-latency-slo
        displayName:
          type: string
          example: Sample latency SLO
        description:
          type: string
          example: This is a sample latency SLO
        project:
          type: object
          properties:
            name:
              type: string
              example: sample-project
            displayName:
              type: string
              example: Sample project
            labels:
              $ref: '#/components/schemas/Labels'
        service:
          type: object
          properties:
            name:
              type: string
              example: sample-service
            displayName:
              type: string
              example: Sample service
            labels:
              $ref: '#/components/schemas/Labels'
        objectives:
          type: array
          items:
            $ref: '#/components/schemas/Objective'
        createdAt:
          type: string
          format: date-time
        composite:
          $ref: '#/components/schemas/Composite'
        labels:
          $ref: '#/components/schemas/Labels'
        annotations:
          $ref: '#/components/schemas/Annotations'
        budgetingMethod:
          type: string
          example: Occurrences
          description: The method used to calculate the error budget. Can be either "Occurrences" or "Time slices".
    Objective:
      type: object
      properties:
        name:
          type: string
          example: objective-1
        displayName:
          type: string
          example: Good
        target:
          type: number
          format: float
          example: 0.5
          description: Target value (percentage in decimal format).
        burnRate:
          type: number
          format: float
          example: 0
          description: Instantaneous burn rate value.
        errorBudgetRemaining:
          type: number
          format: float
          example: 14397.305873435587
          description: Remaining error budget value in seconds.
        errorBudgetRemainingPercentage:
          type: number
          format: float
          example: 0.5951267308794467
          description: Remaining error budget percentage (in decimal format).
        reliability:
          type: number
          format: float
          example: 0.1888888888888888
          description: Reliability burn down value (percentage in decimal form)
        sliType:
          type: string
          enum: [Ratio, Threshold, Composite]
          example: Threshold
          description: Specifies the Service Level Indicator (SLI) type of the objective.
        counts:
          type: object
          properties:
            total:
              type: number
              example: 59
              description:
                Depending on the SLO's budgeting method, this field can represent either\:<br/>
                - Occurrences - the aggregated value of all events in a given time range<br/>
                - Timeslices - total number of minutes in a given time range (minus the minutes with no data)
            good:
              type: number
              example: 1
              description:
                Depending on the SLO's budgeting method, this field can represent either\:<br/>
                - Occurrences - the aggregated value of good events in a given time range<br/>
                - Timeslices - number of good minutes
          description: Aggregated data for the SLO's objective
    Composite:
      description: This object refers to deprecated legacy composite SLOs 1.0 only.
      type: object
      properties:
        target:
          type: number
          format: float
          example: 0.9
        burnRate:
          type: number
          format: float
          example: 0
          description: Instantaneous burn rate value.
        errorBudgetRemaining:
          type: number
          format: float
          example: 14397.305873435587
          description: Remaining error budget value in seconds.
        errorBudgetRemainingPercentage:
          type: number
          format: float
          example: 0.5951267308794467
          description: Remaining error budget percentage (in decimal format).
        reliability:
          type: number
          format: float
          example: 0.1888888888888888
          description: Reliability burn down value (percentage in decimal form)
        burnRateCondition:
          $ref: '#/components/schemas/CompositeBurnRateCondition'
    CompositeBurnRateCondition:
      type: object
      properties:
        value:
          type: number
          format: float
        operator:
          type: string
          enum: [gt]
          example: gt
    Labels:
      type: object
      additionalProperties:
        type: array
        items:
          type: string
      example:
        type:
          - service
        team:
          - foundations
          - io
    Annotations:
      type: object
      description: Metadata annotations added to the SLO.
      additionalProperties:
        type: string
      example:
        internal: "true"
        registry: "docker.io"
    SLOList:
      type: object
      properties:
        data:
          type: array
          items:
            $ref: '#/components/schemas/SLO'
        links:
          $ref: '#/components/schemas/Links'
    Links:
      type: object
      properties:
        self:
          type: string
        next:
          type: string
  responses:
    BadRequestError:
      description: Bad request
    UnauthorizedError:
      description: Unauthorized
      headers:
        WWW-Authenticate:
          schema:
            type: string
            description: 'https://developer.mozilla.org/en-US/docs/Web/HTTP/Headers/WWW-Authenticate'
    ForbiddenError:
      description: Forbidden
    NotFoundError:
      description: One of the resources referenced in query or payload was not found
    TooManyRequestsError:
      description: API call exceeded the rate limit
  securitySchemes:
    bearerAuth:
      type: http
      scheme: bearer
      bearerFormat: JWT
