openapi: 3.1.0
info:
  title: FinOps Foundation FOCUS Cost and Usage Contract Commitments API
  description: An API modeled on the FinOps Open Cost and Usage Specification (FOCUS) v1.3, which defines a standard schema for cloud, SaaS, and other technology billing data. FOCUS normalizes billing datasets across providers to reduce complexity for FinOps practitioners. This specification models the Cost and Usage dataset and the Contract Commitment dataset defined by the FOCUS standard, enabling programmatic access to FOCUS-compliant billing data. The FOCUS specification is maintained by the FinOps Foundation under the Linux Foundation.
  version: 1.3.0
  contact:
    name: FinOps Foundation
    url: https://www.finops.org/
  license:
    name: Community Specification License 1.0
    url: https://github.com/FinOps-Open-Cost-and-Usage-Spec/FOCUS_Spec/blob/main/LICENSE
  x-focus-version: '1.3'
servers:
- url: https://api.example.com/focus/v1
  description: Example FOCUS-compliant API server
security:
- bearerAuth: []
- apiKeyAuth: []
tags:
- name: Contract Commitments
  description: Endpoints for querying contract commitment data, a supplemental dataset introduced in FOCUS v1.3 that isolates contract terms from cost and usage rows.
paths:
  /contract-commitments:
    get:
      operationId: listContractCommitments
      summary: FinOps Foundation List contract commitment records
      description: Retrieves contract commitment records as defined in the FOCUS v1.3 supplemental dataset. Contract commitments isolate contract terms such as start and end dates, remaining units, and descriptions from cost and usage rows.
      tags:
      - Contract Commitments
      parameters:
      - name: commitmentDiscountId
        in: query
        description: Filter by the identifier assigned to a commitment discount by the provider.
        required: false
        schema:
          type: string
      - name: billingAccountId
        in: query
        description: Filter by the unique identifier for a billing account.
        required: false
        schema:
          type: string
      - name: pageSize
        in: query
        description: Number of records to return per page.
        required: false
        schema:
          type: integer
          minimum: 1
          maximum: 10000
          default: 1000
      - name: pageToken
        in: query
        description: Token for retrieving the next page of results.
        required: false
        schema:
          type: string
      responses:
        '200':
          description: A paginated list of contract commitment records.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ContractCommitmentResponse'
        '400':
          description: Invalid request parameters.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '401':
          description: Authentication required.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
components:
  schemas:
    ContractCommitmentRecord:
      type: object
      description: A contract commitment record as defined in FOCUS v1.3. Isolates contract terms including start and end dates, remaining units, and descriptions from cost and usage rows.
      properties:
        CommitmentDiscountId:
          type: string
          description: The unique identifier assigned to a commitment discount by the provider. MUST NOT be null.
        CommitmentDiscountName:
          type: string
          nullable: true
          description: The display name assigned to a commitment discount.
        CommitmentDiscountType:
          type: string
          nullable: true
          description: A provider-assigned label describing the type of commitment discount.
        CommitmentDiscountCategory:
          type: string
          enum:
          - Spend
          - Usage
          description: Whether the commitment discount is based on usage quantity or cost.
        CommitmentStartDate:
          type: string
          format: date-time
          description: The start date and time of the contract commitment.
        CommitmentEndDate:
          type: string
          format: date-time
          description: The end date and time of the contract commitment.
        CommitmentTotalQuantity:
          type: number
          nullable: true
          description: The total quantity of the commitment purchased.
        CommitmentRemainingQuantity:
          type: number
          nullable: true
          description: The remaining quantity of the commitment that has not yet been consumed.
        CommitmentUnit:
          type: string
          nullable: true
          description: The unit of measurement for the commitment quantity.
        CommitmentDescription:
          type: string
          nullable: true
          description: A human-readable description of the contract commitment.
        BillingAccountId:
          type: string
          description: The unique identifier for the billing account associated with the commitment.
        BillingAccountName:
          type: string
          nullable: true
          description: The display name for the billing account.
        ProviderName:
          type: string
          description: The name of the entity that made the commitment discount available.
      required:
      - CommitmentDiscountId
      - CommitmentStartDate
      - CommitmentEndDate
      - BillingAccountId
      - ProviderName
    ContractCommitmentResponse:
      type: object
      properties:
        data:
          type: array
          items:
            $ref: '#/components/schemas/ContractCommitmentRecord'
        nextPageToken:
          type: string
          nullable: true
          description: Token to retrieve the next page of results.
        totalRecords:
          type: integer
          description: Total number of records matching the query.
      required:
      - data
    Error:
      type: object
      properties:
        code:
          type: string
          description: A machine-readable error code.
        message:
          type: string
          description: A human-readable error message.
        details:
          type: string
          nullable: true
          description: Additional details about the error.
      required:
      - code
      - message
  securitySchemes:
    bearerAuth:
      type: http
      scheme: bearer
      description: Bearer token authentication for FOCUS API access.
    apiKeyAuth:
      type: apiKey
      in: header
      name: X-API-Key
      description: API key authentication for FOCUS API access.
externalDocs:
  description: FOCUS Specification v1.3
  url: https://focus.finops.org/focus-specification/v1-3/