DoiT PerfectScale for Commitments General API

openapi: 3.2.0
info:
  title: DoiT PerfectScale for Commitments General API
  description: Programmatic access to DoiT Platform
  version: v1
servers:
- url: https://api.doit.com
security:
- api_key: []
- tenantId: []
  api_key: []
tags:
- name: PerfectScale for Commitments General
  description: Cloud-agnostic PerfectScale for Commitments resources — commitment policies shared by AWS and GCP.
paths:
  /ps4commitments/v1/general/policies:
    get:
      operationId: listCommitmentPolicies
      tags:
      - PerfectScale for Commitments General
      summary: List commitment policies
      description: 'Returns every commitment policy available to the tenant: the three built-in policies

        (`conservative`, `balanced`, `max_savings`) followed by the tenant''s own custom policies.


        Commitment policies are cloud-agnostic. A single catalog is shared by AWS and GCP, and the

        same policy may be assigned to AWS and GCP product lines alike.


        Built-in policies are listed first, ordered from least to most aggressive target coverage;

        custom policies follow in creation order. Percentage parameters are expressed as `1`–`100`, as

        entered in the DoiT Console. This differs from the coverage and utilization fields on

        recommendations and inventory, which are fractions from 0 to 1.


        This endpoint is read-only. Custom policies are created, edited and deleted in the DoiT

        Console on the Commitment Policies page.'
      parameters:
      - $ref: '#/components/parameters/tenantId'
      - $ref: '#/components/parameters/ps4cPageToken'
      - $ref: '#/components/parameters/ps4cMaxResults'
      responses:
        '200':
          description: One page of the tenant's commitment policies.
          headers:
            Request-Id:
              $ref: '#/components/headers/RequestId'
            Content-Language:
              $ref: '#/components/headers/ContentLanguage'
          content:
            application/json:
              schema:
                type: object
                required:
                - items
                - pageToken
                - rowCount
                properties:
                  items:
                    type: array
                    items:
                      $ref: '#/components/schemas/CommitmentPolicy'
                  pageToken:
                    type:
                    - string
                    - 'null'
                    description: Opaque cursor for the next page. `null` when this is the last page.
                  rowCount:
                    type: integer
                    format: int64
                    description: Total number of policies available to the tenant across all pages.
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/Forbidden'
        '500':
          $ref: '#/components/responses/InternalServerError'
        '503':
          $ref: '#/components/responses/ServiceUnavailable'
  /ps4commitments/v1/general/policies/{policyId}:
    get:
      operationId: getCommitmentPolicy
      tags:
      - PerfectScale for Commitments General
      summary: Get a commitment policy
      description: 'Returns one commitment policy by id, with its creation and last-update times and the list of

        account × product-line scopes it is explicitly assigned to across AWS and GCP.


        `assignments` lists explicit assignments only. An account whose settings have not yet been

        materialized falls back to `balanced` implicitly and does not appear here, even though the

        settings endpoints report it as `balanced`. On AWS the assignment is currently recorded per

        tenant and applied to every onboarded organization, so each organization appears once per

        product line. The list is not paginated.


        Resolving assignments reads every onboarded account on both clouds. If either cloud cannot be

        queried the request fails rather than returning a partial list.'
      parameters:
      - $ref: '#/components/parameters/tenantId'
      - $ref: '#/components/parameters/policyId'
      responses:
        '200':
          description: The commitment policy with its assignments.
          headers:
            Request-Id:
              $ref: '#/components/headers/RequestId'
            Content-Language:
              $ref: '#/components/headers/ContentLanguage'
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/CommitmentPolicyDetail'
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/Forbidden'
        '404':
          $ref: '#/components/responses/NotFound'
        '500':
          $ref: '#/components/responses/InternalServerError'
        '503':
          $ref: '#/components/responses/ServiceUnavailable'
