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.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/AssetResponse'
          links:
            idOfAsset:
              operationId: idOfAsset
              parameters:
                id: $response.body#/accountID
        '400':
          $ref: '#/components/responses/400'
        '401':
          $ref: '#/components/responses/401'
        '403':
          $ref: '#/components/responses/403'
        '404':
          $ref: '#/components/responses/404'
  /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:
  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'
    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.
    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.
    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.
    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.
    Error:
      type: object
      description: Standard error response structure.
      properties:
        error:
          type: string
          description: Detailed error message.
    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'
    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
    AssetResponse:
      type: object
      description: Response returned after creating or updating an asset.
      properties:
        accountID:
          type: string
    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
  responses:
    '400':
      description: Bad Request - The server cannot process the request, often due to a malformed request.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
    '401':
      description: Unauthorized - Invalid API key.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
    '404':
      description: Not Found - The requested resource does not exist.
      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'
    '500':
      description: Internal Server Error - Something went wrong with the DoiT API server.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
  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: 'Tenant (customer) ID that sets the request''s customer context.


        Required when the credential can access more than one tenant; omit when the

        credential is scoped to exactly one tenant (the server resolves that tenant

        automatically). If omitted for a multi-tenant credential, the request fails

        with `400` and code `tenant_id_required`. If the value conflicts with the

        credential''s tenant scope, the request fails with `400` and code

        `tenant_id_mismatch`.


        Use this header over the legacy `customerContext` query parameter, which

        only applies to legacy API keys and is ignored by personal and service-account

        API 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