DoiT Assets API

openapi: 3.2.0
info:
  title: DoiT Assets API
  description: Programmatic access to DoiT Platform
  version: v1
servers:
- url: https://api.doit.com
security:
- api_key: []
- tenantId: []
  api_key: []
tags:
- name: Assets
  description: Manage cloud resources or services in your cloud environment.
paths:
  /billing/v1/createAsset:
    post:
      tags:
      - Assets
      summary: Create an asset
      description: Creates a new asset.
      operationId: createAsset
      parameters:
      - name: type
        in: query
        description: Asset type. For example, amazon-web-services
        schema:
          type: string
          default: amazon-web-services
      - name: mode
        in: query
        description: Asset mode.
        schema:
          type: string
          default: New
      - name: accountName
        in: query
        description: The desired name of the account.
        schema:
          type: string
          default: Account name
      - name: rootEmail
        in: query
        description: The root account email.
        schema:
          type: string
      responses:
        '200':
          description: OK - The request succeeded.
          headers:
            Request-Id:
              $ref: '#/components/headers/RequestId'
            Content-Language:
              $ref: '#/components/headers/ContentLanguage'
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/AssetResponse'
          links:
            idOfAsset:
              operationId: idOfAsset
              parameters:
                id: $response.body#/accountID
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/Forbidden'
        '404':
          $ref: '#/components/responses/NotFound'
        '409':
          $ref: '#/components/responses/Conflict'
        '500':
          $ref: '#/components/responses/InternalServerError'
  /billing/v1/assets:
    get:
      tags:
      - Assets
      summary: List assets
      description: 'Returns a list of all available customer assets, such as Google Cloud billing accounts, G Suite/Workspace subscriptions, etc.

        Assets are returned in reverse chronological order by default.'
      operationId: idOfAssets
      x-cli-name: list-assets
      x-cli-aliases:
      - id-of-assets
      parameters:
      - name: maxResults
        in: query
        description: The maximum number of results to return in a single page. Leverage the page tokens to iterate through the entire collection.
        schema:
          type: integer
          format: int64
          default: 50
      - $ref: '#/components/parameters/pageToken'
      - name: filter
        in: query
        description: 'An expression for filtering the results of the request. The syntax

          is `key:[<value>]`. e.g: "type:g-suite". Multiple filters can be

          connected using a pipe |. Note that using different keys in the same

          filter results in “AND,” while using the same key multiple times in

          the same filter results in “OR”.

          '
        schema:
          type: string
      responses:
        '200':
          description: OK - List of available assets returned.
          content:
            application/json:
              schema:
                type: object
                properties:
                  assets:
                    type: array
                    description: Array of Assets
                    items:
                      $ref: '#/components/schemas/AssetItem'
                  pageToken:
                    type: string
                    description: Page token. Can be used to request the next page of results.
                  rowCount:
                    type: integer
                    description: Assets rows count
                    format: int64
        '400':
          $ref: '#/components/responses/400'
        '401':
          $ref: '#/components/responses/401'
        '403':
          $ref: '#/components/responses/403'
        '404':
          $ref: '#/components/responses/404'
  /billing/v1/assets/{id}:
    get:
      tags:
      - Assets
      summary: Retrieve an asset
      description: Returns the full details of an asset specified by the asset id.
      operationId: getAsset
      parameters:
      - name: id
        in: path
        description: The unique id of an asset.
        required: true
        schema:
          type: string
      responses:
        '200':
          description: OK - Asset details returned.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/AssetItemDetailed'
        '400':
          $ref: '#/components/responses/400'
        '401':
          $ref: '#/components/responses/401'
        '403':
          $ref: '#/components/responses/403'
        '404':
          $ref: '#/components/responses/404'
        '500':
          $ref: '#/components/responses/500'
    patch:
      tags:
      - Assets
      summary: Update an asset
      description: Updates an existing asset, such as G Suite/Workspace or Office 365 subscription, to add or remove licenses.
      operationId: idOfAsset
      x-cli-name: update-asset
      x-cli-aliases:
      - id-of-asset
      parameters:
      - name: id
        in: path
        description: The unique id of an asset.
        required: true
        schema:
          type: string
      requestBody:
        content:
          application/json:
            schema:
              type: object
              properties:
                quantity:
                  type: integer
                  format: int64
        required: false
      responses:
        '200':
          description: OK - Asset updated.
          content:
            application/json:
              schema:
                type: object
                properties:
                  id:
                    type: string
                  properties:
                    $ref: '#/components/schemas/AssetProperties'
                  type:
                    type: string
        '400':
          $ref: '#/components/responses/400'
        '401':
          $ref: '#/components/responses/401'
        '403':
          $ref: '#/components/responses/403'
        '404':
          $ref: '#/components/responses/404'
      x-codegen-request-body-name: Body