components:
  responses:
    ServiceUnavailable:
      description: Service temporarily unavailable; retry after the indicated delay.
      headers:
        Retry-After:
          description: Seconds to wait before retrying.
          schema:
            type: integer
            example: 30
        Request-Id:
          $ref: '#/components/headers/RequestId'
        Content-Language:
          $ref: '#/components/headers/ContentLanguage'
      content:
        application/problem+json:
          schema:
            $ref: '#/components/schemas/ProblemDetails'
          example:
            type: https://developer.doit.com/errors/service_unavailable
            title: Service unavailable
            status: 503
            detail: entitlement check temporarily unavailable
            instance: https://api.doit.com/requests/req_01HX9P2KQVJ8Z3M4T5N6V7W8Y9
            code: service_unavailable
            retryable: true
    Unauthorized:
      description: Missing or invalid credentials.
      headers:
        WWW-Authenticate:
          description: Bearer challenge per RFC 6750.
          schema:
            type: string
            example: Bearer realm="api.doit.com"
        Request-Id:
          $ref: '#/components/headers/RequestId'
        Content-Language:
          $ref: '#/components/headers/ContentLanguage'
      content:
        application/problem+json:
          schema:
            $ref: '#/components/schemas/ProblemDetails'
          example:
            type: https://developer.doit.com/errors/unauthorized
            title: Unauthorized
            status: 401
            detail: missing or invalid bearer token
            instance: https://api.doit.com/requests/req_01HX9P2KQVJ8Z3M4T5N6V7W8Y9
            code: unauthorized
            retryable: false
    NotFound:
      description: The requested resource does not exist.
      headers:
        Request-Id:
          $ref: '#/components/headers/RequestId'
        Content-Language:
          $ref: '#/components/headers/ContentLanguage'
      content:
        application/problem+json:
          schema:
            $ref: '#/components/schemas/ProblemDetails'
          example:
            type: https://developer.doit.com/errors/not_found
            title: Resource not found
            status: 404
            detail: organization not found
            instance: https://api.doit.com/requests/req_01HX9P2KQVJ8Z3M4T5N6V7W8Y9
            code: not_found
            retryable: false
    BadRequest:
      description: Syntactically malformed request, missing required parameter, or unsupported parameter value.
      headers:
        Request-Id:
          $ref: '#/components/headers/RequestId'
        Content-Language:
          $ref: '#/components/headers/ContentLanguage'
      content:
        application/problem+json:
          schema:
            $ref: '#/components/schemas/ProblemDetails'
          examples:
            validationFailed:
              summary: Missing or invalid parameter
              value:
                type: https://developer.doit.com/errors/validation_failed
                title: Validation failed
                status: 400
                detail: The request is missing a required parameter or contains an invalid value.
                instance: https://api.doit.com/requests/req_01HX9P2KQVJ8Z3M4T5N6V7W8Y9
                code: validation_failed
                retryable: false
            tenantIdRequired:
              summary: Tenant scope not resolvable
              value:
                type: https://developer.doit.com/errors/tenant_id_required
                title: Tenant ID required
                status: 400
                detail: X-Tenant-Id header is required when the credential can access more than one tenant.
                instance: https://api.doit.com/requests/req_01HX9P2KQVJ8Z3M4T5N6V7W8Y9
                code: tenant_id_required
                retryable: false
            tenantIdMismatch:
              summary: Header conflicts with the key's tenant
              value:
                type: https://developer.doit.com/errors/tenant_id_mismatch
                title: Tenant ID mismatch
                status: 400
                detail: X-Tenant-Id does not match the tenant the credential is scoped to.
                instance: https://api.doit.com/requests/req_01HX9P2KQVJ8Z3M4T5N6V7W8Y9
                code: tenant_id_mismatch
                retryable: false
            gcpServiceRequired:
              summary: GCP region filter without commitment type
              value:
                type: https://developer.doit.com/errors/gcp_service_required
                title: GCP service required
                status: 400
                detail: The region query parameter requires gcp_service.
                instance: https://api.doit.com/requests/req_01HX9P2KQVJ8Z3M4T5N6V7W8Y9
                code: gcp_service_required
                retryable: false
            paginationTokenInvalid:
              summary: Structurally invalid pagination cursor
              value:
                type: https://developer.doit.com/errors/pagination_token_invalid
                title: Invalid pagination token
                status: 400
                detail: The pageToken cursor is structurally invalid (decode failure or tampering).
                instance: https://api.doit.com/requests/req_01HX9P2KQVJ8Z3M4T5N6V7W8Y9
                code: pagination_token_invalid
                retryable: false
            paginationTokenExpired:
              summary: Expired pagination cursor
              value:
                type: https://developer.doit.com/errors/pagination_token_expired
                title: Expired pagination token
                status: 400
                detail: The pageToken cursor is no longer valid; restart pagination from the beginning.
                instance: https://api.doit.com/requests/req_01HX9P2KQVJ8Z3M4T5N6V7W8Y9
                code: pagination_token_expired
                retryable: false
    InternalServerError:
      description: Unexpected server error.
      headers:
        Request-Id:
          $ref: '#/components/headers/RequestId'
        Content-Language:
          $ref: '#/components/headers/ContentLanguage'
      content:
        application/problem+json:
          schema:
            $ref: '#/components/schemas/ProblemDetails'
          example:
            type: https://developer.doit.com/errors/internal_error
            title: Internal server error
            status: 500
            detail: an unexpected error occurred
            instance: https://api.doit.com/requests/req_01HX9P2KQVJ8Z3M4T5N6V7W8Y9
            code: internal_error
            retryable: true
    Forbidden:
      description: Authenticated but not authorized to perform this request.
      headers:
        Request-Id:
          $ref: '#/components/headers/RequestId'
        Content-Language:
          $ref: '#/components/headers/ContentLanguage'
      content:
        application/problem+json:
          schema:
            $ref: '#/components/schemas/ProblemDetails'
          example:
            type: https://developer.doit.com/errors/forbidden
            title: Forbidden
            status: 403
            detail: caller does not have permission to access this customer's commitments
            instance: https://api.doit.com/requests/req_01HX9P2KQVJ8Z3M4T5N6V7W8Y9
            code: forbidden
            retryable: false
  schemas:
    CommitmentPolicyId:
      type: string
      description: 'ID of a commitment policy: either one of the built-in policies — `conservative` (lower

        coverage target, ~65%), `balanced` (moderate, ~80%), `max_savings` (aggressive, ~90%) — or the

        ID of a policy the customer defined in the DoiT Console. One catalog is shared by AWS and GCP,

        and the same policy may be assigned to any AWS organization or GCP billing account product

        line. Custom policies make this an open list, so it is not an enum; treat the value as an

        opaque identifier and use the commitment-policies endpoint to resolve it.'
      example: balanced
    ProblemDetails:
      type: object
      required:
      - type
      - title
      - status
      - detail
      - instance
      - code
      - retryable
      additionalProperties: true
      description: RFC 9457 Problem Details — standard DoiT error envelope for all non-2xx responses.
      properties:
        type:
          type: string
          format: uri
          example: https://developer.doit.com/errors/not_found
        title:
          type: string
          example: Resource not found
        status:
          type: integer
          example: 404
        detail:
          type: string
          example: customer not found
        instance:
          type: string
          format: uri
          example: https://api.doit.com/requests/req_01HX9P2KQVJ8Z3M4T5N6V7W8Y9
        code:
          type: string
          pattern: ^([a-z][a-z0-9_]*|[a-z][a-z0-9]*(?:-[a-z0-9]+)*\.[a-z][a-z0-9_]*)$
          example: not_found
        retryable:
          type: boolean
          example: false
        details:
          type: array
          items:
            type: object
            required:
            - issue
            properties:
              issue:
                type: string
                pattern: ^[a-z][a-z0-9_]*$
              field:
                type: string
            additionalProperties: true
        docsUrl:
          type:
          - string
          - 'null'
          format: uri
    CommitmentPolicyDetail:
      allOf:
      - $ref: '#/components/schemas/CommitmentPolicy'
      - type: object
        required:
        - createdTime
        - updatedTime
        - assignments
        properties:
          createdTime:
            type:
            - string
            - 'null'
            format: date-time
            description: When the policy was created, RFC 3339 UTC. `null` if unknown.
            example: '2026-08-20T09:12:31Z'
          updatedTime:
            type:
            - string
            - 'null'
            format: date-time
            description: When the policy was last written, RFC 3339 UTC. For custom policies this is the last edit; for built-in policies it also advances when DoiT re-publishes the catalog, even if the parameters did not change. `null` if unknown.
            example: '2026-08-20T09:12:31Z'
          assignments:
            type: array
            description: Scopes explicitly assigned to this policy across AWS and GCP, sorted by `cloud`, `accountId`, `service`, `region`. Empty when the policy is not assigned anywhere.
            items:
              $ref: '#/components/schemas/CommitmentPolicyAssignment'
    CommitmentPolicyAssignment:
      type: object
      description: One account × product-line scope a policy is explicitly assigned to, on either cloud.
      required:
      - cloud
      - accountId
      - service
      - region
      properties:
        cloud:
          type: string
          enum:
          - aws
          - gcp
          description: Cloud the scope belongs to.
          x-enumDescriptions:
            aws: An AWS organization (management account).
            gcp: A GCP billing account.
        accountId:
          type: string
          description: AWS management account id or GCP billing account id, matching `managementAccountId` / `billingAccountId` elsewhere in this API.
          example: '123456789012'
        service:
          type: string
          enum:
          - compute
          - database
          - cloud_sql
          description: Product line the policy applies to. `compute` and `database` are AWS Savings Plan lines (GCP also has `compute`); `cloud_sql` is GCP only.
        region:
          type:
          - string
          - 'null'
          pattern: ^(global|[a-z]+(_[a-z0-9]+)+)$
          description: Region scope in `lower_snake_case` wire form (for example `us_east1`) for product lines assigned per region (GCP `cloud_sql`). `null` for every scope assigned per account (all AWS scopes, GCP `compute`); the settings endpoints report the same scope as `global`.
          example: us_east1
    CommitmentPolicy:
      type: object
      description: 'A commitment-laddering policy, either built-in or defined by the tenant. Percentages are

        `1`–`100`, as entered in the DoiT Console, not the 0–1 fractions used by the recommendation and

        inventory coverage fields.'
      required:
      - id
      - name
      - isBuiltIn
      - targetCoverage
      - lookbackDays
      - ladderStepPercent
      - ladderIntervalDays
      - bootstrapPercent
      properties:
        id:
          allOf:
          - $ref: '#/components/schemas/CommitmentPolicyId'
          description: Policy identifier. Built-in policies use the fixed ids `conservative`, `balanced` and `max_savings`; custom policies have an opaque id.
        name:
          type: string
          description: Display name. Built-in names are fixed; custom names are chosen by the tenant.
          example: Balanced
        isBuiltIn:
          type: boolean
          description: '`true` for the three immutable built-in policies, `false` for tenant-defined policies.'
        targetCoverage:
          type: number
          format: double
          minimum: 1
          maximum: 100
          description: Share of the optimal commitment the engine aims to purchase, as a percentage.
          example: 80
        lookbackDays:
          type: integer
          minimum: 1
          description: Days of historical usage analyzed to build the recommendation baseline.
          example: 60
        ladderStepPercent:
          type: number
          format: double
          minimum: 1
          maximum: 100
          description: Size of each incremental laddering step, as a percentage of the target commitment.
          example: 10
        ladderIntervalDays:
          type: integer
          minimum: 1
          description: Days between consecutive laddering steps.
          example: 7
        bootstrapPercent:
          type: number
          format: double
          minimum: 1
          maximum: 100
          description: Share of the target commitment purchased in the first (immediate) step, as a percentage.
          example: 35
  headers:
    RequestId:
      description: DoiT request identifier for support and log correlation. Format `req_<ULID>`.
      schema:
        type: string
        pattern: ^req_[0-9A-HJKMNP-TV-Z]{26}$
        example: req_01HX9P2KQVJ8Z3M4T5N6V7W8Y9
    ContentLanguage:
      description: Language of the response body. Always `en` for this API.
      schema:
        type: string
        enum:
        - en
  parameters:
    tenantId:
      in: header
      name: X-Tenant-Id
      required: false
      description: 'Customer (tenant) ID for the request. This is separate from authentication: you still pass your personal or service account API token in the `Authorization` header (`Bearer <token>`). See [Get Started](https://developer.doit.com/docs/start).


        **When to omit (most callers):** If your personal or service account token belongs to a single customer, omit this header. The API resolves that customer from the token.


        **When to send:** If your credential can access more than one customer, set `X-Tenant-Id` to the customer ID you want to act on. A service account can select an active direct or nested descendant of its home customer; the endpoint''s normal permissions, entitlements, and resource-ownership checks still apply. A service-account target outside that customer subtree returns `403 Forbidden`. Prefer this header over the legacy `customerContext` query parameter, which only applies to legacy API keys and is ignored by personal and service account tokens.'
      schema:
        type: string
        example: Kp2mN8qL4vR0sT1wX3yZ
    ps4cPageToken:
      in: query
      name: pageToken
      required: false
      description: Opaque cursor token returned by a previous list response. Omit to start from the beginning; an empty or absent token in a response means there are no more results. Do not parse it. A structurally invalid cursor returns `400` with code `pagination_token_invalid`; an expired cursor returns `400` with code `pagination_token_expired` — restart pagination from the beginning.
      schema:
        type: string
    ps4cMaxResults:
      in: query
      name: maxResults
      required: false
      description: Maximum number of items to return. Server may return fewer. Defaults to 50; maximum 500.
      schema:
        type: integer
        minimum: 1
        maximum: 500
        default: 50
    policyId:
      name: policyId
      in: path
      required: true
      description: Commitment policy id. Built-in policies use `conservative`, `balanced` or `max_savings`; custom policies have an opaque id returned by the list endpoint.
      schema:
        type: string
        pattern: ^[A-Za-z0-9_-]{1,64}$
        example: balanced
  securitySchemes:
    api_key:
      type: apiKey
      name: Authorization
      description: Use the "Bearer <API_KEY>" format or sign in for autofill
      in: header
    tenantId:
      type: apiKey
      name: X-Tenant-Id
      description: 'Customer (tenant) ID for the request. Separate from your API token: always authenticate with `Authorization: Bearer <token>` (personal or service account). See [Get Started](https://developer.doit.com/docs/start). Omit when your token is scoped to a single customer (resolved automatically). A service account can select an active direct or nested descendant of its home customer; the endpoint''s normal permissions, entitlements, and resource-ownership checks still apply. A service-account target outside that customer subtree returns `403 Forbidden`. Prefer this header over the legacy `customerContext` query parameter, which only applies to legacy API keys and is ignored by personal and service account tokens.'
      in: header
    oauth2:
      type: oauth2
      flows:
        authorizationCode:
          authorizationUrl: https://console.doit.com/sign-in/oauth
          tokenUrl: https://console.doit.com/api/auth/token
          scopes:
            dci: Access All Data
x-samples-languages:
- curl
- go
- node
- python
x-cli-config:
  security: oauth2
  params:
    client_id: cli
x-provenance:
  method: harvested
  publisher: DoiT
  source: https://api.doit.com/openapi.yaml
  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)