openapi: 3.0.1 info: title: DoiT API description: Programmatic access to DoiT Platform version: v1 servers: - url: https://api.doit.com security: - api_key: [] - tenantId: [] api_key: [] tags: - name: Alerts description: Notifications triggered when cloud costs exceed defined thresholds or meet specific conditions. - name: Annotations description: Custom notes added to cost data to provide contextual information. - name: Labels description: Create and manage labels to organize and categorize your cloud resources. - name: Reports Settings description: Configure presentation settings for Cloud Analytics reports, including custom color themes. - name: Allocations description: Define how costs are distributed across your organization. - name: Folders description: Organize Cloud Analytics resources (reports, allocations) into folders. - name: Budgets description: Track actual cloud spend against planned spend. - name: Budget Suggestions description: AI-generated budget recommendations you can accept (link to a budget you created) or dismiss. - name: Dimensions description: View available dimensions for analysis. - name: Reports description: Manage Cloud Analytics reports and get reports data in JSON format. - name: Sharing description: Manage permissions associated with specified Cloud Analytics resources. - name: Anomalies description: Monitor cost spikes in your cloud environment. - name: Auth description: User authentication. - name: Assets description: Manage cloud resources or services in your cloud environment. - name: DataHub description: Ingest third-party cost, usage, and metric-based data for analysis. - name: Invoices description: Access your current and historical billing documents. - name: Cloud Incidents description: Service disruptions and outages from cloud providers. - name: Cloud Diagrams description: Cloud Diagrams visualize your cloud infrastructure and resource relationships. - name: AccountTeam description: Find DoiT account managers assigned to your organization. - name: Contract Templates description: Manage contract templates for PartnerOps resellers (T1/T2). - name: Users description: Manage users who have access to the DoiT platform. - name: Roles description: Manage user permissions and access levels in your organization. - name: Organizations description: Organizations help you segment data by your company or team structure. - name: Platforms description: Metadata about supported cloud providers. - name: Products description: Metadata about cloud services and offerings. - name: Support Requests description: Create and manage support tickets with DoiT. - name: Contracts description: List and manage tenant-scoped contracts as a T1/T2 PartnerOps caller. - name: Commitment Manager description: View and manage commitment contracts with DoiT. - name: Ava description: Interact with Ava, DoiT's AI-powered cloud assistant. - name: Insights description: Manage cloud insights representing recommendations and findings for cloud resources. - name: Cloud Connect description: Manage cloud provider connections and check feature availability for connected accounts. - name: Service Quotas description: Monitor cloud service quota usage across connected accounts and projects. - name: Connections description: Manage cloud provider connections used in CloudFlow workflows (AWS and GCP). - name: Templates description: Browse the catalogue of read-only CloudFlow templates (blueprints) used to create flows. - name: CloudFlow description: Manage CloudFlow. - name: PerfectScale for Commitments AWS description: PerfectScale for Commitments (AWS) — commitment inventory, recommendations, and planned purchases. - name: Billing Transfer description: Manage AWS billing-transfer mappings between distributors and resellers and between resellers and end customers, and list program management accounts. paths: /analytics/v1/alerts: get: tags: - Alerts summary: List alerts description: |- Returns a list of alerts that your account has access to. Alerts are listed in reverse chronological order by default. operationId: listAlerts parameters: - name: sortBy in: query description: A field by which the results will be sorted. schema: type: string enum: - name - createTime - updateTime - lastAlerted - $ref: "#/components/parameters/sortOrder" - $ref: "#/components/parameters/maxResults" - $ref: "#/components/parameters/pageToken" - name: filter in: query description: >- An expression for filtering the results. The syntax is `key:[]`. Multiple filters can be connected using a pipe |. See [Filters](https://developer.doit.com/docs/filters). Available filter keys: **owner**, **name** example: "name:test" schema: type: string responses: "200": description: >- OK - The request succeeded. content: application/json: schema: $ref: "#/components/schemas/ExternalAlertList" "400": $ref: "#/components/responses/400" "401": $ref: "#/components/responses/401" "403": $ref: "#/components/responses/403" "404": $ref: "#/components/responses/404" post: tags: - Alerts summary: Create an alert description: Creates a new alert. operationId: createAlert requestBody: content: application/json: schema: $ref: "#/components/schemas/AlertRequest" responses: "201": description: Created - The request succeeded. content: application/json: schema: $ref: "#/components/schemas/Alert" links: getAlert: operationId: getAlert parameters: id: $response.body#/id updateAlert: operationId: updateAlert parameters: id: $response.body#/id deleteAlert: operationId: deleteAlert parameters: id: $response.body#/id "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 "/analytics/v1/alerts/{id}": get: tags: - Alerts summary: Retrieve an alert description: Returns an alert by the specified Id. operationId: getAlert parameters: - name: id in: path description: Alert ID required: true schema: type: string responses: "200": description: >- OK - Alert returned. content: application/json: schema: $ref: "#/components/schemas/Alert" links: updateAlert: operationId: updateAlert parameters: id: $request.path.id deleteAlert: operationId: deleteAlert parameters: id: $request.path.id "400": $ref: "#/components/responses/400" "401": $ref: "#/components/responses/401" "403": $ref: "#/components/responses/403" "404": $ref: "#/components/responses/404" delete: tags: - Alerts summary: Delete an alert description: Deletes the alert specified by the Id. operationId: deleteAlert parameters: - name: id in: path description: Alert ID required: true schema: type: string responses: "200": description: OK - Alert deleted. "400": $ref: "#/components/responses/400" "401": $ref: "#/components/responses/401" "403": $ref: "#/components/responses/403" "404": $ref: "#/components/responses/404" patch: tags: - Alerts summary: Update an alert description: Updates the alert specified by the Id. operationId: updateAlert parameters: - name: id in: path description: Alert ID required: true schema: type: string requestBody: content: application/json: schema: $ref: "#/components/schemas/AlertUpdateRequest" required: false responses: "200": description: OK - Alert updated. content: application/json: schema: $ref: "#/components/schemas/Alert" "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 /analytics/v1/allocations: get: tags: - Allocations summary: List allocations description: |- Returns a list of allocations that your account has access to. Allocations are listed in reverse chronological order by default. operationId: listAllocations parameters: - $ref: "#/components/parameters/maxResults" - $ref: "#/components/parameters/pageToken" - name: filter in: query description: |- An expression for filtering the results. Valid fields: **type**, **owner**, **name**, **folderId**. example: type:custom schema: type: string - name: sortBy in: query description: A field by which the results will be sorted. schema: type: string enum: - id - name - owner - description - type - createTime - updateTime - $ref: "#/components/parameters/sortOrder" responses: "200": description: >- OK - The request succeeded. content: application/json: schema: type: object properties: pageToken: type: string description: Page token, returned by a previous call, to request the next page of results. rowCount: type: integer description: Total number of allocations in the result set. allocations: type: array items: $ref: "#/components/schemas/AllocationListItem" "400": $ref: "#/components/responses/400" "401": $ref: "#/components/responses/401" "403": $ref: "#/components/responses/403" "404": $ref: "#/components/responses/404" post: tags: - Allocations summary: Create an allocation description: Creates a new allocation. operationId: createAllocation requestBody: content: application/json: schema: $ref: "#/components/schemas/CreateAllocationRequest" responses: "200": description: >- OK - The request succeeded. content: application/json: schema: $ref: "#/components/schemas/Allocation" links: getAllocation: operationId: getAllocation parameters: id: $response.body#/id updateAllocation: operationId: updateAllocation parameters: id: $response.body#/id deleteAllocation: operationId: deleteAllocation parameters: id: $response.body#/id "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 "/analytics/v1/allocations/{id}": get: tags: - Allocations summary: Retrieve an allocation description: Returns an allocation by the specified Id. operationId: getAllocation parameters: - name: id in: path description: Allocation ID required: true schema: type: string responses: "200": description: >- OK - Allocation returned. content: application/json: schema: $ref: "#/components/schemas/Allocation" "400": $ref: "#/components/responses/400" "401": $ref: "#/components/responses/401" "403": $ref: "#/components/responses/403" "404": $ref: "#/components/responses/404" delete: tags: - Allocations summary: Delete an allocation description: Deletes the allocation specified by the Id. operationId: deleteAllocation parameters: - name: id in: path description: Allocation ID required: true schema: type: string responses: "200": description: OK - Allocation deleted. content: application/json: schema: type: object additionalProperties: false example: {} "400": $ref: "#/components/responses/400" "401": $ref: "#/components/responses/401" "403": $ref: "#/components/responses/403" "404": $ref: "#/components/responses/404" "409": description: >- Conflict - The allocation cannot be deleted because it is used by other resources. content: application/json: schema: type: array items: $ref: "#/components/schemas/AllocationDeleteValidation" patch: tags: - Allocations summary: Update an allocation description: Updates the allocation specified by the Id. operationId: updateAllocation parameters: - name: id in: path description: Allocation ID required: true schema: type: string requestBody: content: application/json: schema: $ref: "#/components/schemas/UpdateAllocationRequest" responses: "200": description: OK - Allocation updated. content: application/json: schema: $ref: "#/components/schemas/Allocation" "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 /analytics/v1/annotations: get: tags: - Annotations summary: List annotations description: |- Returns a list of annotations that your account has access to. Annotations are listed in reverse chronological order by default. operationId: listAnnotations parameters: - $ref: "#/components/parameters/maxResults" - $ref: "#/components/parameters/pageToken" - name: filter in: query description: |- An expression for filtering the results. Valid fields: **content**, **timestamp**, **labels**. example: content:budget schema: type: string - name: sortBy in: query description: A field by which the results will be sorted. schema: type: string enum: - id - content - timestamp - timeCreated - timeModified - $ref: "#/components/parameters/sortOrder" responses: "200": description: >- OK - The request succeeded. content: application/json: schema: type: object properties: pageToken: type: string description: Page token, returned by a previous call, to request the next page of results rowCount: type: integer description: Total number of annotations in the result set annotations: type: array items: $ref: "#/components/schemas/AnnotationListItem" "400": $ref: "#/components/responses/400" "401": $ref: "#/components/responses/401" "403": $ref: "#/components/responses/403" "404": $ref: "#/components/responses/404" post: tags: - Annotations summary: Create an annotation description: Creates a new annotation. operationId: createAnnotation requestBody: content: application/json: schema: $ref: "#/components/schemas/CreateAnnotationRequest" required: true responses: "201": description: >- Created - Annotation created successfully. content: application/json: schema: $ref: "#/components/schemas/AnnotationListItem" links: getAnnotation: operationId: getAnnotation parameters: id: $response.body#/id updateAnnotation: operationId: updateAnnotation parameters: id: $response.body#/id deleteAnnotation: operationId: deleteAnnotation parameters: id: $response.body#/id "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 "/analytics/v1/annotations/{id}": get: tags: - Annotations summary: Retrieve an annotation description: Returns an annotation by the specified Id. operationId: getAnnotation parameters: - name: id in: path description: Annotation ID required: true schema: type: string responses: "200": description: >- OK - Annotation returned. content: application/json: schema: $ref: "#/components/schemas/AnnotationListItem" links: updateAnnotation: operationId: updateAnnotation parameters: id: $request.path.id deleteAnnotation: operationId: deleteAnnotation parameters: id: $request.path.id "400": $ref: "#/components/responses/400" "401": $ref: "#/components/responses/401" "403": $ref: "#/components/responses/403" "404": $ref: "#/components/responses/404" delete: tags: - Annotations summary: Delete an annotation description: Deletes the annotation specified by the Id. operationId: deleteAnnotation parameters: - name: id in: path description: Annotation ID required: true schema: type: string responses: "200": description: OK - Annotation deleted. content: application/json: schema: type: object additionalProperties: false example: {} "400": $ref: "#/components/responses/400" "401": $ref: "#/components/responses/401" "403": $ref: "#/components/responses/403" "404": $ref: "#/components/responses/404" patch: tags: - Annotations summary: Update an annotation description: Updates the annotation specified by the Id. operationId: updateAnnotation parameters: - name: id in: path description: Annotation ID required: true schema: type: string requestBody: content: application/json: schema: $ref: "#/components/schemas/UpdateAnnotationRequest" example: content: "Updated annotation content" responses: "200": description: OK - Annotation updated. content: application/json: schema: $ref: "#/components/schemas/AnnotationListItem" "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 /analytics/v1/labels: get: tags: - Labels summary: List labels description: |- Returns a list of labels that your account has access to. Labels are listed in reverse chronological order by default. operationId: listLabels parameters: - $ref: "#/components/parameters/maxResults" - $ref: "#/components/parameters/pageToken" - name: filter in: query description: |- An expression for filtering the results. Valid fields: **name**, **type**. example: name:budget schema: type: string - name: sortBy in: query description: A field by which the results will be sorted. schema: type: string enum: - id - name - type - createTime - updateTime - $ref: "#/components/parameters/sortOrder" responses: "200": description: >- OK - The request succeeded. content: application/json: schema: $ref: "#/components/schemas/LabelList" "400": $ref: "#/components/responses/400" "401": $ref: "#/components/responses/401" "403": $ref: "#/components/responses/403" "404": $ref: "#/components/responses/404" post: tags: - Labels summary: Create a label description: Creates a new label. operationId: createLabel requestBody: content: application/json: schema: $ref: "#/components/schemas/CreateLabelRequest" required: true responses: "201": description: >- Created - Label created successfully. content: application/json: schema: $ref: "#/components/schemas/LabelListItem" links: getLabel: operationId: getLabel parameters: id: $response.body#/id updateLabel: operationId: updateLabel parameters: id: $response.body#/id deleteLabel: operationId: deleteLabel parameters: id: $response.body#/id "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 "/analytics/v1/labels/{id}": get: tags: - Labels summary: Retrieve a label description: Returns a label by the specified Id. operationId: getLabel parameters: - name: id in: path description: Label ID required: true schema: type: string responses: "200": description: >- OK - Label returned. content: application/json: schema: $ref: "#/components/schemas/LabelListItem" links: updateLabel: operationId: updateLabel parameters: id: $request.path.id deleteLabel: operationId: deleteLabel parameters: id: $request.path.id "400": $ref: "#/components/responses/400" "401": $ref: "#/components/responses/401" "403": $ref: "#/components/responses/403" "404": $ref: "#/components/responses/404" delete: tags: - Labels summary: Delete a label description: Deletes the label specified by the Id. operationId: deleteLabel parameters: - name: id in: path description: Label ID required: true schema: type: string responses: "200": description: OK - Label deleted. content: application/json: schema: type: object additionalProperties: false example: {} "400": $ref: "#/components/responses/400" "401": $ref: "#/components/responses/401" "403": $ref: "#/components/responses/403" "404": $ref: "#/components/responses/404" patch: tags: - Labels summary: Update a label description: Updates the label specified by the Id. operationId: updateLabel parameters: - name: id in: path description: Label ID required: true schema: type: string requestBody: content: application/json: schema: $ref: "#/components/schemas/UpdateLabelRequest" responses: "200": description: OK - Label updated. content: application/json: schema: $ref: "#/components/schemas/LabelListItem" "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 "/analytics/v1/labels/{id}/assignments": get: tags: - Labels summary: Get label assignments description: Returns the list of objects currently assigned to the label specified by the ID. operationId: getLabelAssignments parameters: - name: id in: path description: Label ID required: true schema: type: string responses: "200": description: OK - Label assignments returned. content: application/json: schema: $ref: "#/components/schemas/LabelAssignmentsResponse" "400": $ref: "#/components/responses/400" "401": $ref: "#/components/responses/401" "403": $ref: "#/components/responses/403" "404": $ref: "#/components/responses/404" post: tags: - Labels summary: Assign or unassign objects to a label description: Assigns or un-assigns objects to the label specified by the ID. operationId: assignObjectsToLabel parameters: - name: id in: path description: Label ID required: true schema: type: string requestBody: content: application/json: schema: $ref: "#/components/schemas/AssignObjectsToLabelRequest" required: true responses: "200": description: OK - Objects assigned/unassigned successfully. "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 "/analytics/v1/settings/themes": get: tags: - Settings summary: List custom themes description: Returns the list of custom color themes defined for your account. operationId: listCustomThemes responses: "200": description: OK - The request succeeded. content: application/json: schema: type: object properties: rowCount: type: integer description: Total number of custom themes in the result set. themes: type: array items: $ref: "#/components/schemas/CustomTheme" "401": $ref: "#/components/responses/401" "403": $ref: "#/components/responses/403" "404": $ref: "#/components/responses/404" post: tags: - Settings summary: Create a custom theme description: Creates a new custom color theme. Requires Cloud Analytics Admin permission. operationId: createCustomTheme requestBody: content: application/json: schema: $ref: "#/components/schemas/CreateCustomThemeRequest" required: true responses: "201": description: Created - Custom theme created successfully. content: application/json: schema: $ref: "#/components/schemas/CustomTheme" links: getCustomTheme: operationId: getCustomTheme parameters: id: $response.body#/id updateCustomTheme: operationId: updateCustomTheme parameters: id: $response.body#/id deleteCustomTheme: operationId: deleteCustomTheme parameters: id: $response.body#/id "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 "/analytics/v1/settings/themes/{id}": get: tags: - Settings summary: Retrieve a custom theme description: Returns a custom theme by the specified Id. operationId: getCustomTheme parameters: - name: id in: path description: Custom theme ID required: true schema: type: string responses: "200": description: OK - Custom theme returned. content: application/json: schema: $ref: "#/components/schemas/CustomTheme" links: updateCustomTheme: operationId: updateCustomTheme parameters: id: $request.path.id deleteCustomTheme: operationId: deleteCustomTheme parameters: id: $request.path.id "400": $ref: "#/components/responses/400" "401": $ref: "#/components/responses/401" "403": $ref: "#/components/responses/403" "404": $ref: "#/components/responses/404" patch: tags: - Settings summary: Update a custom theme description: Updates the custom theme specified by the Id. Requires Cloud Analytics Admin permission. operationId: updateCustomTheme parameters: - name: id in: path description: Custom theme ID required: true schema: type: string requestBody: content: application/json: schema: $ref: "#/components/schemas/UpdateCustomThemeRequest" required: true responses: "200": description: OK - Custom theme updated. content: application/json: schema: $ref: "#/components/schemas/CustomTheme" "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 delete: tags: - Settings summary: Delete a custom theme description: Deletes the custom theme specified by the Id. Requires Cloud Analytics Admin permission. operationId: deleteCustomTheme parameters: - name: id in: path description: Custom theme ID required: true schema: type: string responses: "200": description: OK - Custom theme deleted. content: application/json: schema: type: object additionalProperties: false example: {} "400": $ref: "#/components/responses/400" "401": $ref: "#/components/responses/401" "403": $ref: "#/components/responses/403" "404": $ref: "#/components/responses/404" "/analytics/v1/settings/active-theme": get: tags: - Settings summary: Get the active theme description: |- Returns the theme currently active for the authenticated user. `themeId` is the reserved sentinel `"default"` when no custom or preset theme is selected and the user is on the built-in default. operationId: getActiveTheme responses: "200": description: OK - The request succeeded. content: application/json: schema: $ref: "#/components/schemas/ActiveTheme" "401": $ref: "#/components/responses/401" "403": $ref: "#/components/responses/403" put: tags: - Settings summary: Set the active theme description: |- Sets the theme active for the authenticated user. Send the reserved sentinel `themeId: "default"` to clear the active theme and fall back to the built-in default. Returns the updated active theme. operationId: setActiveTheme requestBody: content: application/json: schema: $ref: "#/components/schemas/SetActiveThemeRequest" required: true responses: "200": description: OK - Active theme updated. content: application/json: schema: $ref: "#/components/schemas/ActiveTheme" "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 /analytics/v1/budgets: get: tags: - Budgets summary: List budgets description: |- Returns a list of budgets that your account has access to. Budgets are listed in reverse chronological order by default. operationId: listBudgets 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:[]". Available keys: owner, lastModified in ms (>lasModified). 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 - name: minCreationTime in: query description: Min value for reports creation time, in milliseconds since the POSIX epoch. If set, only reports created after or at this timestamp are returned. schema: type: string - name: maxCreationTime in: query description: Max value for reports creation time, in milliseconds since the POSIX epoch. If set, only reports created before or at this timestamp are returned. schema: type: string responses: "200": description: >- OK - The request succeeded. content: application/json: schema: type: object properties: budgets: type: array description: Array of Budgets items: $ref: "#/components/schemas/BudgetListItem" pageToken: type: string description: Page token, returned by a previous call, to request the next page of results rowCount: type: integer description: Budgets rows count format: int64 "400": $ref: "#/components/responses/400" "401": $ref: "#/components/responses/401" "403": $ref: "#/components/responses/403" "404": $ref: "#/components/responses/404" post: tags: - Budgets summary: Create a budget description: Create a new budget operationId: createBudget requestBody: content: application/json: schema: $ref: "#/components/schemas/BudgetCreateUpdateRequest" example: name: monthly-cloud-budget amount: 100 currency: USD usePrevSpend: false type: recurring timeInterval: month startPeriod: 1704067200000 scopes: - id: cloud_provider type: fixed mode: is values: - amazon-web-services collaborators: - role: owner email: placeholder@example.com responses: "201": description: Created - New budget created. content: application/json: schema: $ref: "#/components/schemas/BudgetAPI" links: getBudget: operationId: getBudget parameters: id: $response.body#/id updateBudget: operationId: updateBudget parameters: id: $response.body#/id deleteBudget: operationId: deleteBudget parameters: id: $response.body#/id "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 "/analytics/v1/budgets/{id}": get: tags: - Budgets summary: Retrieve a budget description: Returns the current utilization and configuration of the specified budget. operationId: getBudget parameters: - name: id in: path description: Budget ID required: true schema: type: string responses: "200": description: OK - Budget details returned. content: application/json: schema: $ref: "#/components/schemas/BudgetAPI" "400": $ref: "#/components/responses/400" "401": $ref: "#/components/responses/401" "403": $ref: "#/components/responses/403" "404": $ref: "#/components/responses/404" delete: tags: - Budgets summary: Delete a budget description: Deletes the specified budget. operationId: deleteBudget parameters: - name: id in: path description: Budget ID required: true schema: type: string responses: "200": description: OK - Budget deleted. content: application/json: schema: type: object additionalProperties: false example: {} "400": $ref: "#/components/responses/400" "401": $ref: "#/components/responses/401" "403": $ref: "#/components/responses/403" "404": $ref: "#/components/responses/404" patch: tags: - Budgets summary: Update a budget description: Updates the specified budget. operationId: updateBudget parameters: - name: id in: path required: true schema: type: string requestBody: content: application/json: schema: $ref: "#/components/schemas/BudgetCreateUpdateRequest" required: false responses: "200": description: OK - Budget updated. content: application/json: schema: $ref: "#/components/schemas/BudgetAPI" links: deleteBudget: operationId: deleteBudget parameters: id: $response.body#/id "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 /analytics/v1/budget-suggestions: get: tags: - Budget Suggestions summary: List budget suggestions description: |- Returns the pending AI-generated budget suggestions for your account. The set is small (a handful of pending suggestions) and is returned in full. Each suggestion can be accepted (after you create a matching budget via `POST /analytics/v1/budgets`) or dismissed. operationId: listBudgetSuggestions responses: "200": description: OK - The request succeeded. content: application/json: schema: type: object properties: items: type: array description: Array of pending budget suggestions. items: $ref: "#/components/schemas/BudgetSuggestion" rowCount: type: integer description: Number of suggestions returned. format: int64 "401": $ref: "#/components/responses/401" "403": $ref: "#/components/responses/403" "500": $ref: "#/components/responses/500" "/analytics/v1/budget-suggestions/{id}/actions/accept": post: tags: - Budget Suggestions summary: Accept a budget suggestion description: |- Marks the suggestion as accepted and links it to an existing budget. Create the budget first via `POST /analytics/v1/budgets`, then pass its `id` as `budgetId`. The budget must belong to your account. operationId: acceptBudgetSuggestion parameters: - name: id in: path description: Budget suggestion ID. required: true schema: type: string requestBody: required: true content: application/json: schema: $ref: "#/components/schemas/BudgetSuggestionAcceptRequest" responses: "200": description: OK - The suggestion was accepted and linked to the budget. content: application/json: schema: type: object properties: budgetId: type: string description: ID of the budget the suggestion was linked to. "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" x-codegen-request-body-name: Body "/analytics/v1/budget-suggestions/{id}/actions/dismiss": post: tags: - Budget Suggestions summary: Dismiss a budget suggestion description: Marks the suggestion as dismissed so it no longer appears in the pending list. operationId: dismissBudgetSuggestion parameters: - name: id in: path description: Budget suggestion ID. required: true schema: type: string requestBody: required: false content: application/json: schema: $ref: "#/components/schemas/BudgetSuggestionDismissRequest" responses: "200": description: OK - The suggestion was dismissed. content: application/json: schema: type: object properties: id: type: string description: ID of the dismissed suggestion. status: type: string enum: - dismissed "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" x-codegen-request-body-name: Body /analytics/v1/dimension: get: tags: - Dimensions summary: Retrieve a dimension description: Returns a dimension by type and key. operationId: getDimensions x-cli-name: get-dimension x-cli-aliases: - get-dimensions parameters: - name: type in: query description: Dimension type required: true example: "fixed" schema: $ref: "#/components/schemas/DimensionsTypes" - name: id in: query description: Dimension id required: true example: "service_description" schema: type: string responses: "200": description: OK - The dimension returned. content: application/json: schema: $ref: "#/components/schemas/DimensionsExternalAPIGetResponse" "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" /analytics/v1/folders: get: tags: - Folders summary: List folders description: |- Returns Cloud Analytics folders the current customer has access to. Folders are returned in id-ascending order. operationId: listFolders parameters: - $ref: "#/components/parameters/maxResults" - $ref: "#/components/parameters/pageToken" responses: "200": description: OK - The request succeeded. content: application/json: schema: type: object properties: pageToken: type: string description: Page token, returned by a previous call, to request the next page of results. rowCount: type: integer description: Number of folders returned in this page. folders: type: array items: $ref: "#/components/schemas/Folder" "400": $ref: "#/components/responses/400" "401": $ref: "#/components/responses/401" "403": $ref: "#/components/responses/403" "500": $ref: "#/components/responses/500" post: tags: - Folders summary: Create a folder description: Creates a new Cloud Analytics folder. operationId: createFolder requestBody: required: true content: application/json: schema: $ref: "#/components/schemas/CreateFolderRequest" responses: "201": description: Created - The folder was created. content: application/json: schema: $ref: "#/components/schemas/Folder" links: getFolder: operationId: getFolder parameters: id: $response.body#/id updateFolder: operationId: updateFolder parameters: id: $response.body#/id deleteFolder: operationId: deleteFolder parameters: id: $response.body#/id "400": $ref: "#/components/responses/400" "401": $ref: "#/components/responses/401" "403": $ref: "#/components/responses/403" "500": $ref: "#/components/responses/500" x-codegen-request-body-name: Body "/analytics/v1/folders/{id}": get: tags: - Folders summary: Get a folder description: Returns the specified Cloud Analytics folder. operationId: getFolder parameters: - name: id in: path description: Folder ID. required: true schema: type: string responses: "200": description: OK - Folder returned. content: application/json: schema: $ref: "#/components/schemas/Folder" "401": $ref: "#/components/responses/401" "403": $ref: "#/components/responses/403" "404": $ref: "#/components/responses/404" "500": $ref: "#/components/responses/500" patch: tags: - Folders summary: Update a folder description: |- Updates the specified folder. All fields are optional. To reparent the folder, set `parentFolderId` to the target folder ID (use "root" for the top level). If a sibling at the target has the same name, the folder is auto-renamed. To move reports or allocations into or out of a folder, update the item's `folderId` field via the report or allocation PATCH endpoint. operationId: updateFolder parameters: - name: id in: path description: Folder ID. required: true schema: type: string requestBody: required: true content: application/json: schema: $ref: "#/components/schemas/UpdateFolderRequest" responses: "200": description: OK - Folder updated. content: application/json: schema: $ref: "#/components/schemas/Folder" "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" x-codegen-request-body-name: Body delete: tags: - Folders summary: Delete a folder description: >- Deletes the specified folder. All nested folders will be deleted. Any reports or allocations contained in the folder are moved to the root. operationId: deleteFolder parameters: - name: id in: path description: Folder ID. required: true schema: type: string responses: "204": description: No Content - Folder deleted. "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" /analytics/v1/dimensions: get: tags: - Dimensions summary: List dimensions description: Returns a list of the dimensions that your account has access to. operationId: listDimensions parameters: - $ref: "#/components/parameters/maxResults" - $ref: "#/components/parameters/pageToken" - name: filter in: query description: |- An expression for filtering the results. The fields eligible for filtering are: type, label, key. schema: type: string - name: sortBy in: query description: A field by which the results will be sorted. schema: type: string enum: - type - label - key - timestamp - $ref: "#/components/parameters/sortOrder" responses: "200": description: OK - The request succeeded. content: application/json: schema: $ref: "#/components/schemas/DimensionsExternalAPIListResponse" "400": $ref: "#/components/responses/400" "401": $ref: "#/components/responses/401" "403": $ref: "#/components/responses/403" "404": $ref: "#/components/responses/404" /analytics/v1/reports: get: tags: - Reports summary: List reports description: |- Returns a list of all Cloud Analytics reports that your account has access to. Reports are returned in reverse chronological order by default. operationId: listReports parameters: - $ref: "#/components/parameters/maxResults" - $ref: "#/components/parameters/pageToken" - name: filter in: query description: >- An expression for filtering the results. The syntax is `key:[]`. Multiple filters can be connected using a pipe |. See [Filters](https://developer.doit.com/docs/filters). Possible filter keys: **reportName**, **owner**, **type**, **updateTime**, **folderId** example: "reportName:This Month vs. Last" schema: type: string - name: minCreationTime in: query description: Min value for reports creation time, in milliseconds since the POSIX epoch. If set, only reports created after or at this timestamp are returned. schema: type: string - name: maxCreationTime in: query description: Max value for reports creation time, in milliseconds since the POSIX epoch. If set, only reports created before or at this timestamp are returned. schema: type: string responses: "200": description: OK - The request succeeded. content: application/json: schema: $ref: "#/components/schemas/ReportList" "400": $ref: "#/components/responses/400" "401": $ref: "#/components/responses/401" "403": $ref: "#/components/responses/403" "404": $ref: "#/components/responses/404" post: tags: - Reports summary: Create a report description: >- Creates a new report. operationId: createReport requestBody: content: application/json: schema: type: object properties: name: type: string description: Report name. example: A test report by API description: type: string description: Report description. example: Cost breakdown by service in the last 3 months config: $ref: "#/components/schemas/ExternalConfig" labels: type: array items: type: string description: Array of label IDs assigned to the report folderId: type: string description: Identifier of the folder that contains the report. Set to "root" if the report is at the top level (not in a folder). default: root example: root example: name: monthly-cost-by-service description: Monthly cost grouped by service config: includeSubtotals: false sortGroups: asc sortDimensions: desc metrics: - type: basic value: cost timeRange: amount: 7 includeCurrent: false mode: last unit: day aggregation: total dimensions: - id: service_description type: fixed displayValues: actuals_only timeInterval: day responses: "201": description: Created - The request succeeded. content: application/json: schema: $ref: "#/components/schemas/ExternalReport" links: getReport: operationId: getReport parameters: id: $response.body#/id updateReport: operationId: updateReport parameters: id: $response.body#/id deleteReport: operationId: deleteReport parameters: id: $response.body#/id "400": $ref: "#/components/responses/400" "401": $ref: "#/components/responses/401" "403": $ref: "#/components/responses/403" "500": $ref: "#/components/responses/500" x-codegen-request-body-name: Body /analytics/v1/reports/query: post: tags: - Reports summary: Run a query description: >- Runs a report query with the specified configuration without persisting it. Fields that are not populated will use their default values if needed. operationId: query requestBody: content: application/json: schema: type: object properties: config: $ref: "#/components/schemas/ExternalConfig" example: config: dataSource: billing metrics: - type: basic value: cost timeRange: amount: 30 includeCurrent: false mode: last unit: day group: - id: service_description type: fixed timeInterval: day responses: "200": description: OK - The request succeeded. content: application/json: schema: $ref: "#/components/schemas/RunReportResult" "400": $ref: "#/components/responses/400" "401": $ref: "#/components/responses/401" "500": $ref: "#/components/responses/500" x-codegen-request-body-name: Body "/analytics/v1/reports/{id}": get: tags: - Reports summary: Get report results description: Returns the results of the specified report. operationId: getReport parameters: - $ref: "#/components/parameters/reportId" - name: timeRange in: query description: >- An optional parameter to override the report time settings. Value should be represented in the format P[n]Y[n]M[n]D[n]. In the representations, the [n] is replaced by the value for each of the date and time elements that follow the [n]. schema: type: string pattern: "^P(\\d+Y)?(\\d+M)?(\\d+D)?$" example: P7D - name: startDate in: query description: >- An optional parameter to override the report time settings. Must be provided together with endDate. Format: yyyy-mm-dd schema: type: string format: date example: "2025-01-01" - name: endDate in: query description: >- An optional parameter to override the report time settings. Must be provided together with startDate. Format: yyyy-mm-dd schema: type: string format: date example: "2025-01-31" responses: "200": description: OK - The request succeeded. content: application/json: schema: $ref: "#/components/schemas/GetReportResponse" "400": $ref: "#/components/responses/400" "401": $ref: "#/components/responses/401" "403": $ref: "#/components/responses/403" "404": $ref: "#/components/responses/404" "429": $ref: "#/components/responses/429" delete: tags: - Reports summary: Delete a report description: Deletes the specified Cloud Analytics report. operationId: deleteReport parameters: - $ref: "#/components/parameters/reportId" responses: "200": description: OK - Report deleted. content: application/json: schema: type: object additionalProperties: false example: {} links: listReports: operationId: listReports "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: - Reports summary: Update a report description: |- Updates a report with the specified configuration. Only specified fields will be updated. operationId: updateReport parameters: - $ref: "#/components/parameters/reportId" requestBody: content: application/json: schema: $ref: "#/components/schemas/ExternalUpdateReport" required: false responses: "200": description: OK - Report updated. content: application/json: schema: $ref: "#/components/schemas/ExternalReport" links: getReport: operationId: getReport parameters: id: $response.body#/id deleteReport: operationId: deleteReport parameters: id: $response.body#/id "400": $ref: "#/components/responses/400" "401": $ref: "#/components/responses/401" "403": $ref: "#/components/responses/403" "500": $ref: "#/components/responses/500" x-codegen-request-body-name: Body "/analytics/v1/reports/{id}/config": get: tags: - Reports summary: Get report config description: Returns the configuration of the specified Cloud Analytics report. operationId: getReportConfig parameters: - $ref: "#/components/parameters/reportId" responses: "200": description: OK - Report configuration returned. content: application/json: schema: $ref: "#/components/schemas/ExternalReport" "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" "/sharing/v1/{resourceType}/{resourceId}": get: tags: - Sharing summary: Get resource permissions description: |- Returns the permissions associated with the specified Cloud Analytics resource. Supports Allocations, Alerts, Budgets, and Reports. operationId: getResourcePermission parameters: - $ref: "#/components/parameters/resourceType" - $ref: "#/components/parameters/resourceId" responses: "200": description: OK - Resource permissions returned. content: application/json: schema: $ref: "#/components/schemas/ResourcePermissionsResponse" "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" put: tags: - Sharing summary: Update resource permissions description: |- Updates the permissions associated with the specified Cloud Analytics resource. Supports Allocations, Alerts, Budgets, and Reports. operationId: updateResourcePermission parameters: - $ref: "#/components/parameters/resourceType" - $ref: "#/components/parameters/resourceId" requestBody: content: application/json: schema: type: object properties: permissions: type: array items: $ref: "#/components/schemas/ResourcePermission" public: type: string description: The type of permissions granted to all users in the organization for this resource. enum: - editor - viewer nullable: true responses: "200": description: OK - Resource permissions configuration updated. content: application/json: schema: $ref: "#/components/schemas/ResourcePermissionsResponse" "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" "/customers/{customerID}/contracts": get: tags: - Contracts summary: List contracts description: Lists the contracts held by the specified customer. Callable by a T1/T2 PartnerOps principal for its own tenant or any descendant tenant. Read access requires contractsReadOnly, contractsViewer, or a write-capable role (without contractsReadOnly). User API tokens must include the matching permission in their scope. operationId: listContracts parameters: - name: customerID in: path description: The customer (tenant) whose contracts are requested. required: true schema: type: string responses: "200": description: OK - The request succeeded. content: application/json: schema: type: array items: $ref: "#/components/schemas/MTSContractResponse" "401": $ref: "#/components/responses/401" "403": $ref: "#/components/responses/403" post: tags: - Contracts summary: Create contract description: Creates a draft contract for the specified customer. Requires the caller to be the direct parent (T1 for a T2-level contract, T2 for a T3-level contract). Write access requires a role without contractsReadOnly; user API tokens must include the matching permission in their scope. operationId: createContract parameters: - name: customerID in: path description: The customer (tenant) the contract is created for. required: true schema: type: string requestBody: required: true content: application/json: schema: $ref: "#/components/schemas/MTSContractInput" responses: "201": description: Created - The contract draft was created. content: application/json: schema: $ref: "#/components/schemas/CreateContractResponse" "400": $ref: "#/components/responses/400" "401": $ref: "#/components/responses/401" "403": $ref: "#/components/responses/403" "/customers/{customerID}/contracts/{contractID}": get: tags: - Contracts summary: Retrieve a contract description: Returns the specified contract. operationId: getContract parameters: - name: customerID in: path required: true schema: type: string - name: contractID in: path required: true schema: type: string responses: "200": description: OK - Contract returned. content: application/json: schema: $ref: "#/components/schemas/MTSContractDetailResponse" "401": $ref: "#/components/responses/401" "403": $ref: "#/components/responses/403" "404": $ref: "#/components/responses/404" post: tags: - Contracts summary: Update contract description: Creates a new version of the contract. The contract type is immutable and cannot be changed by an update. operationId: updateContract parameters: - name: customerID in: path required: true schema: type: string - name: contractID in: path required: true schema: type: string requestBody: required: true content: application/json: schema: $ref: "#/components/schemas/MTSContractInput" responses: "200": description: OK - New contract version created. content: application/json: schema: $ref: "#/components/schemas/CreateContractResponse" "400": $ref: "#/components/responses/400" "401": $ref: "#/components/responses/401" "403": $ref: "#/components/responses/403" "404": $ref: "#/components/responses/404" "/customers/{customerID}/contracts/{contractID}/activate": post: tags: - Contracts summary: Activate contract description: Transitions a draft contract to active or scheduled (when the start date is in the future). Produces the same system state as activating via the Console. operationId: activateContract parameters: - name: customerID in: path required: true schema: type: string - name: contractID in: path required: true schema: type: string responses: "200": description: OK - Contract activated or scheduled. content: application/json: schema: $ref: "#/components/schemas/ContractLifecycleResponse" "400": $ref: "#/components/responses/400" "401": $ref: "#/components/responses/401" "403": $ref: "#/components/responses/403" "404": $ref: "#/components/responses/404" "409": description: Conflict - An active contract of the same type already exists for this tier. "/customers/{customerID}/contracts/{contractID}/cancel": post: tags: - Contracts summary: Cancel contract description: Cancels (deactivates) a contract. Active contracts cannot be deleted; cancel is the terminal operation. operationId: cancelContract parameters: - name: customerID in: path required: true schema: type: string - name: contractID in: path required: true schema: type: string requestBody: required: false content: application/json: schema: type: object properties: reason: type: string description: Optional cancellation reason. responses: "200": description: OK - Contract cancelled. content: application/json: schema: $ref: "#/components/schemas/ContractLifecycleResponse" "400": $ref: "#/components/responses/400" "401": $ref: "#/components/responses/401" "403": $ref: "#/components/responses/403" "404": $ref: "#/components/responses/404" /anomalies/v1: get: tags: - Anomalies summary: List anomalies description: |- Returns a list of detected anomalies. Anomalies are returned in reverse chronological order by default. The `notifications` array is always present on each anomaly item; it is empty unless `includeNotifications=true` is supplied. operationId: listAnomalies parameters: - name: minCreationTime in: query description: Min value for the anomaly detection time schema: type: string - name: maxCreationTime in: query description: Max value for the anomaly detection time schema: type: string - name: filter in: query description: An expression for filtering the results of the request schema: type: string - name: maxResults in: query description: The maximum number of results to return in a single page schema: type: integer format: int64 - $ref: "#/components/parameters/pageToken" - name: includeNotifications in: query description: Include anomaly notifications from the subcollection. Defaults to false. schema: type: boolean default: false responses: "200": description: OK - The request succeeded. content: application/json: schema: $ref: "#/components/schemas/AnomaliesResponse" "400": $ref: "#/components/responses/400" "401": $ref: "#/components/responses/401" "403": $ref: "#/components/responses/403" "404": $ref: "#/components/responses/404" "/anomalies/v1/{id}": get: tags: - Anomalies summary: Retrieve an anomaly description: Returns the specified anomaly. operationId: getAnomaly parameters: - name: id in: path description: A unique identifier of the anomaly. required: true schema: type: string responses: "200": description: OK - Anomaly returned. content: application/json: schema: required: - attribution - billingAccount - costOfAnomaly - platform - scope - serviceName - severityLevel - startTime - timeFrame - top3SKUs - notifications type: object properties: attribution: type: string description: Attribution ID billingAccount: type: string description: Billing account ID costOfAnomaly: type: number description: The difference between the actual cost and the maximum cost in the normal range. format: double actualCost: type: number format: double nullable: true description: Observed (actual) cost of the anomaly. expectedMaxCost: type: number format: double nullable: true description: Maximum cost within the expected normal range. platform: type: string description: Cloud Provider name scope: type: string description: "Scope: Project or Account" serviceName: type: string description: Service name severityLevel: type: string description: "Severity level: Information, Warning or Critical" startTime: type: integer description: Usage start time of the anomaly format: int64 endTime: type: integer nullable: true description: End of the anomaly timeFrame: type: string description: "Timeframe: Daily or Hourly" top3SKUs: $ref: "#/components/schemas/AnomalySKUArray" resourceData: $ref: "#/components/schemas/AnomalyResourceArray" status: type: string nullable: true enum: - active - inactive acknowledged: description: "Has the anomaly been acknowledged" type: boolean acknowledgedAt: description: "When the anomaly was first acknowledged" type: string format: date-time nullable: true acknowledgedBy: description: "Email of the user who first acknowledged the anomaly" type: string nullable: true notifications: $ref: "#/components/schemas/NotificationEventArray" "400": $ref: "#/components/responses/400" "401": $ref: "#/components/responses/401" "403": $ref: "#/components/responses/403" "404": $ref: "#/components/responses/404" /auth/v1/validate: get: tags: - Auth summary: Validate a user description: Returns the domain and email of the current API user. operationId: validate responses: "200": description: OK - The domain and email of the API user returned. content: application/json: schema: $ref: "#/components/schemas/ValidateResponse" "400": $ref: "#/components/responses/400" "401": $ref: "#/components/responses/401" "403": $ref: "#/components/responses/403" /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" /datahub/v1/csv/upload: post: tags: - DataHub summary: Ingest CSV file description: Sends a batch of events to DataHub using a CSV file, either uncompressed or compressed in ZIP or GZ format. It may take up to 15 minutes for the data to become available in the DoiT console. operationId: datahubEventsCSVFile requestBody: required: true content: multipart/form-data: schema: type: object properties: provider: type: string description: "The identifier of the data provider. Allowed characters: alphanumeric (0-9,a-z,A-Z), underscore (_), space, dash (-)." example: "Datadog" file: type: string format: binary description: The CSV file to upload, either uncompressed or compressed in ZIP or GZ format. The maximum file size is 30 MB. responses: "201": description: OK - Ingestion succeeded. content: application/json: schema: type: object properties: batch: type: string description: batch id, generated during ingestion example: "your_file.csv.gz_1730972725212" ingestedRows: type: integer description: the number of events that have been accepted for processing example: 15 "400": $ref: "#/components/responses/400" "401": $ref: "#/components/responses/401" "403": $ref: "#/components/responses/403" "500": $ref: "#/components/responses/500" /datahub/v1/events: post: tags: - DataHub summary: Ingest JSON description: Sends a batch of events to DataHub. operationId: datahubEvents requestBody: required: true content: application/json: schema: type: object properties: events: type: array minItems: 1 maxItems: 50000 items: type: object required: - provider - time properties: provider: type: string description: "The identifier of the data provider. Allowed characters: alphanumeric (0-9,a-z,A-Z), underscore (_), space, dash (-)." example: "Datadog" id: type: string description: The event id. Must be unique within the dataset. If not set, a UUIDv4 will be generated at ingestion time. example: "beb21d99-a8c9-4dc0-8a69-5d684cc41e6c" dimensions: type: array items: type: object properties: key: type: string example: "project_id" description: If the type is `fixed`, the key must be a valid fixed value. See the [DataHub API Guide](https://developer.doit.com/docs/datahub-api) for more information. type: type: string description: The dimension type. x-type: string enum: - fixed - label - project_label - system_label value: oneOf: - type: string - type: boolean example: "production-project" time: type: string format: date-time description: The timestamp of the event in RFC3339 format. example: "2024-03-10T23:00:00Z" metrics: type: array items: type: object properties: value: type: number format: double description: The value of the metric. example: 10.5 type: type: string description: 'The type of the metric. If you choose "cost" or "usage", it will map to the basic "Cost" or "Usage" metric in Cloud Analytics reports. You can also use this field to define custom metric types, such as "working_hours", "ride", etc.' example: "cost" responses: "201": description: OK - Ingestion succeeded. content: application/json: schema: type: object properties: message: type: string example: "Ingestion success" "400": $ref: "#/components/responses/400" "401": $ref: "#/components/responses/401" "403": $ref: "#/components/responses/403" "500": $ref: "#/components/responses/500" /datahub/v1/events/delete: post: tags: - DataHub summary: Delete specific events description: >- Deletes specific events using filters. Note that the two filters, `eventIds` and `time ranges`, are mutually exclusive. operationId: deleteDatahubEventsByFilter requestBody: required: true content: application/json: schema: type: object description: Exactly one of "eventIds" or "time ranges" must be provided. required: - dataset properties: dataset: type: string description: The dataset (provider) of the events to be deleted. example: "Datadog" eventIds: type: array items: type: string description: Id of the event to be deleted. example: "beb21d99-a8c9-4dc0-8a69-5d684cc41e6c" startTime: type: string format: date-time description: The start timestamp of the time range in RFC3339 format. example: "2024-03-10T23:00:00Z" endTime: type: string format: date-time description: The end timestamp of the time range in RFC3339 format. example: "2024-03-12T23:00:00Z" minProperties: 1 maxProperties: 1 responses: "200": description: OK - Events deleted. content: application/json: schema: type: object properties: message: type: string example: "Delete success" "400": $ref: "#/components/responses/400" "401": $ref: "#/components/responses/401" "403": $ref: "#/components/responses/403" "500": $ref: "#/components/responses/500" /datahub/v1/datasets: get: tags: - DataHub summary: List datasets description: Returns a list of all DataHub datasets for the customer. operationId: listDatahubDatasets responses: "200": description: OK - List of datasets returned successfully. content: application/json: schema: type: object properties: datasets: type: array items: type: object properties: name: type: string description: The name of the dataset. example: "My Custom Dataset" description: type: string description: The description of the dataset. example: "Dataset for tracking custom business metrics" records: type: integer format: int64 description: The number of records in the dataset. example: 1500 updatedBy: type: string description: The email of the user who last updated the dataset. example: "user@example.com" lastUpdated: type: string description: The timestamp of the last update. example: "2024-03-10T23:00:00Z" "401": $ref: "#/components/responses/401" "403": $ref: "#/components/responses/403" "500": $ref: "#/components/responses/500" post: tags: - DataHub summary: Create dataset description: Creates a new DataHub dataset. A dataset is a logical grouping of events that share the same provider name. Creating a dataset allows you to define metadata such as name and description before ingesting events. operationId: createDatahubDataset requestBody: required: true content: application/json: schema: type: object required: - name properties: name: type: string description: "The name of the dataset. Allowed characters: alphanumeric (0-9,a-z,A-Z), underscore (_), dash (-), and spaces between words." example: "My Custom Dataset" pattern: "^[a-zA-Z0-9_-]+( [a-zA-Z0-9_-]+)*$" description: type: string description: An optional description for the dataset. example: "Dataset for tracking custom business metrics" responses: "201": description: Created - Dataset created successfully. content: application/json: schema: type: object properties: name: type: string description: The name of the dataset. example: "My Custom Dataset" description: type: string description: The description of the dataset. example: "Dataset for tracking custom business metrics" records: type: integer format: int64 description: The number of records in the dataset. example: null nullable: true updatedBy: type: string description: The email of the user who last updated the dataset. example: "user@example.com" lastUpdated: type: string description: The timestamp of the last update. example: "2024-03-10T23:00:00Z" "400": $ref: "#/components/responses/400" "401": $ref: "#/components/responses/401" "403": $ref: "#/components/responses/403" "500": $ref: "#/components/responses/500" delete: tags: - DataHub summary: Delete datasets description: Deletes one or more DataHub datasets and all their associated data. operationId: deleteDatahubDatasets requestBody: required: true content: application/json: schema: type: object required: - datasets properties: datasets: type: array description: List of dataset names to delete. items: type: string example: ["My Custom Dataset", "Old Dataset"] responses: "200": description: OK - Datasets deleted successfully. content: application/json: schema: type: object properties: message: type: string example: "Datasets deleted successfully" "400": $ref: "#/components/responses/400" "401": $ref: "#/components/responses/401" "403": $ref: "#/components/responses/403" "500": $ref: "#/components/responses/500" "/datahub/v1/datasets/{name}": get: tags: - DataHub summary: Retrieve a dataset description: Returns a specific DataHub dataset by name. operationId: getDatahubDataset parameters: - name: name in: path description: The name of the dataset to retrieve. required: true schema: type: string example: "My Custom Dataset" responses: "200": description: OK - Dataset returned. content: application/json: schema: type: object properties: name: type: string description: The name of the dataset. example: "My Custom Dataset" description: type: string description: The description of the dataset. example: "Dataset for tracking custom business metrics" records: type: integer format: int64 description: The number of records in the dataset. example: 1500 updatedBy: type: string description: The email of the user who last updated the dataset. example: "user@example.com" lastUpdated: type: string description: The timestamp of the last update. example: "2024-03-10T23:00:00Z" "401": $ref: "#/components/responses/401" "403": $ref: "#/components/responses/403" "404": $ref: "#/components/responses/404" "500": $ref: "#/components/responses/500" delete: tags: - DataHub summary: Delete a dataset description: Deletes a specific DataHub dataset. operationId: deleteDatahubDataset parameters: - name: name in: path description: The name of the dataset to delete. required: true schema: type: string example: "My Custom Dataset" responses: "200": description: OK - Dataset deleted successfully. content: application/json: schema: type: object properties: message: type: string example: "Dataset deleted successfully" "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: - DataHub summary: Update dataset description: |- Updates an existing DataHub dataset's metadata. Only the description field can be updated. The dataset name is immutable and serves as the resource identifier. To rename a dataset, delete it and create a new one. If `name` is included in the request body, it must match the dataset name in the URL path. A mismatched name will be rejected with a 400 error. operationId: updateDatahubDataset parameters: - name: name in: path description: The name of the dataset to update (immutable, used for identification only). required: true schema: type: string example: "My Custom Dataset" requestBody: required: true content: application/json: schema: type: object additionalProperties: false properties: name: type: string description: "Must match the dataset name in the URL path. Included for idempotency; the name cannot be changed." example: "My Custom Dataset" description: type: string description: The new description for the dataset. example: "Updated description for the dataset" responses: "200": description: OK - Dataset updated successfully. content: application/json: schema: type: object properties: name: type: string description: The name of the dataset. example: "My Custom Dataset" description: type: string description: The description of the dataset. example: "Updated description for the dataset" records: type: integer format: int64 description: The number of records in the dataset. example: 1500 nullable: true updatedBy: type: string description: The email of the user who last updated the dataset. example: "user@example.com" lastUpdated: type: string description: The timestamp of the last update. example: "2024-03-10T23:00:00Z" "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" /billing/v1/invoices: get: tags: - Invoices summary: List invoices description: |- Returns a list of all the current and historical invoices for your organization. Invoices are returned in reverse chronological order by default. operationId: listInvoices 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 schema: $ref: "#/components/schemas/Filter" - name: minCreationTime in: query description: Min value for the invoice creation time, in milliseconds since the POSIX epoch. If set, only invoices created after or at this timestamp are returned. schema: type: integer format: int64 - name: maxCreationTime in: query description: Max value for the invoice creation time, in milliseconds since the POSIX epoch. If set, only invoices created before or at this timestamp are returned. schema: type: integer format: int64 responses: "200": description: OK - All available invoices returned. content: application/json: schema: type: object properties: invoices: type: array description: Array of Invoices items: $ref: "#/components/schemas/InvoiceListItem" pageToken: type: string description: Page token. Can be used to request the next page of results. rowCount: type: integer description: Invoice 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/invoices/{id}": get: tags: - Invoices summary: Retrieve an invoice description: Returns the full details of an invoice specified by the invoice number. operationId: getInvoice parameters: - name: id in: path description: Invoice number. required: true schema: type: string responses: "200": description: OK - Invoice details returned. content: application/json: schema: type: object properties: id: type: string description: Invoice number, identifying the invoice. invoiceDate: type: integer description: The time when this invoice was issued, in milliseconds since the epoch. format: int64 platform: $ref: "#/components/schemas/InvoicePlatform" dueDate: type: integer description: The last day to pay the invoice, in milliseconds since the epoch format: int64 status: type: string description: Status of the invoice enum: - OPEN - PAST DUE - PAID totalAmount: type: number description: Total invoiced amount format: double balanceAmount: type: number description: Invoice balance to be paid format: double currency: $ref: "#/components/schemas/Currency" url: type: string description: Link to [invoice details page](https://help.doit.com/docs/billing/invoices-and-payments/managing-invoices) in the DoiT console. You can download the PDF invoice from the invoice details page. lineItems: type: array description: Invoice line items. items: $ref: "#/components/schemas/ListItem" "400": $ref: "#/components/responses/400" "401": $ref: "#/components/responses/401" "403": $ref: "#/components/responses/403" "404": $ref: "#/components/responses/404" /core/v1/service-quotas: get: tags: - Service Quotas summary: List service quotas description: |- Returns the latest service quota usage snapshots collected by DoiT for the authenticated customer. Results include only quotas retained by DoiT's monitoring collectors and are not a complete or live inventory from the cloud providers. Results are sorted by utilization percentage in descending order. operationId: listServiceQuotas parameters: - name: cloudProvider in: query description: Filter results to a cloud provider. Omit to return all supported providers. schema: type: string enum: - aws - gcp - name: minUtilizationPercent in: query description: Return quotas whose utilization percentage is greater than or equal to this value. schema: type: number format: double minimum: 0 maximum: 100 - name: maxResults in: query description: Maximum number of results to return in one page. schema: type: integer format: int32 minimum: 1 maximum: 200 default: 50 - $ref: "#/components/parameters/pageToken" responses: "200": description: OK - Service quotas returned. content: application/json: schema: $ref: "#/components/schemas/ServiceQuotaList" "400": $ref: "#/components/responses/400" "401": $ref: "#/components/responses/401" "403": $ref: "#/components/responses/403" "500": $ref: "#/components/responses/500" /core/v1/cloudincidents: get: tags: - Cloud Incidents summary: List cloud incidents description: >- Returns a list of all the active and historical cloud incidents for Google Cloud and Amazon Web Services. Incidents are returned in reverse chronological order by default. operationId: listKnownIssues 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. The syntax is `key:[]`. Multiple filters can be connected using a pipe |. See [Filters](https://developer.doit.com/docs/filters). schema: type: string - name: minCreationTime in: query description: Min value for the cloud incident creation time, in milliseconds since the POSIX epoch. If set, only cloud incidents created after or at this timestamp are returned. schema: type: string - name: maxCreationTime in: query description: | Max value for the cloud incident creation time, in milliseconds since the POSIX epoch. If set, only cloud incidents created before or at this timestamp are returned. schema: type: string responses: "200": description: OK - The request succeeded. content: application/json: schema: type: object properties: incidents: type: array description: Array of cloud incidents items: $ref: "#/components/schemas/CloudIncidentListItem" pageToken: type: string description: Page token, returned by a previous call, to request the next page of results rowCount: type: integer description: Cloud incidents rows count format: int64 "400": $ref: "#/components/responses/400" "401": $ref: "#/components/responses/401" "403": $ref: "#/components/responses/403" "404": $ref: "#/components/responses/404" "/core/v1/cloudincidents/{id}": get: tags: - Cloud Incidents summary: Retrieve a cloud incident description: Returns the specified cloud incident. operationId: getKnownIssue parameters: - name: id in: path description: The unique id of a cloud incident. required: true schema: type: string responses: "200": description: OK - Cloud incident returned. content: application/json: schema: type: object properties: createTime: type: integer description: The time when this cloud incident was created, in milliseconds since the epoch. format: int64 description: type: string description: Detailed explanation on the cloud incident. id: type: string description: The unique id of a cloud incident platform: type: string description: The cloud platform. enum: - google-cloud - amazon-web-services product: type: string description: The name of the product affected by the cloud incident status: type: string description: The Status of the issue enum: - active - archived summary: type: string description: A summary of the cloud incident. symptoms: type: string description: Cloud incident symptoms, if available. title: type: string description: Cloud incident name provided by the cloud vendor. workaround: type: string description: Mitigation workaround for the cloud incident, if available. "400": $ref: "#/components/responses/400" "401": $ref: "#/components/responses/401" "403": $ref: "#/components/responses/403" "404": $ref: "#/components/responses/404" /billing/v1/contract-templates: get: tags: - Contract Templates summary: List contract templates description: >- Lists contract templates owned by the authenticated tenant (from the bearer token). Requires ContractTemplatesAdmin, DoiT API access (`platform:externalApi`), and the `channelops:contracts:templates` entitlement. operationId: listContractTemplates responses: "200": description: OK - Contract templates returned. content: application/json: schema: type: array items: $ref: "#/components/schemas/ContractTemplateResponse" "401": $ref: "#/components/responses/401" "403": $ref: "#/components/responses/403" "500": $ref: "#/components/responses/500" post: tags: - Contract Templates summary: Create contract template description: >- Creates a contract template for the authenticated tenant (from the bearer token). Requires ContractTemplatesAdmin, DoiT API access (`platform:externalApi`), and the `channelops:contracts:templates` entitlement. operationId: createContractTemplate requestBody: required: true content: application/json: schema: $ref: "#/components/schemas/ContractTemplateInput" responses: "201": description: Created - Contract template created. content: application/json: schema: $ref: "#/components/schemas/ContractTemplateResponse" "400": $ref: "#/components/responses/400" "401": $ref: "#/components/responses/401" "403": $ref: "#/components/responses/403" "409": $ref: "#/components/responses/409" "500": $ref: "#/components/responses/500" "/billing/v1/contract-templates/{templateID}": get: tags: - Contract Templates summary: Get contract template description: >- Returns a single contract template owned by the authenticated tenant (from the bearer token). Requires ContractTemplatesAdmin, DoiT API access (`platform:externalApi`), and the `channelops:contracts:templates` entitlement. operationId: getContractTemplate parameters: - name: templateID in: path required: true schema: type: string responses: "200": description: OK - Contract template returned. content: application/json: schema: $ref: "#/components/schemas/ContractTemplateResponse" "401": $ref: "#/components/responses/401" "403": $ref: "#/components/responses/403" "404": $ref: "#/components/responses/404" "500": $ref: "#/components/responses/500" put: tags: - Contract Templates summary: Update contract template description: >- Updates a contract template owned by the authenticated tenant (from the bearer token). Requires ContractTemplatesAdmin, DoiT API access (`platform:externalApi`), and the `channelops:contracts:templates` entitlement. operationId: updateContractTemplate parameters: - name: templateID in: path required: true schema: type: string requestBody: required: true content: application/json: schema: $ref: "#/components/schemas/ContractTemplateInput" responses: "200": description: OK - Contract template updated. content: application/json: schema: $ref: "#/components/schemas/ContractTemplateResponse" "400": $ref: "#/components/responses/400" "401": $ref: "#/components/responses/401" "403": $ref: "#/components/responses/403" "404": $ref: "#/components/responses/404" "409": $ref: "#/components/responses/409" "500": $ref: "#/components/responses/500" delete: tags: - Contract Templates summary: Archive contract template description: >- Soft-deletes (archives) a contract template owned by the authenticated tenant (from the bearer token). Instantiated contracts are unaffected. Requires ContractTemplatesAdmin, DoiT API access (`platform:externalApi`), and the `channelops:contracts:templates` entitlement. operationId: archiveContractTemplate parameters: - name: templateID in: path required: true schema: type: string responses: "200": description: OK - Contract template archived. content: application/json: schema: $ref: "#/components/schemas/ContractTemplateResponse" "401": $ref: "#/components/responses/401" "403": $ref: "#/components/responses/403" "404": $ref: "#/components/responses/404" "409": $ref: "#/components/responses/409" "500": $ref: "#/components/responses/500" /customers/v1/accountTeam: get: tags: - AccountTeam summary: List account team description: Returns a list of all DoiT account managers assigned to your organization. operationId: listAccountTeam responses: "200": description: OK - List of account managers returned. content: application/json: schema: type: object properties: accountManagers: type: array items: $ref: "#/components/schemas/AccountManagerListItem" "400": $ref: "#/components/responses/400" "401": $ref: "#/components/responses/401" "403": $ref: "#/components/responses/403" "/cloudflow/v1/trigger/{flowId}": post: tags: - CloudFlow summary: Trigger a webhook flow description: |- Triggers execution of a published CloudFlow whose first node is a webhook trigger. The request body must be valid JSON and is passed to the flow as webhook payload data. operationId: triggerCloudflowWebhook parameters: - name: flowId in: path description: The unique ID of the published CloudFlow to trigger. required: true schema: type: string requestBody: required: true content: application/json: schema: type: object properties: {} additionalProperties: true description: Arbitrary JSON payload delivered to the webhook trigger node. example: key: value responses: "202": description: Accepted - CloudFlow execution started. content: application/json: schema: type: object required: - executionLink properties: executionLink: type: string description: Console URL for the started CloudFlow execution history entry. example: "https://console.doit.com/customers/customer-id/cloudflow/history/execution-id" "400": $ref: "#/components/responses/400" "401": $ref: "#/components/responses/401" "403": $ref: "#/components/responses/403" "404": $ref: "#/components/responses/404" "409": description: >- Conflict - The CloudFlow already has an active execution and cannot be triggered until it completes. content: application/json: schema: $ref: "#/components/schemas/Error" "500": $ref: "#/components/responses/500" /cloudflow/v1/flows/{flowId}/actions/refine: post: tags: - CloudFlow summary: Refine a CloudFlow from natural language intent description: >- Refines the specified CloudFlow by generating and updating nodes and connections based on the provided natural language intent. The operation streams incremental build events as they are produced. operationId: refineCloudFlow parameters: - name: flowId in: path required: true schema: type: string requestBody: required: true content: application/json: schema: $ref: "#/components/schemas/CloudFlowRefineRequest" responses: "200": description: OK - Refine event stream. content: text/event-stream: schema: type: string "400": $ref: "#/components/responses/400" "401": $ref: "#/components/responses/401" "403": $ref: "#/components/responses/403" "406": description: Not Acceptable — the client did not include `text/event-stream` in the Accept header. content: application/json: schema: $ref: "#/components/schemas/Error" "500": $ref: "#/components/responses/500" "502": description: Bad Gateway — the upstream refine service returned an unexpected error. content: application/json: schema: $ref: "#/components/schemas/Error" /cloudflow/v1/flows/actions/build: post: tags: - CloudFlow summary: Build a new CloudFlow from scratch description: >- Creates a new CloudFlow and generates its nodes and connections based on the provided natural language intent. The operation streams incremental build events, including the ID of the newly created flow, as they are produced. operationId: buildCloudFlow requestBody: required: true content: application/json: schema: $ref: "#/components/schemas/CloudFlowBuildRequest" responses: "200": description: OK - Build event stream. content: text/event-stream: schema: type: string "400": $ref: "#/components/responses/400" "401": $ref: "#/components/responses/401" "403": $ref: "#/components/responses/403" "406": description: Not Acceptable — the client did not include `text/event-stream` in the Accept header. content: application/json: schema: $ref: "#/components/schemas/Error" "500": $ref: "#/components/responses/500" "502": description: Bad Gateway — the upstream build service returned an unexpected error. content: application/json: schema: $ref: "#/components/schemas/Error" /iam/v1/users: get: tags: - Users summary: List users description: |- Returns a list of users in the organization, including both active users and invited users. When the `email` query parameter is provided, returns only the user matching that email address. If no user is found for the given email, an empty list is returned. operationId: listUsers parameters: - name: email in: query description: Filter by exact email address. When provided, returns at most one user matching this email. The email is matched case-insensitively. required: false schema: type: string format: email responses: "200": description: OK - List of users returned. content: application/json: schema: $ref: "#/components/schemas/ListUsersResponseBody" "400": $ref: "#/components/responses/400" "401": $ref: "#/components/responses/401" "403": $ref: "#/components/responses/403" "500": $ref: "#/components/responses/500" "/iam/v1/users/{id}": delete: tags: - Users summary: Delete user description: Deletes a user. operationId: deleteUser parameters: - name: id in: path description: The unique ID of the user to delete required: true schema: type: string responses: "200": description: OK - User deleted successfully. content: application/json: schema: $ref: "#/components/schemas/DeleteUserResponse" "400": $ref: "#/components/responses/400" "401": $ref: "#/components/responses/401" "403": $ref: "#/components/responses/403" "500": $ref: "#/components/responses/500" patch: tags: - Users summary: Update user description: Updates user information, including name, job function, phone, language, and role. operationId: updateUser parameters: - name: id in: path description: The unique ID of the user to update. required: true schema: type: string requestBody: required: true content: application/json: schema: $ref: "#/components/schemas/UpdateUserRequest" responses: "200": description: OK - User updated successfully. content: application/json: schema: $ref: "#/components/schemas/UpdateUserResponse" "400": $ref: "#/components/responses/400" "401": $ref: "#/components/responses/401" "403": $ref: "#/components/responses/403" "500": $ref: "#/components/responses/500" /iam/v1/users/invite: post: tags: - Users summary: Invite user description: Invites a new user to the organization with specified role and organization. operationId: inviteUser requestBody: required: true content: application/json: schema: $ref: "#/components/schemas/InviteUserRequest" responses: "201": description: Created - User invitation created successfully. content: application/json: schema: $ref: "#/components/schemas/InviteResponse" "400": $ref: "#/components/responses/400" "401": $ref: "#/components/responses/401" "403": $ref: "#/components/responses/403" "500": $ref: "#/components/responses/500" "/iam/v1/users/{id}/actions/resend": post: tags: - Users summary: Resend invite description: | Resets the invite expiry to 48 hours from now, invalidates the previous invite token (so old email links stop working), and triggers a fresh invitation email. Works on invites in any state including `Cancelled` — resending a cancelled invite reactivates it to `Pending`. Returns `404` if no invite exists for the given ID (never created, or already accepted and removed). Requires `usersManager` permission. operationId: resendInvite parameters: - name: id in: path description: The unique ID of the invited user. required: true schema: type: string - name: Idempotency-Key in: header required: true description: | Client-generated idempotency key (UUID v4 or ULID recommended, max 255 characters). Re-submitting the same key with the same request returns the cached response without re-executing side effects. The server retains the key for at least 24 hours. schema: type: string maxLength: 255 - name: dryRun in: query required: false description: | If `true`, validates and simulates the operation without committing changes. The response shape is identical to a real execution. schema: type: boolean default: false requestBody: required: false content: application/json: schema: type: object responses: "200": description: OK - Invite resent and expiry reset. content: application/json: schema: $ref: "#/components/schemas/ResendInviteResponse" "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" "/iam/v1/users/{id}/actions/cancel": post: tags: - Users summary: Cancel invite description: | Marks the invite as `Cancelled` and invalidates the invite token so any outstanding email links stop working. The invite document is retained (soft cancel) — the user row remains visible in `GET /iam/v1/users` with `inviteStatus: Cancelled`. Use `DELETE /iam/v1/users/{id}` to fully remove the record. Returns `404` if no invite exists for the given ID, and `409` if the invite is already cancelled. Requires `usersManager` permission. operationId: cancelInvite parameters: - name: id in: path description: The unique ID of the invited user. required: true schema: type: string - name: Idempotency-Key in: header required: true description: | Client-generated idempotency key (UUID v4 or ULID recommended, max 255 characters). Re-submitting the same key with the same request returns the cached response without re-executing side effects. The server retains the key for at least 24 hours. schema: type: string maxLength: 255 - name: dryRun in: query required: false description: | If `true`, validates and simulates the operation without committing changes. The response shape is identical to a real execution. schema: type: boolean default: false requestBody: required: false content: application/json: schema: type: object responses: "200": description: OK - Invite cancelled. content: application/json: schema: $ref: "#/components/schemas/CancelInviteResponse" "400": $ref: "#/components/responses/400" "401": $ref: "#/components/responses/401" "403": $ref: "#/components/responses/403" "404": $ref: "#/components/responses/404" "409": description: Conflict - Invite already cancelled. content: application/json: schema: $ref: "#/components/schemas/Error" "500": $ref: "#/components/responses/500" /iam/v1/roles: get: tags: - Roles summary: List roles description: Returns a list of roles. operationId: listRoles responses: "200": description: OK - List of roles returned. content: application/json: schema: type: object properties: roles: type: array items: $ref: "#/components/schemas/Role" "400": $ref: "#/components/responses/400" "401": $ref: "#/components/responses/401" "403": $ref: "#/components/responses/403" "500": $ref: "#/components/responses/500" /iam/v1/organizations: get: tags: - Organizations summary: List organizations description: Returns a list of organizations. operationId: listOrganizations responses: "200": description: OK - List of organizations returned. content: application/json: schema: type: object properties: organizations: type: array items: $ref: "#/components/schemas/Organization" rowCount: type: integer description: Organizations row count format: int64 "400": $ref: "#/components/responses/400" "401": $ref: "#/components/responses/401" "403": $ref: "#/components/responses/403" "500": $ref: "#/components/responses/500" /support/v1/metadata/platforms: get: tags: - Platforms summary: List available platforms description: Returns a list of all the available platforms. operationId: listPlatforms responses: "200": description: OK - List of available platforms returned. content: application/json: schema: type: object properties: platforms: type: array items: $ref: "#/components/schemas/PlatformAPI" "400": $ref: "#/components/responses/400" "401": $ref: "#/components/responses/401" "403": $ref: "#/components/responses/403" /support/v1/metadata/products: get: tags: - Products summary: List available products description: Returns a list of all the available products of specific platforms. operationId: listProducts parameters: - name: platform in: query schema: type: string responses: "200": description: OK - List of available products returned. content: application/json: schema: type: object properties: products: type: array items: $ref: "#/components/schemas/ProductAPI" "400": $ref: "#/components/responses/400" "401": $ref: "#/components/responses/401" "403": $ref: "#/components/responses/403" /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:[]`. 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 /support/v1/tickets: get: tags: - Support Requests summary: List requests description: |- Returns a list of all historical requests that your account has access to. Tickets are returned in reverse chronological order by default. operationId: idOfTickets x-cli-name: list-tickets x-cli-aliases: - id-of-tickets 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: minimum: 1 maximum: 100 type: integer format: int64 default: 100 - $ref: "#/components/parameters/pageToken" - name: filter in: query description: | An expression for filtering the results of the request. The syntax is `key:[]`. e.g: "severity:normal". 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 - name: minCreationTime in: query description: Min value for tickets creation time, in milliseconds since the POSIX epoch. If set, only tickets created after or at this timestamp are returned. schema: type: string - name: maxCreationTime in: query description: Max value for tickets creation time, in milliseconds since the POSIX epoch. If set, only tickets created before or at this timestamp are returned. schema: type: string responses: "200": description: OK - List of historical requests returned. content: application/json: schema: $ref: "#/components/schemas/TicketsList" "400": $ref: "#/components/responses/400" "401": $ref: "#/components/responses/401" "403": $ref: "#/components/responses/403" "404": $ref: "#/components/responses/404" "502": $ref: "#/components/responses/502" "503": $ref: "#/components/responses/503" post: tags: - Support Requests summary: Create a request description: Creates a new support request operationId: idOfTicketsPost x-cli-name: create-ticket x-cli-aliases: - id-of-tickets-post requestBody: content: application/json: schema: $ref: "#/components/schemas/TicketCreateFormExtAPI" required: true responses: "201": description: Created - New support request created. content: application/json: schema: $ref: "#/components/schemas/TicketResponseExtAPI" "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 /support/v1/tickets/{ticketId}: get: tags: - Support Requests summary: Get a request description: Returns the details of a single support request by its ID. operationId: idOfTicketGet x-cli-name: get-ticket x-cli-aliases: - id-of-ticket-get parameters: - name: ticketId in: path required: true description: The unique identifier of the support request. schema: type: integer format: int64 responses: "200": description: OK - Support request details returned. content: application/json: schema: $ref: "#/components/schemas/TicketDetailExtAPI" "400": $ref: "#/components/responses/400" "401": $ref: "#/components/responses/401" "403": $ref: "#/components/responses/403" "404": $ref: "#/components/responses/404" "502": $ref: "#/components/responses/502" "503": $ref: "#/components/responses/503" patch: tags: - Support Requests summary: Update a request description: |- Partially updates a support request. Supports setting the request `status` and/or `assignee`. DoiT employees may set any of `open`, `pending`, `hold`, or `solved` and may set the `assignee`; customers may set only `solved` (parity with the console "mark as resolved" action) and may not set an assignee. `closed` is not settable via the API (Zendesk auto-closes from `solved`). The `assignee` is a DoiT-employee email, resolved server-side to a Zendesk agent; an email that does not resolve to an active agent returns `400`. At least one mutable field must be present. The response echoes the fields that were applied. operationId: idOfTicketUpdate x-cli-name: update-ticket x-cli-aliases: - id-of-ticket-update parameters: - name: ticketId in: path required: true description: The unique identifier of the support request. schema: type: integer format: int64 requestBody: required: true content: application/json: schema: type: object minProperties: 1 properties: status: type: string description: The status to set on the request. enum: - open - pending - hold - solved assignee: type: string format: email description: |- Email of the DoiT employee to assign the request to, resolved to a Zendesk agent. DoiT employees only. responses: "200": description: OK - Request updated. Echoes the fields that were applied. content: application/json: schema: type: object properties: id: type: integer format: int64 status: type: string assignee: type: string "400": $ref: "#/components/responses/400" "401": $ref: "#/components/responses/401" "403": $ref: "#/components/responses/403" "404": $ref: "#/components/responses/404" /support/v1/tickets/{ticketId}/comments: get: tags: - Support Requests summary: List request comments description: |- Returns all comments on a support request. For customers, only public comments are returned. For DoiT employees, both public and private comments are returned. All comments are returned in a single response (no pagination). operationId: idOfTicketCommentsList x-cli-name: list-ticket-comments x-cli-aliases: - id-of-ticket-comments-list parameters: - name: ticketId in: path required: true description: The unique identifier of the support request. schema: type: integer format: int64 responses: "200": description: OK - List of comments returned. content: application/json: schema: $ref: "#/components/schemas/CommentsResponseExtAPI" "401": $ref: "#/components/responses/401" "403": $ref: "#/components/responses/403" "404": $ref: "#/components/responses/404" "502": $ref: "#/components/responses/502" "503": $ref: "#/components/responses/503" post: tags: - Support Requests summary: Add a comment description: |- Adds a comment to an existing support request. For customers, comments are always public. For DoiT employees, comments can be marked as private (internal notes) by setting the `private` field to `true`. operationId: idOfTicketCommentsPost x-cli-name: create-ticket-comment x-cli-aliases: - id-of-ticket-comments-post parameters: - name: ticketId in: path required: true description: The unique identifier of the support request. schema: type: integer format: int64 requestBody: required: true content: application/json: schema: $ref: "#/components/schemas/CreateCommentRequest" responses: "201": description: Created - Comment added to the support request. content: application/json: schema: $ref: "#/components/schemas/CommentExtAPI" "400": $ref: "#/components/responses/400" "401": $ref: "#/components/responses/401" "403": $ref: "#/components/responses/403" "404": $ref: "#/components/responses/404" /support/v1/tickets/{ticketId}/tags: get: tags: - Support Requests summary: List tags on a support request description: |- Returns the tags currently set on a support request. DoiT employee (doer) callers receive the full tag set verbatim, including internal namespaces (e.g. `tier/*`, `synapse_*`). Customer callers receive only tags under the `customer_tag/` namespace, with that prefix stripped (e.g. a tag added as `billing` reads back as `billing`). Always present; empty array when the caller has no visible tags. operationId: listTicketTags parameters: - name: ticketId in: path required: true description: The unique identifier of the support request. schema: type: integer format: int64 responses: "200": description: OK content: application/json: schema: $ref: "#/components/schemas/TagsGetResponse" "400": $ref: "#/components/responses/400" "401": $ref: "#/components/responses/401" "403": $ref: "#/components/responses/403" "404": $ref: "#/components/responses/404" post: tags: - Support Requests summary: Add tags to a support request description: |- Adds one or more tags to an existing support request. The operation is surgical — only the tags listed in the request are added; existing tags on the ticket are preserved. Re-adding a tag that is already present is a successful no-op. All submitted tags are normalized (trim + lowercase) before storage. For customers, the system additionally applies a `customer_tag/` namespace prefix to prevent collisions with internal DoiT process tags. The response echoes the actual stored strings so callers can verify the transform. operationId: idOfTicketTagsAdd x-cli-name: add-ticket-tags x-cli-aliases: - id-of-ticket-tags-add parameters: - name: ticketId in: path required: true description: The unique identifier of the support request. schema: type: integer format: int64 requestBody: required: true content: application/json: schema: $ref: "#/components/schemas/TagsRequest" responses: "200": description: OK - Tags added (or already present). content: application/json: schema: $ref: "#/components/schemas/TagsResponse" "400": $ref: "#/components/responses/400" "401": $ref: "#/components/responses/401" "403": $ref: "#/components/responses/403" "404": $ref: "#/components/responses/404" delete: tags: - Support Requests summary: Remove tags from a support request description: |- Removes one or more tags from an existing support request. The operation is surgical — only the tags listed in the request are removed; tags not listed are preserved. Removing a tag that is not present is a successful no-op. For customers, the system applies the same `customer_tag/` namespace mapping as on add, so a customer who added `my_tag` (stored as `customer_tag/my_tag`) can remove it by sending `my_tag`. operationId: idOfTicketTagsRemove x-cli-name: remove-ticket-tags x-cli-aliases: - id-of-ticket-tags-remove parameters: - name: ticketId in: path required: true description: The unique identifier of the support request. schema: type: integer format: int64 requestBody: required: true content: application/json: schema: $ref: "#/components/schemas/TagsRequest" responses: "200": description: OK - Tags removed (or already absent). content: application/json: schema: $ref: "#/components/schemas/TagsResponse" "400": $ref: "#/components/responses/400" "401": $ref: "#/components/responses/401" "403": $ref: "#/components/responses/403" "404": $ref: "#/components/responses/404" /clouddiagrams/v1/scheme/find: post: tags: - Cloud Diagrams summary: Find diagrams description: Returns diagram URLs matching the provided resource IDs. operationId: findCloudDiagrams requestBody: required: true content: application/json: schema: $ref: "#/components/schemas/FindCloudDiagramsRequest" responses: "200": description: OK - Diagram URLs matching the criteria returned. content: application/json: schema: $ref: "#/components/schemas/FindCloudDiagramsResponse" "400": $ref: "#/components/responses/400" "401": $ref: "#/components/responses/401" "403": $ref: "#/components/responses/403" /clouddiagrams/v1/scheme/stats: get: tags: - Cloud Diagrams summary: Get diagrams with stats description: Returns a list of all diagrams with activity stats for the given time period. operationId: getCloudDiagramsStats parameters: - name: start in: query required: true description: Start of the period. example: "2026-04-01T00:00:00Z" schema: type: string format: date-time - name: end in: query required: true description: End of the period. example: "2026-04-28T00:00:00Z" schema: type: string format: date-time responses: "200": description: OK - List of diagrams with stats returned. content: application/json: schema: type: array items: $ref: "#/components/schemas/CloudDiagramStats" "400": $ref: "#/components/responses/400" "401": $ref: "#/components/responses/401" "403": $ref: "#/components/responses/403" /clouddiagrams/v1/scheme/get: post: tags: - Cloud Diagrams summary: Get diagram components description: |- Returns diagram and layer data. When the request body is empty, returns all diagrams the caller has access to. When the body is populated, returns full diagram data including layer components projected to key display and cloud fields. operationId: getCloudDiagramComponents parameters: - name: components in: query description: Include components in the layer response. schema: type: boolean - name: external in: query description: Include external (cross-diagram) components. schema: type: boolean - name: element in: query description: Include elements. schema: type: boolean - name: link in: query description: Include links. schema: type: boolean - name: group in: query description: Include groups. schema: type: boolean - name: note in: query description: Include notes. schema: type: boolean - name: combiner in: query description: Include combiners. schema: type: boolean - name: type in: query description: Filter diagrams by type. schema: type: array items: type: string enum: - application - infrastructure - network - template - name: node_type in: query description: Filter components by node type. schema: type: string enum: - app_component - app_group - app_link - attachment - group - host - link - service - name: alarms_count in: query description: Include alarm counts (default true). schema: type: boolean - name: issues_count in: query description: Include issue counts. schema: type: boolean - name: skip_empty in: query description: Omit diagrams that have no components. schema: type: boolean - name: exclude_default_vpc in: query description: Exclude the default VPC group (default true). schema: type: boolean - name: exclude_empty_subnets in: query description: Exclude empty subnet groups (default true). schema: type: boolean requestBody: required: false content: application/json: schema: $ref: "#/components/schemas/CloudDiagramsGetRequest" responses: "200": description: OK - Diagram and component data returned. content: application/json: schema: $ref: "#/components/schemas/CloudDiagramsGetResponse" "400": $ref: "#/components/responses/400" "401": $ref: "#/components/responses/401" "403": $ref: "#/components/responses/403" /clouddiagrams/v1/scheme/search: post: tags: - Cloud Diagrams summary: Search diagrams and components description: |- Full-text search across diagram layers, components by name, and components by property values. Returns three result categories: diagram (matching layers), component (matching components by name), and prop (matching components by property values). operationId: searchCloudDiagrams requestBody: required: true content: application/json: schema: $ref: "#/components/schemas/CloudDiagramsSearchRequest" responses: "200": description: OK - Search results returned. content: application/json: schema: $ref: "#/components/schemas/CloudDiagramsSearchResponse" "400": $ref: "#/components/responses/400" "401": $ref: "#/components/responses/401" "403": $ref: "#/components/responses/403" /clouddiagrams/v1/statussheet/{id}/get: post: tags: - Cloud Diagrams summary: Get layer components description: |- Returns the specified components of a diagram layer. Provide at least one component type with one or more IDs in the request body (for example, `node` or `element`). operationId: getStatussheetComponents parameters: - name: id in: path required: true description: Layer ID. schema: type: string - name: p in: query description: Space-separated projection fields for component documents. schema: type: string requestBody: required: true content: application/json: schema: $ref: "#/components/schemas/CloudDiagramStatussheetGetRequest" responses: "200": description: OK - Layer components returned. content: application/json: schema: $ref: "#/components/schemas/CloudDiagramStatussheetComponents" "400": $ref: "#/components/responses/400" "401": $ref: "#/components/responses/401" "403": $ref: "#/components/responses/403_resource_or_forbidden" /clouddiagrams/v1/statussheet/{id}/export-json: get: tags: - Cloud Diagrams summary: Export diagram as JSON description: |- Exports the full content of a diagram layer as a structured JSON document, including all components and export metadata. operationId: exportCloudDiagramJson parameters: - name: id in: path required: true description: Layer ID. schema: type: string responses: "200": description: OK - Diagram exported as JSON. content: application/json: schema: $ref: "#/components/schemas/CloudDiagramExportJsonResponse" "400": $ref: "#/components/responses/400" "401": $ref: "#/components/responses/401" "403": $ref: "#/components/responses/403_resource_or_forbidden" /clouddiagrams/v1/statussheet/{id}/costs: get: tags: - Cloud Diagrams summary: Get diagram cost snapshot description: |- Returns a bounded cost snapshot for the specified diagram layer over a date window. The response composes the diagram's total spend, period-over-period change, top resources by cost (capped at 5), top services by cost (capped at 5), and a trend series (most recent 12 buckets at the requested interval). operationId: getCloudDiagramCostSnapshot parameters: - name: id in: path required: true description: Layer ID. schema: type: string - name: startDate in: query required: true description: Inclusive start of the cost window (ISO date, e.g. `2026-04-01`). schema: type: string format: date - name: endDate in: query required: true description: Inclusive end of the cost window (ISO date, e.g. `2026-04-28`). schema: type: string format: date - name: interval in: query required: false description: Bucket interval for the trend series. Defaults to `day` when omitted. schema: type: string enum: - day - week - month responses: "200": description: OK - Diagram cost snapshot returned. content: application/json: schema: $ref: "#/components/schemas/CloudDiagramCostSnapshot" "400": $ref: "#/components/responses/400" "401": $ref: "#/components/responses/401" "403": $ref: "#/components/responses/403_resource_or_forbidden" /clouddiagrams/v1/statussheet/{id}/snapshots: get: tags: - Cloud Diagrams summary: List layer snapshots description: Returns the list of saved snapshots for the specified diagram layer. operationId: listCloudDiagramLayerSnapshots parameters: - name: id in: path required: true description: Layer ID. schema: type: string - name: offset in: query description: Number of snapshots to skip (default 0). schema: type: integer minimum: 0 - name: limit in: query description: Maximum number of snapshots to return (default 10). schema: type: integer minimum: 1 - name: sort in: query description: Sort expression (e.g. "-createdAt" for descending). schema: type: string responses: "200": description: OK - Snapshots returned. content: application/json: schema: type: array items: $ref: "#/components/schemas/CloudDiagramLayerSnapshot" "400": $ref: "#/components/responses/400" "401": $ref: "#/components/responses/401" "403": $ref: "#/components/responses/403_resource_or_forbidden" /clouddiagrams/v1/statussheet/{id}/snapshot: get: tags: - Cloud Diagrams summary: Get a layer snapshot description: Returns a single snapshot of the specified diagram layer identified by its ID. operationId: getCloudDiagramLayerSnapshot parameters: - name: id in: path required: true description: Layer ID. schema: type: string - name: snapshot_id in: query required: true description: Snapshot ID. schema: type: string responses: "200": description: OK - Snapshot returned. content: application/json: schema: $ref: "#/components/schemas/CloudDiagramLayerSnapshot" "400": $ref: "#/components/responses/400" "401": $ref: "#/components/responses/401" "403": $ref: "#/components/responses/403_resource_or_forbidden" /clouddiagrams/v1/statussheet/{id}/resources/{rid}/relationships: get: tags: - Cloud Diagrams summary: Get resource relationships description: |- Walks the diagram graph from the anchor resource and returns related resources. Edge traversal walks the diagram's link set (same-scheme guard, BFS, cycle-safe); group traversal walks the group membership set. The result list is capped at 200 relations; `truncated` is `true` when the cap is hit. Read-only: does not mutate diagram state. operationId: getCloudDiagramResourceRelationships parameters: - name: id in: path required: true description: Diagram (layer) ID. schema: type: string - name: rid in: path required: true description: Anchor resource ID — must exist as a node, element, or group on the diagram. schema: type: string - name: direction in: query description: Edge direction relative to the anchor. `both` returns upstream and downstream neighbours. Defaults to `both`. schema: type: string enum: - downstream - upstream - both default: both - name: depth in: query description: |- `direct` returns one-hop neighbours; `transitive` runs a cycle-safe BFS to the connected component (still capped at 200 relations). Defaults to `direct`. schema: type: string enum: - direct - transitive default: direct - name: kind in: query description: |- `edges` walks the link graph; `group_members` walks group membership (children and parent groups); `both` merges the two and dedupes by id, preserving the smallest observed hop count. Defaults to `edges`. schema: type: string enum: - edges - group_members - both default: edges responses: "200": description: OK - Related resources returned. content: application/json: schema: $ref: "#/components/schemas/DiagramRelationshipsResponse" "400": $ref: "#/components/responses/400" "401": $ref: "#/components/responses/401" "403": $ref: "#/components/responses/403_resource_or_forbidden" "404": $ref: "#/components/responses/404" /clouddiagrams/v1/activity: get: tags: - Cloud Diagrams summary: List activity groups for a layer description: |- Returns snapshot activity groups for the specified diagram layer, ordered by timestamp descending. Each group contains a snapshot reference and the individual activity records that belong to it. operationId: listCloudDiagramActivityGroups parameters: - name: ss_id in: query required: true description: Layer ID. schema: type: string - name: limit in: query description: Maximum number of groups to return (default 10). schema: type: integer minimum: 1 - name: offset in: query description: Number of groups to skip (default 0). schema: type: integer minimum: 0 - name: tags in: query description: Filter by tags. schema: type: array items: type: string responses: "200": description: OK - Activity groups returned. content: application/json: schema: type: array items: $ref: "#/components/schemas/CloudDiagramSnapshotActivityGroup" "400": $ref: "#/components/responses/400" "401": $ref: "#/components/responses/401" "403": $ref: "#/components/responses/403" /clouddiagrams/v1/activity/node-activities: get: tags: - Cloud Diagrams summary: List node activities description: Returns individual activity records for the specified component node, ordered by timestamp descending. operationId: listCloudDiagramNodeActivities parameters: - name: ss_id in: query required: true description: Layer ID. schema: type: string - name: nodeId in: query required: true description: Node component ID. schema: type: string - name: limit in: query description: Maximum number of records to return (default 50). schema: type: integer minimum: 1 - name: offset in: query description: Number of records to skip (default 0). schema: type: integer minimum: 0 responses: "200": description: OK - Node activity records returned. content: application/json: schema: type: array items: $ref: "#/components/schemas/CloudDiagramNodeActivity" "400": $ref: "#/components/responses/400" "401": $ref: "#/components/responses/401" "403": $ref: "#/components/responses/403" /analytics/v1/commitment-manager: get: tags: - Commitment Manager summary: List commitments description: |- Returns a list of commitments for the customer. Commitments are listed in reverse chronological order by default. operationId: listCommitments parameters: - name: sortBy in: query description: A field by which the results will be sorted. schema: type: string enum: - name - startDate - endDate - provider - createTime - updateTime - $ref: "#/components/parameters/sortOrder" - $ref: "#/components/parameters/maxResults" - $ref: "#/components/parameters/pageToken" - name: filter in: query description: >- An expression for filtering the results. The syntax is `key:[]`. Multiple filters can be connected using a pipe |. See [Filters](https://developer.doit.com/docs/filters). Available filter keys: **name**, **provider** example: "provider:google-cloud" schema: type: string responses: "200": description: >- OK - The request succeeded. content: application/json: schema: $ref: "#/components/schemas/CommitmentExternalList" "400": $ref: "#/components/responses/400" "401": $ref: "#/components/responses/401" "403": $ref: "#/components/responses/403" "500": $ref: "#/components/responses/500" "/analytics/v1/commitment-manager/{id}": get: tags: - Commitment Manager summary: Retrieve a commitment description: Returns a commitment by the specified Id. operationId: getCommitment parameters: - name: id in: path description: Commitment ID required: true schema: type: string responses: "200": description: >- OK - Commitment returned. content: application/json: schema: $ref: "#/components/schemas/CommitmentExternal" "400": $ref: "#/components/responses/400" "401": $ref: "#/components/responses/401" "403": $ref: "#/components/responses/403" "404": $ref: "#/components/responses/404" /ava/v1/ask: post: tags: - Ava summary: Ask Ava (streaming) description: |- Send a question to Ava and receive a streaming response via Server-Sent Events (SSE). The response streams back events containing the answer text, conversation ID, and message metadata. operationId: askAvaStreaming requestBody: required: true content: application/json: schema: $ref: "#/components/schemas/AvaAskRequest" responses: "200": description: OK - SSE stream of Ava response events. content: text/event-stream: schema: type: string "400": $ref: "#/components/responses/400" "401": $ref: "#/components/responses/401" "403": $ref: "#/components/responses/403" "500": $ref: "#/components/responses/500" /ava/v1/askSync: post: tags: - Ava summary: Ask Ava description: |- Send a question to Ava and receive a synchronous response. Set `ephemeral` to `true` to skip conversation persistence (recommended for programmatic consumers). When `ephemeral` is `false` (default), the response includes a `conversationId` that can be used with the delete endpoint. operationId: askAvaSync requestBody: required: true content: application/json: schema: $ref: "#/components/schemas/AvaAskSyncRequest" responses: "200": description: OK - Ava response returned. content: application/json: schema: $ref: "#/components/schemas/AvaAskSyncResponse" "400": $ref: "#/components/responses/400" "401": $ref: "#/components/responses/401" "403": $ref: "#/components/responses/403" "500": $ref: "#/components/responses/500" /ava/v1/feedback: post: tags: - Ava summary: Submit feedback description: Submit feedback on an Ava answer to help improve response quality. operationId: avaFeedback requestBody: required: true content: application/json: schema: $ref: "#/components/schemas/AvaFeedbackRequest" responses: "200": description: OK - Feedback submitted. "400": $ref: "#/components/responses/400" "401": $ref: "#/components/responses/401" "403": $ref: "#/components/responses/403" "500": $ref: "#/components/responses/500" /ava/v1/deleteConversation: delete: tags: - Ava summary: Delete a conversation description: Deletes an Ava conversation by its ID. operationId: deleteAvaConversation parameters: - name: conversationId in: query description: The ID of the conversation to delete. required: true schema: type: string responses: "200": description: OK - Conversation deleted. "400": $ref: "#/components/responses/400" "401": $ref: "#/components/responses/401" "403": $ref: "#/components/responses/403" "500": $ref: "#/components/responses/500" /insights/v1/results: get: tags: - Insights summary: List insights description: | Returns a paginated list of insights with their aggregate summaries (savings, risk counts). Use query parameters to filter by status, category, provider, or priority. Does not include individual resource-level results — use the resource-results endpoint for those. operationId: getInsightResults parameters: - in: query name: searchTerm description: Free-text search term to filter insights by title or description. schema: type: string required: false - in: query name: displayStatus description: Filter by one or more display statuses. schema: type: array items: type: string enum: ["actionable", "acknowledged", "in progress", "optimized", "dismissed"] required: false - in: query name: category description: Filter by insight category. schema: type: string enum: ["FinOps", "OperationalExcellence", "PerformanceEfficiency", "Reliability", "Security", "Sustainability"] required: false - in: query name: cloudProvider description: Filter by cloud provider (e.g. "aws", "gcp", "azure"). schema: $ref: "#/components/schemas/CloudProvider" required: false - in: query name: source description: the source that generated insights schema: type: array items: $ref: "#/components/schemas/Source" required: false - in: query name: priority description: Filter by one or more priority levels. schema: type: array items: type: string enum: ["Low", "Medium", "High"] required: false - in: query name: tag description: Filter by one or more tags (e.g. security certification labels like "ISO"). schema: type: array items: type: string required: false - in: query name: easyWin description: When true, return only insights flagged as easy wins. schema: type: boolean required: false - in: query name: cloudFlows description: When true, return only insights that have associated CloudFlow automations. schema: type: boolean required: false - in: query name: pageToken description: Token from a previous response to fetch the next page. schema: type: string required: false - in: query name: maxResults description: Maximum number of results per page (default 50, max 500). schema: type: integer minimum: 1 maximum: 500 default: 50 required: false responses: "200": description: Successful operation content: application/json: schema: $ref: "#/components/schemas/ResultsBody" "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" post: tags: - Insights summary: Create insights (batch) description: | Creates or updates multiple insights in a single batch request. Each insight in the batch includes its metadata and resource results inline. For granular control over insight metadata and resource results independently, use the single-insight and resource-results endpoints instead. operationId: postInsightResults requestBody: content: application/json: schema: $ref: "#/components/schemas/CreateResultsBody" responses: "200": description: Successful operation content: application/json: schema: type: array items: $ref: "#/components/schemas/ResultsError" "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" delete: tags: - Insights summary: Delete insights (batch) description: | Deletes all insights matching the specified key from the batch source. This removes the insight and all its associated resource results. For single-insight deletion, use `DELETE /source/{sourceID}/insight/{insightKey}` instead. operationId: deleteInsightResults parameters: - in: query name: insightKey description: The unique key identifying the insight to delete. schema: type: string required: true responses: "204": description: No content "401": $ref: "#/components/responses/401" "403": $ref: "#/components/responses/403" "500": $ref: "#/components/responses/500" /insights/v1/results/source/{sourceID}/insight/{insightKey}: get: tags: - Insights summary: Retrieve an insight description: | Returns the metadata and aggregate summary for a single insight identified by source and key. Does not include individual resource-level results — use the resource-results endpoint for those. operationId: getInsightResult parameters: - in: path name: sourceID description: The identifier of the source that generated the insight. required: true schema: type: string - in: path name: insightKey description: The unique key identifying the insight. required: true schema: type: string responses: "200": description: Successful operation content: application/json: schema: $ref: "#/components/schemas/InsightResponse" "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" post: tags: - Insights summary: Create or update an insight description: | Creates or updates a single insight for the given source and key. If an insight with the same key already exists for the source, it will be updated. Resource results are managed separately via the resource-results endpoint. operationId: postInsightResult parameters: - in: path name: sourceID description: Only insights created via the public API can be managed. Currently only "public-api" is supported. required: true schema: type: string enum: - public-api - in: path name: insightKey description: The unique key identifying the insight. required: true schema: type: string requestBody: required: true content: application/json: schema: $ref: "#/components/schemas/InsightMetadataRequest" responses: "200": description: Successful operation content: application/json: schema: $ref: "#/components/schemas/InsightResponse" "400": $ref: "#/components/responses/400" "401": $ref: "#/components/responses/401" "403": $ref: "#/components/responses/403" "500": $ref: "#/components/responses/500" delete: tags: - Insights summary: Delete an insight description: | Permanently deletes a single insight and all its associated resource results. Only insights created via the public API can be deleted. operationId: deleteInsightResult parameters: - in: path name: sourceID description: Only insights created via the public API can be managed. Currently only "public-api" is supported. required: true schema: type: string enum: - public-api - in: path name: insightKey description: The unique key identifying the insight to delete. required: true schema: type: string responses: "204": description: No content "401": $ref: "#/components/responses/401" "403": $ref: "#/components/responses/403" "500": $ref: "#/components/responses/500" /insights/v1/results/source/{sourceID}/insight/{insightKey}/status: put: tags: - Insights summary: Update Insight Status description: | Updates the display status (e.g. actionable, acknowledged, dismissed) of a single insight. Only insights created via the public API can have their status changed. Deprecated: use the status field on the create/update insight endpoint instead. deprecated: true operationId: updateInsightStatus parameters: - in: path name: sourceID description: Only insights created via the public API can be managed. Currently only "public-api" is supported. required: true schema: type: string enum: - public-api - in: path name: insightKey description: The unique key identifying the insight to update. required: true schema: type: string requestBody: required: true content: application/json: schema: $ref: "#/components/schemas/UpdateStatusRequest" responses: "204": description: Status updated successfully "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" /insights/v1/results/source/{sourceID}/insight/{insightKey}/resource-results: get: tags: - Insights summary: List resource results for an insight description: | Returns a paginated list of individual resource-level results for a specific insight. Each resource result represents a single cloud resource (e.g. an EC2 instance, a GCS bucket) affected by the insight, along with its risk scores or potential savings. operationId: getInsightResourceResults parameters: - in: path name: sourceID description: The identifier of the source that generated the insight. required: true schema: type: string - in: path name: insightKey description: The unique key identifying the insight. required: true schema: type: string - in: query name: pageToken description: Token from a previous response to fetch the next page. schema: type: string required: false - in: query name: maxResults description: Maximum number of results per page (default 1000, max 5000). schema: type: integer minimum: 1 maximum: 5000 default: 1000 required: false responses: "200": description: Successful operation content: application/json: schema: $ref: "#/components/schemas/ResourceResultsResponse" "400": $ref: "#/components/responses/400" "401": $ref: "#/components/responses/401" "403": $ref: "#/components/responses/403" "404": $ref: "#/components/responses/404" post: tags: - Insights summary: Replace resource results for an insight description: > Replaces all resource results for the specified insight. Any existing unresolved resource results not present in the new set will be removed. The response includes server-computed fields (severity, resolved, enhancement) for each resource result. To delete all resource results, send an empty array. operationId: postInsightResourceResults parameters: - in: path name: sourceID description: Only insights created via the public API can be managed. Currently only "public-api" is supported. required: true schema: type: string enum: - public-api - in: path name: insightKey description: The unique key identifying the insight. required: true schema: type: string - in: query name: maxResults description: Maximum number of results per page in the response (default 1000, max 5000). schema: type: integer minimum: 1 maximum: 5000 default: 1000 required: false requestBody: required: true content: application/json: schema: $ref: "#/components/schemas/CreateResourceResultsBody" responses: "200": description: Resource results created/replaced successfully content: application/json: schema: $ref: "#/components/schemas/ResourceResultsResponse" "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" "/core/v1/cloudconnect/supportedFeatures/{accountID}": get: tags: - Cloud Connect summary: Get supported features for a connected account description: |- Returns the list of supported features and their permission status for a cloud account connected via CloudConnect. The account must belong to the authenticated customer. Supports AWS and Azure accounts. operationId: getCloudConnectSupportedFeatures parameters: - name: accountID in: path description: The cloud provider account ID (AWS account ID or Azure tenant ID). required: true schema: type: string responses: "200": description: OK - Supported features returned. content: application/json: schema: $ref: "#/components/schemas/SupportedFeaturesResponse" "400": $ref: "#/components/responses/400" "401": $ref: "#/components/responses/401" "403": $ref: "#/components/responses/403" "404": description: Not Found - No CloudConnect document found for this account. content: application/json: schema: $ref: "#/components/schemas/Error" "500": $ref: "#/components/responses/500" /core/v1/cloudconnect/aws/accounts: post: tags: - Cloud Connect summary: Create or update an AWS account role description: |- Creates or updates a CloudConnect document for an AWS account. Unlike the CloudFormation variant, this endpoint does not update Firestore channel documents or require a CloudFormation stack ID. operationId: createAccountRole requestBody: required: true content: application/json: schema: type: object required: - accountID - roleArn - enabledFeatures properties: accountID: type: string description: The AWS account ID. example: "123456789012" roleArn: type: string description: The ARN of the IAM role created for DoiT access. example: "arn:aws:iam::123456789012:role/DoiTRole" s3Bucket: type: string description: S3 bucket name for CloudTrail real-time anomaly detection. Required together with s3BucketRegion. s3BucketRegion: type: string description: AWS region of the S3 bucket. Required together with s3Bucket. example: "us-east-1" enabledFeatures: type: array items: type: string description: Declares which supported AWS features the caller intends to enable. Values must match feature names configured in awsFeaturePermissions on app/cloud-connect. The value is persisted and returned in account responses. When "real-time-data" is included, s3Bucket and s3BucketRegion are required; when it is not included, s3Bucket and s3BucketRegion are not allowed. example: ["real-time-data"] responses: "200": description: OK - Role created/updated successfully. content: application/json: schema: $ref: "#/components/schemas/AwsAccountResponse" "400": $ref: "#/components/responses/400" "401": $ref: "#/components/responses/401" "403": $ref: "#/components/responses/403" "409": description: Conflict - Account already exists. content: application/json: schema: $ref: "#/components/schemas/Error" "500": $ref: "#/components/responses/500" /core/v1/cloudconnect/aws/accounts/{accountID}: parameters: - name: accountID in: path required: true schema: type: string description: The AWS account ID. example: "123456789012" get: tags: - Cloud Connect summary: Get an AWS account description: Returns the current state of an AWS account including role, supported features, and optional S3 bucket configuration. operationId: getAwsAccount responses: "200": description: OK - Account details returned successfully. content: application/json: schema: $ref: "#/components/schemas/AwsAccountResponse" "400": $ref: "#/components/responses/400" "401": $ref: "#/components/responses/401" "403": $ref: "#/components/responses/403" "404": description: Not Found - No CloudConnect document found for this account. content: application/json: schema: $ref: "#/components/schemas/Error" "500": $ref: "#/components/responses/500" delete: tags: - Cloud Connect summary: Delete an AWS account role description: Deletes a CloudConnect document for an AWS account. operationId: deleteAccountRole responses: "200": description: OK - Role deleted successfully. "400": $ref: "#/components/responses/400" "401": $ref: "#/components/responses/401" "403": $ref: "#/components/responses/403" "500": $ref: "#/components/responses/500" put: tags: - Cloud Connect summary: Update an AWS feature description: |- Updates an AWS feature for an existing CloudConnect account. Unlike the CloudFormation variant, this endpoint does not update Firestore channel documents, require a CloudFormation stack ID, or handle StackSet member role ARNs. operationId: updateAwsFeature requestBody: required: true content: application/json: schema: type: object required: - enabledFeatures properties: s3Bucket: type: string description: S3 bucket name for CloudTrail real-time anomaly detection. Required together with s3BucketRegion. s3BucketRegion: type: string description: AWS region of the S3 bucket. Required together with s3Bucket. example: "us-east-1" enabledFeatures: type: array items: type: string description: Declares which supported AWS features the caller intends to enable. Values must match feature names configured in awsFeaturePermissions on app/cloud-connect. The value is persisted and returned in account responses. When "real-time-data" is included, s3Bucket and s3BucketRegion are required; when it is not included, s3Bucket and s3BucketRegion are not allowed. example: ["real-time-data"] responses: "200": description: OK - Feature updated successfully. content: application/json: schema: $ref: "#/components/schemas/AwsAccountResponse" "400": $ref: "#/components/responses/400" "401": $ref: "#/components/responses/401" "403": $ref: "#/components/responses/403" "500": $ref: "#/components/responses/500" # ============================================================ # CloudFlows # ============================================================ /cloudflow/v1/flows: get: tags: - CloudFlow summary: List CloudFlows description: Returns a cursor-paginated list of CloudFlows. operationId: listCloudflows parameters: - name: maxResults in: query description: Maximum number of flows to return (1–500). Defaults to 50. schema: type: integer minimum: 1 maximum: 500 default: 50 - name: pageToken in: query description: Opaque cursor for the next page, taken from `pageToken` in the previous response. Omit to start from the beginning. schema: type: string responses: "200": description: Paginated list of CloudFlows. content: application/json: schema: $ref: "#/components/schemas/CloudflowListResponse" "400": $ref: "#/components/responses/400" "401": $ref: "#/components/responses/401" "403": $ref: "#/components/responses/403" "500": $ref: "#/components/responses/500" # ============================================================ # CloudFlow Connections # ============================================================ /cloudflow/v1/connections: get: tags: - Connections summary: List connections description: Returns a cursor-paginated list of cloud provider connections for the authenticated tenant. operationId: listCloudflowConnections parameters: - name: maxResults in: query description: Maximum number of connections to return (1–100). Defaults to 50. schema: type: integer minimum: 1 maximum: 100 default: 50 - name: pageToken in: query description: Pagination cursor returned by a previous call. schema: type: string responses: "200": description: OK content: application/json: schema: $ref: "#/components/schemas/CloudflowConnectionListResponse" "400": $ref: "#/components/responses/400" "401": $ref: "#/components/responses/401" "403": $ref: "#/components/responses/403" "500": $ref: "#/components/responses/500" post: tags: - Connections summary: Create a connection description: |- Creates a new cloud provider connection. Exactly one of `gcpConfig` or `awsConfig` must be supplied. Returns `400 invalid_connection_config` when both or neither are present. operationId: createCloudflowConnection requestBody: required: true content: application/json: schema: type: object required: - name properties: name: type: string description: Human-readable connection name. description: type: string description: Optional description. gcpConfig: $ref: "#/components/schemas/CloudflowGCPConfigRequest" awsConfig: $ref: "#/components/schemas/CloudflowAWSConfigRequest" collaborators: type: array items: $ref: "#/components/schemas/CloudflowCollaborator" enabled: type: boolean description: When false, the connection is created in a disabled state. default: true responses: "201": description: Created content: application/json: schema: $ref: "#/components/schemas/CloudflowConnection" "400": $ref: "#/components/responses/400" "401": $ref: "#/components/responses/401" "403": $ref: "#/components/responses/403" "500": $ref: "#/components/responses/500" /cloudflow/v1/connections/{connectionId}: get: tags: - Connections summary: Retrieve a connection description: Returns a single connection by ID. operationId: getCloudflowConnection parameters: - name: connectionId in: path required: true schema: type: string responses: "200": description: OK content: application/json: schema: $ref: "#/components/schemas/CloudflowConnection" "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: - Connections summary: Update a connection description: |- Partially updates a connection. All fields are optional. At most one of `gcpConfig` or `awsConfig` may be set per request. operationId: updateCloudflowConnection parameters: - name: connectionId in: path required: true schema: type: string requestBody: required: true content: application/json: schema: type: object properties: name: type: string description: type: string gcpConfig: $ref: "#/components/schemas/CloudflowGCPConfigRequest" awsConfig: $ref: "#/components/schemas/CloudflowAWSConfigRequest" collaborators: type: array items: $ref: "#/components/schemas/CloudflowCollaborator" enabled: type: boolean description: Set to false to disable the connection, true to re-enable it. responses: "200": description: OK content: application/json: schema: $ref: "#/components/schemas/CloudflowConnection" "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" delete: tags: - Connections summary: Delete a connection description: Deletes a connection. Returns 409 if the connection is referenced by one or more flows. operationId: deleteCloudflowConnection parameters: - name: connectionId in: path required: true schema: type: string responses: "204": description: No Content — connection deleted. "400": $ref: "#/components/responses/400" "401": $ref: "#/components/responses/401" "403": $ref: "#/components/responses/403" "404": $ref: "#/components/responses/404" "409": description: Conflict — connection is in use by one or more flows. content: application/json: schema: type: object properties: type: type: string title: type: string status: type: integer code: type: string "500": $ref: "#/components/responses/500" # ============================================================ # CloudFlow Templates # ============================================================ /cloudflow/v1/templates: get: tags: - Templates - CloudFlow summary: List templates description: |- Returns the catalogue of available CloudFlow templates (blueprints). Templates are read-only. To create a flow from a template, use `POST /flows` with a `templateId`. operationId: listCloudflowTemplates parameters: - name: maxResults in: query description: Maximum number of templates to return (1–500). Defaults to 50. schema: type: integer minimum: 1 maximum: 500 default: 50 - name: pageToken in: query description: Opaque cursor for the next page, taken from `pageToken` in the previous response. Omit to start from the beginning. schema: type: string responses: "200": description: OK content: application/json: schema: $ref: "#/components/schemas/CloudflowTemplateListResponse" "400": $ref: "#/components/responses/400" "401": $ref: "#/components/responses/401" "403": $ref: "#/components/responses/403" "500": $ref: "#/components/responses/500" /cloudflow/v1/templates/{templateId}: get: tags: - Templates - CloudFlow summary: Retrieve a template description: Returns a single CloudFlow template by ID. operationId: getCloudflowTemplate parameters: - name: templateId in: path required: true schema: type: string responses: "200": description: OK content: application/json: schema: $ref: "#/components/schemas/CloudflowTemplate" "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" /ps4commitments/v1/aws/organizations: get: operationId: listAwsOrganizations tags: - PerfectScale for Commitments AWS summary: List AWS organizations description: |- Returns all AWS Organizations accessible to the authenticated tenant. Each item includes metadata, trailing 30-day aggregate statistics, precomputed YTD/lifetime savings totals per SP type so customer-level savings can be aggregated client-side by summing across organizations, and estimated monthly potential savings (`monthlyPotentialSavings`) per SP type from the latest projection. parameters: - $ref: "#/components/parameters/tenantId" - $ref: "#/components/parameters/ps4cPageToken" - $ref: "#/components/parameters/ps4cMaxResults" responses: "200": description: List of AWS Organizations. headers: Request-Id: $ref: "#/components/headers/RequestId" Content-Language: $ref: "#/components/headers/ContentLanguage" content: application/json: schema: type: object required: - items properties: items: type: array items: $ref: "#/components/schemas/AwsOrganization" pageToken: type: string nullable: true rowCount: type: integer format: int64 description: Best-effort count for the filtered result set. May be null or omitted for expensive counts. nullable: true "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/aws/organizations/{managementAccountId}: get: operationId: getAwsOrganization tags: - PerfectScale for Commitments AWS summary: Get an AWS organization description: | Returns a single AWS Organization including metadata, 30-day aggregates, and the trailing-window stats that drive the customer Overview screen: - `monthlyStats` — last 6 calendar months (ESR, on-demand cost, cost with savings). - `dailyCoverage` — last 30 days of commitment coverage breakdown. - `savingsTotals` — year-to-date and lifetime savings per SP type. - `monthlyPotentialSavings` — estimated monthly additional savings per SP type from the latest projection. parameters: - $ref: "#/components/parameters/tenantId" - $ref: "#/components/parameters/managementAccountId" responses: "200": description: AWS Organization detail. headers: Request-Id: $ref: "#/components/headers/RequestId" Content-Language: $ref: "#/components/headers/ContentLanguage" content: application/json: schema: $ref: "#/components/schemas/AwsOrganizationDetail" "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" /ps4commitments/v1/aws/organizations/{managementAccountId}/member-accounts: get: operationId: listAwsMemberAccounts tags: - PerfectScale for Commitments AWS summary: List member accounts under an organization description: |- Returns all member AWS accounts under the specified organization that have active or historical commitment coverage. Includes 30-day statistics and estimated monthly potential savings (`monthlyPotentialSavings`) per SP type. parameters: - $ref: "#/components/parameters/tenantId" - $ref: "#/components/parameters/managementAccountId" - $ref: "#/components/parameters/ps4cPageToken" - $ref: "#/components/parameters/ps4cMaxResults" responses: "200": description: List of member accounts. headers: Request-Id: $ref: "#/components/headers/RequestId" Content-Language: $ref: "#/components/headers/ContentLanguage" content: application/json: schema: type: object required: - items properties: items: type: array items: $ref: "#/components/schemas/AwsMemberAccount" pageToken: type: string nullable: true rowCount: type: integer format: int64 description: Best-effort count for the filtered result set. May be null or omitted for expensive counts. nullable: true "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" /ps4commitments/v1/aws/organizations/{managementAccountId}/member-accounts/{memberAccountId}: get: operationId: getAwsMemberAccount tags: - PerfectScale for Commitments AWS summary: Get a member account description: | Returns a single member AWS account including 30-day aggregates and the trailing-window stats that drive the member-account Overview view: - `monthlyStats` — last 6 calendar months per SP type. - `dailyCoverage` — last 30 days of commitment coverage breakdown. - `savingsTotals` — year-to-date and lifetime savings per SP type, clamped to the parent organization's onboarding start. - `monthlyPotentialSavings` — estimated monthly additional savings per SP type, attributed from the parent organization's projection. parameters: - $ref: "#/components/parameters/tenantId" - $ref: "#/components/parameters/managementAccountId" - $ref: "#/components/parameters/memberAccountId" responses: "200": description: Member account detail. headers: Request-Id: $ref: "#/components/headers/RequestId" Content-Language: $ref: "#/components/headers/ContentLanguage" content: application/json: schema: $ref: "#/components/schemas/AwsMemberAccountDetail" "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" /ps4commitments/v1/aws/organizations/{managementAccountId}/savings-plans: get: operationId: listAwsSavingsPlans tags: - PerfectScale for Commitments AWS summary: List AWS Savings Plans description: |- Returns the paginated list of Savings Plans for the specified organization. Filterable by plan type and state. parameters: - $ref: "#/components/parameters/tenantId" - $ref: "#/components/parameters/managementAccountId" - in: query name: type required: false description: Filter by Savings Plan type. schema: type: string enum: - compute - ec2_instance - sagemaker - database - in: query name: status required: false description: Filter by Savings Plan state. schema: type: string enum: - pending_return - returning - active - expired - queued - queued_returning - payment_failed - payment_pending - $ref: "#/components/parameters/ps4cPageToken" - $ref: "#/components/parameters/ps4cMaxResults" responses: "200": description: Paginated list of Savings Plans. headers: Request-Id: $ref: "#/components/headers/RequestId" Content-Language: $ref: "#/components/headers/ContentLanguage" content: application/json: schema: type: object required: - items properties: items: type: array items: $ref: "#/components/schemas/AwsSavingsPlan" pageToken: type: string nullable: true rowCount: type: integer format: int64 description: Best-effort count for the filtered result set. May be null or omitted for expensive counts. nullable: true "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" /ps4commitments/v1/aws/organizations/{managementAccountId}/reserved-instances: get: operationId: listAwsReservedInstances tags: - PerfectScale for Commitments AWS summary: List AWS Reserved Instances description: |- Returns the paginated list of Reserved Instances (RIs) for the specified organization. Filterable by state, instance type/family, region, and offering class. parameters: - $ref: "#/components/parameters/tenantId" - $ref: "#/components/parameters/managementAccountId" - in: query name: status required: false description: Filter by Reserved Instance state. schema: type: string enum: - active - retired - payment_pending - payment_failed - queued - queued_deleted - in: query name: instanceType required: false description: Filter by exact EC2 instance type (e.g. `m5.large`). Case-sensitive. schema: type: string - in: query name: instanceFamily required: false description: Filter by EC2 instance family — the leading segment of `instanceType` before the dot (e.g. `m5` matches `m5.large`, `m5.xlarge`). Case-sensitive. schema: type: string - in: query name: region required: false description: Filter by AWS region (e.g. `us-east-1`). Case-sensitive. schema: type: string - in: query name: offeringClass required: false description: Filter by RI offering class. schema: type: string enum: - standard - convertible - $ref: "#/components/parameters/ps4cPageToken" - $ref: "#/components/parameters/ps4cMaxResults" responses: "200": description: Paginated list of Reserved Instances. headers: Request-Id: $ref: "#/components/headers/RequestId" Content-Language: $ref: "#/components/headers/ContentLanguage" content: application/json: schema: type: object required: - items properties: items: type: array items: $ref: "#/components/schemas/AwsReservedInstance" pageToken: type: string nullable: true rowCount: type: integer format: int64 description: Best-effort count for the filtered result set. May be null or omitted for expensive counts. nullable: true "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" /ps4commitments/v1/aws/organizations/{managementAccountId}/recommendations: get: operationId: listAwsRecommendations tags: - PerfectScale for Commitments AWS summary: List AWS recommendations description: |- Returns commitment purchase recommendations for the organization. Multiple recommendations may exist per organization (one per service). parameters: - $ref: "#/components/parameters/tenantId" - $ref: "#/components/parameters/managementAccountId" responses: "200": description: List of recommendations. headers: Request-Id: $ref: "#/components/headers/RequestId" Content-Language: $ref: "#/components/headers/ContentLanguage" content: application/json: schema: $ref: "#/components/schemas/AwsRecommendations" "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" /ps4commitments/v1/aws/organizations/{managementAccountId}/recommendations/{serviceId}: get: operationId: getAwsRecommendation tags: - PerfectScale for Commitments AWS summary: Get an AWS recommendation description: Returns full detail for a single recommendation including analysis metrics. parameters: - $ref: "#/components/parameters/tenantId" - $ref: "#/components/parameters/managementAccountId" - $ref: "#/components/parameters/serviceId" - $ref: "#/components/parameters/eligibleSpendGranularity" responses: "200": description: Recommendation detail. headers: Request-Id: $ref: "#/components/headers/RequestId" Content-Language: $ref: "#/components/headers/ContentLanguage" content: application/json: schema: $ref: "#/components/schemas/AwsRecommendationWithEligibleSpend" "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" /ps4commitments/v1/aws/organizations/{managementAccountId}/planned-purchases: get: operationId: listAwsPlannedPurchases tags: - PerfectScale for Commitments AWS summary: List AWS planned purchases description: |- Returns the laddering projections for the organization — one item per available `purchases-projection` document (typically `compute` and/or `database`; up to four product lines as PS4C expands). With no filters, returns all existing projection documents for the organization in stable product-line order (`compute`, then `database`, then any future lines in enum order). When a filtered product line has no projection document, the response is an empty `items` array (not `404`). Partial projection documents return only the fields available in storage. `404` is returned only when the organization does not exist or the caller cannot access it. An organization that is not onboarded for PS4C still returns `200` with an empty `items` array when no projection documents exist — use `GET /ps4commitments/v1/aws/organizations` (or get-by-id) for `onboardingStatus`. **Pagination**: results are returned in stable product-line order (`compute`, then `database`, then any future lines in enum order). Use `maxResults` to limit page size (default 50, max 500). When more items remain, the response includes a non-null `pageToken`; pass it unchanged on the next request with the same query parameters (`service`, `maxResults`). `rowCount` is the number of items in this page. An invalid `pageToken` returns `400` with code `pagination_token_invalid`; an expired token returns `400` with code `pagination_token_expired`. parameters: - $ref: "#/components/parameters/tenantId" - $ref: "#/components/parameters/managementAccountId" - $ref: "#/components/parameters/service" - $ref: "#/components/parameters/ps4cPageToken" - $ref: "#/components/parameters/ps4cMaxResults" responses: "200": description: Paginated list of planned purchase projections. headers: Request-Id: $ref: "#/components/headers/RequestId" Content-Language: $ref: "#/components/headers/ContentLanguage" content: application/json: schema: type: object required: - items - rowCount properties: items: type: array items: $ref: "#/components/schemas/AwsPlannedPurchase" pageToken: type: string nullable: true rowCount: type: integer format: int64 description: Number of items in `items` for this response. "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" /ps4commitments/v1/aws/settings: get: operationId: listAwsOrganizationsSettings tags: - PerfectScale for Commitments AWS summary: List organization engine settings description: |- Returns automation and recommendation engine settings for every onboarded organization, broken down by product line (`compute`, `database`). Settings are configured at the customer level and apply uniformly across all organizations. Only product lines that are activated/onboarded for a given organization are returned. The `purchaseAccountId` is the member AWS account designated to execute SP purchases on behalf of that organization. parameters: - $ref: "#/components/parameters/tenantId" - $ref: "#/components/parameters/ps4cPageToken" - $ref: "#/components/parameters/ps4cMaxResults" responses: "200": description: List of per-organization per-product-line engine settings. headers: Request-Id: $ref: "#/components/headers/RequestId" Content-Language: $ref: "#/components/headers/ContentLanguage" content: application/json: schema: type: object required: - items properties: items: type: array items: $ref: "#/components/schemas/AwsOrganizationSettingsItem" pageToken: type: string description: Opaque cursor for the next page. Absent when this is the last page. nullable: true rowCount: type: integer format: int64 description: Number of items returned in this page. "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" /billingtransfer/v1/resellerhandshakes: post: tags: - Billing Transfer summary: Create reseller handshakes (batch) description: | Maps reseller to distributor; also sends the handshake if required, as part of AWS billing transfer onboarding. Distributor-only; callers without the ChannelOps distributor tier entitlement receive `403`. Each item in the batch is processed independently; per-item outcomes are returned in `results[]` with HTTP `200` even when some items fail. Malformed items (missing fields, duplicate `resellerPmaAccountId` within the batch) are rejected up front with `422` and reported in `invalidItems`, and none of the batch is processed in that case. operationId: createBillingTransferResellerHandshakes parameters: - $ref: "#/components/parameters/tenantId" - name: Idempotency-Key in: header required: true description: | Client-generated idempotency key (UUID v4 or ULID recommended, max 255 characters). Re-submitting the same key with the same request returns the cached response without re-executing side effects. schema: type: string maxLength: 255 - name: dryRun in: query required: false description: | If `true`, validates the batch and simulates the outcome without issuing any AWS Organizations handshakes. The response shape is identical to a real execution. schema: type: boolean default: false requestBody: required: true content: application/json: schema: $ref: "#/components/schemas/ResellerHandshakeBatchCreate" responses: "200": description: OK - Batch processed; see `results` and `summary` for per-item outcomes. content: application/json: schema: $ref: "#/components/schemas/ResellerHandshakeBatchResult" "400": $ref: "#/components/responses/400" "401": $ref: "#/components/responses/401" "403": description: >- Forbidden - The caller is not entitled to the ChannelOps distributor tier, or does not own the referenced `dpmaId`. content: application/json: schema: $ref: "#/components/schemas/BillingTransferProblemDetails" "422": $ref: "#/components/responses/422_billing_transfer_batch_validation" "500": $ref: "#/components/responses/500" "502": description: Bad Gateway - AWS Organizations was unreachable; retry later. content: application/json: schema: $ref: "#/components/schemas/BillingTransferProblemDetails" /billingtransfer/v1/programmanagementaccounts: get: tags: - Billing Transfer summary: List program management accounts description: | Lists the caller's program management accounts (PMAs) and the reseller tenants mapped to each one, including AWS Organizations handshake status per account. Distributor-only. operationId: listBillingTransferProgramManagementAccounts parameters: - $ref: "#/components/parameters/tenantId" - $ref: "#/components/parameters/maxResults" - $ref: "#/components/parameters/pageToken" responses: "200": description: OK content: application/json: schema: $ref: "#/components/schemas/ProgramManagementAccountList" "400": $ref: "#/components/responses/400" "401": $ref: "#/components/responses/401" "403": $ref: "#/components/responses/403" "500": $ref: "#/components/responses/500" /billingtransfer/v1/end-customer-mappings: post: tags: - Billing Transfer summary: Create end-customer mappings (batch) description: | Maps end-customer AWS accounts under a reseller's PMA to their DoiT tenant, as part of AWS billing transfer onboarding. Reseller-only; distributors are explicitly denied (`403`). Unlike `POST /billingtransfer/v1/resellerhandshakes`, this endpoint has no `Idempotency-Key` requirement and no `dryRun` support. This path is a deliberate exception to the de-hyphenation convention used by the sibling `resellerhandshakes` and `programmanagementaccounts` paths — it stays hyphenated to match the existing Go route and its console-facing equivalent. Each item in the batch is processed independently; per-item outcomes are returned in `results[]` with HTTP `200`. Malformed items are rejected up front and reported in `invalidItems` without processing any of the batch. operationId: createBillingTransferEndCustomerMappings parameters: - $ref: "#/components/parameters/tenantId" requestBody: required: true content: application/json: schema: $ref: "#/components/schemas/EndCustomerMappingBatchCreate" responses: "200": description: >- OK - Batch processed; see `results` for per-item outcomes and `invalidItems` for any items rejected before processing. content: application/json: schema: $ref: "#/components/schemas/EndCustomerMappingBatchResult" "400": $ref: "#/components/responses/400" "401": $ref: "#/components/responses/401" "403": description: >- Forbidden - The caller is a distributor (denied), does not own the referenced `resellerPmaAccountId`, or the reseller is not mapped to the referenced `dpmaId`. content: application/json: schema: $ref: "#/components/schemas/BillingTransferProblemDetails" "422": $ref: "#/components/responses/422_billing_transfer_batch_validation" "500": $ref: "#/components/responses/500" /billingtransfer/v1/programmanagementaccounts/status: get: tags: - Billing Transfer summary: Get program management account status description: | Lightweight polling surface for the onboarding wizard: returns each of the caller's PMAs with only its IAM status/diff and timestamps — no tenant fan-out, no handshake aggregation, no pagination. Distributor-only. operationId: getBillingTransferProgramManagementAccountsStatus parameters: - $ref: "#/components/parameters/tenantId" responses: "200": description: OK content: application/json: schema: $ref: "#/components/schemas/ProgramManagementAccountsStatusResponse" "400": $ref: "#/components/responses/400" "401": $ref: "#/components/responses/401" "403": $ref: "#/components/responses/403" "500": $ref: "#/components/responses/500" /billingtransfer/v1/end-customers: get: tags: - Billing Transfer summary: List end-customers under a reseller PMA description: | Lists the end-customer AWS account mappings under a reseller's program management account, identified by `dpmaId` and `resellerPmaAccountId`. Callable by the reseller who owns the PMA or the distributor who owns the DPMA. operationId: listBillingTransferEndCustomers parameters: - $ref: "#/components/parameters/tenantId" - name: dpmaId in: query required: true description: DPMA ID that owns the reseller PMA referenced by `resellerPmaAccountId`. schema: type: string - name: resellerPmaAccountId in: query required: true description: 12-digit AWS account ID of the reseller's program management account. schema: type: string example: "123456789012" - $ref: "#/components/parameters/includeRevoked" responses: "200": description: OK content: application/json: schema: $ref: "#/components/schemas/ListEndCustomersResponse" "400": $ref: "#/components/responses/400" "401": $ref: "#/components/responses/401" "403": description: >- Forbidden - The caller lacks the BillingTransferAdmin permission, or is not the reseller who owns this PMA nor the distributor who owns the DPMA. content: application/json: schema: $ref: "#/components/schemas/BillingTransferProblemDetails" "404": description: >- Not Found - No reseller PMA exists for the given `resellerPmaAccountId` under the given `dpmaId`. content: application/json: schema: $ref: "#/components/schemas/BillingTransferProblemDetails" "500": $ref: "#/components/responses/500" /billingtransfer/v1/resellers/{resellerPmaAccountId}/end-customers: get: tags: - Billing Transfer summary: List end-customers under a reseller PMA, by reseller PMA alone description: | Same result as `GET /billingtransfer/v1/end-customers`, identified by `resellerPmaAccountId` alone (no `dpmaId` needed). Callable by the reseller who owns the PMA or the distributor who owns its DPMA. operationId: listBillingTransferEndCustomersByReseller parameters: - $ref: "#/components/parameters/tenantId" - name: resellerPmaAccountId in: path required: true description: 12-digit AWS account ID of the reseller's program management account. schema: type: string example: "123456789012" - $ref: "#/components/parameters/includeRevoked" responses: "200": description: OK content: application/json: schema: $ref: "#/components/schemas/ListEndCustomersResponse" "400": $ref: "#/components/responses/400" "401": $ref: "#/components/responses/401" "403": description: Forbidden - The caller lacks the BillingTransferAdmin permission. content: application/json: schema: $ref: "#/components/schemas/BillingTransferProblemDetails" "404": description: >- Not Found - No reseller PMA exists for the given `resellerPmaAccountId`, or it exists but the caller is not the reseller who owns it or the distributor who owns its DPMA. content: application/json: schema: $ref: "#/components/schemas/BillingTransferProblemDetails" "500": $ref: "#/components/responses/500" /billingtransfer/v1/reseller-accounts: get: tags: - Billing Transfer summary: List the caller's reseller PMA nodes description: | Lists every reseller program management account (RPMA) node belonging to the calling reseller, with handshake state and status but without end-customer tenants — the reseller-tier analog of `GET /billingtransfer/v1/programmanagementaccounts`. operationId: listBillingTransferResellerAccounts parameters: - $ref: "#/components/parameters/tenantId" responses: "200": description: OK content: application/json: schema: $ref: "#/components/schemas/ListResellerAccountsResponse" "400": $ref: "#/components/responses/400" "401": $ref: "#/components/responses/401" "403": description: Forbidden - The caller lacks the BillingTransferAdmin permission. content: application/json: schema: $ref: "#/components/schemas/BillingTransferProblemDetails" "500": $ref: "#/components/responses/500" /billingtransfer/v1/reseller-accounts/end-customers: get: tags: - Billing Transfer summary: List the caller's reseller PMA nodes with their end-customer tenants description: | Lists every reseller PMA node belonging to the calling reseller, each with the end-customer tenants connected under it — the reseller-tier analog of `GET /billingtransfer/v1/programmanagementaccounts`. `region`, `iamStatus` and `lastRefreshTime` are inherited from the parent DPMA root; the reseller node itself carries no IAM/region metadata of its own. operationId: listBillingTransferResellerAccountsWithTenants parameters: - $ref: "#/components/parameters/tenantId" - $ref: "#/components/parameters/includeRevoked" responses: "200": description: OK content: application/json: schema: $ref: "#/components/schemas/ListResellerAccountsWithTenantsResponse" "400": $ref: "#/components/responses/400" "401": $ref: "#/components/responses/401" "403": description: Forbidden - The caller lacks the BillingTransferAdmin permission. content: application/json: schema: $ref: "#/components/schemas/BillingTransferProblemDetails" "500": $ref: "#/components/responses/500" components: schemas: CloudflowCollaborator: type: object properties: email: type: string format: email role: type: string enum: [owner, editor, user] CloudflowGCPConfigRequest: type: object description: GCP connection configuration. Server-owned fields (status, deploymentCommand) are excluded. properties: organizationId: type: string folderId: type: string projectId: type: string level: type: string enum: [organization, folder, project] serviceAccountName: type: string predefinedRoles: type: array items: type: string customRole: type: object properties: roleId: type: string permissions: type: array items: type: string infraManagerProject: type: string infraManagerLocation: type: string infraManagerServiceAccount: type: string CloudflowAWSConfigRequest: type: object description: AWS connection configuration. Server-owned fields (context[].status, context[].nextStackOperation, stackSet) are excluded. properties: context: type: array items: type: object properties: accountId: type: string regions: type: array items: type: string roleName: type: string permissions: type: object managementAccount: type: string organizationRootId: type: string scopeTargetedOrganizationalUnitIds: type: array items: type: string scopeExplicitAccountIds: type: array items: type: string scopeExcludedAccountIds: type: array items: type: string scopeManagementAccountExplicitInScope: type: boolean CloudflowConnection: type: object description: A cloud provider connection used in CloudFlow workflows. properties: connectionId: type: string description: Unique identifier for the connection. name: type: string description: type: string gcpConfig: allOf: - $ref: "#/components/schemas/CloudflowGCPConfigRequest" - type: object description: Response extends request schema with server-owned read-only fields. properties: status: type: string description: Server-managed GCP config status. deploymentCommand: type: string description: Generated deployment command. awsConfig: allOf: - $ref: "#/components/schemas/CloudflowAWSConfigRequest" - type: object description: Response extends request schema with server-owned read-only fields. properties: context: type: array items: type: object properties: accountId: type: string regions: type: array items: type: string status: type: string description: Server-managed per-account deployment status. collaborators: type: array items: $ref: "#/components/schemas/CloudflowCollaborator" enabled: type: boolean description: false when the connection is disabled. status: type: string description: Overall connection status. createdAt: type: string format: date-time updatedAt: type: string format: date-time CloudflowTemplate: type: object description: A read-only CloudFlow template (blueprint). Use `POST /flows` with `templateId` to create a new flow initialised from this template. required: - id - name - createTime properties: id: type: string description: Unique identifier of the template. name: type: string description: Human-readable display name of the template. description: type: string description: Short summary of what the template does and which use case it addresses. instructions: type: string nullable: true description: Step-by-step operator guidance for configuring a flow created from this template. `null` when no instructions have been authored. createTime: type: string format: date-time description: ISO 8601 (UTC) creation timestamp. updateTime: type: string format: date-time nullable: true description: ISO 8601 (UTC) last-modified timestamp. `null` if never modified. Cloudflow: type: object required: - id - name - published - createTime properties: id: type: string name: type: string description: type: string instructions: type: string nullable: true published: type: boolean triggerType: type: string nullable: true createTime: type: string format: date-time updateTime: type: string format: date-time nullable: true lastExecutedTime: type: string format: date-time nullable: true lastExecutionStatus: type: string nullable: true enum: [pending, running, complete, pending-approval, failed, sleeping, stopped] nextRun: type: string format: date-time nullable: true description: Next scheduled execution time. `null` when the CloudFlow has no active schedule. CloudflowListResponse: type: object required: - items properties: items: type: array items: $ref: "#/components/schemas/Cloudflow" description: List of CloudFlows. pageToken: type: string nullable: true description: Opaque cursor for the next page. `null` when there are no more CloudFlows. rowCount: type: integer nullable: true description: Always `null`. Row count is not computed for this endpoint. CloudflowConnectionListResponse: type: object description: Cursor-paginated list of CloudFlow connections. required: - items properties: items: type: array description: List of connections for the current page. items: $ref: "#/components/schemas/CloudflowConnection" pageToken: type: string nullable: true description: Opaque cursor for the next page. `null` when there are no more results. rowCount: type: integer nullable: true description: Always `null`. Row count is not computed for this endpoint. CloudflowTemplateListResponse: type: object description: Cursor-paginated list of CloudFlow templates. required: - items properties: items: type: array items: $ref: "#/components/schemas/CloudflowTemplate" pageToken: type: string nullable: true description: Opaque cursor for the next page. `null` when there are no more results. rowCount: type: integer nullable: true description: Total number of templates matching the current query. AwsAccountResponse: type: object properties: accountID: type: string description: The AWS account ID. example: "123456789012" roleArn: type: string description: The ARN of the IAM role. example: "arn:aws:iam::123456789012:role/DoiTRole" s3Bucket: type: string description: S3 bucket name for real-time anomaly detection. Present only if real-time is enabled. s3BucketRegion: type: string description: AWS region of the S3 bucket. Present only if s3Bucket exists. example: "us-east-1" supportedFeatures: type: array items: $ref: "#/components/schemas/AwsSupportedFeature" description: List of supported features and their permission status. enabledFeatures: type: array items: type: string description: List of supported AWS features enabled by the caller. Returned in the same order as provided. timeLinked: type: string description: ISO 8601 timestamp of when the role was linked. example: "2024-01-15T10:30:00Z" AwsSupportedFeature: type: object properties: name: type: string description: Feature name. example: "spot-scaling" hasRequiredPermissions: type: boolean description: Whether the role has the required permissions for this feature. DisplayStatus: type: string enum: - "actionable" - "acknowledged" - "optimized" - "dismissed" - "in progress" - "upgrade needed" - "permissions needed" description: The display status of the insight. ResultsBody: type: object description: Paginated list of insight results. properties: results: description: List of insight results. type: array items: $ref: "#/components/schemas/InsightResponse" pagination: $ref: "#/components/schemas/Pagination" CreateResultsBody: type: object description: Request body for creating or updating multiple insights in a batch. required: - results properties: results: description: List of insights to create or update. type: array items: $ref: "#/components/schemas/InsightRequest" InsightRequest: type: object description: Request body for creating or updating an insight via the batch endpoint. Includes resource results. required: [key, title, shortDescription, cloudProvider, categories, resourceResults] properties: key: type: string description: A unique key for this insight within the source. title: type: string description: The display title of the insight. shortDescription: type: string description: A brief summary of the insight. detailedDescriptionMdx: type: string description: A detailed description of the insight in MDX format. cloudProvider: $ref: "#/components/schemas/CloudProvider" categories: description: One or more categories this insight belongs to. type: array minItems: 1 uniqueItems: true items: $ref: "#/components/schemas/CreateCategory" reportUrl: type: string description: URL to an external report related to this insight. cloudFlowTemplateId: type: string description: ID of a CloudFlow template that can automate the remediation of this insight. easyWinDescription: type: string description: A description of why this insight is considered an easy win. resourceResults: $ref: "#/components/schemas/ResourceResults" InsightMetadataRequest: type: object description: Request body for creating or updating a single insight's metadata. Resource results are managed separately via the resource-results endpoint. required: [key, title, shortDescription, cloudProvider, categories] properties: key: type: string description: A unique key for this insight within the source. title: type: string description: The display title of the insight. shortDescription: type: string description: A brief summary of the insight. detailedDescriptionMdx: type: string description: A detailed description of the insight in MDX format. cloudProvider: $ref: "#/components/schemas/CloudProvider" categories: description: One or more categories this insight belongs to. type: array minItems: 1 uniqueItems: true items: $ref: "#/components/schemas/CreateCategory" reportUrl: type: string description: URL to an external report related to this insight. cloudFlowTemplateId: type: string description: ID of a CloudFlow template that can automate the remediation of this insight. easyWinDescription: type: string description: A description of why this insight is considered an easy win. status: $ref: "#/components/schemas/DisplayStatus" dismissalDetails: $ref: "#/components/schemas/DismissalDetails" CreateResourceResultsBody: type: object description: Request body for creating or replacing resource results for an insight. required: - resourceResults properties: resourceResults: $ref: "#/components/schemas/ResourceResults" InsightResponse: type: object description: An insight result containing summary information and metadata. properties: source: $ref: "#/components/schemas/Source" key: type: string description: The unique key identifying this insight. title: type: string description: The display title of the insight. shortDescription: type: string description: A brief summary of the insight. detailedDescriptionMdx: type: string description: A detailed description of the insight in MDX format. displayStatus: $ref: "#/components/schemas/DisplayStatus" cloudProvider: $ref: "#/components/schemas/CloudProvider" categories: description: Categories this insight belongs to. type: array items: $ref: "#/components/schemas/Category" summary: $ref: "#/components/schemas/InsightSummary" lastStatusChange: $ref: "#/components/schemas/LastInsightStatusChange" lastUpdated: type: string format: date-time description: Timestamp of the last update to this insight. tags: description: Tags for the insight, primarily used for security certification labels (e.g. ISO). type: array items: type: string reportUrl: type: string description: URL to an external report related to this insight. cloudFlowTemplateId: type: string description: ID of a CloudFlow template that can automate the remediation of this insight. easyWinDescription: type: string description: A description of why this insight is considered an easy win. dismissalDetails: $ref: "#/components/schemas/DismissalDetails" Category: type: string description: The insight category. enum: ["FinOps", "Operational excellence", "Performance efficiency", "Reliability", "Security", "Sustainability"] CreateCategory: type: string description: Allowed categories when creating insights via the public API. enum: ["FinOps", "Security"] InsightSummary: type: object description: Aggregate summary of risks and savings across all resource results for an insight. properties: operationalRisks: type: number format: double description: Total number of operational risks. performanceRisks: type: number format: double description: Total number of performance risks. potentialDailySavings: type: number format: double description: Total potential daily savings in USD. reliabilityRisks: type: number format: double description: Total number of reliability risks. securityRisks: type: number format: double description: Total number of security risks. sustainabilityRisks: type: number format: double description: Total number of sustainability risks. ResourceResults: type: array description: A list of resource-level results for creating or updating an insight. items: $ref: "#/components/schemas/ResourceResultRequest" ResourceResultRequest: type: object description: > A single resource-level result for creating or updating an insight. Server-computed fields (severity, resolved, enhancement) are not accepted here and will be ignored. Identity fields (resourceId, resultType, account, cloudProvider) form the composite key. The fields location and resource_type are set on creation only — any values provided for these fields during subsequent upserts are silently ignored. required: - resourceId - resultType - account - cloudProvider properties: resourceId: type: string description: The cloud resource identifier. resourceType: description: > What the resource actually is, e.g. for an EC2 resource ID, this field would be `instance`. Immutable after creation — updates to this field are silently ignored. type: string example: instance, disk, cache cloudProvider: description: Immutable after creation — updates to this field are silently ignored. allOf: - $ref: "#/components/schemas/CloudProvider" account: type: string description: The cloud account or project ID containing this resource. Immutable after creation — updates to this field are silently ignored. location: type: string description: > Represents the region/zone of the resource in AWS, or equivalent for other providers. Immutable after creation — updates to this field are silently ignored. example: eu-west-2 externalId: type: string description: the external ID of the resource in the provider's system for the resource externalUrl: type: string description: the URL to the resource-level issue in the provider's system metadata: type: object description: contains any additional information for the resource results resultType: type: string enum: [ "security_risk", "potential_daily_savings", "potential_daily_savings_with_recommendation", "potential_daily_savings_with_cluster_agent", ] description: The discriminator property that determines which fields are populated in the 'result' object. result: description: > The result data for this resource. Which fields are populated depends on the resultType. For security_risk: critical, high, medium, low. For potential_daily_savings: value. For potential_daily_savings_with_recommendation: value, current, recommendation. For potential_daily_savings_with_cluster_agent: value, agentInstalled. type: object properties: value: type: number format: double description: the daily saving amount for this result critical: type: integer description: number of critical security risks high: type: integer description: number of high security risks medium: type: integer description: number of medium security risks low: type: integer description: number of low security risks current: type: string description: the current state (i.e. current instance type) recommendation: type: string description: the recommended state (i.e. recommended instance type) agentInstalled: type: boolean description: true if the agent is installed ResourceResult: type: object description: A single resource-level result within an insight, as returned in API responses. required: - resourceId - resultType - account - cloudProvider properties: resourceId: description: The cloud resource identifier. type: string resourceType: description: What the resource actually is, eg. for an EC2 resource ID, this field would be `instance` type: string example: instance, disk, cache cloudProvider: $ref: "#/components/schemas/CloudProvider" account: type: string description: The cloud account or project ID containing this resource. location: type: string description: represents the region/zone of the resource in AWS, or equivalent for other providers example: eu-west-2 resolved: type: boolean description: Whether this resource-level issue has been resolved. Computed server-side. severity: type: string enum: ["critical", "high", "medium", "low"] description: The severity level of the finding. Computed server-side from the security risk counts. externalId: type: string description: the external ID of the resource in the provider's system for the resource externalUrl: type: string description: the URL to the resource-level issue in the provider's system metadata: type: object description: contains any additional information for the resource results enhancement: $ref: "#/components/schemas/ResourceResultEnhancement" resultType: type: string enum: [ "security_risk", "potential_daily_savings", "potential_daily_savings_with_recommendation", "potential_daily_savings_with_cluster_agent", ] description: The discriminator property that determines which fields are populated in the 'result' object. result: description: > The result data for this resource. Which fields are populated depends on the resultType. For security_risk: critical, high, medium, low. For potential_daily_savings: value. For potential_daily_savings_with_recommendation: value, current, recommendation. For potential_daily_savings_with_cluster_agent: value, agentInstalled. type: object properties: value: type: number format: double description: the daily saving amount for this result critical: type: integer description: number of critical security risks high: type: integer description: number of high security risks medium: type: integer description: number of medium security risks low: type: integer description: number of low security risks current: type: string description: the current state (i.e. current instance type) recommendation: type: string description: the recommended state (i.e. recommended instance type) agentInstalled: type: boolean description: true if the agent is installed ResourceResultEnhancement: type: object description: DoiT-managed metadata associated with a resource result. properties: tags: type: array description: Tags assigned to this resource result. items: type: string priority: type: object description: Priority information for this resource result. properties: value: { type: string, description: "The priority level (e.g. Low, Medium, High)." } priorityScore: { type: number, format: double, description: "Numeric priority score." } lastUpdatedBy: { type: string, description: "The user who last updated this enhancement." } lastUpdatedAt: { type: string, format: date-time, description: "Timestamp of the last update." } UpdateStatusRequest: type: object description: Request body for updating an insight's display status. required: - status properties: status: $ref: "#/components/schemas/DisplayStatus" dismissalDetails: $ref: "#/components/schemas/DismissalDetails" DismissalDetails: type: object description: Details for why an insight was dismissed. properties: reason: type: string description: The reason for dismissal. enum: - "not relevant" - "not enough information" - "not worth the effort" - "inaccurate optimization opportunities" comment: type: string description: An optional free-text comment providing additional context. IssueStatus: type: string description: The lifecycle status of an issue. enum: - open - in_progress - resolved - ignored ResultsError: type: object description: Error details for a failed insight in a batch operation. properties: insightKey: type: string description: The key of the insight that failed. error: type: string description: The error message. code: type: integer description: The HTTP status code associated with the error. CloudProvider: type: string example: aws description: The cloud provider associated with the resource. Source: type: string description: The source that generated the insight. example: aws-trusted-advisor, aws-cost-optimization-hub, aws-security-hub, azure-advisor, custom, gcp-recommender Pagination: type: object description: Cursor-based pagination metadata. required: - rowCount properties: pageToken: type: string description: Token to retrieve the next page. Absent when there are no more pages. rowCount: type: integer description: Number of items in this page. ResourceResultsResponse: type: object required: - resourceResults - rowCount properties: resourceResults: type: array items: $ref: "#/components/schemas/ResourceResult" pageToken: type: string rowCount: type: integer LastInsightStatusChange: description: If set, this object contains the last status change made by a user for this insight type: object properties: userId: description: > the reference to the user who made the change (if it was made by a user) If the change was made by an automated system, this reference is empty. type: string example: /users/0Rkrkeq5P0XLe8QFHKq2 lastChangedAt: type: string format: date-time required: - userId - lastChangedAt AccountManagerListItem: type: object description: Information of a DoiT account manager assigned to your organization. properties: email: type: string id: type: string name: type: string role: type: string calendlyLink: type: string UserListItem: type: object description: Summary information of a user. properties: id: type: string description: The unique ID of the user. email: type: string description: The email address of the user. displayName: type: string description: The user's display name. firstName: type: string description: The user's first name. lastName: type: string description: The user's last name. jobTitle: type: string description: The user's job function. enum: - "Data Engineer / Data Analysts" - "Executive Team" - "Finance / Accounting" - "Founder" - "Legal / Purchasing" - "Management" - "Sales / Marketing" - "Software / Ops Engineer" phone: type: string description: The user's country code (e.g., +44). pattern: '^\+[0-9]+$' phoneExtension: type: string description: The user's phone extension. language: type: string description: The user's preferred language. enum: - en - ja roleId: type: string description: The ID of the user's role. organizationId: type: string description: The ID of the user's organization. status: type: string description: The status of the user (active or invited). enum: - active - invited InviteUserRequest: type: object description: Request body to invite a new user to the organization. required: - email properties: email: type: string description: The email address of the user. format: email firstName: type: string description: The first name of the user being invited. lastName: type: string description: The last name of the user being invited. jobTitle: type: string description: The job function of the user being invited. enum: - "Data Engineer / Data Analysts" - "Executive Team" - "Finance / Accounting" - "Founder" - "Legal / Purchasing" - "Management" - "Sales / Marketing" - "Software / Ops Engineer" roleId: type: string description: The ID of the role to assign to the user. organizationId: type: string description: The ID of the organization to assign the user to. UpdateUserRequest: type: object description: Fields allowed when updating an existing user. properties: firstName: type: string description: The user's first name. lastName: type: string description: The user's last name. jobTitle: type: string description: The user's job function. enum: - "Data Engineer / Data Analysts" - "Executive Team" - "Finance / Accounting" - "Founder" - "Legal / Purchasing" - "Management" - "Sales / Marketing" - "Software / Ops Engineer" jobFunction: type: string deprecated: true description: "Deprecated: use 'jobTitle' instead. If both are provided, 'jobTitle' takes precedence." enum: - "Data Engineer / Data Analysts" - "Executive Team" - "Finance / Accounting" - "Founder" - "Legal / Purchasing" - "Management" - "Sales / Marketing" - "Software / Ops Engineer" phone: type: string description: The user's country code (e.g., +44). pattern: '^\+[0-9]+$' phoneExtension: type: string description: The user's phone extension (8-15 digits). pattern: "^[0-9]{8,15}$" language: type: string description: The user's preferred language. enum: - en - ja roleId: type: string description: The ID of the role to assign to the user. UpdateUserResponse: type: object description: Response of a user update operation. properties: message: type: string description: Success message user: $ref: "#/components/schemas/UpdatedUserBody" UpdatedUserBody: type: object description: The updated user record. properties: id: type: string description: The unique ID of the user. displayName: type: string description: The user's display name. firstName: type: string description: The user's first name. lastName: type: string description: The user's last name. email: type: string description: The user's email address. jobTitle: type: string description: The user's job function. enum: - "Data Engineer / Data Analysts" - "Executive Team" - "Finance / Accounting" - "Founder" - "Legal / Purchasing" - "Management" - "Sales / Marketing" - "Software / Ops Engineer" phone: type: string description: The user's country code (e.g., +44). pattern: '^\+[0-9]+$' phoneExtension: type: string description: The user's phone extension. language: type: string description: The user's preferred language. enum: - en - ja roleId: type: string description: The ID of the user's role. organizationId: type: string description: The ID of the user's organization. DeleteUserResponse: type: object description: Response confirming user deletion. properties: message: type: string description: Success message ResendInviteResponse: type: object description: Response confirming invite resend. required: [message, inviteId] properties: message: type: string description: Success message inviteId: type: string description: The invite document ID. CancelInviteResponse: type: object description: Response confirming invite cancellation. required: [message, inviteId] properties: message: type: string description: Success message inviteId: type: string description: The invite document ID. AdvancedAnalysis: type: object description: Advanced analysis options. Each can be set independently. properties: forecast: type: boolean notTrending: type: boolean trendingDown: type: boolean trendingUp: type: boolean ExternalForecastDateRange: type: object description: Start and end timestamps in RFC3339 format. properties: from: type: string format: date-time description: Start timestamp in RFC3339 format. example: "2026-07-10T00:00:00Z" to: type: string format: date-time description: End timestamp in RFC3339 format. example: "2026-09-30T23:59:59Z" ExternalForecastSettings: type: object description: |- Settings for cost forecasting on the report. Historical fields choose which past data the model learns from. Future fields choose how far ahead predicted costs are projected. When a custom date range is set for a side, it takes precedence over the corresponding interval count. futureCustomDateRange is converted to futureTimeIntervals using the report timeInterval. Providing forecastSettings enables forecast (advancedAnalysis.forecast) automatically. On PATCH, omit forecastSettings to leave forecasting unchanged; send forecastSettings: null to clear/disable forecasting (also removes the forecast feature flag). An empty object enables forecast with default mode totals. Interval counts outside the allowed min/max for the report timeInterval are rejected with a validation error that includes the allowed range. properties: mode: type: string description: Forecast granularity mode. enum: - totals - grouping default: totals historicalTimeIntervals: type: integer format: int64 description: |- How many past timeInterval periods of data the model learns from. Allowed ranges by timeInterval: hour 2-1000, day 2-500, week 2-100, month 2-36, quarter 2-12, year 2-6. futureTimeIntervals: type: integer format: int64 description: |- How many future timeInterval periods of predicted costs to project. Allowed ranges by timeInterval: hour 1-1000, day 1-100, week 1-52, month 1-12, quarter 1-4, year 1-3. historicalCustomDateRange: description: Past date range of billed data the model learns from. Takes precedence over historicalTimeIntervals. allOf: - $ref: "#/components/schemas/ExternalForecastDateRange" futureCustomDateRange: description: |- Date range for how far ahead to project predicted costs. Takes precedence over futureTimeIntervals. The range must resolve to a futureTimeIntervals count within the allowed min/max for the report timeInterval. allOf: - $ref: "#/components/schemas/ExternalForecastDateRange" example: mode: totals futureCustomDateRange: from: "2026-07-10T00:00:00Z" to: "2026-09-30T23:59:59Z" Alert: required: - name type: object description: Configuration and runtime metadata of an alert. properties: id: type: string description: Alert ID. name: type: string description: Alert Name. default: "" createTime: type: integer description: The time when the alert was created (in UNIX timestamp). format: int64 updateTime: type: integer description: Last time the alert was modified (in UNIX timestamp). format: int64 lastAlerted: type: integer description: Last time the alert was triggered (in UNIX timestamp). format: int64 recipients: type: array description: List of emails that will be notified when the alert is triggered. items: type: string config: $ref: "#/components/schemas/AlertConfig" example: id: 7jyrczd6CSh3M8TuQ6Qq name: fgfgh createTime: 1678628817062 updateTime: 1678628938891 lastAlerted: null recipients: - user1@example.com - user2@example.com config: condition: value currency: USD metric: type: basic value: cost operator: gt evaluateForEach: "" attributions: - PvqyGcdFcTHh7aLUdGdf scopes: [] timeInterval: month dataSource: billing value: 500 AlertListItem: description: >- Alert as returned by the list endpoint. Identical to `Alert` but also includes `owner`. The `owner` field is only populated in list results; it is not returned by the get, create, or update endpoints. allOf: - $ref: "#/components/schemas/Alert" - type: object properties: owner: type: string description: Email of the alert owner (the collaborator with the owner role). AlertConfig: type: object description: Parameters that define when and how an alert is evaluated. required: - metric - timeInterval - value properties: dataSource: type: string description: Data source used to query data for the alert. Affects which dimensions and metrics are available. default: billing enum: - billing - billing-datahub x-enumDescriptions: billing: Standard Cloud Analytics billing data only. billing-datahub: Billing data plus DataHub custom dimensions and metrics (requires a DataHub subscription). scopes: type: array description: >- The filters that define the scope of the alert. Each item is a Cloud Analytics filter (same idea as report filters). Note: Only the first scope in the array is currently applied; any additional scopes are validated but ignored. If additional scopes are malformed the call will fail silently. Use a single, well-chosen filter, or dataSource plus evaluateForEach to slice spend instead. items: $ref: "#/components/schemas/ExternalConfigFilter" metric: $ref: "#/components/schemas/MetricConfig" currency: $ref: "#/components/schemas/Currency" timeInterval: type: string description: The period each evaluation looks at. default: year enum: - day - week - month - quarter - year condition: $ref: "#/components/schemas/Condition" operator: $ref: "#/components/schemas/MetricFilterText" value: type: number format: double description: The `condition` threshold value. For example, actual metric threshold value for the `value` condition, or percentage change threshold value for the `percentage-change` condition. evaluateForEach: type: string description: >- Add a dimension to break down the evaluation of the condition. For example, evaluate a condition over an attribution for each "Service". Must be a dimension key returned by GET /analytics/v1/dimensions. Not allowed with condition: `forecast`. Used when you Investigate an alert, the dimension becomes the report grouping. attributions: type: array deprecated: true description: Use 'scopes' instead. The attributions selected define the scope to monitor. items: type: string AlertRequest: required: - config - name type: object description: Request body for creating a new alert. properties: name: type: string description: Name of the alert (max 64 characters). config: $ref: "#/components/schemas/AlertConfig" recipients: type: array description: List of emails to notify when the alert is triggered. If omitted on create, defaults to the API user’s email. Must match allowed customer domains. items: type: string example: config: metric: type: basic value: cost timeInterval: year operator: gt scopes: - key: service_description type: fixed values: - Amazon Simple Storage Service condition: value currency: USD value: 1000 name: test08 AlertThreshold: type: object description: A numeric or percentage threshold. properties: amount: type: number format: double percentage: type: number format: double AlertUpdateRequest: required: - config type: object description: Request body for modifying an existing alert. properties: name: type: string description: Alert name config: $ref: "#/components/schemas/AlertConfig" recipients: type: array description: List of emails to notify when the alert is triggered. items: type: string AllocationComponent: required: - key - type - values - mode type: object description: |- A filter component used inside allocation rules. When the type is "allocation_rule", the component references existing allocation rules (nested allocation rules). A maximum nesting depth of 3 levels is supported, and circular references are not allowed. properties: key: type: string description: |- Key of an existing dimension. Examples: "billing_account_id", "country". When type is "allocation_rule", the key must be set to "allocation_rule". Use `GET /analytics/v1/dimensions` to retrieve all available dimensions. type: $ref: "#/components/schemas/AllocationDimensionsTypes" values: type: array description: Values to filter on. When type is "allocation_rule", the values are IDs of existing allocation rules. items: type: string inverse: type: boolean description: If true, all selected values will be excluded. default: false inverse_selection: type: boolean description: If true, all selected values will be excluded. default: false deprecated: true includeNull: type: boolean description: Include null values. default: false caseInsensitive: type: boolean description: If true, string matching is case-insensitive. Effective only for starts_with, ends_with, and contains modes; rejected otherwise. default: false mode: type: string description: Filter mode to apply. When type is "allocation_rule", only "is" and "contains" modes are supported. enum: - is - starts_with - ends_with - contains - regexp ContractTemplateInput: type: object description: Payload for creating or updating a contract template. required: - name - platform - eligibleFrom properties: name: type: string platform: type: string structure: description: >- Which preset the template started from. Optional — an omitted or blank value is recorded as "blank". type: string eligibleFrom: type: string format: date-time eligibleTo: type: string format: date-time billingRules: type: array items: $ref: "#/components/schemas/ContractTemplateBillingRule" priceBooks: type: array items: $ref: "#/components/schemas/ContractTemplatePriceBook" customLineItems: type: array items: type: object additionalProperties: true ContractTemplateResponse: type: object description: Contract template returned by the PartnerOps external API. properties: templateId: type: string name: type: string platform: type: string status: type: string enum: [active, archived] structure: type: string eligibleFrom: type: string format: date-time eligibleTo: type: string format: date-time billingRules: type: array items: $ref: "#/components/schemas/ContractTemplateBillingRule" priceBooks: type: array items: $ref: "#/components/schemas/ContractTemplatePriceBook" customLineItems: type: array items: type: object additionalProperties: true createdAt: type: string format: date-time updatedAt: type: string format: date-time archivedAt: type: string format: date-time ContractTemplateBillingRule: type: object properties: name: type: string managementAccounts: type: array items: type: string filters: type: array items: type: object additionalProperties: true formula: type: string ContractTemplatePriceBook: type: object properties: name: type: string managementAccounts: type: array items: type: string rules: type: array items: $ref: "#/components/schemas/ContractTemplatePriceBookRule" ContractTemplatePriceBookRule: type: object properties: name: type: string percentageChange: type: number format: double unitPrice: type: number format: double filters: type: array items: type: object additionalProperties: true formula: type: string cloud: type: string lineItemDescription: type: string applyInLine: type: boolean includeCredits: type: boolean applyAWSEligibleDiscount: type: boolean CreateAllocationRequest: required: - name - description type: object description: Request body for creating an allocation. properties: name: type: string description: Allocation name. description: type: string description: Allocation description. anomalyDetection: type: boolean description: Whether anomaly detection is enabled for this allocation. Only applicable to single allocations. rule: $ref: "#/components/schemas/AllocationRule" rules: type: array items: $ref: "#/components/schemas/GroupAllocationRule" unallocatedCosts: type: string description: Custom label for values that do not fit into allocation (required for group type allocation). nullable: true folderId: type: string description: Identifier of the folder that contains the allocation. Set to "root" if the allocation is at the top level (not in a folder). default: root example: root UpdateAllocationRequest: type: object description: Request body for updating an allocation. properties: name: type: string description: Allocation name nullable: true description: type: string description: Allocation description nullable: true anomalyDetection: type: boolean description: Whether anomaly detection is enabled for this allocation. Only applicable to single allocations. rule: $ref: "#/components/schemas/AllocationRule" rules: type: array items: $ref: "#/components/schemas/GroupAllocationRule" unallocatedCosts: type: string description: Custom label for values that do not fit into allocation (required for group type allocation). nullable: true folderId: type: string description: Identifier of the folder that contains the allocation. Set to "root" if the allocation is at the top level (not in a folder). default: root example: root AllocationListItem: type: object description: Summary information for an allocation. properties: id: type: string description: Allocation ID. name: type: string description: Allocation name. owner: type: string description: Allocation owner. description: type: string description: Allocation description. type: type: string description: Type of allocation (preset or custom). allocationType: type: string description: Composition type of allocation (single or group). enum: - single - group createTime: type: integer description: The time when the allocation was created (in UNIX timestamp). format: int64 updateTime: type: integer description: Last time the allocation was modified (in UNIX timestamp). format: int64 urlUI: type: string description: URL to view the allocation in the DoiT console. folderId: type: string description: Identifier of the folder that contains the allocation. Set to "root" if the allocation is at the top level (not in a folder). default: root example: root anomalyDetection: type: boolean description: Whether anomaly detection is enabled for this allocation. Only applicable to single allocations. AllocationRule: required: - components - formula type: object description: Single allocation rule. Components can reference other existing allocation rules by using the "allocation_rule" dimension type. nullable: true properties: components: type: array description: List of allocation filter components. items: $ref: "#/components/schemas/AllocationComponent" formula: type: string description: Formula for combining components (A is the first component, B is the second one, etc.). example: "A AND B" AllocationDeleteValidation: type: object description: Details about why an allocation cannot be deleted. properties: id: type: string description: Allocation ID. type: type: string description: Type of allocation. enum: - single - group error: type: string description: Error message explaining why deletion failed. resources: type: object description: Map of resources using this allocation, keyed by resource type. additionalProperties: type: array items: $ref: "#/components/schemas/ResourceReference" AnomaliesResponse: type: object description: List of detected cloud cost anomalies. properties: anomalies: type: array items: $ref: "#/components/schemas/AnomalyItem" pageToken: type: string rowCount: type: integer format: int64 AnomalyItem: required: - attribution - billingAccount - costOfAnomaly - platform - scope - serviceName - severityLevel - startTime - timeFrame - top3SKUs - notifications type: object description: >- Detailed information about a detected anomaly. The `notifications` array is always present; list responses return an empty array unless `includeNotifications=true` is requested. properties: attribution: type: string description: Attribution ID. billingAccount: type: string description: Billing account ID. costOfAnomaly: type: number description: Excess cost over and above the expected normal cost. format: double actualCost: type: number format: double nullable: true description: Observed (actual) cost of the anomaly. expectedMaxCost: type: number format: double nullable: true description: Maximum cost within the expected normal range. id: type: string platform: type: string description: Cloud Provider name. scope: type: string description: "Scope: Project or Account" serviceName: type: string description: Service name. severityLevel: type: string description: "Severity level: Information, Warning or Critical" startTime: type: integer description: Usage start time of the anomaly. format: int64 endTime: type: integer nullable: true description: End of the anomaly. timeFrame: type: string description: "Timeframe: Daily or Hourly" top3SKUs: $ref: "#/components/schemas/AnomalySKUArray" resourceData: $ref: "#/components/schemas/AnomalyResourceArray" status: type: string nullable: true enum: - active - inactive acknowledged: description: "Has the anomaly been acknowledged" type: boolean acknowledgedAt: description: "When the anomaly was first acknowledged" type: string format: date-time nullable: true acknowledgedBy: description: "Email of the user who first acknowledged the anomaly" type: string nullable: true notifications: $ref: "#/components/schemas/NotificationEventArray" AnomalySKU: type: object description: SKU-level information contributing to an anomaly. properties: cost: type: number format: double name: type: string AnomalySKUArray: type: array description: Array of SKU entries contributing to an anomaly. items: $ref: "#/components/schemas/AnomalySKU" NotificationEvent: type: object description: |- A successful notification dispatch for an anomaly. This records that the API/worker sent the notification, not that delivery was confirmed. required: - timestamp - channel properties: timestamp: type: string format: date-time description: Dispatch timestamp in RFC3339 UTC. channel: type: string description: Dispatch channel. enum: - email - slack - msteams NotificationEventArray: type: array description: Chronologically ordered notification dispatch events. items: $ref: "#/components/schemas/NotificationEvent" AnomalyResource: type: object description: Resource-specific contribution to an anomaly. properties: cost: type: number format: double resourceId: type: string skuDescription: type: string operation: description: "For anomalies related to AWS S3" type: string labels: type: array description: |- Labels (also known as cost-allocation tags) present on this resource during the anomaly; each entry reports the label's key, its value, and the resource's cost tagged with that key/value pair. Cloud providers use different names for the same concept; GCP uses "labels", AWS uses "cost-allocation tags", and Azure uses "tags". We refer to all of these as labels. items: $ref: "#/components/schemas/AnomalyResourceLabel" AnomalyResourceArray: type: array description: Array of resources contributing to an anomaly. items: $ref: "#/components/schemas/AnomalyResource" AnomalyResourceLabel: type: object description: |- A single label (a.k.a. cost-allocation tag) on the resource, paired with the resource's cost tagged with this key/value pair. properties: key: type: string description: The label/tag key. value: type: string description: The label/tag value. cost: type: number format: double description: The resource's cost tagged with this key/value pair; typically equal to the resource's cost, since labels/tags usually cover all of its spend. AssetResponse: type: object description: Response returned after creating or updating an asset. properties: accountID: type: string LabelInfo: required: - id - name type: object description: Metadata for a label. properties: id: type: string description: The unique identifier of the label. name: type: string description: The name of the label. AnnotationListItem: required: - id - content - timestamp type: object description: Summary information about an annotation. properties: id: type: string description: The unique identifier of the annotation. content: type: string description: The content of the annotation. timestamp: type: string format: date-time description: The date associated with the annotation. reports: type: array items: type: string description: List of report IDs associated with the annotation. labels: type: array items: $ref: "#/components/schemas/LabelInfo" description: List of labels associated with the annotation. createTime: type: string format: date-time description: The creation time of the annotation. updateTime: type: string format: date-time description: The time when the annotation was last updated. CreateAnnotationRequest: required: - content - timestamp type: object description: Request body to create an annotation. properties: content: type: string description: The content of the annotation. timestamp: type: string format: date-time description: The date associated with the annotation. reports: type: array items: type: string description: List of report IDs associated with the annotation. labels: type: array items: type: string description: List of label IDs to associate with the annotation. Labels must already exist. UpdateAnnotationRequest: type: object description: Request body for updating an annotation. properties: content: type: string description: The content of the annotation. nullable: true timestamp: type: string format: date-time description: The date associated with the annotation. nullable: true reports: type: array items: type: string description: List of report IDs associated with the annotation. nullable: true labels: type: array items: type: string description: List of label IDs to associate with the annotation. Labels must already exist. nullable: true LabelListItem: required: - id - name - color type: object description: Label metadata. properties: id: type: string description: The unique identifier of the label. name: type: string description: The name of the label. color: type: string enum: - blue - skyBlue - teal - mint - lime - softYellow - apricot - lavender - purple - rosePink - slateGrey description: The color of the label. type: type: string enum: - custom - preset description: The type of the label (custom or preset). createTime: type: string format: date-time description: The time when the label was created. updateTime: type: string format: date-time description: The time when the label was last updated. LabelList: type: object description: Paged list of labels. properties: pageToken: type: string description: Page token, returned by a previous call, to request the next page of results. rowCount: type: integer description: Total number of labels in the result set. labels: type: array items: $ref: "#/components/schemas/LabelListItem" CreateLabelRequest: required: - name - color type: object description: Request body for creating a label. properties: name: type: string description: The name of the label. color: type: string enum: - blue - skyBlue - teal - mint - lime - softYellow - apricot - lavender - purple - rosePink - slateGrey description: The color of the label. UpdateLabelRequest: type: object description: Request body for updating a label. properties: name: type: string description: The name of the label. nullable: true color: type: string enum: - blue - skyBlue - teal - mint - lime - softYellow - apricot - lavender - purple - rosePink - slateGrey description: The color of the label. nullable: true AssignObjectsToLabelRequest: type: object description: Request to assign or remove objects from a label. properties: add: type: array items: $ref: "#/components/schemas/LabelAssignmentObject" description: Array of objects to assign to the label. remove: type: array items: $ref: "#/components/schemas/LabelAssignmentObject" description: Array of objects to unassign from the label. LabelAssignmentObject: required: - objectId - objectType type: object description: Object identifier and type used for label assignments. properties: objectId: type: string description: The ID of the object to assign/unassign. objectType: type: string enum: - alert - allocation - budget - metric - report - annotation description: The type of the object. LabelAssignmentsResponse: type: object description: Response containing the list of objects assigned to a label. properties: assignments: type: array items: $ref: "#/components/schemas/LabelAssignmentObject" description: Array of objects currently assigned to the label. HexColor: type: string description: A color in hex notation. Accepts `#RGB`, `#RRGGBB`, or `#RRGGBBAA`. pattern: "^#([0-9a-fA-F]{3}|[0-9a-fA-F]{6}|[0-9a-fA-F]{8})$" example: "#1A73E8" ThemeColors: type: object required: - light - dark description: |- Palettes for light and dark display modes. Each palette must contain between 1 and 32 hex colors. properties: light: type: array minItems: 1 maxItems: 32 items: $ref: "#/components/schemas/HexColor" description: Colors used when the report is displayed in light mode. dark: type: array minItems: 1 maxItems: 32 items: $ref: "#/components/schemas/HexColor" description: Colors used when the report is displayed in dark mode. CustomTheme: required: - id - name - primaryColor - colors type: object description: A custom color theme applied to Cloud Analytics reports. properties: id: type: string description: The unique identifier of the custom theme. name: type: string description: The display name of the custom theme. maxLength: 200 primaryColor: $ref: "#/components/schemas/HexColor" colors: $ref: "#/components/schemas/ThemeColors" createTime: type: string format: date-time description: The creation time of the custom theme. updateTime: type: string format: date-time description: The time when the custom theme was last updated. CreateCustomThemeRequest: required: - name - primaryColor - colors type: object description: Request body for creating a custom theme. properties: name: type: string description: The display name of the custom theme. maxLength: 200 primaryColor: $ref: "#/components/schemas/HexColor" colors: $ref: "#/components/schemas/ThemeColors" UpdateCustomThemeRequest: type: object description: Request body for updating a custom theme. Only provided fields are modified. properties: name: type: string description: The display name of the custom theme. maxLength: 200 nullable: true primaryColor: $ref: "#/components/schemas/HexColor" colors: $ref: "#/components/schemas/ThemeColors" ActiveTheme: type: object required: - themeId description: The theme currently active for the authenticated user. properties: themeId: type: string default: "default" description: |- Identifier of the active theme. The reserved sentinel `"default"` is returned when the user is using the built-in default (no custom or preset theme stored). SetActiveThemeRequest: type: object required: - themeId description: Request body for setting the active custom or preset theme for the authenticated user. properties: themeId: type: string default: "default" description: |- Identifier of the theme to activate. Send the reserved sentinel `"default"` to clear the active theme and fall back to the built-in default. Budget: required: - currency - name - scope - startPeriod - timeInterval - type type: object description: Budget configuration used to track spend. properties: alerts: type: array description: Up to three thresholds defined as a percentage of amount. items: $ref: "#/components/schemas/ExternalBudgetAlert" amount: type: number description: |- Budget period amount required: true(if usePrevSpend is false) format: double collaborators: type: array description: List of permitted users to view/edit the report. items: $ref: "#/components/schemas/Collaborator" currency: $ref: "#/components/schemas/Currency" description: type: string description: Budget description. default: '""' endPeriod: type: integer description: |- Fixed budget end date required: true(if budget type is fixed), in milliseconds since the epoch. format: int64 growthPerPeriod: type: number description: Periodical growth percentage in recurring budget. format: double default: 0 id: type: string description: |- budget ID, identifying the report in:path metric: type: string description: Budget metric enum: - cost - amortized_cost default: "cost" name: type: string description: Budget Name public: description: Public sharing access level for the budget. type: string enum: - owner - editor - viewer recipients: type: array description: List of emails to notify when reaching alert threshold items: type: string recipientsSlackChannels: type: array description: List of slack channels to notify when reaching alert threshold. items: $ref: "#/components/schemas/SlackChannel" scope: type: array description: List of allocations that defines the budget scope. items: type: string startPeriod: type: integer description: Budget start Date, in milliseconds since the epoch. format: int64 timeInterval: type: string description: 'Recurring budget interval can be one of: ["day", "week", "month", "quarter", "year"]' type: type: string description: 'budget type can be one of: ["fixed", "recurring"]' usePrevSpend: type: boolean description: Use the last period's spend as the target amount for recurring budgets. default: false BudgetAPI: required: - currency - name - scopes - startPeriod - timeInterval - type type: object description: Budget details and runtime metrics. properties: alerts: type: array description: List of up to three thresholds defined as a percentage of amount. items: $ref: "#/components/schemas/ExternalBudgetAlert" amount: type: number description: |- Budget period amount required: true(if usePrevSpend is false) format: double seasonalAmounts: type: array description: List of seasonal amounts for recurring budgets with different amounts per period. items: type: number format: double collaborators: type: array description: List of permitted users to view/edit the report. items: $ref: "#/components/schemas/Collaborator" createTime: type: integer description: Creation time (in UNIX timestamp). format: int64 currency: $ref: "#/components/schemas/Currency" currentUtilization: type: number format: double description: type: string description: Budget description. endPeriod: type: integer description: |- Fixed budget end date (in UNIX timestamp) required: true(if budget type is fixed) format: int64 forecastedUtilization: type: number format: double growthPerPeriod: type: number description: Periodical growth percentage in recurring budgets. format: double default: 0 id: type: string description: |- budget ID, identifying the report in:path metric: type: string description: Budget metric - currently fixed to "cost" default: "cost" name: type: string description: Budget Name public: description: Public sharing access level for the budget. type: string enum: - owner - editor - viewer recipients: type: array description: List of emails to notify when reaching alert threshold. items: type: string recipientsSlackChannels: type: array description: List of Slack channels to notify when reaching alert threshold. items: $ref: "#/components/schemas/SlackChannel" scope: type: array description: List of allocations that defines the budget scope. items: type: string scopes: type: array description: The filters selected define the scope of the budget. items: $ref: "#/components/schemas/ExternalConfigFilter" startPeriod: type: integer description: Budget start date (in UNIX timestamp). format: int64 timeInterval: type: string description: 'Recurring budget interval can be one of: ["day", "week", "month", "quarter" ,"year"]' type: type: string description: 'budget type can be one of: ["fixed", "recurring"]' updateTime: type: integer description: Update time (in UNIX timestamp). format: int64 usePrevSpend: type: boolean description: Use the last period's spend as the target amount for recurring budgets. default: false BudgetListItem: type: object description: Summary information for a budget. properties: alertThresholds: type: array items: $ref: "#/components/schemas/AlertThreshold" amount: type: number format: double budgetName: type: string createTime: type: integer format: int64 currency: type: string currentUtilization: type: number format: double endPeriod: type: integer format: int64 forecastedUtilizationDate: type: integer format: int64 id: type: string owner: type: string scope: type: array description: List of allocations that define the budget scope. items: type: string deprecated: true scopes: type: array description: The filters selected define the scope of the budget. items: $ref: "#/components/schemas/ExternalConfigFilter" startPeriod: type: integer format: int64 timeInterval: type: string updateTime: type: integer format: int64 url: type: string BudgetCreateUpdateAlert: type: object description: Threshold settings for budget alerts. properties: percentage: type: number format: double BudgetCreateUpdateRequest: type: object description: Request body for creating or updating a budget. properties: alerts: type: array description: List of up to three thresholds defined as a percentage of the amount. items: $ref: "#/components/schemas/BudgetCreateUpdateAlert" amount: type: number description: |- Budget period amount required: true(if usePrevSpend is false) format: double seasonalAmounts: type: array description: List of seasonal amounts for recurring budgets with different amounts per period. items: type: number format: double collaborators: type: array description: List of permitted users to view/edit the report. items: $ref: "#/components/schemas/Collaborator" currency: $ref: "#/components/schemas/Currency" description: type: string description: Budget description default: "" endPeriod: type: integer description: |- Fixed budget end date required: true(if budget type is fixed) format: int64 growthPerPeriod: type: number description: Periodical growth percentage in recurring budget format: double default: 0 metric: type: string description: Budget metric enum: - cost - amortized_cost default: "cost" name: type: string description: Budget Name. public: type: string enum: - owner - editor - viewer recipients: type: array description: List of emails to notify when reaching alert threshold. items: type: string recipientsSlackChannels: type: array description: List of Slack channels to notify when reaching alert threshold. items: $ref: "#/components/schemas/SlackChannel" scope: type: array description: List of allocations that define the budget scope. items: type: string deprecated: true scopes: type: array description: The filters selected define the scope of the budget. items: $ref: "#/components/schemas/ExternalConfigFilter" startPeriod: type: integer description: Budget start Date format: int64 timeInterval: type: string description: 'Recurring budget interval can be one of: ["day", "week", "month", "quarter", "year"]' type: type: string description: 'budget type can be one of: ["fixed", "recurring"]' usePrevSpend: type: boolean description: Use the last period's spend as the target amount for recurring budgets default: false BudgetSuggestion: type: object description: An AI-generated budget recommendation. properties: id: type: string name: type: string description: type: string rationale: type: string description: Explanation of why this budget is suggested. confidence: type: string enum: - high - medium - low amount: type: object description: Suggested budget amount as a decimal-string value with its currency. properties: amount: type: string description: Decimal string, e.g. "1234.56". currency: type: string timeInterval: type: string alertThresholds: type: array description: Suggested alert thresholds as percentages of the amount. items: type: number format: double scopeChips: type: array description: Human-readable summary of the suggested budget scope. items: type: object properties: key: type: string values: type: array items: type: string config: type: object description: Draft budget configuration to merge over the create-budget defaults. additionalProperties: true generatedTime: type: string description: Timestamp when the suggestion was generated. format: date-time status: type: string enum: - pending - accepted - dismissed - skippedDraft BudgetSuggestionAcceptRequest: type: object description: Links a budget suggestion to an existing budget. required: - budgetId properties: budgetId: type: string description: ID of the budget (created via POST /analytics/v1/budgets) to link this suggestion to. editedBeforeAccept: type: boolean description: Whether the customer edited the suggested values before accepting. BudgetSuggestionDismissRequest: type: object description: Optional reason for dismissing a budget suggestion. properties: reason: type: string enum: - not_relevant - wrong_amount - covered_elsewhere - other Collaborator: type: object description: A user or identity that has access to a resource. properties: email: type: string role: type: string enum: - owner - editor - viewer CollectionRef: description: Reference to a Firestore collection. type: object properties: ID: type: string description: The collection identifier. Parent: type: object description: The root collection. Path: type: string description: 'The full resource path of the collection: "projects/P/databases/D/documents..."' Condition: type: string description: >- Type of comparison for the alert threshold (used with `operator` and `value`). If omitted on create, defaults to `percentage-change`. default: percentage-change enum: - value - percentage-change - forecast x-enumDescriptions: value: Actual metric in the selected period (console condition "is"). Example — monthly cost is greater than $100. percentage-change: Percent change versus the previous period (console condition "percentage change is"). Example — daily cost increased by more than 20%. forecast: Forecasted metric for the period (console condition "is forecasted to be"). Cannot be combined with `evaluateForEach`. Currency: description: Currency code for monetary values. type: string enum: - USD - ILS - EUR - AUD - CAD - GBP - DKK - NOK - SEK - BRL - SGD - MXN - CHF - MYR - TWD - EGP - ZAR - JPY - IDR - AED - THB - COP Dimension: description: Definition of a report dimension. type: object properties: id: type: string description: The identifier of the dimension. type: $ref: "#/components/schemas/DimensionsTypes" example: id: sku_description type: fixed DimensionsExternalAPIGetResponse: type: object description: Dimension metadata returned by the API. properties: id: type: string label: type: string type: $ref: "#/components/schemas/DimensionsTypes" values: type: array items: $ref: "#/components/schemas/ExternalAPIGetValue" DimensionsExternalAPIListResponse: type: object description: Paged list of available dimensions. properties: dimensions: type: array description: Array of dimensions. items: $ref: "#/components/schemas/DimensionExternalAPIListItem" pageToken: type: string rowCount: type: integer format: int64 DimensionExternalAPIListItem: type: object description: Summary information about a dimension. properties: id: type: string description: The identifier of the dimension. label: type: string description: The label of the dimension. type: $ref: "#/components/schemas/DimensionsTypes" DimensionsTypes: description: |- Dimension filter type. Always pair `type` with `id` on scope filters. Discover valid `id` + `type` pairs for your account with `GET /analytics/v1/dimensions`. `allocation_rule` replaces `attribution`; `allocation` replaces `attribution_group`. type: string enum: - datetime - fixed - optional - label - tag - project_label - system_label - attribution - attribution_group - allocation - allocation_rule - gke - gke_label x-enumDescriptions: fixed: Standard built-in billing dimensions (Service, Provider, Project/Account ID, SKU, Region, etc.). label: Customer-defined resource labels; id is the label key, values are label values. tag: AWS cost allocation tags; id is the tag key. project_label: Google Cloud project-level labels; id is the label key. system_label: DoiT- or provider-generated system labels; id is the system label key. optional: Console grouping for label/tag keys; use label, tag, project_label, or system_label in API scopes. datetime: Time dimensions (Year, Month, Day) for date-based filtering or grouping. allocation_rule: Allocation rule filter; id must be allocation_rule, values are rule IDs. allocation: Allocation group filter; id is the allocation group ID. gke: Google Kubernetes Engine cost-allocation dimensions. gke_label: GKE workload labels; id is the label key. attribution: "Deprecated. Use allocation_rule." attribution_group: "Deprecated. Use allocation." AllocationDimensionsTypes: description: |- Dimension filter type for allocation rule components. See `DimensionsTypes` for per-value meanings. Allocation components do not support `allocation`, `attribution`, or `attribution_group` types. type: string enum: - datetime - fixed - optional - label - tag - project_label - system_label - allocation_rule - gke - gke_label x-enumDescriptions: fixed: Standard built-in billing dimensions. label: Customer-defined resource labels; key is the label key. tag: AWS cost allocation tags; key is the tag key. project_label: Google Cloud project-level labels. system_label: DoiT- or provider-generated system labels. optional: Console grouping for label/tag keys; use a concrete subtype in filters. datetime: Time dimensions for date-based filtering. allocation_rule: Reference another allocation rule by ID. gke: Google Kubernetes Engine cost-allocation dimensions. gke_label: GKE workload labels. DocumentRef: description: Reference to a Firestore document. type: object properties: ID: type: string description: ID of the document. The last component of the resource path. Parent: $ref: "#/components/schemas/CollectionRef" Path: type: string description: >- The full resource path of the document. A document "doc-1" in collection "coll-1" would be: "projects/P/databases/D/documents/coll-1/doc-1". Error: type: object description: Standard error response structure. properties: error: type: string description: Detailed error message. ExternalAPIGetValue: type: object description: Single value entry used by some dimension endpoints. properties: cloud: type: string value: type: string ExternalAlertList: type: object description: List of alerts. properties: pageToken: type: string description: Page token. It is used to request a specific page of the list results. example: bDl0QkEwVFZxUEwxaUJRaHhTcXM rowCount: type: integer description: The number of returned records. format: int64 example: 1 alerts: type: array description: Array of alerts. items: $ref: "#/components/schemas/AlertListItem" ExternalBudgetAlert: type: object description: Budget alert status details. properties: forecastedDate: type: integer format: int64 percentage: type: number format: double triggered: type: boolean ExternalConfig: type: object description: Report configuration. properties: metric: deprecated: true description: "Deprecated: Use 'metrics' instead." allOf: - $ref: "#/components/schemas/ExternalMetric" metrics: type: array description: The list of metrics to apply to the report. Custom metric can be used only once. Maximum number of metrics is 4. items: $ref: "#/components/schemas/ExternalMetric" metricFilter: $ref: "#/components/schemas/ExternalConfigMetricFilter" limitAggregation: type: string description: |- Controls how rows excluded by limits are rendered. Applies when any limit type is active (`metricFilter`, `limitByChange`, or a `group` entry with a `limit`). A report may configure at most two of those three limit types — not all three. When `displayValues` is not `actuals_only`, this field must be `none` (or omitted, which defaults to `none`). enum: - none - top - all default: none limitByChange: $ref: "#/components/schemas/ExternalLimitByChange" aggregation: description: How to aggregate data values in the report. type: string enum: - total - percent_total - percent_col - percent_row - total_over_total - count advancedAnalysis: $ref: "#/components/schemas/AdvancedAnalysis" forecastSettings: allOf: - $ref: "#/components/schemas/ExternalForecastSettings" nullable: true description: |- Forecast configuration. On PATCH, omit to preserve existing settings; send null to clear/disable forecasting. timeInterval: description: Time interval for grouping data in the report. type: string enum: - hour - day - dayCumSum - week - isoweek - month - quarter - year - week_day dimensions: description: See [Dimensions](https://help.doit.com/docs/cloud-analytics/reports/editing-your-cloud-report#dimensions). type: array items: $ref: "#/components/schemas/Dimension" timeRange: $ref: "#/components/schemas/TimeSettings" secondaryTimeRange: $ref: "#/components/schemas/TimeSettingsSecondary" includePromotionalCredits: type: boolean description: |- Whether to include [promotional credits](https://help.doit.com/docs/cloud-analytics/reports/editing-your-cloud-report#promotional-credits). If set to **true**, the report must use time interval `month`, `quarter`, or `year`. includeSubtotals: type: boolean description: |- Whether to include subgroup totals in the report. This option has no impact when reading a report via API. default: false filters: type: array description: The filters to apply to the report. items: $ref: "#/components/schemas/ExternalConfigFilter" group: type: array description: |- The rows that appear in the tabular format of the report. See [Group by](https://help.doit.com/docs/cloud-analytics/reports/editing-your-cloud-report#group-by). items: $ref: "#/components/schemas/Group" layout: $ref: "#/components/schemas/ExternalRenderer" displayValues: type: string description: See [View data as (Comparative report)](https://help.doit.com/docs/cloud-analytics/reports/editing-your-cloud-report#view-as). enum: - actuals_only - absolute_change - percentage_change - absolute_and_percentage currency: $ref: "#/components/schemas/Currency" sortGroups: type: string default: asc enum: - asc - desc - a_to_z description: This option has no impact when reading reports via API. sortDimensions: type: string default: desc enum: - asc - desc - a_to_z description: This option has no impact when reading reports via API. dataSource: type: string description: Data source of the report. enum: - billing - bqlens - billing-datahub - kubernetes-utilization splits: type: array description: The splits to use in the report. items: $ref: "#/components/schemas/ExternalSplit" displaySettings: $ref: "#/components/schemas/ExternalDisplaySettings" customTimeRange: description: Required when the time range is set to "custom". type: object properties: from: type: string format: date-time description: The start timestamp of the time range in RFC3339 format. example: "2024-03-10T23:00:00Z" to: type: string format: date-time description: The end timestamp of the time range in RFC3339 format. example: "2024-03-12T23:00:00Z" count: type: object description: |- The field to count distinct values of. Only applicable when aggregation is set to "count". required: - id - type properties: id: type: string description: The field identifier to count distinct values of. type: type: string enum: - fixed - label - tag - project_label - system_label description: The metadata field type. example: metrics: - type: basic value: cost - type: basic value: usage - type: extended value: amortized_cost metricFilter: metric: type: basic value: cost operator: nb values: - -1 - 1 operand: series_total limitAggregation: top limitByChange: metric: type: basic value: cost changeType: percentage operator: ">=" values: - 50 aggregation: total advancedAnalysis: forecast: false notTrending: false trendingDown: false trendingUp: false forecastSettings: mode: totals futureTimeIntervals: 3 timeInterval: month dimensions: - id: year type: datetime - id: month type: datetime timeRange: amount: 3 includeCurrent: false mode: last unit: month includePromotionalCredits: false includeSubtotals: false filters: - id: attribution type: attribution values: - RB8DndcxODriK83IBXXf - D7r4znsTj2UC95zGnunW inverse: true - id: cloud_provider type: fixed values: - amazon-web-services - google-cloud - microsoft-azure group: - id: service_description limit: metric: type: basic value: cost sort: a_to_z value: 0 type: fixed layout: table displayValues: actuals_only currency: USD sortGroups: a_to_z sortDimensions: a_to_z dataSource: billing ExternalDisplaySettings: type: object description: Display settings for the report. properties: themeId: type: string default: "default" description: |- Identifier of the theme applied to the report. The reserved sentinel `"default"` is returned on GET when no theme is stored and clears the stored value on PATCH. Omit the field on PATCH to leave the stored value unchanged. dataLabelFontSize: type: string description: Font size used for data labels on charts. enum: - auto - small - medium - large axisLabelFontSize: type: string description: Font size used for axis labels on charts. enum: - auto - small - medium - large numberScale: type: string description: Scale applied to numeric values when rendering the report. enum: - auto - thousands - millions - billions - raw decimalPrecision: type: integer minimum: 0 maximum: 8 description: Number of decimal places shown for numeric values. ExternalConfigFilter: description: |- To include or exclude certain values. When using allocation rules as a filter, both the type and the ID must be "allocation_rule", and the values array contains the allocation rule IDs. When using allocations as a filter, the type must be "allocation" and the ID is the actual allocation group ID. type: object required: - id - type properties: id: type: string description: >- Dimension key to filter on. Must pair with `type` and match a dimension returned by `GET /analytics/v1/dimensions` (for example, `service_description` with `type: fixed`). For `allocation_rule`, use `allocation_rule`. For `allocation`, use the allocation group ID. See `DimensionsTypes` for how each `type` uses `id`. type: $ref: "#/components/schemas/DimensionsTypes" values: type: array description: >- List of values to include or exclude. Must match exact strings from your billing or DataHub data for the dimension (for example, `Amazon Simple Storage Service` for AWS S3 on `service_description`). For `allocation_rule`, use allocation rule IDs. items: type: string mode: type: string description: Controls how the dimension’s `values` are matched when the alert query runs. If mode is omitted, behavior defaults to is. enum: - is - starts_with - ends_with - contains - regexp x-enumDescriptions: is: Exact match on one or more values. starts_with: Value starts with the given string(s). ends_with: Value ends with the given string(s). contains: Value contains the given string(s). regexp: Value matches the regular expression in `values` (exactly one pattern). inverse: type: boolean description: Set to `true` to exclude the set values. If inverse is omitted, behavior defaults to `false`. caseInsensitive: type: boolean description: If true, string matching is case-insensitive. Effective only for starts_with, ends_with, and contains modes; ignored otherwise. default: false includeNull: type: boolean description: Include rows where the dimension is null. If includeNull is omitted, behavior defaults to `false`. default: false example: id: cloud_provider type: fixed inverse: false values: - google-cloud ExternalConfigMetricFilter: description: Metric filter to limit report rows by metric value. type: object required: - metric - operator - values properties: metric: $ref: "#/components/schemas/ExternalMetric" operator: description: |- Comparison operator for filtering metric values. Uses short names (`gt`, `gte`, …). `limitByChange.operator` uses SQL-style symbols (`>`, `>=`, …) instead. type: string enum: - gt - lt - lte - gte - b - nb - e - ne values: type: array items: type: number format: double operand: type: string description: |- Whether the threshold applies to each value (default) or the series total. Same field as the DoiT Console metric filter `operand` (`OperandSingleValue` / `OperandSeriesTotal`). On input, omitted defaults to `single_value`. GET responses echo the effective value (`single_value` or `series_total`). enum: - single_value - series_total default: single_value example: metric: type: basic value: cost operator: gt values: - 50 ExternalLimitByChange: description: |- Limit by change filter. A report may configure at most two of `metricFilter`, `limitByChange`, and top/bottom `group` limits — not all three. type: object required: - metric - changeType - operator - values - includeIncompleteData properties: metric: $ref: "#/components/schemas/ExternalMetric" changeType: type: string enum: - percentage - absolute operator: type: string description: Comparison operator for period-over-period deltas. enum: - ">" - ">=" - "<" - "<=" - between - not_between values: type: array description: |- Threshold value(s). Unary operators use one entry; `between` and `not_between` require two ordered entries. items: type: number format: double includeIncompleteData: type: boolean description: When true, keeps rows whose deltas could not be evaluated. example: metric: type: basic value: cost changeType: percentage operator: ">=" values: - 50 includeIncompleteData: false ExternalMetric: description: Metric selector used in reports and filters. type: object required: - type - value properties: type: description: Type of metric to use. type: string enum: - basic - custom - extended value: type: string description: >- For basic metrics, the value can be one of: ["cost", "usage", "savings"] If using custom metrics, the value must refer to an existing custom metric ID. example: type: basic value: cost ExternalOrigin: type: object description: Origin info for cost splitting. properties: id: type: string description: ID of the origin. type: type: string description: |- Type of the origin. example: "attribution" enum: - datetime - fixed - optional - label - tag - project_label - system_label - attribution - attribution_group - gke - gke_label - unallocated ExternalRenderer: type: string description: Type of visualization or output format. enum: - column_chart - stacked_column_chart - bar_chart - stacked_bar_chart - line_chart - spline_chart - area_chart - area_spline_chart - stacked_area_chart - treemap_chart - table - table_heatmap - table_row_heatmap - table_col_heatmap - csv_export - sheets_export Folder: type: object description: A Cloud Analytics folder. properties: id: type: string description: Folder ID. name: type: string description: Folder name. description: type: string description: Folder description. parentFolderId: type: string description: Identifier of the parent folder. Set to "root" if the folder is at the top level. default: root example: root CreateFolderRequest: required: - name type: object description: Request body for creating a folder. properties: name: type: string description: Folder name. description: type: string description: Folder description. parentFolderId: type: string description: Identifier of the parent folder. Use "root" or omit to place the folder at the top level. default: root example: root UpdateFolderRequest: type: object description: |- Request body for updating a folder. All fields are optional; only fields the caller wants to change should be set. properties: name: type: string description: Folder name. description: type: string description: Folder description. parentFolderId: type: string description: >- Identifier of the new parent folder. Use "root" to move the folder to the top level. If a sibling at the new parent has the same name, the folder is auto-renamed (e.g. "Foo" → "Foo (1)"). default: root example: root ExternalReport: required: - name type: object description: Configuration and metadata of a stored report. properties: id: type: string description: Report ID. name: type: string description: Report name. description: type: string description: Report description. type: type: string description: Report type. enum: - custom - preset - managed config: $ref: "#/components/schemas/ExternalConfig" labels: type: array items: type: string description: Array of label IDs assigned to the report folderId: type: string description: Identifier of the folder that contains the report. Set to "root" if the report is at the top level (not in a folder). default: root example: root ExternalSplit: type: object description: Specification of how to split costs. properties: id: type: string description: ID of the field to split. includeOrigin: type: boolean description: Indicate whether to include the origin. mode: type: string enum: - even - custom - proportional origin: $ref: "#/components/schemas/ExternalOrigin" targets: type: array description: Targets for the split. items: $ref: "#/components/schemas/ExternalSplitTarget" type: type: string description: |- Type of the split. example: "attribution_group" enum: - datetime - fixed - optional - label - tag - project_label - system_label - attribution - attribution_group - gke - gke_label ExternalSplitTarget: type: object description: Target and value of a split definition. properties: id: type: string description: ID of the target. type: type: string description: |- Type of the target. If split type is "attribution_group", then target type must be "attribution". Otherwise split types and target types must be the same. example: "attribution" enum: - datetime - fixed - optional - label - tag - project_label - system_label - attribution - attribution_group - gke - gke_label value: type: number description: Percent of the target, represented in float format. E.g. 30% is 0.3. Required only if the Split Mode is custom. format: double ExternalUpdateReport: type: object description: Partial report object used for updates. properties: config: $ref: "#/components/schemas/ExternalConfig" description: type: string description: Report description name: type: string description: Report name labels: type: array items: type: string description: Array of label IDs assigned to the report folderId: type: string description: Identifier of the folder that contains the report. Set to "root" if the report is at the top level (not in a folder). default: root example: root example: config: timeRange: amount: 1 includeCurrent: false mode: last unit: month timeInterval: week description: An update via API name: A new name Allocation: type: object description: Allocation object, including rules and metadata. properties: id: type: string description: Allocation ID. name: type: string description: Allocation name. description: type: string description: Allocation description. type: type: string description: Type of allocation (preset or custom). allocationType: type: string description: Composition type of allocation. enum: - single - group createTime: type: integer description: The time when the allocation was created (in UNIX timestamp). format: int64 updateTime: type: integer description: Last time the allocation was modified (in UNIX timestamp). format: int64 anomalyDetection: type: boolean description: Whether anomaly detection is enabled for this allocation. Only applicable to single allocations. rule: $ref: "#/components/schemas/AllocationRule" rules: type: array items: $ref: "#/components/schemas/GroupAllocationRule" unallocatedCosts: type: string description: Custom label for values that do not fit into allocation (required for group type allocation). nullable: true folderId: type: string description: Identifier of the folder that contains the allocation. Set to "root" if the allocation is at the top level (not in a folder). default: root example: root GroupAllocationRule: required: - action type: object nullable: true description: Allocation rule for a group type allocation. Components can reference other existing allocation rules by using the "allocation_rule" dimension type. properties: name: type: string description: Name of the allocation rule. description: type: string description: Description of the allocation rule. action: type: string description: Action to perform with this rule. enum: - create - update - select id: type: string description: ID of existing allocation (required for 'update' or 'select' action). components: type: array description: List of allocation filter components (required for 'create' or 'update' action). Can include components of type "allocation_rule" to reference existing allocation rules. items: $ref: "#/components/schemas/AllocationComponent" formula: type: string description: Formula for combining components (A is the first component, B is the second one, etc.) example: "A AND B" ResourcePermissionsResponse: type: object description: Permissions and metadata for a resource returned by the sharing API. properties: id: type: string description: Resource ID. name: type: string description: Resource name. description: type: string description: Resource description. createTime: type: integer description: The time when this resource was created, in milliseconds since the epoch. format: int64 updateTime: type: integer description: The time when this resource was last updated, in milliseconds since the epoch. format: int64 permissions: type: array items: $ref: "#/components/schemas/ResourcePermission" public: type: string description: Type of permissions users in the entire organization have for this resource enum: - editor - viewer nullable: true ResourcePermission: type: object description: A single user's permission entry for a resource. properties: user: type: string description: The email address of the user to whom the role is assigned. role: type: string description: The role assigned to the user, defining their level of access to the resource. enum: - owner - editor - viewer Filter: type: string description: >- An expression for filtering the results. The syntax is `key:[]`. Multiple filters can be connected using a pipe |. See [Filters](https://developer.doit.com/docs/filters). Group: description: The dimension that defines a row in the report. type: object properties: id: type: string description: Dimension ID. example: service_description limit: $ref: "#/components/schemas/Limit" type: $ref: "#/components/schemas/DimensionsTypes" example: id: service_description type: fixed limit: value: 3 sort: desc metric: type: basic value: cost InvoiceListItem: type: object description: Summary information about an invoice. properties: id: type: string description: Invoice number, identifying the invoice. invoiceDate: type: integer description: The time when this invoice was issued, in milliseconds since the epoch. format: int64 platform: $ref: "#/components/schemas/InvoicePlatform" dueDate: type: integer description: The last day to pay the invoice, in milliseconds since the epoch format: int64 status: type: string description: Status of the invoice enum: - OPEN - PAST DUE - PAID totalAmount: type: number description: Total invoiced amount format: double balanceAmount: type: number description: Invoice balance to be paid format: double currency: $ref: "#/components/schemas/Currency" url: type: string description: Link to [invoice details page](https://help.doit.com/docs/billing/invoices-and-payments/managing-invoices) in the DoiT console. You can download the PDF invoice from the invoice details page. InvoicePlatform: type: string description: Platform identifier for invoice source. enum: - google-cloud - amazon-web-services - microsoft-azure - g-suite - office-365 - superquery - looker - navigator - solve CloudIncidentListItem: type: object description: Summary information for a cloud incident. properties: createTime: type: integer description: The creation time of this cloud incident, in milliseconds since the epoch. format: int64 id: type: string description: The unique cloud incident identifier. platform: type: string description: The Cloud Platform. enum: - google-cloud - amazon-web-services - microsoft-azure product: type: string description: The name of the product affected by the cloud incident status: type: string description: The Status of the issue enum: - active - archived title: type: string description: Cloud incident name as provided by the cloud platform vendor Limit: type: object description: |- To limit the number of results based on ranking. See [Limit by top/bottom](https://help.doit.com/docs/cloud-analytics/reports/editing-your-cloud-report#limit-by-topbottom). required: - metric properties: metric: $ref: "#/components/schemas/ExternalMetric" sort: description: Sort order for ranking results. type: string enum: - a_to_z - asc - desc value: type: integer description: The number of items to show format: int64 example: value: 3 sort: desc metric: type: basic value: cost ListItem: type: object description: Invoice line item. properties: currency: type: string description: type: string details: type: string price: type: number format: double qty: type: number format: double type: type: string MetricConfig: type: object description: Define how metrics are selected and filtered in reports. required: - type - value properties: type: $ref: "#/components/schemas/MetricType" value: type: string MetricFilterText: type: string description: Text/operator used to filter metric values in metric filters (gt = greater than, lt = less than). enum: - gt - lt MetricType: type: string description: Identifier for metric type (e.g., basic, custom, extended). ObjectType: type: string description: Generic object type identifier. PlatformAPI: type: object description: Platform metadata used by product listing endpoints. properties: displayName: type: string id: type: string ProductAPI: type: object description: Platform/product metadata used by product listing endpoints. properties: displayName: type: string id: type: string platform: type: string GetReportResponse: type: object description: Results returned when running a report; includes schema and rows. properties: id: type: string description: Report ID. reportName: type: string description: The name of the report. owner: type: string description: Email address of the report owner. type: type: string enum: - custom - preset createTime: type: integer description: The creation time of the report, in milliseconds since the epoch. format: int64 updateTime: type: integer description: The time when this report was last updated, in milliseconds since the epoch. format: int64 urlUI: type: string description: The URL of the report in DoiT console. labels: type: array items: $ref: "#/components/schemas/LabelInfo" description: List of labels associated with the report. result: type: object properties: schema: type: array items: $ref: "#/components/schemas/SchemaField" mlFeatures: type: array items: type: string enum: - increasing - decreasing - none - forecast rows: type: array items: type: array items: $ref: "#/components/schemas/Value" secondaryRows: type: array description: Secondary time range rows. items: type: array items: $ref: "#/components/schemas/Value" forecastRows: type: array items: type: array items: $ref: "#/components/schemas/Value" cacheHit: type: boolean description: If true, results were fetched from the cache. Report: type: object description: Report metadata and the console URL. properties: id: type: string description: Report ID. reportName: type: string description: The name of the report. owner: type: string description: Email address of the report owner. type: type: string enum: - custom - preset createTime: type: integer description: The creation time of the report, in milliseconds since the epoch. format: int64 updateTime: type: integer description: The time when this report was last updated, in milliseconds since the epoch. format: int64 urlUI: type: string description: The URL of the report in DoiT console. labels: type: array items: $ref: "#/components/schemas/LabelInfo" description: List of labels associated with the report. ReportList: type: object description: List of reports. properties: pageToken: type: string description: Page token. It is used to request a specific page of the list results. rowCount: type: integer description: The number of returned records. format: int64 example: 5 reports: type: array items: $ref: "#/components/schemas/Report" RunReportResult: type: object description: Results returned when running a report; includes schema and rows. properties: result: type: object properties: schema: type: array items: $ref: "#/components/schemas/SchemaField" mlFeatures: type: array items: type: string enum: - increasing - decreasing - none - forecast rows: type: array items: type: array items: $ref: "#/components/schemas/Value" secondaryRows: type: array description: Secondary time range rows. items: type: array items: $ref: "#/components/schemas/Value" forecastRows: type: array items: type: array items: $ref: "#/components/schemas/Value" cacheHit: type: boolean description: If true, results were fetched from the cache. SchemaField: type: object description: Schema of a report result column. properties: name: type: string type: type: string SlackChannel: type: object description: Information of a Slack channel for notifications. properties: customerId: type: string id: type: string name: type: string shared: type: boolean type: type: string workspace: type: string ServiceQuotaList: type: object required: - items - rowCount properties: items: type: array description: Service quotas in this page. items: $ref: "#/components/schemas/ServiceQuota" pageToken: type: string description: Opaque token for the next page. Omitted when there are no more results. rowCount: type: integer format: int64 description: Total number of results after filtering and before pagination. ServiceQuota: type: object required: - cloudProvider - resource - service - quota - limit - usage - utilizationPercent - status - observedAt properties: cloudProvider: type: string description: Cloud provider that owns the quota. enum: - aws - gcp resource: $ref: "#/components/schemas/ServiceQuotaResource" service: type: string description: Cloud service associated with the quota. example: Compute Engine quota: type: string description: Provider quota or metric name. example: CPUS region: type: string description: Cloud region associated with the quota. Omitted for global quotas. example: us-central1 limit: type: number format: double description: Current quota limit. example: 100 usage: type: number format: double description: Current measured quota usage. example: 85 utilizationPercent: type: number format: double description: Usage divided by limit, expressed as a percentage. example: 85 status: type: string description: Normalized utilization status. Warning begins at 80 percent; exceeded begins at 100 percent. enum: - ok - warning - exceeded observedAt: type: string format: date-time description: Time when DoiT last updated the provider snapshot. example: "2026-07-17T12:00:00Z" ServiceQuotaResource: type: object required: - type - id properties: type: type: string description: Provider resource scope for the quota. enum: - account - project id: type: string description: AWS account ID or Google Cloud project ID. example: example-project name: type: string description: Human-readable resource name when available. example: Example Project SupportedFeaturesResponse: type: object description: Response containing the supported features for a CloudConnect account. properties: supportedFeatures: type: array description: List of features and their permission status. items: $ref: "#/components/schemas/SupportedFeature" SupportedFeature: type: object description: A feature supported by a CloudConnect account. properties: name: type: string description: The name of the feature. example: "sandbox" hasRequiredPermissions: type: boolean description: Whether the connected account has the required permissions for this feature. example: true TimeSettings: type: object description: >- Specify a predefined or custom time range for the report. For example, to specify a custom time range of "last 2 days", set the mode to `last`, the amount to `2`, and the unit to `day`. If `includeCurrent` is `true`, the range will be yesterday and today; otherwise, the range will be yesterday and the day before yesterday. If "custom" type is specified, you need to provide a custom time range in the `customTimeRange` field. properties: amount: description: Number of time units to include in the time range. maximum: 5000 minimum: 0 type: integer format: int64 includeCurrent: description: Whether to include the current time period. type: boolean mode: description: Time range mode (last N periods, current period, or custom). type: string enum: - last - current - custom unit: description: Time unit for the time range. type: string enum: - day - week - month - quarter - year example: amount: 3 includeCurrent: false mode: last unit: month TimeSettingsSecondary: type: object description: Secondary time range for comparative reports. properties: amount: description: Number of periods to shift back. type: integer format: int64 includeCurrent: description: >- Whether to align to complete previous periods (full year/quarter/month) vs shifting dates by amount. When `true`, selects complete periods (e.g., full previous year Jan 1-Dec 31, not up to today). When `false`, shifts dates by amount, which may result in partial periods extending to today. type: boolean unit: description: Time interval unit for shifting. type: string enum: - day - month - quarter - year customTimeRange: description: Custom date range for the secondary time range. type: object properties: from: type: string format: date-time description: Start date. to: type: string format: date-time description: End date. example: amount: 1 includeCurrent: false unit: year ValidateResponse: type: object description: A response confirming caller's domain and email. properties: domain: type: string email: type: string Value: description: The content of a single cell from a BigQuery result. Can be a string, number, or null. nullable: true oneOf: - type: string - type: number - type: integer 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. 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" 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" 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." 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 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." 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." 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 TicketCreateFormExtAPI: type: object description: Wrapper object for creating support tickets via the external API. x-cloudflow-labels: ticket: "Ticket details" properties: ticket: $ref: "#/components/schemas/TicketExtAPI" required: - ticket TicketExtAPI: type: object description: Payload to create a support ticket via API. required: - body - platform - product - severity - subject properties: body: type: string description: The body of the ticket (can include html formatting). x-cloudflow-format: "multiReference" created: type: string description: Ticket creation time. platform: type: string description: Platform of the ticket. enum: - doit - google_cloud_platform - amazon_web_services - microsoft_azure product: type: string description: Ticket product details. severity: type: string description: Ticket severity. enum: - low - normal - high - urgent x-cloudflow-format: "noReference" subject: type: string description: The subject of the ticket. TicketListItem: type: object description: Summary information about a support ticket. properties: createTime: type: integer description: The time when this ticket was created, in milliseconds since the epoch. format: int64 id: type: integer description: Ticket ID (e.g., "33234"). format: int64 is_public: type: boolean description: Whether the ticket is public. platform: type: string description: Platform of the ticket. enum: - doit - google_cloud_platform - amazon_web_services - microsoft_azure product: type: string description: Ticket product. requester: type: string description: The ticket requester in the form of user@domain.com severity: type: string description: Ticket severity. status: type: string description: Ticket status. subject: type: string description: The subject of the ticket. updateTime: type: integer description: The time when this ticket was last updated, in milliseconds since the epoch. format: int64 urlUI: type: string description: Link to the report in DoiT console. tags: type: array items: type: string description: |- Ticket tags, filtered by caller type. DoiT employee (doer) callers receive the full tag set verbatim, including internal namespaces (e.g. `tier/*`, `synapse_*`). Customer callers receive only tags under the `customer_tag/` namespace, with that prefix stripped. Always present; empty array when the caller has no visible tags. TicketResponseExtAPI: type: object description: Response returned after creating a ticket. properties: created: type: integer description: Ticket creation time. format: int64 id: type: integer description: Ticket ID. format: int64 platform: type: string description: Ticket platform. enum: - doit - google_cloud_platform - amazon_web_services - microsoft_azure product: type: string description: Ticket product. requester: type: string description: Email address of the requester. severity: type: string description: Severity of the ticket. enum: - low - normal - high - urgent status: type: string description: Ticket status. subject: type: string description: Ticket subject. urlUI: type: string description: URL to access the ticket in DoiT console. TicketsList: type: object description: List of support tickets. properties: pageToken: type: string description: Page token, returned by a previous call, to request the next page of results. rowCount: type: integer description: Tickets rows count format: int64 tickets: type: array items: $ref: "#/components/schemas/TicketListItem" TicketDetailExtAPI: type: object description: Detailed information about a single support ticket. properties: id: type: integer description: Ticket ID. format: int64 subject: type: string description: The subject of the ticket. description: type: string description: The body of the initial ticket message. requester: type: string description: Email address of the ticket requester. severity: type: string description: Ticket severity. enum: - low - normal - high - urgent platform: type: string description: Platform of the ticket. enum: - doit - google_cloud_platform - amazon_web_services - microsoft_azure product: type: string description: Ticket product. platform_info: type: string description: |- The cloud asset identifier(s) the requester selected on the support form's asset-selector control — typically the GCP project ID, AWS account ID, Azure subscription ID, or equivalent. May contain multiple identifiers as a comma-separated list (no spaces) when the requester selected more than one asset, e.g. "111111111111,222222222222". Empty string when the ticket has no asset value (e.g. older tickets or tickets opened through paths that bypass the form selector). example: cmp-playground status: type: string description: Ticket status. createTime: type: integer description: The time when this ticket was created, in milliseconds since the epoch. format: int64 updateTime: type: integer description: The time when this ticket was last updated, in milliseconds since the epoch. format: int64 urlUI: type: string description: Link to the ticket in DoiT console. is_public: type: boolean description: Whether the ticket is public. tags: type: array items: type: string description: |- Ticket tags, filtered by caller type. DoiT employee (doer) callers receive the full tag set verbatim, including internal namespaces (e.g. `tier/*`, `synapse_*`). Customer callers receive only tags under the `customer_tag/` namespace, with that prefix stripped (e.g. a tag added as `billing` reads back as `billing`). Always present; empty array when the caller has no visible tags. CommentExtAPI: type: object description: A comment on a support ticket. properties: id: type: integer description: Comment ID. format: int64 body: type: string description: The text content of the comment. author: type: string description: Email address of the comment author. created: type: integer description: The time when this comment was created, in milliseconds since the epoch. format: int64 attachments: type: array description: File attachments on the comment. items: type: object properties: id: type: integer format: int64 file_name: type: string content_url: type: string CommentsResponseExtAPI: type: object description: Response containing all comments on a support ticket. properties: comments: type: array items: $ref: "#/components/schemas/CommentExtAPI" CreateCommentRequest: type: object description: Request body for adding a comment to a support ticket. required: - body properties: body: type: string description: The text content of the comment. Must not be empty. private: type: boolean description: If true, creates a private internal note. Only honored for DoiT employees; ignored for customers. default: false TagsRequest: type: object description: | Request body for adding (POST) or removing (DELETE) tags on a support request. The operation is surgical — only the tags listed are affected; any other tags on the ticket are preserved. required: - tags properties: tags: type: array minItems: 1 maxItems: 50 items: type: string minLength: 1 maxLength: 80 description: List of tags to add or remove. Customer-submitted tags are auto-prefixed with `customer_tag/`. TagsResponse: type: object description: | Response body echoing the tags the operation actually acted on, after server-side transformation (trim + lowercase + customer namespace prefix where applicable). properties: applied_tags: type: array items: type: string description: The tags that were stored on (POST) or removed from (DELETE) the ticket. TagsGetResponse: type: object description: |- Response body for GET /support/v1/tickets/{ticketId}/tags. Contains the current tags visible to the caller. properties: tags: type: array items: type: string description: |- Ticket tags, filtered by caller type. DoiT employee (doer) callers receive the full tag set verbatim, including internal namespaces (e.g. `tier/*`, `synapse_*`). Customer callers receive only tags under the `customer_tag/` namespace, with that prefix stripped. Always present; empty array when the caller has no visible tags. ResourceReference: type: object description: Reference to another resource, used when listing blockers or usages. properties: id: type: string description: Resource identifier name: type: string description: Resource name owner: type: string description: Resource owner (only present if requester doesn't have access) BlockingResources: type: object description: Map of resources that block deletion operations. properties: alerts: type: array description: List of alerts using this resource. items: $ref: "#/components/schemas/ResourceReference" attributionGroups: type: array description: List of attribution groups using this resource (only applicable for attribution deletion). items: $ref: "#/components/schemas/ResourceReference" attributions: type: array description: List of attributions using this resource (only applicable for attribution deletion). items: $ref: "#/components/schemas/ResourceReference" budgets: type: array description: List of budgets using this resource. items: $ref: "#/components/schemas/ResourceReference" reports: type: array description: List of reports using this resource. items: $ref: "#/components/schemas/ResourceReference" example: budgets: - id: "budget-id" name: "Example Budget" Role: type: object description: Definition and permissions assigned to a role. properties: id: type: string description: The unique ID of the role. name: type: string description: The name of the role. type: type: string description: The type of the role (preset or custom). customer: type: string description: The customer ID if this is a custom role. permissions: type: array description: List of permission IDs assigned to the role. items: type: string FindCloudDiagramsRequest: type: object required: - resources description: Request body for locating cloud diagrams for given resource IDs. properties: resources: type: array description: Resource IDs to find diagrams for. items: type: string FindCloudDiagramsResponse: type: array description: List of diagram URLs matching the criteria. items: type: object required: - diagramUrl - imageUrl properties: diagramUrl: type: string format: uri description: URL to the diagram viewer. imageUrl: type: string format: uri description: URL to the diagram image. CloudDiagramStats: type: object description: Diagram with activity stats for a given time period. properties: _id: type: string description: ID of the diagram. ss_id: type: string description: ID of the layer the diagram belongs to. name: type: string description: Name of the diagram. type: type: string enum: - application - infrastructure - network - template description: Type of the diagram. account_name: type: string description: Cloud account name. account_id: type: string description: Cloud account ID. account_type: type: string description: Cloud account type. changes: type: array description: Activity changes within the period. items: $ref: "#/components/schemas/CloudDiagramStatsChange" import: $ref: "#/components/schemas/CloudDiagramImportState" CloudDiagramStatsChange: type: object description: A single activity change entry in a diagram stats record. properties: type: type: string enum: - NODE_CREATE - NODE_UPDATE - NODE_DELETE description: Type of the change. service: type: string description: Cloud service the change applies to. count: type: integer description: Number of occurrences of this change type. CloudDiagramImportState: type: object description: Current import/sync state for a cloud-connected diagram. properties: status: type: string enum: - queued - in_progress - success - failure description: Import status. type: type: string enum: - AWS - GCP - AZURE description: Connected cloud account type. account: type: string description: Connected account ID. cloudId: type: string description: Cloud account ID. errorMessage: type: string description: Error message if the import failed. syncedAt: type: string format: date-time description: Timestamp of the last successful sync. CloudDiagramIssue: type: object description: Issue annotation linked to a component. properties: _id: type: string description: Issue reference ID. comment: type: string description: Optional comment on the issue. snoozed: type: number description: Snooze duration in seconds. jira: type: string description: Linked Jira ticket key or URL. CloudDiagramInfraNodeRef: type: object required: - _id - scheme_id - ss_id description: Reference to a linked infrastructure node in another diagram. properties: _id: type: string description: Infrastructure node ID. scheme_id: type: string description: Parent diagram ID. ss_id: type: string description: Parent layer ID. CloudDiagramNode: type: object required: - _id description: A node component (host, service, or application component). properties: _id: type: string description: Node ID. name: type: string description: Component name. props: type: object additionalProperties: true description: Custom component properties (key-value pairs). cld_id: type: string description: Cloud resource ID (set on cloud-imported components). cld_type: type: string enum: - AWS - GCP - AZURE description: Cloud account type. cld_sync: type: boolean description: Whether this component is synced with cloud. cld_account: type: string description: Cloud account ID. tags: type: array description: Tags assigned to the component. items: type: string color: type: string description: Node color. icon: type: string description: Node icon identifier. parent: type: string description: Parent node ID. infra_node: $ref: "#/components/schemas/CloudDiagramInfraNodeRef" instance_count: type: integer description: Number of instances represented by this node. running: type: boolean description: Whether the node is currently running. issues: type: array description: Issues associated with this node. items: $ref: "#/components/schemas/CloudDiagramIssue" CloudDiagramElement: type: object required: - _id description: An element component (application-layer component). properties: _id: type: string description: Element ID. name: type: string description: Component name. props: type: object additionalProperties: true description: Custom component properties (key-value pairs). cld_id: type: string description: Cloud resource ID (set on cloud-imported components). cld_type: type: string enum: - AWS - GCP - AZURE description: Cloud account type. cld_sync: type: boolean description: Whether this component is synced with cloud. cld_account: type: string description: Cloud account ID. tags: type: array description: Tags assigned to the component. items: type: string color: type: string description: Element color. icon: type: string description: Element icon identifier. parent: type: string description: Parent element ID. issues: type: array description: Issues associated with this element. items: $ref: "#/components/schemas/CloudDiagramIssue" CloudDiagramGroupItem: type: object required: - _id - type description: Reference to a component contained within a group. properties: _id: type: string description: Component ID. type: type: string enum: - attachment - combiner - element - group - link - node - note - scheme - statussheet description: Component type. CloudDiagramGroup: type: object required: - _id description: A group component (VPC, subnet, region, cluster, etc.). properties: _id: type: string description: Group ID. name: type: string description: Component name. props: type: object additionalProperties: true description: Custom component properties (key-value pairs). cld_id: type: string description: Cloud resource ID (set on cloud-imported components). cld_type: type: string enum: - AWS - GCP - AZURE description: Cloud account type. cld_sync: type: boolean description: Whether this component is synced with cloud. cld_account: type: string description: Cloud account ID. tags: type: array description: Tags assigned to the component. items: type: string group_type: type: string enum: - account - az - azure_subscription - customer_gateway - ecs - eks - aks - k8s_namespace - k8s_pod - k8s_deployment - k8s_daemon_set - k8s_replica_set - k8s_stateful_set - project - region - security_group - subnet - vpc - gcp_instance_group - gcp_managed_zone - gke_cluster - azure_dns_zone - azure_cdn_profile - azure_resource_group description: Group type. color: type: string description: Group color. icon: type: string description: Group icon identifier. items: type: array description: Components contained in the group. items: $ref: "#/components/schemas/CloudDiagramGroupItem" issues: type: array description: Issues associated with this group. items: $ref: "#/components/schemas/CloudDiagramIssue" CloudDiagramComponentRef: type: object required: - _id - type - scheme_id - ss_id description: Reference to a diagram component, including its parent diagram and layer. properties: _id: type: string description: Component ID. type: type: string enum: - attachment - combiner - element - group - link - node - note - scheme - statussheet description: Component type. scheme_id: type: string description: Parent diagram ID. ss_id: type: string description: Parent layer ID. CloudDiagramLink: type: object required: - _id - origin - destination description: A link component connecting two nodes or groups. properties: _id: type: string description: Link ID. name: type: string description: Component name. props: type: object additionalProperties: true description: Custom component properties (key-value pairs). cld_id: type: string description: Cloud resource ID (set on cloud-imported components). cld_type: type: string enum: - AWS - GCP - AZURE description: Cloud account type. cld_sync: type: boolean description: Whether this component is synced with cloud. cld_account: type: string description: Cloud account ID. tags: type: array description: Tags assigned to the component. items: type: string connection_type: type: string enum: - normal - tunnel - private - VPN - VPC Peering - Network Connectivity Center - Private Service Connect - Private Google Access - Serverless VPC - Serverless VPC Access Connector - Cross Cloud Interconnect - Partner Interconnect - Dedicated Interconnect description: Link connection type. origin: $ref: "#/components/schemas/CloudDiagramComponentRef" destination: $ref: "#/components/schemas/CloudDiagramComponentRef" owner_ss_id: type: string description: Owner layer ID for cross-diagram links. issues: type: array description: Issues associated with this link. items: $ref: "#/components/schemas/CloudDiagramIssue" CloudDiagramAttachment: type: object required: - _id description: An attachment component added to a group. properties: _id: type: string description: Attachment ID. name: type: string description: Component name. props: type: object additionalProperties: true description: Custom component properties (key-value pairs). cld_id: type: string description: Cloud resource ID (set on cloud-imported components). cld_type: type: string enum: - AWS - GCP - AZURE description: Cloud account type. cld_sync: type: boolean description: Whether this component is synced with cloud. cld_account: type: string description: Cloud account ID. tags: type: array description: Tags assigned to the component. items: type: string color: type: string description: Attachment color. icon: type: string description: Attachment icon identifier. group: type: string description: Parent group ID. issues: type: array description: Issues associated with this attachment. items: $ref: "#/components/schemas/CloudDiagramIssue" CloudDiagramCombinerItem: type: object required: - _id - type description: A component reference contained within a combiner. properties: _id: type: string description: Component ID. type: type: string enum: - attachment - combiner - element - group - link - node - note - scheme - statussheet description: Component type. CloudDiagramCombiner: type: object required: - _id description: A combiner component that visually groups multiple components. properties: _id: type: string description: Combiner ID. name: type: string description: Combiner name. color: type: string description: Combiner color. icon: type: string description: Combiner icon identifier. items: type: array description: Components contained in the combiner. items: $ref: "#/components/schemas/CloudDiagramCombinerItem" CloudDiagramNote: type: object required: - _id description: A text note placed on the diagram. properties: _id: type: string description: Note ID. text: type: string description: Note text content. color: type: string description: Note background color. font_size: type: number description: Note font size. CloudDiagramStatussheetComponents: type: object description: Component collections of a diagram layer, keyed by component ID. properties: node: type: object description: Map of node ID to node component. additionalProperties: $ref: "#/components/schemas/CloudDiagramNode" element: type: object description: Map of element ID to element component. additionalProperties: $ref: "#/components/schemas/CloudDiagramElement" group: type: object description: Map of group ID to group component. additionalProperties: $ref: "#/components/schemas/CloudDiagramGroup" link: type: object description: Map of link ID to link component. additionalProperties: $ref: "#/components/schemas/CloudDiagramLink" attachment: type: object description: Map of attachment ID to attachment component. additionalProperties: $ref: "#/components/schemas/CloudDiagramAttachment" combiner: type: object description: Map of combiner ID to combiner component. additionalProperties: $ref: "#/components/schemas/CloudDiagramCombiner" note: type: object description: Map of note ID to note component. additionalProperties: $ref: "#/components/schemas/CloudDiagramNote" CloudDiagramStatussheetMeta: type: object required: - _id - updatedAt description: |- Projected layer metadata returned inside each layer entry. Contains import state, last updated timestamp, and links version. properties: _id: type: string description: Layer ID. import: $ref: "#/components/schemas/CloudDiagramImportState" updatedAt: type: string format: date-time description: Timestamp of the last update. linksVersion: type: integer description: Links version counter, incremented on every link change. CloudDiagramStatussheetData: type: object required: - statussheet description: A layer entry with projected metadata and component collections. properties: statussheet: $ref: "#/components/schemas/CloudDiagramStatussheetMeta" node: type: object description: Map of node ID to node component. additionalProperties: $ref: "#/components/schemas/CloudDiagramNode" element: type: object description: Map of element ID to element component. additionalProperties: $ref: "#/components/schemas/CloudDiagramElement" group: type: object description: Map of group ID to group component. additionalProperties: $ref: "#/components/schemas/CloudDiagramGroup" link: type: object description: Map of link ID to link component. additionalProperties: $ref: "#/components/schemas/CloudDiagramLink" attachment: type: object description: Map of attachment ID to attachment component. additionalProperties: $ref: "#/components/schemas/CloudDiagramAttachment" combiner: type: object description: Map of combiner ID to combiner component. additionalProperties: $ref: "#/components/schemas/CloudDiagramCombiner" note: type: object description: Map of note ID to note component. additionalProperties: $ref: "#/components/schemas/CloudDiagramNote" CloudDiagramSchemeStatussheetInfo: type: object required: - ssid - name - account_name - alarms_count - empty - color description: Summary of a cloud account (layer) connected to a diagram. properties: ssid: type: string description: Layer ID. name: type: string description: Layer name. account_name: type: string description: Connected cloud account name. alarms_count: type: integer description: Number of active alarms. empty: type: boolean description: True when the layer contains no components. color: type: string description: Layer color. CloudDiagramSchemeResult: type: object required: - _id - name - type - statussheet description: A diagram with its connected cloud accounts. properties: _id: type: string description: Diagram ID. name: type: string description: Diagram name. color: type: string description: Diagram color. type: type: string enum: - application - infrastructure - network - template description: Diagram type. statussheet: type: array description: Connected cloud accounts (layers). items: $ref: "#/components/schemas/CloudDiagramSchemeStatussheetInfo" CloudDiagramsGetRequest: type: object description: |- Request body for getting diagram components. Leave empty to retrieve all accessible diagrams (returns scheme map only). properties: scheme: type: array description: IDs of diagrams to load. items: type: string statussheet: type: array description: IDs of layers to load. items: type: string template: description: Template type or array of template layer IDs to include. oneOf: - type: string enum: - component - statussheet - type: array items: type: string CloudDiagramsGetResponse: type: object description: |- Diagram and layer data. When called with an empty body, only the diagram map is populated. When called with a populated body, both diagram and layer maps are returned with components projected to key display and cloud fields by default. properties: scheme: type: object description: Map of diagram ID to diagram with its connected cloud accounts. additionalProperties: $ref: "#/components/schemas/CloudDiagramSchemeResult" statussheet: type: object description: |- Map of layer ID to layer metadata and component collections. Components are projected to key display and cloud fields by default. additionalProperties: $ref: "#/components/schemas/CloudDiagramStatussheetData" template: type: object description: Map of template layer ID to template data. additionalProperties: true CloudDiagramSchemeSearchItem: type: object required: - _id - type description: A diagram layer (cloud account) matching the search query. properties: _id: type: string description: Layer ID. account_name: type: string description: Cloud account name. scheme_id: type: string description: Parent diagram ID. ss_id: type: string description: Layer ID (same as _id). scheme: type: string description: Parent diagram name. status: type: string description: Import/sync status. name: type: string description: Layer name. type: type: string enum: - statussheet description: Component type — always "statussheet" for this category. CloudDiagramComponentSearchItem: type: object required: - _id - type description: A component matching the search query. properties: _id: type: string description: Component ID. account_name: type: string description: Cloud account name. icon: type: string description: Component icon identifier. color: type: string description: Component color. scheme_id: type: string description: Parent diagram ID. ss_id: type: string description: Layer ID. name: type: string description: Component name. type: type: string enum: - attachment - combiner - element - group - link - node - note description: Component type. node_type: type: string enum: - app_component - app_group - app_link - attachment - group - host - link - service description: Node type. group_type: type: string description: Group type (for group components). props: type: object description: Component properties. For the "prop" category contains the matched property key-value pairs. properties: service_type: type: string description: Cloud service type (e.g. AWS::EC2::Instance). CloudDiagramsSearchRequest: type: object required: - query description: Request body for searching diagrams and components. properties: query: type: string description: Search query string. ss_id: type: string description: Limit search to components within this layer. from: type: integer minimum: 0 description: Pagination offset (default 0). size: type: integer minimum: 1 description: Maximum number of results per category (default 20). CloudDiagramsSearchResponse: type: object description: Search results grouped into three categories. properties: scheme: type: array description: Diagram layers (cloud accounts) matching the query. items: $ref: "#/components/schemas/CloudDiagramSchemeSearchItem" component: type: array description: Components matching the query by name. items: $ref: "#/components/schemas/CloudDiagramComponentSearchItem" prop: type: array description: Components matching the query by property values. items: $ref: "#/components/schemas/CloudDiagramComponentSearchItem" CloudDiagramStatussheetGetRequest: type: object description: |- Request body for getting layer components. At least one component type must be provided with one or more IDs. minProperties: 1 properties: node: type: array minItems: 1 description: Node IDs to fetch. items: type: string element: type: array minItems: 1 description: Element IDs to fetch. items: type: string link: type: array minItems: 1 description: Link IDs to fetch. items: type: string group: type: array minItems: 1 description: Group IDs to fetch. items: type: string attachment: type: array minItems: 1 description: Attachment IDs to fetch. items: type: string note: type: array minItems: 1 description: Note IDs to fetch. items: type: string combiner: type: array minItems: 1 description: Combiner IDs to fetch. items: type: string CloudDiagramExportJsonMetadata: type: object required: - user - date - version description: Metadata included in a diagram JSON export. properties: user: type: string description: Email of the user who triggered the export. date: type: string format: date-time description: ISO 8601 timestamp of the export. version: type: string description: Export format version. connections: type: object description: Map of component ID to display label for external connections referenced by cross-diagram links. additionalProperties: type: string CloudDiagramExportJsonResponse: type: object required: - metadata description: Full diagram export as a structured JSON document. properties: statussheet: type: object description: Diagram-level metadata (excluding internal IDs). additionalProperties: true metadata: $ref: "#/components/schemas/CloudDiagramExportJsonMetadata" nodes: type: array description: Exported nodes. items: $ref: "#/components/schemas/CloudDiagramNode" elements: type: array description: Exported elements. items: $ref: "#/components/schemas/CloudDiagramElement" groups: type: array description: Exported groups. items: $ref: "#/components/schemas/CloudDiagramGroup" attachments: type: array description: Exported attachments. items: $ref: "#/components/schemas/CloudDiagramAttachment" links: type: array description: Exported links. items: $ref: "#/components/schemas/CloudDiagramLink" combiners: type: array description: Exported combiners. items: $ref: "#/components/schemas/CloudDiagramCombiner" notes: type: array description: Exported notes. items: $ref: "#/components/schemas/CloudDiagramNote" CloudDiagramCostTimeRange: type: object required: - startDate - endDate - interval description: Resolved cost window for the snapshot. properties: startDate: type: string format: date description: Inclusive start of the cost window (ISO date). endDate: type: string format: date description: Inclusive end of the cost window (ISO date). interval: type: string enum: - day - week - month description: Bucket interval used for the trend series. CloudDiagramCostResource: type: object required: - id - name - type - amount description: A single resource entry within the top-resources list. properties: id: type: string description: Resource id (cloud-native id when available; otherwise the diagram component id). name: type: string description: Human-readable resource name. type: type: string description: Resource type label (e.g. `ec2`, `rds`). amount: type: number description: Cost amount for this resource within the snapshot window. CloudDiagramCostServiceBreakdown: type: object required: - service - amount description: A single service entry within the cost-by-service breakdown. properties: service: type: string description: Cloud service label (e.g. `EC2`). amount: type: number description: Cost amount for this service within the snapshot window. CloudDiagramCostTrendBucket: type: object required: - bucketStart - amount description: A single bucket in the trend series. properties: bucketStart: type: string description: Inclusive start of this bucket. ISO date for `day` and `month`; week label for `week`. amount: type: number description: Total cost for this bucket. CloudDiagramCostSnapshot: type: object required: - diagramId - currency - timeRange - total - trendingPct - topResources - byService - trend description: |- Bounded cost snapshot for a diagram layer. Composes the diagram's total spend, period-over-period change, top resources by cost (capped at 5), top services by cost (capped at 5), and the most recent 12 trend buckets at the requested interval. properties: diagramId: type: string description: Diagram (layer) ID this snapshot was computed for. currency: type: string description: Currency the cost numbers are reported in (e.g. `USD`). timeRange: $ref: "#/components/schemas/CloudDiagramCostTimeRange" total: type: number description: Total cost across the entire diagram for the snapshot window. trendingPct: type: number nullable: true description: |- Period-over-period change as a fraction (e.g. 0.142 = +14.2%). `null` when no prior period of equal length is available for comparison. topResources: type: array description: Top resources by cost, capped at 5. maxItems: 5 items: $ref: "#/components/schemas/CloudDiagramCostResource" byService: type: array description: Top services by cost, capped at 5. maxItems: 5 items: $ref: "#/components/schemas/CloudDiagramCostServiceBreakdown" trend: type: array description: Most recent trend buckets at the requested interval, capped at 12. maxItems: 12 items: $ref: "#/components/schemas/CloudDiagramCostTrendBucket" CloudDiagramLayerSnapshot: type: object required: - _id - createdAt description: A saved snapshot of a diagram layer's state. properties: _id: type: string description: Snapshot ID. name: type: string description: Snapshot name. createdAt: type: string format: date-time description: Timestamp when the snapshot was created. prevState: type: string description: ID of the previous snapshot in the chain. CloudDiagramActivityItem: type: object required: - _id - group - activity - timestamp description: An individual activity record within an activity group. properties: _id: type: string description: Activity record ID. group: type: string description: ID of the activity group this record belongs to. activity: type: string enum: - NODE_CREATE - NODE_UPDATE - NODE_DELETE - LINK_CREATE - LINK_UPDATE - LINK_DELETE - GROUP_CREATE - GROUP_UPDATE - GROUP_DELETE - ATTACHMENT_CREATE - ATTACHMENT_UPDATE - ATTACHMENT_DELETE description: Activity type. metadata: type: object additionalProperties: true description: Activity-specific payload (structure varies by activity type). timestamp: type: string format: date-time description: Timestamp of the activity. service_type: type: string description: Cloud service type the activity applies to. group_type: type: string description: Activity group sub-type. tags: type: array description: Tags associated with the activity. items: type: string CloudDiagramSnapshotActivityGroup: type: object required: - _id - statussheet - timestamp - snapshot description: A snapshot activity group containing the individual activity records that produced it. properties: _id: type: string description: Activity group ID. statussheet: type: string description: Layer ID this group belongs to. timestamp: type: string format: date-time description: Timestamp of the activity group. tags: type: array description: Tags associated with the group. items: type: string snapshot: type: string description: ID of the associated snapshot (equal to the group ID). items: type: array description: Individual activity records within this group. items: $ref: "#/components/schemas/CloudDiagramActivityItem" CloudDiagramNodeActivity: type: object required: - _id - activity - timestamp - user - statussheet description: An individual activity record scoped to a specific component node. properties: _id: type: string description: Activity record ID. activity: type: string enum: - NODE_CREATE - NODE_UPDATE - NODE_DELETE description: Activity type. metadata: type: object additionalProperties: true description: Activity-specific payload (structure varies by activity type). timestamp: type: string format: date-time description: Timestamp of the activity. user: type: string description: ID of the user who performed the activity. statussheet: type: string description: Layer ID where the activity occurred. DiagramRelationshipsAnchor: type: object required: - id - type - name description: The anchor resource the traversal started from. properties: id: type: string description: Anchor resource ID (matches the `rid` path parameter). type: type: string enum: - node - element - group description: Component bucket the anchor lives in. name: type: string description: Human-readable resource name. serviceType: type: string description: Cloud service type when available (e.g. `Amazon RDS`, `GCP Cloud SQL`). DiagramRelationship: type: object required: - id - type - name - relation - hops description: One related resource returned by the traversal. properties: id: type: string description: Related resource ID. type: type: string enum: - node - element - group description: Component bucket the related resource lives in. name: type: string description: Human-readable name of the related resource. serviceType: type: string description: Cloud service type when available. relation: type: string enum: - downstream - upstream - group_member - group_parent description: |- How the resource is related to the anchor. `downstream` / `upstream` are edge relations (anchor is the edge origin / destination respectively). `group_member` means the related resource is contained in the anchor (anchor is a group); `group_parent` means the related resource is a group that contains the anchor. hops: type: integer minimum: 1 description: Edge hop count from the anchor. Group-member / group-parent entries are reported as 1. DiagramRelationshipsResponse: type: object required: - anchor - direction - depth - kind - relations - truncated description: The response payload for the resource relationships endpoint. properties: anchor: $ref: "#/components/schemas/DiagramRelationshipsAnchor" direction: type: string enum: - downstream - upstream - both depth: type: string enum: - direct - transitive kind: type: string enum: - edges - group_members - both relations: type: array items: $ref: "#/components/schemas/DiagramRelationship" description: Resources related to the anchor (capped at 200). truncated: type: boolean description: True when the relation list was capped at 200 entries. Organization: type: object description: Organization metadata returned by the API. properties: id: type: string description: The unique ID of the organization name: type: string description: The name of the organization ListUsersResponseBody: type: object description: Response body for the list users endpoint. properties: users: type: array items: $ref: "#/components/schemas/UserListItem" rowCount: type: integer description: The number of returned records. format: int64 example: 5 InviteResponse: type: object description: Response returned after creating a user invitation. properties: message: type: string description: Success message user: $ref: "#/components/schemas/InvitedUserBody" InvitedUserBody: type: object properties: id: type: string description: The unique ID of the invited user. email: type: string description: The email address of the invited user. firstName: type: string description: The first name of the invited user, if provided during invitation. lastName: type: string description: The last name of the invited user, if provided during invitation. displayName: type: string description: The display name of the invited user, if provided during invitation. jobTitle: type: string description: The job function of the invited user, if provided during invitation. roleId: type: string description: The ID of the role assigned to the user. organizationId: type: string description: The ID of the organization assigned to the user. status: type: string description: The status of the user (invited) enum: - invited MTSContractResponse: type: object description: External view of a contract. DoiT-internal fields are not exposed. properties: id: type: string description: The unique identifier of the contract. customerId: type: string description: The customer (tenant) that holds the contract. type: type: string description: The immutable contract type. status: type: string description: The contract status. enum: - draft - scheduled - active - cancelled - expired - superseded name: type: string description: The contract name. startDate: type: string format: date-time nullable: true description: The contract start date. endDate: type: string format: date-time nullable: true description: The contract end date. renewalPolicy: type: string description: The renewal policy. enum: - auto - manual - fixed currentVersionNumber: type: integer nullable: true description: The current version number of the contract. timeCreated: type: string format: date-time description: When the contract was created. MTSContractDetailResponse: description: A single contract with its version terms. DoiT-internal fields are not exposed. allOf: - $ref: "#/components/schemas/MTSContractResponse" - type: object properties: versions: type: array description: The contract versions, newest last, with their billing terms. items: type: object properties: version: type: integer description: Contract version number. status: type: string description: Version status. name: type: string startDate: type: string format: date-time endDate: type: string format: date-time nullable: true effectiveStart: type: string format: date-time effectiveEnd: type: string format: date-time nullable: true renewalPolicy: type: string cancellationReason: type: string nullable: true billingProfile: type: object invoicesEmail: type: string format: email contractUpdatesEmail: type: string format: email managementAccounts: type: array items: type: string billingRules: type: array items: type: object priceBooks: type: array items: type: object customLineItems: type: array items: type: object MTSContractInput: type: object description: Contract create/update payload. Full field-level validation is applied server-side. required: - name - startDate - renewalPolicy - invoicesEmail - contractUpdatesEmail - billingProfile properties: name: type: string startDate: type: string format: date-time endDate: type: string format: date-time nullable: true renewalPolicy: type: string enum: - auto - manual - fixed invoicesEmail: type: string format: email contractUpdatesEmail: type: string format: email billingProfile: type: object description: The billing profile (name, country, state, city, address, zip). managementAccounts: type: array items: type: string billingRules: type: array items: type: object priceBooks: type: array items: type: object customLineItems: type: array items: type: object CreateContractResponse: type: object description: The result of creating a contract or contract version. properties: contractId: type: string version: type: integer status: type: string message: type: string timestamp: type: string format: date-time ContractLifecycleResponse: type: object description: Result of an activate or cancel operation. properties: contractId: type: string description: The contract identifier. status: type: string description: The contract status after the operation (`active`, `scheduled`, or `cancelled`). enum: - active - scheduled - cancelled CommitmentExternal: type: object description: A commitment contract. properties: id: type: string description: The unique identifier of the commitment. name: type: string description: The name of the commitment. startDate: type: string format: date-time example: "2024-03-10T23:00:00Z" description: The start date of the commitment. endDate: type: string format: date-time example: "2024-03-10T23:00:00Z" description: The end date of the commitment. currency: type: string description: The currency of the commitment (e.g., USD). example: USD cloudProvider: type: string description: The cloud provider associated with the commitment. enum: - google-cloud - amazon-web-services - microsoft-azure totalCommitmentValue: type: number format: double description: The total value of the commitment across all periods. totalCurrentAttainment: type: number format: double description: The total current spend attainment across all periods. totalMarketplaceSpend: type: number format: double description: The total marketplace spend across all periods. totalForecastValue: type: number format: double description: The total projected spend at the end of the commitment, summed across all periods. 0 when insufficient history is available to compute a forecast. periods: type: array description: The list of commitment periods. items: $ref: "#/components/schemas/CommitmentPeriod" createTime: type: integer format: int64 description: The creation time in milliseconds since epoch. updateTime: type: integer format: int64 description: The last update time in milliseconds since epoch. CommitmentExternalList: type: object description: List of commitments. properties: pageToken: type: string description: Page token. It is used to request a specific page of the list results. example: bDl0QkEwVFZxUEwxaUJRaHhTcXM rowCount: type: integer description: The number of returned records. format: int64 example: 1 commitments: type: array description: Array of commitments. items: $ref: "#/components/schemas/CommitmentExternalListItem" CommitmentExternalListItem: type: object description: Summary information of a commitment in a list. properties: id: type: string description: The unique identifier of the commitment. name: type: string description: The name of the commitment. startDate: type: string format: date-time example: "2024-03-10T23:00:00Z" description: The start date of the commitment. endDate: type: string format: date-time example: "2024-03-10T23:00:00Z" description: The end date of the commitment. currency: type: string description: The currency of the commitment. example: USD cloudProvider: type: string description: The cloud provider associated with the commitment. enum: - google-cloud - amazon-web-services - microsoft-azure totalCommitmentValue: type: number format: double description: The total value of the commitment across all periods. totalCurrentAttainment: type: number format: double description: The total current spend attainment across all periods. totalMarketplaceSpend: type: number format: double description: The total marketplace spend across all periods. totalForecastValue: type: number format: double description: The total projected spend at the end of the commitment, summed across all periods. 0 when insufficient history is available to compute a forecast. periods: type: array description: The list of commitment periods. items: $ref: "#/components/schemas/CommitmentPeriod" createTime: type: integer format: int64 description: The creation time in milliseconds since epoch. updateTime: type: integer format: int64 description: The last update time in milliseconds since epoch. CommitmentPeriod: type: object description: A single period within a commitment. properties: startDate: type: string format: date-time example: "2024-03-10T23:00:00Z" description: The start date of the period. endDate: type: string format: date-time example: "2024-03-10T23:00:00Z" description: The end date of the period. commitmentValue: type: number format: double description: The commitment value for this period. marketplaceLimitPercentage: type: number format: double description: The marketplace limit as a percentage (0-100). marketplaceSpend: type: number format: double description: The marketplace spend within this period. marketplaceLimitAmount: type: number format: double description: The marketplace limit in absolute currency for this period, derived as commitmentValue * marketplaceLimitPercentage / 100. forecastValue: type: number format: double description: The projected spend at the end of this period, based on a linear regression over the period's total spend series. 0 when insufficient history is available to compute a forecast. CloudFlowRefineRequest: type: object required: - question properties: question: type: string description: Natural language description of what to refine or modify in the CloudFlow. conversationId: type: string description: ID of an existing conversation to continue. When omitted, a new conversation is started. CloudFlowBuildRequest: type: object required: - question properties: question: type: string description: Natural language description of the CloudFlow to build from scratch. conversationId: type: string description: ID of an existing conversation to continue. When omitted, a new conversation is started. AvaAskRequest: type: object properties: question: type: string description: The question to ask Ava. conversationId: type: string description: Optional ID of an existing conversation to continue. required: - question AvaAskSyncRequest: type: object properties: question: type: string description: The question to ask Ava. conversationId: type: string description: Optional ID of an existing conversation to continue. ephemeral: type: boolean default: false description: When true, the conversation is not persisted. Recommended for programmatic consumers (Terraform, MCP, CI pipelines). required: - question AvaAskSyncResponse: type: object description: >- Ava's response. On success, `answer` is present. The endpoint streams keep-alive whitespace while generating (to avoid proxy timeouts), so the HTTP status is committed to 200 before the answer is ready; if generation then fails, `answer` is omitted and `error` carries a message instead. Consumers should check for `error` before reading `answer`. properties: answer: type: string description: The Ava response text. Present on success. conversationId: type: string description: The conversation ID. Present only for non-ephemeral requests. Can be used with the delete conversation endpoint. answerId: type: string description: The answer ID within the conversation. Present only for non-ephemeral requests. Required for the feedback endpoint. error: type: string description: >- Present instead of `answer` when generation fails after the response has begun streaming (the HTTP status remains 200). A human-readable error message. AvaFeedbackRequest: type: object properties: conversationId: type: string description: The conversation ID the feedback relates to. answerId: type: string description: The specific answer ID within the conversation. feedback: type: object properties: positive: type: boolean description: Whether the feedback is positive or negative. text: type: string description: Optional text providing additional feedback details. required: - positive required: - conversationId - answerId - feedback 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 format: uri CommitmentTerm: type: string enum: - one_year - three_year description: Commitment term length. Policy: type: string enum: - conservative - balanced - max_savings description: | Coverage target policy. - `conservative` — lower coverage target (~65%) - `balanced` — moderate coverage target (~80%) - `max_savings` — aggressive coverage target (~90%) PaymentOption: type: string enum: - no_upfront - partial_upfront - all_upfront description: | Payment structure for a commitment. - `no_upfront` — all charges paid monthly - `partial_upfront` — a portion paid upfront; remainder monthly - `all_upfront` — full commitment paid upfront Money: type: object required: - amount - currency properties: amount: type: string pattern: ^-?(0|[1-9]\d*)(\.\d+)?$ description: Decimal monetary amount at ISO 4217 minor-unit precision (string). currency: type: string pattern: ^[A-Z]{3}$ description: ISO 4217 currency code. example: USD Stats30dSummary: type: object description: | Minimal 30-day aggregate. Only `esr` and `savings` are persisted at this granularity. Responses are denominated in USD. Used by both AWS organization/member-account and GCP billing-account list items. properties: esr: type: number format: double description: Effective Savings Rate over the last 30 days (0–1). nullable: true example: 0.187 savings: allOf: - $ref: "#/components/schemas/Money" description: Realized savings amount over the last 30 days. AwsOnboardingStatusEntry: type: object required: - status description: Per-product-line PS4C onboarding state. properties: status: type: string description: Current onboarding lifecycle stage for this product line. enum: - not_started - onboarding - done - error onboardingStartedAt: type: string format: date-time description: | When PS4C first began tracking commitments for this product line. Used to bound lifetime savings totals and to render onboarding history in the DoiT Console. nullable: true AwsOnboardingStatus: type: object description: | PS4C onboarding state grouped by product line. A product line is omitted when it is not onboarded at all. properties: compute: $ref: "#/components/schemas/AwsOnboardingStatusEntry" database: $ref: "#/components/schemas/AwsOnboardingStatusEntry" AwsOrganization: type: object required: - managementAccountId properties: managementAccountId: type: string description: 12-digit account number of the organization's management (payer) account. example: "123456789012" displayName: type: string description: Human-readable account alias, if available. nullable: true example: Acme Prod onboardingStatus: allOf: - $ref: "#/components/schemas/AwsOnboardingStatus" description: Per-product-line PS4C onboarding state for this organization. savingsPlansSyncTime: type: string format: date-time description: Timestamp of the last successful Savings Plan inventory sync. nullable: true stats30d: type: object description: Trailing 30-day aggregate metrics, broken down by SP type. properties: compute: $ref: "#/components/schemas/Stats30dSummary" database: $ref: "#/components/schemas/Stats30dSummary" savingsTotals: type: object description: | Year-to-date and lifetime savings per SP type. Same figures the detail endpoint returns — surfaced on the list item so callers can compute customer-level totals (sum across organizations) without an extra round-trip per organization. Lifetime is bounded by each organization's PS4C onboarding start. properties: compute: $ref: "#/components/schemas/AwsSavingsTotals" database: $ref: "#/components/schemas/AwsSavingsTotals" monthlyPotentialSavings: allOf: - $ref: "#/components/schemas/AwsMonthlyPotentialSavings" description: Estimated monthly additional savings per SP type for this organization. AwsMonthlyPotentialSavings: type: object description: | Estimated monthly additional savings per SP type, taken from the latest PS4C purchase projection. Unlike `savingsTotals` (realized YTD/lifetime savings), this is a forward-looking estimate of the monthly savings achievable if the recommended commitments were purchased. For member accounts, the organization figure is attributed by each member account's share of trailing-60-day SP-eligible on-demand cost. A per-SP-type value of `0.00` means the latest projection is missing, expired, or empty. The field is omitted entirely only for accounts that have never had potential savings computed. properties: compute: $ref: "#/components/schemas/Money" database: $ref: "#/components/schemas/Money" AwsMonthlyStatsEntry: type: object required: - month - esr - onDemandCost - costWithSavings description: | One calendar-month aggregate for the organization. Money fields are wrapped objects (`{amount, currency}`). properties: month: type: string pattern: ^\d{4}-(0[1-9]|1[0-2])$ example: 2025-06 esr: type: number format: double description: Effective Savings Rate for the month (0–1). onDemandCost: allOf: - $ref: "#/components/schemas/Money" description: Eligible on-demand cost for the month. costWithSavings: allOf: - $ref: "#/components/schemas/Money" description: Actual cost after commitments for the month. AwsDailyCoverageEntry: type: object required: - date description: | One day of commitment-coverage breakdown. Money fields are wrapped objects (`{amount, currency}`). properties: date: type: string format: date onDemandCost: $ref: "#/components/schemas/Money" savingsPlanCost: $ref: "#/components/schemas/Money" reservedInstCost: $ref: "#/components/schemas/Money" flexsaveCost: $ref: "#/components/schemas/Money" spotCost: $ref: "#/components/schemas/Money" AwsSavingsTotals: type: object required: - ytd - lifetime description: | Running savings figures derived server-side from the full monthly stats history (`onDemandCost - costWithSavings` per month, optionally bounded by onboarding start date and start of year). properties: ytd: allOf: - $ref: "#/components/schemas/Money" description: Year-to-date realized savings. lifetime: allOf: - $ref: "#/components/schemas/Money" description: Lifetime realized savings since onboarding. AwsOrganizationDetail: description: | Single AWS Organization detail. Adds the trailing-window stats that drive the DoiT Console overview screen on top of the list-item shape: - `monthlyStats` — last 6 calendar months per SP type - `dailyCoverage` — last 30 days per SP type `savingsTotals` (precomputed YTD and lifetime savings per SP type) and `monthlyPotentialSavings` (estimated monthly additional savings per SP type) are inherited from the list-item shape (`AwsOrganization`). allOf: - $ref: "#/components/schemas/AwsOrganization" - type: object properties: monthlyStats: type: object description: Trailing 6 calendar months of organization stats, grouped by SP type. properties: compute: type: array items: $ref: "#/components/schemas/AwsMonthlyStatsEntry" database: type: array items: $ref: "#/components/schemas/AwsMonthlyStatsEntry" dailyCoverage: type: object description: Trailing 30 days of commitment coverage, grouped by SP type. properties: compute: type: array items: $ref: "#/components/schemas/AwsDailyCoverageEntry" database: type: array items: $ref: "#/components/schemas/AwsDailyCoverageEntry" AwsMemberAccount: type: object required: - memberAccountId - managementAccountId properties: memberAccountId: type: string description: 12-digit AWS member account ID. managementAccountId: type: string description: 12-digit AWS management (payer) account ID of the parent AWS Organization. displayName: type: string description: Human-readable account alias, if available. nullable: true example: prod-web stats30d: type: object description: Trailing 30-day aggregate metrics per SP type. properties: compute: $ref: "#/components/schemas/Stats30dSummary" database: $ref: "#/components/schemas/Stats30dSummary" monthlyPotentialSavings: allOf: - $ref: "#/components/schemas/AwsMonthlyPotentialSavings" description: | Estimated monthly additional savings per SP type for this member account, attributed from the parent organization's projection by share of trailing-60-day SP-eligible on-demand cost. AwsMemberAccountDetail: description: | Single member AWS account detail. Adds the trailing-window stats that drive the per-member-account view on the DoiT Console overview screen on top of the list-item shape: - `monthlyStats` — last 6 calendar months per SP type - `dailyCoverage` — last 30 days per SP type - `savingsTotals` — YTD and lifetime savings per SP type, bounded by the parent organization's PS4C onboarding start `monthlyPotentialSavings` (estimated monthly additional savings per SP type) is inherited from the list-item shape (`AwsMemberAccount`). allOf: - $ref: "#/components/schemas/AwsMemberAccount" - type: object properties: monthlyStats: type: object description: Trailing 6 calendar months of stats, grouped by SP type. properties: compute: type: array items: $ref: "#/components/schemas/AwsMonthlyStatsEntry" database: type: array items: $ref: "#/components/schemas/AwsMonthlyStatsEntry" dailyCoverage: type: object description: Trailing 30 days of commitment coverage, grouped by SP type. properties: compute: type: array items: $ref: "#/components/schemas/AwsDailyCoverageEntry" database: type: array items: $ref: "#/components/schemas/AwsDailyCoverageEntry" savingsTotals: type: object description: | Year-to-date and lifetime savings, grouped by SP type. Lifetime is bounded by the parent organization's PS4C onboarding start. properties: compute: $ref: "#/components/schemas/AwsSavingsTotals" database: $ref: "#/components/schemas/AwsSavingsTotals" AwsSavingsPlan: type: object required: - commitmentId - savingsPlanType - state properties: commitmentId: type: string description: Savings Plan ID (AWS-assigned GUID). savingsPlanArn: type: string description: Full ARN of the Savings Plan. nullable: true savingsPlanType: type: string enum: - compute - ec2_instance - sagemaker - database state: type: string enum: - pending_return - returning - active - expired - queued - queued_returning - payment_failed - payment_pending paymentOption: type: string enum: - no_upfront - partial_upfront - all_upfront termDuration: $ref: "#/components/schemas/CommitmentTerm" commitment: allOf: - $ref: "#/components/schemas/Money" description: Hourly commitment amount. upfrontPaymentAmount: allOf: - $ref: "#/components/schemas/Money" recurringPaymentAmount: allOf: - $ref: "#/components/schemas/Money" ec2InstanceFamily: type: string nullable: true region: type: string nullable: true startTime: type: string format: date-time nullable: true endTime: type: string format: date-time nullable: true lastMonthUtilization: type: number format: double description: Utilization percentage (0–1) in the last full calendar month. nullable: true lastMonthSavings: allOf: - $ref: "#/components/schemas/Money" description: Realized savings in the last full calendar month. Null if not yet available. AwsReservedInstanceRecurringCharge: type: object required: - amount - frequency properties: amount: type: number format: double description: The amount of the recurring charge. frequency: type: string description: The frequency of the recurring charge (e.g. `Hourly`). AwsReservedInstance: type: object required: - commitmentId - accountId - state - instanceType - mtdSavings description: Reserved Instance item in the external inventory response. Money fields are wrapped `{amount, currency}` objects. properties: commitmentId: type: string description: Reserved Instance ID (AWS-assigned). reservedInstanceArn: type: string description: Full ARN of the Reserved Instance, when known. nullable: true accountId: type: string description: AWS account ID where the Reserved Instance exists. state: type: string description: | Reserved Instance state, tracking the AWS EC2 Reserved Instance API verbatim in external snake_case form. Differs from Savings Plan states by design — for example, the terminal state is `retired` here vs `expired` on Savings Plans. enum: - active - retired - payment_pending - payment_failed - queued - queued_deleted instanceType: type: string description: EC2 instance type on which the RI can be used (e.g. `m5.large`). instanceCount: type: integer format: int64 nullable: true instanceTenancy: type: string description: Tenancy of the instance (e.g. `default`, `dedicated`). availabilityZone: type: string nullable: true region: type: string nullable: true platform: type: string nullable: true description: type: string description: Product platform description. scope: type: string description: Scope of the Reserved Instance (e.g. `Availability Zone`, `Region`). offeringClass: type: string enum: - standard - convertible offeringType: type: string description: RI offering type (e.g. `All Upfront`). termDuration: allOf: - $ref: "#/components/schemas/CommitmentTerm" description: Term inferred from the RI duration. Absent when it does not map cleanly to 1yr / 3yr. durationSeconds: type: integer format: int64 description: RI duration in seconds. nullable: true startTime: type: string format: date-time nullable: true endTime: type: string format: date-time nullable: true currencyCode: type: string description: ISO 4217 currency code (USD in practice). fixedPrice: allOf: - $ref: "#/components/schemas/Money" description: Purchase price of the Reserved Instance. usagePrice: allOf: - $ref: "#/components/schemas/Money" description: Usage price per hour. hourlyRecurringFee: allOf: - $ref: "#/components/schemas/Money" upfrontFee: allOf: - $ref: "#/components/schemas/Money" totalAssetValue: allOf: - $ref: "#/components/schemas/Money" averageOnDemandHourlyRate: allOf: - $ref: "#/components/schemas/Money" amortizedRecurringFee: allOf: - $ref: "#/components/schemas/Money" amortizedUpfrontFee: allOf: - $ref: "#/components/schemas/Money" totalAmortizedFee: allOf: - $ref: "#/components/schemas/Money" netRiSavings: allOf: - $ref: "#/components/schemas/Money" realizedSavings: allOf: - $ref: "#/components/schemas/Money" unrealizedSavings: allOf: - $ref: "#/components/schemas/Money" totalPotentialRiSavings: allOf: - $ref: "#/components/schemas/Money" onDemandCostOfRiHoursUsed: allOf: - $ref: "#/components/schemas/Money" riCostForUnusedHours: allOf: - $ref: "#/components/schemas/Money" purchasedHours: type: integer format: int64 nullable: true purchasedUnits: type: integer format: int64 nullable: true totalActualHours: type: integer format: int64 nullable: true totalNormalizedUnits: type: integer format: int64 nullable: true unusedHours: type: integer format: int64 nullable: true unusedNormalizedUnits: type: integer format: int64 nullable: true utilizationPercentage: type: number format: double description: Cost-explorer reported utilization percentage (0–1). nullable: true utilizationPercentageInUnits: type: number format: double nullable: true mtdSavings: allOf: - $ref: "#/components/schemas/Money" description: Month-to-date realized savings. mtdUtilization: type: number format: double description: | Month-to-date utilization (0–1). Null when not yet available. A stored 0% is indistinguishable from unavailable and is returned as null. nullable: true updatedAt: type: string format: date-time description: Timestamp of the last successful inventory sync for this Reserved Instance. nullable: true recurringCharges: type: array items: $ref: "#/components/schemas/AwsReservedInstanceRecurringCharge" AwsPurchasePlanStep: type: object description: A single weekly ladder step within a projection. required: - order - scheduledDate - purchaseAmount - cumulativeCommitment - estimatedSavings - isBootstrap - isFinal - requiresApproval properties: order: type: integer description: Step sequence number (1-based). scheduledDate: type: string format: date purchaseAmount: allOf: - $ref: "#/components/schemas/Money" description: Hourly commitment to purchase on this step. cumulativeCommitment: allOf: - $ref: "#/components/schemas/Money" description: Total hourly commitment after this step executes. estimatedSavings: allOf: - $ref: "#/components/schemas/Money" description: |- This step's proportional share of the projection-level `estimatedSavings` (allocated by purchase amount). Zero when the recommendation total is unavailable. isBootstrap: type: boolean description: "`true` if this is the initial bootstrap purchase." isFinal: type: boolean description: "`true` if this step reaches the target commitment." requiresApproval: type: boolean description: |- `true` when this step's `cumulativeCommitment` exceeds the customer-approved commitment ceiling (`approvedFinalCommitment`). Used for per-step status in the ladder even when the projection-level `purchaseApprovalStatus` is `approved`. AwsPlannedPurchase: type: object required: - managementAccountId - service - status properties: managementAccountId: type: string description: 12-digit account number of the organization's management (payer) account. service: type: string enum: - compute - database description: PS4C product line this projection belongs to. status: type: string enum: - valid - expired description: |- Projection lifecycle state. `expired` means the planning cycle has lapsed and a new projection should be triggered by the automated scheduler. When the stored document has no `status`, the server returns `valid`. purchaseApprovalStatus: type: string enum: - pending_approval - approved - paused description: |- Customer commitment approval state for this product line. Absent or unrecognized stored values are returned as `pending_approval`. pauseNote: type: string description: Customer-visible pause reason, when purchases are paused. nullable: true requiresApproval: type: boolean description: |- `true` when the projection as a whole requires customer approval before the planner stores a purchase plan: the target `finalCommitment` exceeds the approved ceiling, and/or `purchaseApprovalStatus` is not `approved`. Distinct from step-level `steps[].requiresApproval`, which flags individual ladder rows that exceed the ceiling. wowViolation: type: boolean description: "`true` when week-over-week eligible spend dropped beyond the allowed threshold." profile: $ref: "#/components/schemas/Policy" term: $ref: "#/components/schemas/CommitmentTerm" paymentOption: type: string enum: - no_upfront - partial_upfront - all_upfront - null nullable: true finalCommitment: allOf: - $ref: "#/components/schemas/Money" description: Target hourly commitment at the end of the laddering cycle. Currency is `USD` in v1. weeksToTarget: type: integer description: Number of ladder steps remaining to reach the target commitment. nullable: true planningCycleStartDate: type: string format: date nullable: true planningCycleEndDate: type: string format: date nullable: true estimatedSavings: allOf: - $ref: "#/components/schemas/Money" description: Total estimated savings from the underlying recommendation. Currency is `USD` in v1. steps: type: array items: $ref: "#/components/schemas/AwsPurchasePlanStep" description: |- Weekly ladder steps from the projection output. Omitted when the stored document has no `output` section. AwsRecommendation: type: object description: Recommended commitments properties: policy: type: string description: Actual configured policy currentCommitment: type: number format: double description: Active commitments currently applied to this account, measured in hourly spend. recommendedCommitment: type: number format: double description: Recommended hourly commitment level based on usage patterns and your commitment policy, designed to increase savings while managing underutilization risk. potentialAdditionalSavings: type: number format: double description: Estimated additional monthly savings from applying the recommended commitment policy. estimatedAverageCoverage: type: number format: double description: Estimated average coverage. estimatedEquivalentRecommendedCommitment: type: number format: double description: Estimated shelf-price hourly equivalent of the recommended commitment, derived from the median hourly eligible usage over the last 60 days multiplied by the estimated average coverage. AwsRecommendations: type: object description: Recommended commitments for onboarded services properties: compute: allOf: - $ref: "#/components/schemas/AwsRecommendation" description: Recommended commitments for compute database: allOf: - $ref: "#/components/schemas/AwsRecommendation" description: Recommended commitments for database EligibleSpendDataPoint: type: object description: One time-bucketed eligible-spend usage data point. properties: usageTime: type: string format: date-time nullable: true totalUsage: type: number format: double description: Total usage. minUsage: type: number format: double description: Min usage. maxUsage: type: number format: double description: Max usage. medianUsage: type: number format: double description: Median usage. AwsRecommendationWithEligibleSpend: type: object description: Service recommendation with eligible spend data properties: recommendation: allOf: - $ref: "#/components/schemas/AwsRecommendation" description: Recommended commitments eligibleUsage: type: array items: $ref: "#/components/schemas/EligibleSpendDataPoint" AwsOrganizationSettings: type: object description: Automation and recommendation engine settings for one product line. required: - purchaseMode - minimumCommitment - lastDayOfMonthForPurchase - maximumCommitment - term - paymentOption - policy properties: purchaseMode: type: string enum: - autonomous - requires_approval description: Whether purchases execute automatically or require approval. minimumCommitment: type: number format: double description: Minimum hourly commitment amount (USD) per purchase step. lastDayOfMonthForPurchase: type: integer description: Latest calendar day of the month on which a purchase may be scheduled. maximumCommitment: type: number format: double description: Maximum total hourly commitment (USD). 0 means no cap. term: allOf: - $ref: "#/components/schemas/CommitmentTerm" description: Preferred commitment term length. paymentOption: allOf: - $ref: "#/components/schemas/PaymentOption" description: Preferred payment structure for new commitments. policy: allOf: - $ref: "#/components/schemas/Policy" description: Coverage target policy. upfrontPercentage: type: number format: double description: Fraction of the hourly commitment paid upfront (0–1). Only present when paymentOption is `partial_upfront`. AwsOrganizationServiceSettings: type: object required: - service - settings properties: service: type: string enum: - compute - database description: Product line these settings apply to. settings: $ref: "#/components/schemas/AwsOrganizationSettings" AwsOrganizationSettingsItem: type: object required: - managementAccountId - purchaseAccountId - services properties: managementAccountId: type: string description: 12-digit account number of the organization's management (payer) account. example: "123456789012" purchaseAccountId: type: string description: Member AWS account used to execute SP purchases for this organization. Null if not configured. nullable: true example: "987654321098" services: type: array items: $ref: "#/components/schemas/AwsOrganizationServiceSettings" description: Settings for each activated product line. BillingTransferProblemDetails: type: object description: >- RFC 7807 problem-detail body returned by Billing Transfer endpoints for 4xx/5xx errors. additionalProperties: false required: - type - title - status - code properties: type: type: string format: uri description: A URI identifying the problem type. title: type: string description: Short, human-readable summary of the problem type. status: type: integer description: The HTTP status code repeated in the body. detail: type: string description: Human-readable explanation specific to this occurrence of the problem. code: type: string description: Stable machine-readable error code. example: "billing-transfer.batch_validation_failed" retryable: type: boolean description: Whether retrying the same request may succeed without changes. invalidItems: type: array description: Present on batch-validation failures; the batch items that failed validation. items: $ref: "#/components/schemas/InvalidHandshakeItem" InvalidHandshakeItem: type: object description: A single batch item that failed validation before processing began. additionalProperties: false required: - index - code properties: index: type: integer description: Zero-based position of the invalid item within the submitted batch. resellerCustomerId: type: string description: Present when the invalid item is a reseller-handshake batch item. code: type: string description: >- Stable machine-readable error code (e.g. `duplicate_pma`, `duplicate_ec_account`). example: "duplicate_pma" reason: type: string description: Human-readable explanation of why the item is invalid. HandshakeState: type: string description: AWS Organizations Handshake `State` value, lowercased. enum: - requested - open - canceled - accepted - declined - expired ResellerHandshakeItem: type: object additionalProperties: false required: - resellerCustomerId - resellerPmaAccountId properties: resellerCustomerId: type: string description: DoiT customer ID of the reseller's end customer to issue a handshake for. resellerPmaAccountId: type: string description: 12-digit AWS account ID of the reseller's program management account (PMA). example: "123456789012" ResellerHandshakeBatchCreate: type: object additionalProperties: false required: - dpmaId - items properties: dpmaId: type: string description: The distributor's program management account (DPMA) ID issuing the handshakes. sendHandshakes: type: boolean description: >- If `true`, issues a new AWS Organizations handshake for each item without an existing one. If omitted or `false`, maps the batch in place without issuing any AWS Organizations handshakes. default: false items: type: array minItems: 1 maxItems: 100 description: Batch items. Duplicate `resellerPmaAccountId` values within the batch are rejected. items: $ref: "#/components/schemas/ResellerHandshakeItem" ResellerHandshakeError: type: object additionalProperties: false required: - code - message properties: code: type: string description: Stable machine-readable error code for this item. message: type: string description: Human-readable explanation of the failure. ResellerHandshakeStatus: type: string description: Outcome of processing this batch item. enum: - handshake_issued - no_op - mapped - remapped - failed ResellerHandshakeResult: type: object additionalProperties: false required: - resellerCustomerId - resellerPmaAccountId - status properties: resellerCustomerId: type: string resellerPmaAccountId: type: string status: $ref: "#/components/schemas/ResellerHandshakeStatus" handshakeId: type: string description: >- AWS Organizations handshake ID. Absent when no handshake was issued (e.g. `no_op`, `failed`, or dry run). handshakeState: $ref: "#/components/schemas/HandshakeState" error: $ref: "#/components/schemas/ResellerHandshakeError" ResellerHandshakeBatchSummary: type: object description: >- Per-outcome counts across the batch. Field names are snake_case, matching the actual wire format returned by this endpoint — an intentional inconsistency with the rest of the payload, which is camelCase. additionalProperties: false required: - handshake_issued - no_op - mapped - remapped - failed properties: handshake_issued: type: integer no_op: type: integer mapped: type: integer remapped: type: integer failed: type: integer ResellerHandshakeBatchResult: type: object additionalProperties: false required: - dpmaId - results - summary properties: dpmaId: type: string results: type: array items: $ref: "#/components/schemas/ResellerHandshakeResult" summary: $ref: "#/components/schemas/ResellerHandshakeBatchSummary" IamDiff: type: object additionalProperties: false properties: missing: type: array items: type: string extra: type: array items: type: string MappedTenant: type: object additionalProperties: false required: - customerId - tenantType - parentTenant - displayName - resellerPmaAccountId - handshakeState - status properties: customerId: type: string tenantType: type: string parentTenant: type: string displayName: type: string resellerPmaAccountId: type: string example: "123456789012" handshakeState: $ref: "#/components/schemas/HandshakeState" status: type: string effectiveTime: type: string format: date-time nullable: true description: When the handshake reached a terminal state. `null` until then. HandshakeStatus: type: object description: Per-AWS-Organizations-handshake-state counts across all tenants mapped to a PMA. additionalProperties: false required: - total - requested - open - accepted - declined - canceled - expired properties: total: type: integer requested: type: integer open: type: integer accepted: type: integer declined: type: integer canceled: type: integer expired: type: integer ProgramManagementAccount: type: object additionalProperties: false required: - dpmaId - accountId - roleArn - stackName - region - iamStatus - createdAt - tenants - handshakeStatus properties: dpmaId: type: string accountId: type: string description: 12-digit AWS account ID of the program management account. example: "123456789012" roleArn: type: string stackName: type: string region: type: string iamStatus: type: string iamDiff: allOf: - $ref: "#/components/schemas/IamDiff" nullable: true description: >- Present when `iamStatus` indicates drift. `null` when the deployed IAM matches expectations. createdAt: type: string format: date-time lastRefreshTime: type: string format: date-time nullable: true description: When this account's handshake/tenant state was last refreshed. `null` if never refreshed. tenants: type: array items: $ref: "#/components/schemas/MappedTenant" handshakeStatus: $ref: "#/components/schemas/HandshakeStatus" ProgramManagementAccountList: type: object additionalProperties: false required: - items - rowCount properties: items: type: array items: $ref: "#/components/schemas/ProgramManagementAccount" pageToken: type: string description: Opaque cursor for the next page. Absent when this is the last page. rowCount: type: integer EndCustomerMappingItem: type: object additionalProperties: false required: - ecAccountId - ecCustomerId properties: ecAccountId: type: string description: 12-digit AWS account ID of the end-customer account being mapped. example: "123456789012" ecCustomerId: type: string description: DoiT customer ID to map the end-customer account to. curBasePath: type: string description: Optional CUR export base path for the end-customer account. EndCustomerMappingBatchCreate: type: object additionalProperties: false required: - dpmaId - resellerPmaAccountId - items properties: dpmaId: type: string resellerPmaAccountId: type: string description: 12-digit AWS account ID of the reseller's program management account. example: "123456789012" items: type: array minItems: 1 maxItems: 100 description: >- Batch items. Duplicate `ecAccountId` or `ecCustomerId` values within the batch are rejected. items: $ref: "#/components/schemas/EndCustomerMappingItem" EndCustomerMappingResultStatus: type: string enum: - mapped - already_mapped - remapped EndCustomerMappingResult: type: object additionalProperties: false required: - ecAccountId - ecCustomerId - status properties: ecAccountId: type: string ecCustomerId: type: string curBasePath: type: string status: $ref: "#/components/schemas/EndCustomerMappingResultStatus" EndCustomerMappingBatchResult: type: object additionalProperties: false required: - dpmaId - resellerPmaAccountId - results properties: dpmaId: type: string resellerPmaAccountId: type: string results: type: array items: $ref: "#/components/schemas/EndCustomerMappingResult" invalidItems: type: array description: Items rejected before processing. Omitted when every item passed validation. items: $ref: "#/components/schemas/InvalidHandshakeItem" EndCustomerNode: type: object additionalProperties: false required: - ecAccountId - ecCustomerId - status - handshakeState - billSourceType - createdAt properties: ecAccountId: type: string description: 12-digit AWS account ID of the end-customer account. example: "123456789012" ecCustomerId: type: string description: DoiT customer ID the end-customer account is mapped to. status: type: string enum: - pending - cur_export_waiting - active - canceled - declined - expired - revoked handshakeState: $ref: "#/components/schemas/HandshakeState" billSourceType: type: string effectiveTime: type: string format: date-time nullable: true description: When the handshake reached a terminal state. `null` until then. createdAt: type: string format: date-time lastRefreshTime: type: string format: date-time nullable: true description: When this mapping's status was last refreshed. `null` if never refreshed. ListEndCustomersResponse: type: object additionalProperties: false required: - items properties: items: type: array items: $ref: "#/components/schemas/EndCustomerNode" ProgramManagementAccountStatus: type: object additionalProperties: false required: - dpmaId - accountId - iamStatus - createdAt properties: dpmaId: type: string accountId: type: string description: 12-digit AWS account ID of the program management account. example: "123456789012" iamStatus: type: string iamDiff: allOf: - $ref: "#/components/schemas/IamDiff" nullable: true description: >- Present when `iamStatus` indicates drift. `null` when the deployed IAM matches expectations. createdAt: type: string format: date-time updatedAt: type: string format: date-time nullable: true description: When this account's root record was last updated. `null` if never updated. ProgramManagementAccountsStatusResponse: type: object additionalProperties: false required: - items properties: items: type: array items: $ref: "#/components/schemas/ProgramManagementAccountStatus" ResellerAccount: type: object additionalProperties: false required: - resellerPmaAccountId - dpmaId - handshakeId - handshakeState - status - createdAt properties: resellerPmaAccountId: type: string description: 12-digit AWS account ID of the reseller's program management account. example: "123456789012" dpmaId: type: string handshakeId: type: string handshakeState: $ref: "#/components/schemas/HandshakeState" status: type: string enum: - handshake_pending - cur_export_waiting - active - declined - canceled - expired effectiveTime: type: string format: date-time nullable: true description: When the handshake reached a terminal state. `null` until then. createdAt: type: string format: date-time ListResellerAccountsResponse: type: object additionalProperties: false required: - items properties: items: type: array items: $ref: "#/components/schemas/ResellerAccount" ResellerAccountWithTenants: type: object additionalProperties: false required: - resellerPmaAccountId - dpmaId - handshakeId - handshakeState - status - region - iamStatus - createdAt - handshakeStatus - tenants properties: resellerPmaAccountId: type: string description: 12-digit AWS account ID of the reseller's program management account. example: "123456789012" dpmaId: type: string handshakeId: type: string handshakeState: $ref: "#/components/schemas/HandshakeState" status: type: string enum: - handshake_pending - cur_export_waiting - active - declined - canceled - expired region: type: string description: Inherited from the parent DPMA root; the reseller node itself carries no region metadata. iamStatus: type: string description: Inherited from the parent DPMA root; the reseller node itself carries no IAM metadata. lastRefreshTime: type: string format: date-time nullable: true description: Inherited from the parent DPMA root. `null` if never refreshed. effectiveTime: type: string format: date-time nullable: true description: When the handshake reached a terminal state. `null` until then. createdAt: type: string format: date-time handshakeStatus: $ref: "#/components/schemas/HandshakeStatus" tenants: type: array items: $ref: "#/components/schemas/EndCustomerNode" ListResellerAccountsWithTenantsResponse: type: object additionalProperties: false required: - items properties: items: type: array items: $ref: "#/components/schemas/ResellerAccountWithTenants" 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" "403": description: >- Forbidden - The client is not authorized to perform the request. content: application/json: schema: $ref: "#/components/schemas/Error" "403_resource_or_forbidden": description: >- Forbidden - Either the resource does not exist, or the caller is not authorized to access it. These two cases are deliberately indistinguishable to avoid information disclosure: the access guard runs before any existence check, so callers receive 403 (not 404) for unknown IDs on this endpoint. Used by Cloud Diagrams routes keyed by a path-param resource id (e.g. `/clouddiagrams/v1/statussheet/{id}/...`). 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" "409": description: >- Conflict - The request conflicts with the current state of the resource. content: application/json: schema: $ref: "#/components/schemas/Error" "422_billing_transfer_batch_validation": description: >- Unprocessable Entity - One or more items in the batch failed validation before any processing began (missing required fields, or duplicate account/customer IDs within the batch), or a batch-level field such as `dpmaId` is missing or invalid. None of the batch was processed; resubmit with corrected `items`. Invalid items are listed in `invalidItems`. content: application/json: schema: $ref: "#/components/schemas/BillingTransferProblemDetails" "429": description: >- Too Many Requests. 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" "502": description: >- Bad Gateway - The upstream support system returned an error that a retry will not resolve (e.g. an authentication or configuration problem). Escalation is required. content: application/json: schema: $ref: "#/components/schemas/Error" "503": description: >- Service Unavailable - The upstream support system is temporarily unavailable (rate limited, upstream 5xx, or a network error). Retry after the interval indicated by the Retry-After header. content: application/json: schema: $ref: "#/components/schemas/Error" TicketResponseExtAPI: description: Creates a new service or support request. content: application/json: schema: $ref: "#/components/schemas/TicketResponseExtAPI" TicketsList: description: Lists all historical requests the user has access to. content: application/json: schema: $ref: "#/components/schemas/TicketsList" anomaliesResponse: description: Lists all cloud cost anomalies. content: application/json: schema: type: object properties: Report: $ref: "#/components/schemas/AnomaliesResponse" anomalyResponse: description: Returns cloud cost anomaly details based on anomalyId. content: application/json: schema: required: - attribution - billingAccount - costOfAnomaly - platform - scope - serviceName - severityLevel - startTime - timeFrame - top3SKUs type: object properties: attribution: type: string description: Attribution ID billingAccount: type: string description: Billing account ID costOfAnomaly: type: number description: Excess cost over and above the expected normal cost format: double platform: type: string description: Cloud Provider name scope: type: string description: "Scope: Project or Account" serviceName: type: string description: Service name severityLevel: type: string description: "Severity level: Information, Warning or Critical" startTime: type: integer description: Usage start time of the anomaly format: int64 timeFrame: type: string description: "Timeframe: Daily or Hourly" top3SKUs: $ref: "#/components/schemas/AnomalySKUArray" resourceData: $ref: "#/components/schemas/AnomalyResourceArray" 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 (§15) 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 (§15) 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 product line 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 (§8) 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 (§8) 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 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 Forbidden: description: Authenticated but not authorised to access this customer's PS4C resources. 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 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 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 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 parameters: maxResults: name: maxResults in: query description: >- The maximum number of results to return in a single page. Use the page tokens to iterate through the entire collection. schema: type: integer format: int64 default: 50 pageToken: name: pageToken in: query description: Page token, returned by a previous call, to request the next page of results schema: type: string includeRevoked: name: includeRevoked in: query required: false description: >- If `true`, includes end-customer mappings that have been revoked. Defaults to `false` (revoked mappings are excluded). schema: type: boolean default: false reportId: name: id in: path description: Report ID. See [Resource IDs](https://developer.doit.com/docs/resource-ids). required: true schema: type: string sortOrder: name: sortOrder in: query description: Sort order can be ascending or descending. schema: type: string enum: - asc - desc resourceType: name: resourceType in: path description: Resource type. required: true schema: type: string enum: - alerts - budgets - reports - allocations resourceId: name: resourceId in: path description: Resource ID. See [Resource IDs](https://developer.doit.com/docs/resource-ids). required: true schema: type: string tenantId: in: header name: X-Tenant-Id required: false description: | Tenant (customer) identifier that conveys the tenant scope for the request (DoiT API Design Standards §15). Resolution when the header is absent: - A key scoped to exactly one tenant resolves to that tenant automatically; the header is optional. - A principal that can access more than one tenant (e.g. DoiT-employee keys) must supply the header. Without it the request is rejected with `400` and code `tenant_id_required` — the server does not guess across tenant scopes. When the header is present but conflicts with the tenant the key is scoped to, the request is rejected with `400` and code `tenant_id_mismatch`. schema: type: string example: Kp2mN8qL4vR0sT1wX3yZ managementAccountId: in: path name: managementAccountId required: true description: 12-digit AWS management (payer) account ID (the account that owns the AWS Organization) that scopes the request. schema: type: string pattern: ^\d{12}$ example: "123456789012" 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 service: in: query name: service required: false description: Filter by PS4C product line (AWS planned purchases). schema: type: string enum: - compute - database serviceId: in: path name: serviceId required: true description: Service ID (compute|database). schema: type: string enum: - compute - database eligibleSpendGranularity: in: query name: granularity required: false description: Time bucket for eligible spend data points. schema: type: string enum: - hour - day - week - month default: day memberAccountId: in: path name: memberAccountId required: true description: AWS member account ID (12-digit AWS account number). schema: type: string pattern: ^\d{12}$ example: "987654321098" securitySchemes: api_key: type: apiKey name: Authorization description: Use the "Bearer " 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 headers: RequestId: description: DoiT request identifier for support and log correlation. Format `req_`. 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 x-samples-languages: - curl - go - node - python x-cli-config: security: oauth2 params: client_id: cli