components:
  responses:
    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
    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
    '400':
      description: Bad Request - The server cannot process the request, often due to a malformed request.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
    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
    Conflict:
      description: The request conflicts with the current state of the resource.
      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/conflict
            title: Conflict
            status: 409
            detail: The requested resource already exists.
            instance: https://api.doit.com/requests/req_01HX9P2KQVJ8Z3M4T5N6V7W8Y9
            code: conflict
            retryable: false
    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
    '401':
      description: Unauthorized - Invalid API key.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
    '403':
      description: Forbidden - The client is not authorized to perform the request.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
    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
    '404':
      description: Not Found - The requested resource does not exist.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
    '500':
      description: Internal Server Error - Something went wrong with the DoiT API server.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
  schemas:
    AssetProperties:
      type: object
      description: Additional properties associated with an asset, such as subscription and customer details.
      properties:
        customerDomain:
          type: string
          description: The primary domain of the customer associated with this asset.
        customerID:
          type: string
          description: The unique identifier of the customer in the reseller or partner portal.
        reseller:
          type: string
          description: The reseller domain through which this asset was provisioned.
        subscription:
          $ref: '#/components/schemas/Subscription'
    Seats:
      type: object
      description: Licensing seat counts for a subscription.
      properties:
        licensedNumberOfSeats:
          type: integer
          description: The number of seats that are currently in use or assigned to users.
          format: int64
        maximumNumberOfSeats:
          type: integer
          description: The maximum number of seats that can be used. Applies to flexible (non-commitment) plans.
          format: int64
        numberOfSeats:
          type: integer
          description: The number of committed seats. Applies to annual commitment plans.
          format: int64
    Error:
      type: object
      description: Standard error response structure.
      properties:
        error:
          type: string
          description: Detailed error message.
    RenewalSettings:
      type: object
      description: Settings that control subscription renewal behavior at the end of a commitment term.
      properties:
        renewalType:
          type: string
          description: The type of renewal, e.g. AUTO_RENEW_MONTHLY_PAY, AUTO_RENEW_YEARLY_PAY, RENEW_CURRENT_USERS_MONTHLY_PAY, RENEW_CURRENT_USERS_YEARLY_PAY, SWITCH_TO_PAY_AS_YOU_GO, or CANCEL.
    AssetResponse:
      type: object
      description: Response returned after creating or updating an asset.
      properties:
        accountID:
          type: string
    AssetItemDetailed:
      type: object
      description: Detailed information about a single asset, including subscription properties.
      properties:
        createTime:
          type: integer
          description: The time when the asset was created, in milliseconds since the epoch.
          format: int64
        id:
          type: string
          description: The unique identifier of the asset.
        name:
          type: string
          description: A human-readable label for the asset, typically combining the product name and domain or account ID.
        quantity:
          type: integer
          description: The number of licenses or seats currently assigned to this asset.
          format: int64
        type:
          type: string
          description: The asset type, e.g. g-suite, office-365, google-cloud, amazon-web-services, or microsoft-azure.
        url:
          type: string
          description: A link to the asset details page in the DoiT console.
        properties:
          $ref: '#/components/schemas/AssetProperties'
    SubscriptionPlanCommitmentInterval:
      type: object
      description: The start and end dates of an annual commitment term.
      properties:
        endTime:
          type: integer
          description: The end time of the commitment interval, in milliseconds since the epoch.
          format: int64
        startTime:
          type: integer
          description: The start time of the commitment interval, in milliseconds since the epoch.
          format: int64
    SubscriptionPlan:
      type: object
      description: Plan details for a subscription, indicating whether it is a commitment or flexible plan.
      properties:
        commitmentInterval:
          $ref: '#/components/schemas/SubscriptionPlanCommitmentInterval'
        isCommitmentPlan:
          type: boolean
          description: Whether this subscription is on an annual commitment plan (true) or a flexible plan (false).
        planName:
          type: string
          description: The name of the plan, e.g. ANNUAL_MONTHLY_PAY, ANNUAL_YEARLY_PAY, FLEXIBLE, or TRIAL.
    Subscription:
      type: object
      description: Subscription details for a G Suite or Office 365 asset.
      properties:
        billingMethod:
          type: string
          description: The billing method, e.g. ONLINE or OFFLINE.
        creationTime:
          type: integer
          description: The time when the subscription was created, in milliseconds since the epoch.
          format: int64
        id:
          type: string
          description: The unique identifier of the subscription.
        plan:
          $ref: '#/components/schemas/SubscriptionPlan'
        purchaseOrderID:
          type: string
          description: The purchase order ID associated with this subscription, if any.
        renewalSettings:
          $ref: '#/components/schemas/RenewalSettings'
        resourceUIURL:
          type: string
          description: A URL to the subscription management page in the admin console.
        seats:
          $ref: '#/components/schemas/Seats'
        skuID:
          type: string
          description: The unique SKU identifier for the subscribed product.
        skuName:
          type: string
          description: A human-readable name for the subscribed product SKU.
        status:
          type: string
          description: The current status of the subscription, e.g. ACTIVE, SUSPENDED, or PENDING.
    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
    AssetItem:
      type: object
      description: Summary information about a single asset.
      properties:
        createTime:
          type: integer
          description: The time when the asset was created, in milliseconds since the epoch.
          format: int64
        id:
          type: string
          description: The unique identifier of the asset.
        name:
          type: string
          description: A human-readable label for the asset, typically combining the product name and domain or account ID.
        quantity:
          type: integer
          description: The number of licenses or seats currently assigned to this asset.
          format: int64
        type:
          type: string
          description: The asset type, e.g. g-suite, office-365, google-cloud, amazon-web-services, or microsoft-azure.
        url:
          type: string
          description: A link to the asset details page in the DoiT console.
  headers:
    ContentLanguage:
      description: Language of the response body. Always `en` for this API.
      schema:
        type: string
        enum:
        - en
    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
  parameters:
    pageToken:
      name: pageToken
      in: query
      description: Page token, returned by a previous call, to request the next page of results
      schema:
        type: string
  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)