{ "openapi": "3.1.0", "info": { "title": "nOps Public API", "version": "1.0.0", "description": "Programmatic access to nOps cost, budgets, cost allocation, Explorer dashboards, AI optimization, MAP manager, business unit economics, contract tracker, reports, recommendations, feed, scheduled prompts, and notifications. Authenticate with an API key (Bearer token). Available on Inform + Operate." }, "servers": [ { "url": "https://api.nops.io", "description": "Production" } ], "tags": [ { "name": "Recommendations", "description": "Cost optimization recommendations." }, { "name": "Anomalies", "description": "AWS cost anomaly detection." }, { "name": "Explorer", "description": "Cost Explorer queries — summary, history, heatmap, and dimensions." }, { "name": "Budgets", "description": "Budgets, planning grids, alerts, and exports." }, { "name": "Reports", "description": "Saved reports — create, update, render, and send." }, { "name": "Feed", "description": "Clara Feed runs and delivery history." }, { "name": "Scheduled prompts", "description": "Scheduled Clara prompts and manual runs." }, { "name": "Notifications", "description": "Schedule and manage notification deliveries." }, { "name": "Commitments", "description": "Commitment inventory (reserved for future use)." }, { "name": "Cost allocation", "description": "Cost Allocation showbacks, rules, and spend analytics." }, { "name": "Explorer dashboards", "description": "Explorer dashboard layouts and widgets." }, { "name": "AI optimization", "description": "AI Optimization default dashboard and anomaly insights." }, { "name": "MAP Manager", "description": "AWS Migration Acceleration Program (MAP) project tracking." }, { "name": "Business unit economics", "description": "Business unit economics models, units, and portfolio summaries." }, { "name": "Contract tracker", "description": "Enterprise contract tracking and burndown analytics." } ], "security": [ { "bearerApiKey": [] } ], "components": { "securitySchemes": { "bearerApiKey": { "type": "http", "scheme": "bearer", "description": "API key from Settings → Security → API Keys. Pass as `Authorization: Bearer YOUR_API_KEY`." } }, "schemas": { "PublicApiError": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "request_id": { "type": "string" } }, "required": [ "code", "message", "request_id" ] } }, "required": [ "error" ] }, "Pagination": { "type": "object", "properties": { "limit": { "type": "integer", "description": "Page size used for this response." }, "has_more": { "type": "boolean", "description": "True when more results are available via next_cursor." }, "next_cursor": { "type": "string", "nullable": true, "description": "Opaque cursor for the next page, or null when there are no more results." } }, "required": [ "limit", "has_more", "next_cursor" ] } }, "parameters": {} }, "paths": { "/v1/recommendations": { "get": { "tags": [ "Recommendations" ], "summary": "List recommendations", "description": "Returns cost optimization recommendations for your organization.", "operationId": "listRecommendations", "security": [ { "bearerApiKey": [] } ], "parameters": [ { "schema": { "type": "integer", "minimum": 1, "maximum": 200, "description": "Maximum items to return (1–200, default 50)." }, "required": false, "name": "limit", "in": "query" }, { "schema": { "type": "string", "description": "Opaque cursor from a previous response's `pagination.next_cursor`." }, "required": false, "name": "cursor", "in": "query" } ], "responses": { "200": { "description": "List recommendations", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "array", "items": { "type": "object", "description": "JSON object", "additionalProperties": true } }, "pagination": { "$ref": "#/components/schemas/Pagination" } }, "required": [ "data", "pagination" ] }, "example": { "data": [ { "recommendation_id": "rec-ec2-rightsize-001", "recommendation_name": "Rightsize underutilized EC2 instances", "estimated_monthly_savings": 842.5, "implementation_effort": "Low", "category": "Compute", "action_type": "Rightsize", "account_name": "Production", "region": "us-east-1", "resource_id": "i-0abc123def456" } ], "pagination": { "limit": 50, "has_more": false, "next_cursor": null } } } } }, "401": { "description": "Unauthorized — invalid or missing API key", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PublicApiError" }, "example": { "error": { "code": "forbidden_scope", "message": "API key is missing required scope: budgets:write", "request_id": "550e8400-e29b-41d4-a716-446655440000" } } } } }, "403": { "description": "Forbidden — insufficient permissions or entitlement", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PublicApiError" }, "example": { "error": { "code": "forbidden_scope", "message": "API key is missing required scope: budgets:write", "request_id": "550e8400-e29b-41d4-a716-446655440000" } } } } } } } }, "/v1/anomalies": { "get": { "tags": [ "Anomalies" ], "summary": "List anomalies", "description": "Returns AWS cost anomalies detected for your organization.", "operationId": "listAnomalies", "security": [ { "bearerApiKey": [] } ], "parameters": [ { "schema": { "type": "integer", "minimum": 1, "maximum": 200, "description": "Maximum items to return (1–200, default 50)." }, "required": false, "name": "limit", "in": "query" }, { "schema": { "type": "string", "description": "Opaque cursor from a previous response's `pagination.next_cursor`." }, "required": false, "name": "cursor", "in": "query" } ], "responses": { "200": { "description": "List anomalies", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "array", "items": { "type": "object", "description": "JSON object", "additionalProperties": true } }, "pagination": { "$ref": "#/components/schemas/Pagination" } }, "required": [ "data", "pagination" ] }, "example": { "data": [ { "anomaly_id": "anom-ec2-spike-001", "service": "Amazon Elastic Compute Cloud - Compute", "start_date": "2026-07-10", "end_date": "2026-07-12", "score_current": 0.92, "score_max": 0.95, "impact_max": 1240.5, "impact_total": 2481, "impact_pct": 42.3, "impact_actual_spend": 4200, "impact_expected_spend": 1718.5, "dimension_value": "us-east-1", "detection_source": "aws" } ], "pagination": { "limit": 50, "has_more": false, "next_cursor": null } } } } }, "401": { "description": "Unauthorized — invalid or missing API key", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PublicApiError" }, "example": { "error": { "code": "forbidden_scope", "message": "API key is missing required scope: budgets:write", "request_id": "550e8400-e29b-41d4-a716-446655440000" } } } } }, "403": { "description": "Forbidden — insufficient permissions or entitlement", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PublicApiError" }, "example": { "error": { "code": "forbidden_scope", "message": "API key is missing required scope: budgets:write", "request_id": "550e8400-e29b-41d4-a716-446655440000" } } } } } } } }, "/v1/explorer/summary": { "post": { "tags": [ "Explorer" ], "summary": "Explorer summary totals", "description": "Aggregate cost totals for the selected filters and date range.", "operationId": "explorerSummary", "security": [ { "bearerApiKey": [] } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "description": "JSON request body", "additionalProperties": true }, "example": { "dateRange": { "start": "2026-05-31", "end": "2026-06-29" }, "groupBy": "product_product_name", "costType": "line_item_unblended_cost", "granularity": "day", "filters": [] } } } }, "responses": { "200": { "description": "Explorer summary totals", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "object", "description": "JSON object", "additionalProperties": true } }, "required": [ "data" ] }, "example": { "data": { "cards": [ { "title": "Yesterday", "description": "", "value": 1240.55, "previousValue": 1180.2 }, { "title": "MTD", "description": "", "value": 18450.12, "previousValue": 17200 }, { "title": "Interval", "description": "", "value": 42100.88, "previousValue": 39800.5 } ], "servedFromCache": true } } } } }, "401": { "description": "Unauthorized — invalid or missing API key", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PublicApiError" }, "example": { "error": { "code": "forbidden_scope", "message": "API key is missing required scope: budgets:write", "request_id": "550e8400-e29b-41d4-a716-446655440000" } } } } }, "403": { "description": "Forbidden — insufficient permissions or entitlement", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PublicApiError" }, "example": { "error": { "code": "forbidden_scope", "message": "API key is missing required scope: budgets:write", "request_id": "550e8400-e29b-41d4-a716-446655440000" } } } } } } } }, "/v1/explorer/previous-period": { "post": { "tags": [ "Explorer" ], "summary": "Explorer previous period comparison", "description": "Compare current period spend against the previous period.", "operationId": "explorerPreviousPeriod", "security": [ { "bearerApiKey": [] } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "description": "JSON request body", "additionalProperties": true }, "example": { "dateRange": { "start": "2026-05-31", "end": "2026-06-29" }, "groupBy": "product_product_name", "costType": "line_item_unblended_cost", "granularity": "day", "filters": [] } } } }, "responses": { "200": { "description": "Explorer previous period comparison", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "object", "description": "JSON object", "additionalProperties": true } }, "required": [ "data" ] }, "example": { "data": { "currentTotal": 42100.88, "previousTotal": 39800.5, "changePercent": 5.78, "servedFromCache": true } } } } }, "401": { "description": "Unauthorized — invalid or missing API key", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PublicApiError" }, "example": { "error": { "code": "forbidden_scope", "message": "API key is missing required scope: budgets:write", "request_id": "550e8400-e29b-41d4-a716-446655440000" } } } } }, "403": { "description": "Forbidden — insufficient permissions or entitlement", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PublicApiError" }, "example": { "error": { "code": "forbidden_scope", "message": "API key is missing required scope: budgets:write", "request_id": "550e8400-e29b-41d4-a716-446655440000" } } } } } } } }, "/v1/explorer/history": { "post": { "tags": [ "Explorer" ], "summary": "Explorer cost history", "description": "Time-series cost history for the selected filters.", "operationId": "explorerHistory", "security": [ { "bearerApiKey": [] } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "description": "JSON request body", "additionalProperties": true }, "example": { "dateRange": { "start": "2026-05-31", "end": "2026-06-29" }, "groupBy": "product_product_name", "costType": "line_item_unblended_cost", "granularity": "day", "filters": [] } } } }, "responses": { "200": { "description": "Explorer cost history", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "object", "description": "JSON object", "additionalProperties": true } }, "required": [ "data" ] }, "example": { "data": { "costRows": [ { "product_product_name": "Amazon EC2", "day": 20260601, "cost": 1240.55 } ], "totalsByTimeRows": [], "usageRows": [], "usageGroupRows": [], "timeColumn": "day", "groupBy": "product_product_name", "servedFromCache": true } } } } }, "401": { "description": "Unauthorized — invalid or missing API key", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PublicApiError" }, "example": { "error": { "code": "forbidden_scope", "message": "API key is missing required scope: budgets:write", "request_id": "550e8400-e29b-41d4-a716-446655440000" } } } } }, "403": { "description": "Forbidden — insufficient permissions or entitlement", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PublicApiError" }, "example": { "error": { "code": "forbidden_scope", "message": "API key is missing required scope: budgets:write", "request_id": "550e8400-e29b-41d4-a716-446655440000" } } } } } } } }, "/v1/explorer/heatmap": { "post": { "tags": [ "Explorer" ], "summary": "Explorer cost heatmap", "description": "Heatmap-style cost breakdown across dimensions.", "operationId": "explorerHeatmap", "security": [ { "bearerApiKey": [] } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "description": "JSON request body", "additionalProperties": true }, "example": { "dateRange": { "start": "2026-05-31", "end": "2026-06-29" }, "groupBy": "product_product_name", "costType": "line_item_unblended_cost", "granularity": "day", "filters": [] } } } }, "responses": { "200": { "description": "Explorer cost heatmap", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "object", "description": "JSON object", "additionalProperties": true } }, "required": [ "data" ] }, "example": { "data": { "rows": [ { "dimension": "Amazon EC2", "day": "2026-06-01", "cost": 420.12 }, { "dimension": "Amazon S3", "day": "2026-06-01", "cost": 88.4 } ], "servedFromCache": true } } } } }, "401": { "description": "Unauthorized — invalid or missing API key", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PublicApiError" }, "example": { "error": { "code": "forbidden_scope", "message": "API key is missing required scope: budgets:write", "request_id": "550e8400-e29b-41d4-a716-446655440000" } } } } }, "403": { "description": "Forbidden — insufficient permissions or entitlement", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PublicApiError" }, "example": { "error": { "code": "forbidden_scope", "message": "API key is missing required scope: budgets:write", "request_id": "550e8400-e29b-41d4-a716-446655440000" } } } } } } } }, "/v1/explorer/dimensions/{key}/values": { "get": { "tags": [ "Explorer" ], "summary": "List dimension values", "description": "List available values for an Explorer dimension key.", "operationId": "explorerDimensionValues", "security": [ { "bearerApiKey": [] } ], "parameters": [ { "schema": { "type": "string", "description": "Dimension key (for example, service or account)" }, "required": true, "name": "key", "in": "path" } ], "responses": { "200": { "description": "List dimension values", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "object", "description": "JSON object", "additionalProperties": true } }, "required": [ "data" ] }, "example": { "data": { "items": [ { "value": "Amazon EC2", "cost": 18450.12 }, { "value": "Amazon S3", "cost": 3200.5 } ], "values": [ "Amazon EC2", "Amazon S3" ], "hasMore": false, "servedFromCache": true } } } } }, "401": { "description": "Unauthorized — invalid or missing API key", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PublicApiError" }, "example": { "error": { "code": "forbidden_scope", "message": "API key is missing required scope: budgets:write", "request_id": "550e8400-e29b-41d4-a716-446655440000" } } } } }, "403": { "description": "Forbidden — insufficient permissions or entitlement", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PublicApiError" }, "example": { "error": { "code": "forbidden_scope", "message": "API key is missing required scope: budgets:write", "request_id": "550e8400-e29b-41d4-a716-446655440000" } } } } } } } }, "/v1/budgets": { "get": { "tags": [ "Budgets" ], "summary": "List budgets", "operationId": "listBudgets", "security": [ { "bearerApiKey": [] } ], "parameters": [ { "schema": { "type": "integer", "minimum": 1, "maximum": 200, "description": "Maximum items to return (1–200, default 50)." }, "required": false, "name": "limit", "in": "query" }, { "schema": { "type": "string", "description": "Opaque cursor from a previous response's `pagination.next_cursor`." }, "required": false, "name": "cursor", "in": "query" } ], "responses": { "200": { "description": "List budgets", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "array", "items": { "type": "object", "description": "JSON object", "additionalProperties": true } }, "pagination": { "$ref": "#/components/schemas/Pagination" } }, "required": [ "data", "pagination" ] }, "example": { "data": [ { "id": "budget-1", "name": "Q1 Cloud Budget", "targetType": "BUDGET", "period": "MONTHLY", "status": "ACTIVE", "numberOfPeriods": 12, "startDate": "2026-01-01", "endDate": "2026-12-01", "lookbackPeriod": null, "budgetType": null, "startingValue": null, "customStartingValue": null, "growthRate": null, "normalizationPeriod": false, "organizationId": "org-1", "nopsClientId": 42, "creatorId": "user-1", "explorerReportId": "report-1", "createdAt": "2026-07-17T12:00:00.000Z", "updatedAt": "2026-07-17T12:00:00.000Z", "explorerReport": { "id": "report-1", "name": "AWS Spend by Account" }, "creator": { "id": "user-1", "firstName": "FinOps", "lastName": "Analyst", "email": "finops@example.com" }, "plannings": [] } ], "pagination": { "limit": 50, "has_more": false, "next_cursor": null } } } } }, "401": { "description": "Unauthorized — invalid or missing API key", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PublicApiError" }, "example": { "error": { "code": "forbidden_scope", "message": "API key is missing required scope: budgets:write", "request_id": "550e8400-e29b-41d4-a716-446655440000" } } } } }, "403": { "description": "Forbidden — insufficient permissions or entitlement", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PublicApiError" }, "example": { "error": { "code": "forbidden_scope", "message": "API key is missing required scope: budgets:write", "request_id": "550e8400-e29b-41d4-a716-446655440000" } } } } } } }, "post": { "tags": [ "Budgets" ], "summary": "Create budget", "operationId": "createBudget", "security": [ { "bearerApiKey": [] } ], "parameters": [ { "schema": { "type": "string", "maxLength": 64, "description": "Unique key for safe retries on write requests (required, max 64 characters)." }, "required": true, "name": "Idempotency-Key", "in": "header" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "description": "JSON request body", "additionalProperties": true }, "example": { "name": "Q1 Cloud Budget", "targetType": "BUDGET", "period": "MONTHLY", "status": "DRAFT", "numberOfPeriods": 12, "startDate": "2026-01-01", "explorerReportId": "report-1" } } } }, "responses": { "200": { "description": "Create budget", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "object", "description": "JSON object", "additionalProperties": true } }, "required": [ "data" ] }, "example": { "data": { "budget": { "id": "budget-1", "name": "Q1 Cloud Budget", "targetType": "BUDGET", "period": "MONTHLY", "status": "ACTIVE", "numberOfPeriods": 12, "startDate": "2026-01-01", "endDate": "2026-12-01", "lookbackPeriod": null, "budgetType": null, "startingValue": null, "customStartingValue": null, "growthRate": null, "normalizationPeriod": false, "organizationId": "org-1", "nopsClientId": 42, "creatorId": "user-1", "explorerReportId": "report-1", "createdAt": "2026-07-17T12:00:00.000Z", "updatedAt": "2026-07-17T12:00:00.000Z", "explorerReport": { "id": "report-1", "name": "AWS Spend by Account" }, "creator": { "id": "user-1", "firstName": "FinOps", "lastName": "Analyst", "email": "finops@example.com" }, "plannings": [] } } } } } }, "401": { "description": "Unauthorized — invalid or missing API key", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PublicApiError" }, "example": { "error": { "code": "forbidden_scope", "message": "API key is missing required scope: budgets:write", "request_id": "550e8400-e29b-41d4-a716-446655440000" } } } } }, "403": { "description": "Forbidden — insufficient permissions or entitlement", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PublicApiError" }, "example": { "error": { "code": "forbidden_scope", "message": "API key is missing required scope: budgets:write", "request_id": "550e8400-e29b-41d4-a716-446655440000" } } } } } } } }, "/v1/budgets/lookback": { "get": { "tags": [ "Budgets" ], "summary": "Budget lookback preview", "description": "Preview historical spend for budget planning.", "operationId": "budgetLookbackGet", "security": [ { "bearerApiKey": [] } ], "responses": { "200": { "description": "Budget lookback preview", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "object", "description": "JSON object", "additionalProperties": true } }, "required": [ "data" ] }, "example": { "data": { "periods": [ { "periodKey": "2026-01", "actual": 15200.5, "projected": 16000 }, { "periodKey": "2026-02", "actual": 14800.25, "projected": 16000 } ] } } } } }, "401": { "description": "Unauthorized — invalid or missing API key", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PublicApiError" }, "example": { "error": { "code": "forbidden_scope", "message": "API key is missing required scope: budgets:write", "request_id": "550e8400-e29b-41d4-a716-446655440000" } } } } }, "403": { "description": "Forbidden — insufficient permissions or entitlement", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PublicApiError" }, "example": { "error": { "code": "forbidden_scope", "message": "API key is missing required scope: budgets:write", "request_id": "550e8400-e29b-41d4-a716-446655440000" } } } } } } }, "post": { "tags": [ "Budgets" ], "summary": "Budget lookback query", "description": "Query historical spend for budget planning with filters.", "operationId": "budgetLookbackPost", "security": [ { "bearerApiKey": [] } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "description": "JSON request body", "additionalProperties": true }, "example": { "explorerReportId": "report-1", "startDate": "2026-01-01", "period": "MONTHLY", "lookbackPeriod": 6, "numberOfPeriods": 12 } } } }, "responses": { "200": { "description": "Budget lookback query", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "object", "description": "JSON object", "additionalProperties": true } }, "required": [ "data" ] }, "example": { "data": { "periods": [ { "periodKey": "2026-01", "actual": 15200.5 }, { "periodKey": "2026-02", "actual": 14800.25 } ] } } } } }, "401": { "description": "Unauthorized — invalid or missing API key", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PublicApiError" }, "example": { "error": { "code": "forbidden_scope", "message": "API key is missing required scope: budgets:write", "request_id": "550e8400-e29b-41d4-a716-446655440000" } } } } }, "403": { "description": "Forbidden — insufficient permissions or entitlement", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PublicApiError" }, "example": { "error": { "code": "forbidden_scope", "message": "API key is missing required scope: budgets:write", "request_id": "550e8400-e29b-41d4-a716-446655440000" } } } } } } } }, "/v1/budgets/{id}": { "get": { "tags": [ "Budgets" ], "summary": "Get budget", "operationId": "getBudget", "security": [ { "bearerApiKey": [] } ], "parameters": [ { "schema": { "type": "string", "description": "Budget ID" }, "required": true, "name": "id", "in": "path" } ], "responses": { "200": { "description": "Get budget", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "object", "description": "JSON object", "additionalProperties": true } }, "required": [ "data" ] }, "example": { "data": { "budget": { "id": "budget-1", "name": "Q1 Cloud Budget", "targetType": "BUDGET", "period": "MONTHLY", "status": "ACTIVE", "numberOfPeriods": 12, "startDate": "2026-01-01", "endDate": "2026-12-01", "lookbackPeriod": null, "budgetType": null, "startingValue": null, "customStartingValue": null, "growthRate": null, "normalizationPeriod": false, "organizationId": "org-1", "nopsClientId": 42, "creatorId": "user-1", "explorerReportId": "report-1", "createdAt": "2026-07-17T12:00:00.000Z", "updatedAt": "2026-07-17T12:00:00.000Z", "explorerReport": { "id": "report-1", "name": "AWS Spend by Account" }, "creator": { "id": "user-1", "firstName": "FinOps", "lastName": "Analyst", "email": "finops@example.com" }, "plannings": [], "metrics": { "totalTarget": 16000, "totalActual": 15200.5, "variance": -799.5 }, "dimensions": [] } } } } } }, "401": { "description": "Unauthorized — invalid or missing API key", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PublicApiError" }, "example": { "error": { "code": "forbidden_scope", "message": "API key is missing required scope: budgets:write", "request_id": "550e8400-e29b-41d4-a716-446655440000" } } } } }, "403": { "description": "Forbidden — insufficient permissions or entitlement", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PublicApiError" }, "example": { "error": { "code": "forbidden_scope", "message": "API key is missing required scope: budgets:write", "request_id": "550e8400-e29b-41d4-a716-446655440000" } } } } } } }, "patch": { "tags": [ "Budgets" ], "summary": "Update budget", "operationId": "updateBudget", "security": [ { "bearerApiKey": [] } ], "parameters": [ { "schema": { "type": "string", "description": "Budget ID" }, "required": true, "name": "id", "in": "path" }, { "schema": { "type": "string", "maxLength": 64, "description": "Unique key for safe retries on write requests (required, max 64 characters)." }, "required": true, "name": "Idempotency-Key", "in": "header" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "description": "JSON request body", "additionalProperties": true }, "example": { "name": "Q1 Cloud Budget (updated)" } } } }, "responses": { "200": { "description": "Update budget", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "object", "description": "JSON object", "additionalProperties": true } }, "required": [ "data" ] }, "example": { "data": { "budget": { "id": "budget-1", "name": "Q1 Cloud Budget (updated)", "targetType": "BUDGET", "period": "MONTHLY", "status": "ACTIVE", "numberOfPeriods": 12, "startDate": "2026-01-01", "endDate": "2026-12-01", "lookbackPeriod": null, "budgetType": null, "startingValue": null, "customStartingValue": null, "growthRate": null, "normalizationPeriod": false, "organizationId": "org-1", "nopsClientId": 42, "creatorId": "user-1", "explorerReportId": "report-1", "createdAt": "2026-07-17T12:00:00.000Z", "updatedAt": "2026-07-17T12:00:00.000Z", "explorerReport": { "id": "report-1", "name": "AWS Spend by Account" }, "creator": { "id": "user-1", "firstName": "FinOps", "lastName": "Analyst", "email": "finops@example.com" }, "plannings": [] } } } } } }, "401": { "description": "Unauthorized — invalid or missing API key", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PublicApiError" }, "example": { "error": { "code": "forbidden_scope", "message": "API key is missing required scope: budgets:write", "request_id": "550e8400-e29b-41d4-a716-446655440000" } } } } }, "403": { "description": "Forbidden — insufficient permissions or entitlement", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PublicApiError" }, "example": { "error": { "code": "forbidden_scope", "message": "API key is missing required scope: budgets:write", "request_id": "550e8400-e29b-41d4-a716-446655440000" } } } } } } }, "delete": { "tags": [ "Budgets" ], "summary": "Delete budget", "operationId": "deleteBudget", "security": [ { "bearerApiKey": [] } ], "parameters": [ { "schema": { "type": "string", "description": "Budget ID" }, "required": true, "name": "id", "in": "path" } ], "responses": { "200": { "description": "Delete budget", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "object", "description": "JSON object", "additionalProperties": true } }, "required": [ "data" ] }, "example": { "data": { "success": true } } } } }, "401": { "description": "Unauthorized — invalid or missing API key", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PublicApiError" }, "example": { "error": { "code": "forbidden_scope", "message": "API key is missing required scope: budgets:write", "request_id": "550e8400-e29b-41d4-a716-446655440000" } } } } }, "403": { "description": "Forbidden — insufficient permissions or entitlement", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PublicApiError" }, "example": { "error": { "code": "forbidden_scope", "message": "API key is missing required scope: budgets:write", "request_id": "550e8400-e29b-41d4-a716-446655440000" } } } } } } } }, "/v1/budgets/{id}/actuals": { "get": { "tags": [ "Budgets" ], "summary": "Get budget actuals", "operationId": "getBudgetActuals", "security": [ { "bearerApiKey": [] } ], "parameters": [ { "schema": { "type": "string", "description": "Budget ID" }, "required": true, "name": "id", "in": "path" } ], "responses": { "200": { "description": "Get budget actuals", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "object", "description": "JSON object", "additionalProperties": true } }, "required": [ "data" ] }, "example": { "data": { "actualsByPlanning": { "planning-1": { "2026-01": 15200.5, "2026-02": 14800.25 } }, "accountActualsByPeriod": { "2026-01": 15200.5, "2026-02": 14800.25 } } } } } }, "401": { "description": "Unauthorized — invalid or missing API key", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PublicApiError" }, "example": { "error": { "code": "forbidden_scope", "message": "API key is missing required scope: budgets:write", "request_id": "550e8400-e29b-41d4-a716-446655440000" } } } } }, "403": { "description": "Forbidden — insufficient permissions or entitlement", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PublicApiError" }, "example": { "error": { "code": "forbidden_scope", "message": "API key is missing required scope: budgets:write", "request_id": "550e8400-e29b-41d4-a716-446655440000" } } } } } } } }, "/v1/budgets/{id}/planning": { "get": { "tags": [ "Budgets" ], "summary": "Get budget planning grid", "operationId": "getBudgetPlanning", "security": [ { "bearerApiKey": [] } ], "parameters": [ { "schema": { "type": "string", "description": "Budget ID" }, "required": true, "name": "id", "in": "path" } ], "responses": { "200": { "description": "Get budget planning grid", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "object", "description": "JSON object", "additionalProperties": true } }, "required": [ "data" ] }, "example": { "data": { "plannings": [ { "id": "planning-1", "budgetId": "budget-1", "dimension1": "billing_account_name", "dimension2": "", "previousMonth": 15200.5, "avgLookback": 15000, "percentGrowth": 5, "percentSpend": null, "targetItems": { "Production": 12000, "Staging": 4000 }, "targetType": "PLANNING_ITEM", "createdAt": "2026-07-17T12:00:00.000Z", "updatedAt": "2026-07-17T12:00:00.000Z" } ] } } } } }, "401": { "description": "Unauthorized — invalid or missing API key", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PublicApiError" }, "example": { "error": { "code": "forbidden_scope", "message": "API key is missing required scope: budgets:write", "request_id": "550e8400-e29b-41d4-a716-446655440000" } } } } }, "403": { "description": "Forbidden — insufficient permissions or entitlement", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PublicApiError" }, "example": { "error": { "code": "forbidden_scope", "message": "API key is missing required scope: budgets:write", "request_id": "550e8400-e29b-41d4-a716-446655440000" } } } } } } }, "post": { "tags": [ "Budgets" ], "summary": "Save budget planning grid", "operationId": "saveBudgetPlanning", "security": [ { "bearerApiKey": [] } ], "parameters": [ { "schema": { "type": "string", "description": "Budget ID" }, "required": true, "name": "id", "in": "path" }, { "schema": { "type": "string", "maxLength": 64, "description": "Unique key for safe retries on write requests (required, max 64 characters)." }, "required": true, "name": "Idempotency-Key", "in": "header" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "description": "JSON request body", "additionalProperties": true }, "example": { "dimension1": "billing_account_name", "dimension2": "", "targetItems": { "Production": 12000, "Staging": 4000 } } } } }, "responses": { "200": { "description": "Save budget planning grid", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "object", "description": "JSON object", "additionalProperties": true } }, "required": [ "data" ] }, "example": { "data": { "success": true } } } } }, "401": { "description": "Unauthorized — invalid or missing API key", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PublicApiError" }, "example": { "error": { "code": "forbidden_scope", "message": "API key is missing required scope: budgets:write", "request_id": "550e8400-e29b-41d4-a716-446655440000" } } } } }, "403": { "description": "Forbidden — insufficient permissions or entitlement", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PublicApiError" }, "example": { "error": { "code": "forbidden_scope", "message": "API key is missing required scope: budgets:write", "request_id": "550e8400-e29b-41d4-a716-446655440000" } } } } } } }, "patch": { "tags": [ "Budgets" ], "summary": "Patch budget planning grid", "operationId": "patchBudgetPlanning", "security": [ { "bearerApiKey": [] } ], "parameters": [ { "schema": { "type": "string", "description": "Budget ID" }, "required": true, "name": "id", "in": "path" }, { "schema": { "type": "string", "maxLength": 64, "description": "Unique key for safe retries on write requests (required, max 64 characters)." }, "required": true, "name": "Idempotency-Key", "in": "header" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "description": "JSON request body", "additionalProperties": true }, "example": { "percentGrowth": 8 } } } }, "responses": { "200": { "description": "Patch budget planning grid", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "object", "description": "JSON object", "additionalProperties": true } }, "required": [ "data" ] }, "example": { "data": { "success": true } } } } }, "401": { "description": "Unauthorized — invalid or missing API key", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PublicApiError" }, "example": { "error": { "code": "forbidden_scope", "message": "API key is missing required scope: budgets:write", "request_id": "550e8400-e29b-41d4-a716-446655440000" } } } } }, "403": { "description": "Forbidden — insufficient permissions or entitlement", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PublicApiError" }, "example": { "error": { "code": "forbidden_scope", "message": "API key is missing required scope: budgets:write", "request_id": "550e8400-e29b-41d4-a716-446655440000" } } } } } } }, "delete": { "tags": [ "Budgets" ], "summary": "Clear budget planning grid", "operationId": "deleteBudgetPlanning", "security": [ { "bearerApiKey": [] } ], "parameters": [ { "schema": { "type": "string", "description": "Budget ID" }, "required": true, "name": "id", "in": "path" } ], "responses": { "200": { "description": "Clear budget planning grid", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "object", "description": "JSON object", "additionalProperties": true } }, "required": [ "data" ] }, "example": { "data": { "success": true } } } } }, "401": { "description": "Unauthorized — invalid or missing API key", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PublicApiError" }, "example": { "error": { "code": "forbidden_scope", "message": "API key is missing required scope: budgets:write", "request_id": "550e8400-e29b-41d4-a716-446655440000" } } } } }, "403": { "description": "Forbidden — insufficient permissions or entitlement", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PublicApiError" }, "example": { "error": { "code": "forbidden_scope", "message": "API key is missing required scope: budgets:write", "request_id": "550e8400-e29b-41d4-a716-446655440000" } } } } } } } }, "/v1/budgets/{id}/planning/generate": { "post": { "tags": [ "Budgets" ], "summary": "Generate budget planning grid", "operationId": "generateBudgetPlanning", "security": [ { "bearerApiKey": [] } ], "parameters": [ { "schema": { "type": "string", "description": "Budget ID" }, "required": true, "name": "id", "in": "path" }, { "schema": { "type": "string", "maxLength": 64, "description": "Unique key for safe retries on write requests (required, max 64 characters)." }, "required": true, "name": "Idempotency-Key", "in": "header" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "description": "JSON request body", "additionalProperties": true }, "example": { "dimension1": "billing_account_name" } } } }, "responses": { "200": { "description": "Generate budget planning grid", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "object", "description": "JSON object", "additionalProperties": true } }, "required": [ "data" ] }, "example": { "data": { "success": true, "plannings": [] } } } } }, "401": { "description": "Unauthorized — invalid or missing API key", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PublicApiError" }, "example": { "error": { "code": "forbidden_scope", "message": "API key is missing required scope: budgets:write", "request_id": "550e8400-e29b-41d4-a716-446655440000" } } } } }, "403": { "description": "Forbidden — insufficient permissions or entitlement", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PublicApiError" }, "example": { "error": { "code": "forbidden_scope", "message": "API key is missing required scope: budgets:write", "request_id": "550e8400-e29b-41d4-a716-446655440000" } } } } } } } }, "/v1/budgets/{id}/send": { "post": { "tags": [ "Budgets" ], "summary": "Send budget report", "operationId": "sendBudget", "security": [ { "bearerApiKey": [] } ], "parameters": [ { "schema": { "type": "string", "description": "Budget ID" }, "required": true, "name": "id", "in": "path" }, { "schema": { "type": "string", "maxLength": 64, "description": "Unique key for safe retries on write requests (required, max 64 characters)." }, "required": true, "name": "Idempotency-Key", "in": "header" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "description": "JSON request body", "additionalProperties": true }, "example": { "recipients": [ "finops@example.com" ], "subject": "Q1 budget report", "body": "Attached is your budget summary." } } } }, "responses": { "200": { "description": "Send budget report", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "object", "description": "JSON object", "additionalProperties": true } }, "required": [ "data" ] }, "example": { "data": { "success": true } } } } }, "401": { "description": "Unauthorized — invalid or missing API key", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PublicApiError" }, "example": { "error": { "code": "forbidden_scope", "message": "API key is missing required scope: budgets:write", "request_id": "550e8400-e29b-41d4-a716-446655440000" } } } } }, "403": { "description": "Forbidden — insufficient permissions or entitlement", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PublicApiError" }, "example": { "error": { "code": "forbidden_scope", "message": "API key is missing required scope: budgets:write", "request_id": "550e8400-e29b-41d4-a716-446655440000" } } } } } } } }, "/v1/budgets/{id}/csv": { "get": { "tags": [ "Budgets" ], "summary": "Export budget CSV", "operationId": "exportBudgetCsv", "security": [ { "bearerApiKey": [] } ], "parameters": [ { "schema": { "type": "string", "description": "Budget ID" }, "required": true, "name": "id", "in": "path" } ], "responses": { "200": { "description": "Export budget CSV", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "object", "description": "JSON object", "additionalProperties": true } }, "required": [ "data" ] }, "example": { "data": { "csv": "dimension,2026-01,2026-02\nProduction,12000,11800\n", "filename": "budget-1.csv" } } } } }, "401": { "description": "Unauthorized — invalid or missing API key", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PublicApiError" }, "example": { "error": { "code": "forbidden_scope", "message": "API key is missing required scope: budgets:write", "request_id": "550e8400-e29b-41d4-a716-446655440000" } } } } }, "403": { "description": "Forbidden — insufficient permissions or entitlement", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PublicApiError" }, "example": { "error": { "code": "forbidden_scope", "message": "API key is missing required scope: budgets:write", "request_id": "550e8400-e29b-41d4-a716-446655440000" } } } } } } }, "post": { "tags": [ "Budgets" ], "summary": "Import budget CSV", "operationId": "importBudgetCsv", "security": [ { "bearerApiKey": [] } ], "parameters": [ { "schema": { "type": "string", "description": "Budget ID" }, "required": true, "name": "id", "in": "path" }, { "schema": { "type": "string", "maxLength": 64, "description": "Unique key for safe retries on write requests (required, max 64 characters)." }, "required": true, "name": "Idempotency-Key", "in": "header" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "description": "JSON request body", "additionalProperties": true }, "example": { "csv": "dimension,2026-01,2026-02\nProduction,12000,11800\n" } } } }, "responses": { "200": { "description": "Import budget CSV", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "object", "description": "JSON object", "additionalProperties": true } }, "required": [ "data" ] }, "example": { "data": { "success": true } } } } }, "401": { "description": "Unauthorized — invalid or missing API key", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PublicApiError" }, "example": { "error": { "code": "forbidden_scope", "message": "API key is missing required scope: budgets:write", "request_id": "550e8400-e29b-41d4-a716-446655440000" } } } } }, "403": { "description": "Forbidden — insufficient permissions or entitlement", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PublicApiError" }, "example": { "error": { "code": "forbidden_scope", "message": "API key is missing required scope: budgets:write", "request_id": "550e8400-e29b-41d4-a716-446655440000" } } } } } } } }, "/v1/budgets/{id}/alerts": { "get": { "tags": [ "Budgets" ], "summary": "List budget alerts", "operationId": "listBudgetAlerts", "security": [ { "bearerApiKey": [] } ], "parameters": [ { "schema": { "type": "string", "description": "Budget ID" }, "required": true, "name": "id", "in": "path" }, { "schema": { "type": "integer", "minimum": 1, "maximum": 200, "description": "Maximum items to return (1–200, default 50)." }, "required": false, "name": "limit", "in": "query" }, { "schema": { "type": "string", "description": "Opaque cursor from a previous response's `pagination.next_cursor`." }, "required": false, "name": "cursor", "in": "query" } ], "responses": { "200": { "description": "List budget alerts", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "array", "items": { "type": "object", "description": "JSON object", "additionalProperties": true } }, "pagination": { "$ref": "#/components/schemas/Pagination" } }, "required": [ "data", "pagination" ] }, "example": { "data": [ { "id": "alert-1", "budgetId": "budget-1", "thresholdType": "PERCENTAGE_OVER", "thresholdValue": 90, "triggerThresholdValue": null, "alertFrequency": "MONTHLY", "aggregation": "SINGLE", "emailRecipients": [ "finops@example.com" ], "chatChannels": [], "slackWebhooks": [], "slackMentions": null, "planningIds": [], "isActive": true, "createdAt": "2026-07-17T12:00:00.000Z", "updatedAt": "2026-07-17T12:00:00.000Z" } ], "pagination": { "limit": 50, "has_more": false, "next_cursor": null } } } } }, "401": { "description": "Unauthorized — invalid or missing API key", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PublicApiError" }, "example": { "error": { "code": "forbidden_scope", "message": "API key is missing required scope: budgets:write", "request_id": "550e8400-e29b-41d4-a716-446655440000" } } } } }, "403": { "description": "Forbidden — insufficient permissions or entitlement", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PublicApiError" }, "example": { "error": { "code": "forbidden_scope", "message": "API key is missing required scope: budgets:write", "request_id": "550e8400-e29b-41d4-a716-446655440000" } } } } } } }, "post": { "tags": [ "Budgets" ], "summary": "Create budget alert", "operationId": "createBudgetAlert", "security": [ { "bearerApiKey": [] } ], "parameters": [ { "schema": { "type": "string", "description": "Budget ID" }, "required": true, "name": "id", "in": "path" }, { "schema": { "type": "string", "maxLength": 64, "description": "Unique key for safe retries on write requests (required, max 64 characters)." }, "required": true, "name": "Idempotency-Key", "in": "header" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "description": "JSON request body", "additionalProperties": true }, "example": { "thresholdType": "PERCENTAGE_OVER", "thresholdValue": 90, "emailRecipients": [ "finops@example.com" ], "isActive": true } } } }, "responses": { "200": { "description": "Create budget alert", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "object", "description": "JSON object", "additionalProperties": true } }, "required": [ "data" ] }, "example": { "data": { "alert": { "id": "alert-1", "budgetId": "budget-1", "thresholdType": "PERCENTAGE_OVER", "thresholdValue": 90, "triggerThresholdValue": null, "alertFrequency": "MONTHLY", "aggregation": "SINGLE", "emailRecipients": [ "finops@example.com" ], "chatChannels": [], "slackWebhooks": [], "slackMentions": null, "planningIds": [], "isActive": true, "createdAt": "2026-07-17T12:00:00.000Z", "updatedAt": "2026-07-17T12:00:00.000Z" } } } } } }, "401": { "description": "Unauthorized — invalid or missing API key", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PublicApiError" }, "example": { "error": { "code": "forbidden_scope", "message": "API key is missing required scope: budgets:write", "request_id": "550e8400-e29b-41d4-a716-446655440000" } } } } }, "403": { "description": "Forbidden — insufficient permissions or entitlement", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PublicApiError" }, "example": { "error": { "code": "forbidden_scope", "message": "API key is missing required scope: budgets:write", "request_id": "550e8400-e29b-41d4-a716-446655440000" } } } } } } } }, "/v1/budgets/{id}/alerts/{alertId}": { "get": { "tags": [ "Budgets" ], "summary": "Get budget alert", "operationId": "getBudgetAlert", "security": [ { "bearerApiKey": [] } ], "parameters": [ { "schema": { "type": "string", "description": "Budget ID" }, "required": true, "name": "id", "in": "path" }, { "schema": { "type": "string", "description": "Alert ID" }, "required": true, "name": "alertId", "in": "path" } ], "responses": { "200": { "description": "Get budget alert", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "object", "description": "JSON object", "additionalProperties": true } }, "required": [ "data" ] }, "example": { "data": { "alert": { "id": "alert-1", "budgetId": "budget-1", "thresholdType": "PERCENTAGE_OVER", "thresholdValue": 90, "triggerThresholdValue": null, "alertFrequency": "MONTHLY", "aggregation": "SINGLE", "emailRecipients": [ "finops@example.com" ], "chatChannels": [], "slackWebhooks": [], "slackMentions": null, "planningIds": [], "isActive": true, "createdAt": "2026-07-17T12:00:00.000Z", "updatedAt": "2026-07-17T12:00:00.000Z" } } } } } }, "401": { "description": "Unauthorized — invalid or missing API key", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PublicApiError" }, "example": { "error": { "code": "forbidden_scope", "message": "API key is missing required scope: budgets:write", "request_id": "550e8400-e29b-41d4-a716-446655440000" } } } } }, "403": { "description": "Forbidden — insufficient permissions or entitlement", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PublicApiError" }, "example": { "error": { "code": "forbidden_scope", "message": "API key is missing required scope: budgets:write", "request_id": "550e8400-e29b-41d4-a716-446655440000" } } } } } } }, "patch": { "tags": [ "Budgets" ], "summary": "Update budget alert", "operationId": "updateBudgetAlert", "security": [ { "bearerApiKey": [] } ], "parameters": [ { "schema": { "type": "string", "description": "Budget ID" }, "required": true, "name": "id", "in": "path" }, { "schema": { "type": "string", "description": "Alert ID" }, "required": true, "name": "alertId", "in": "path" }, { "schema": { "type": "string", "maxLength": 64, "description": "Unique key for safe retries on write requests (required, max 64 characters)." }, "required": true, "name": "Idempotency-Key", "in": "header" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "description": "JSON request body", "additionalProperties": true }, "example": { "thresholdValue": 95 } } } }, "responses": { "200": { "description": "Update budget alert", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "object", "description": "JSON object", "additionalProperties": true } }, "required": [ "data" ] }, "example": { "data": { "alert": { "id": "alert-1", "budgetId": "budget-1", "thresholdType": "PERCENTAGE_OVER", "thresholdValue": 95, "triggerThresholdValue": null, "alertFrequency": "MONTHLY", "aggregation": "SINGLE", "emailRecipients": [ "finops@example.com" ], "chatChannels": [], "slackWebhooks": [], "slackMentions": null, "planningIds": [], "isActive": true, "createdAt": "2026-07-17T12:00:00.000Z", "updatedAt": "2026-07-17T12:00:00.000Z" } } } } } }, "401": { "description": "Unauthorized — invalid or missing API key", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PublicApiError" }, "example": { "error": { "code": "forbidden_scope", "message": "API key is missing required scope: budgets:write", "request_id": "550e8400-e29b-41d4-a716-446655440000" } } } } }, "403": { "description": "Forbidden — insufficient permissions or entitlement", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PublicApiError" }, "example": { "error": { "code": "forbidden_scope", "message": "API key is missing required scope: budgets:write", "request_id": "550e8400-e29b-41d4-a716-446655440000" } } } } } } }, "delete": { "tags": [ "Budgets" ], "summary": "Delete budget alert", "operationId": "deleteBudgetAlert", "security": [ { "bearerApiKey": [] } ], "parameters": [ { "schema": { "type": "string", "description": "Budget ID" }, "required": true, "name": "id", "in": "path" }, { "schema": { "type": "string", "description": "Alert ID" }, "required": true, "name": "alertId", "in": "path" } ], "responses": { "200": { "description": "Delete budget alert", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "object", "description": "JSON object", "additionalProperties": true } }, "required": [ "data" ] }, "example": { "data": { "success": true } } } } }, "401": { "description": "Unauthorized — invalid or missing API key", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PublicApiError" }, "example": { "error": { "code": "forbidden_scope", "message": "API key is missing required scope: budgets:write", "request_id": "550e8400-e29b-41d4-a716-446655440000" } } } } }, "403": { "description": "Forbidden — insufficient permissions or entitlement", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PublicApiError" }, "example": { "error": { "code": "forbidden_scope", "message": "API key is missing required scope: budgets:write", "request_id": "550e8400-e29b-41d4-a716-446655440000" } } } } } } } }, "/v1/budgets/{id}/ai-seat-tracking": { "get": { "tags": [ "Budgets" ], "summary": "Get budget AI seat tracking", "description": "Per-user AI seat spend and limits for providers enabled on this budget (Claude Enterprise, Cursor).", "operationId": "getBudgetAiSeatTracking", "security": [ { "bearerApiKey": [] } ], "parameters": [ { "schema": { "type": "string", "description": "Budget ID" }, "required": true, "name": "id", "in": "path" } ], "responses": { "200": { "description": "Get budget AI seat tracking", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "object", "description": "JSON object", "additionalProperties": true } }, "required": [ "data" ] }, "example": { "data": { "enabledProviders": [ "claude-enterprise" ], "users": [ { "userId": "user-1", "email": "alice@example.com", "name": "Alice", "providers": { "claude-enterprise": { "email": "alice@example.com", "name": "Alice", "periodToDateSpend": 42.5, "effectiveLimit": 100, "currency": "USD", "period": "monthly", "sourceLabel": "User override", "providerUserId": "claude-user-1", "spendLimitId": "spl_abc", "limitIsUserOverride": true } } } ] } } } } }, "401": { "description": "Unauthorized — invalid or missing API key", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PublicApiError" }, "example": { "error": { "code": "forbidden_scope", "message": "API key is missing required scope: budgets:write", "request_id": "550e8400-e29b-41d4-a716-446655440000" } } } } }, "403": { "description": "Forbidden — insufficient permissions or entitlement", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PublicApiError" }, "example": { "error": { "code": "forbidden_scope", "message": "API key is missing required scope: budgets:write", "request_id": "550e8400-e29b-41d4-a716-446655440000" } } } } } } }, "put": { "tags": [ "Budgets" ], "summary": "Update budget AI seat tracking providers", "description": "Enable or disable AI seat tracking providers on a budget.", "operationId": "updateBudgetAiSeatTracking", "security": [ { "bearerApiKey": [] } ], "parameters": [ { "schema": { "type": "string", "description": "Budget ID" }, "required": true, "name": "id", "in": "path" }, { "schema": { "type": "string", "maxLength": 64, "description": "Unique key for safe retries on write requests (required, max 64 characters)." }, "required": true, "name": "Idempotency-Key", "in": "header" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "description": "JSON request body", "additionalProperties": true }, "example": { "providers": [ "claude-enterprise", "cursor" ] } } } }, "responses": { "200": { "description": "Update budget AI seat tracking providers", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "object", "description": "JSON object", "additionalProperties": true } }, "required": [ "data" ] }, "example": { "data": { "enabledProviders": [ "claude-enterprise", "cursor" ] } } } } }, "401": { "description": "Unauthorized — invalid or missing API key", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PublicApiError" }, "example": { "error": { "code": "forbidden_scope", "message": "API key is missing required scope: budgets:write", "request_id": "550e8400-e29b-41d4-a716-446655440000" } } } } }, "403": { "description": "Forbidden — insufficient permissions or entitlement", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PublicApiError" }, "example": { "error": { "code": "forbidden_scope", "message": "API key is missing required scope: budgets:write", "request_id": "550e8400-e29b-41d4-a716-446655440000" } } } } } } } }, "/v1/budgets/{id}/ai-seat-tracking/limits": { "patch": { "tags": [ "Budgets" ], "summary": "Update budget AI seat spend limit", "description": "Set or clear a per-user Claude Enterprise spend limit override. Cursor limits are read-only.", "operationId": "updateBudgetAiSeatLimit", "security": [ { "bearerApiKey": [] } ], "parameters": [ { "schema": { "type": "string", "description": "Budget ID" }, "required": true, "name": "id", "in": "path" }, { "schema": { "type": "string", "maxLength": 64, "description": "Unique key for safe retries on write requests (required, max 64 characters)." }, "required": true, "name": "Idempotency-Key", "in": "header" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "description": "JSON request body", "additionalProperties": true }, "example": { "provider": "claude-enterprise", "providerUserId": "claude-user-1", "limitDollars": 100, "period": "monthly" } } } }, "responses": { "200": { "description": "Update budget AI seat spend limit", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "object", "description": "JSON object", "additionalProperties": true } }, "required": [ "data" ] }, "example": { "data": { "provider": "claude-enterprise", "providerUserId": "claude-user-1", "spendLimitId": "spl_new" } } } } }, "401": { "description": "Unauthorized — invalid or missing API key", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PublicApiError" }, "example": { "error": { "code": "forbidden_scope", "message": "API key is missing required scope: budgets:write", "request_id": "550e8400-e29b-41d4-a716-446655440000" } } } } }, "403": { "description": "Forbidden — insufficient permissions or entitlement", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PublicApiError" }, "example": { "error": { "code": "forbidden_scope", "message": "API key is missing required scope: budgets:write", "request_id": "550e8400-e29b-41d4-a716-446655440000" } } } } } } } }, "/v1/reports": { "get": { "tags": [ "Reports" ], "summary": "List reports", "operationId": "listReports", "security": [ { "bearerApiKey": [] } ], "parameters": [ { "schema": { "type": "integer", "minimum": 1, "maximum": 200, "description": "Maximum items to return (1–200, default 50)." }, "required": false, "name": "limit", "in": "query" }, { "schema": { "type": "string", "description": "Opaque cursor from a previous response's `pagination.next_cursor`." }, "required": false, "name": "cursor", "in": "query" } ], "responses": { "200": { "description": "List reports", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "array", "items": { "type": "object", "description": "JSON object", "additionalProperties": true } }, "pagination": { "$ref": "#/components/schemas/Pagination" } }, "required": [ "data", "pagination" ] }, "example": { "data": [ { "id": "report-1", "name": "AWS Spend by Account", "scope": "private", "config": { "dateRange": { "start": "2026-05-31", "end": "2026-06-29" }, "groupBy": "product_product_name", "costType": "line_item_unblended_cost", "granularity": "day", "filters": [] }, "organizationId": "org-1", "nopsClientId": 42, "creatorId": "user-1", "createdAt": "2026-07-17T12:00:00.000Z", "updatedAt": "2026-07-17T12:00:00.000Z", "creator": { "id": "user-1", "firstName": "FinOps", "lastName": "Analyst", "email": "finops@example.com" } } ], "pagination": { "limit": 50, "has_more": false, "next_cursor": null } } } } }, "401": { "description": "Unauthorized — invalid or missing API key", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PublicApiError" }, "example": { "error": { "code": "forbidden_scope", "message": "API key is missing required scope: budgets:write", "request_id": "550e8400-e29b-41d4-a716-446655440000" } } } } }, "403": { "description": "Forbidden — insufficient permissions or entitlement", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PublicApiError" }, "example": { "error": { "code": "forbidden_scope", "message": "API key is missing required scope: budgets:write", "request_id": "550e8400-e29b-41d4-a716-446655440000" } } } } } } }, "post": { "tags": [ "Reports" ], "summary": "Create report", "operationId": "createReport", "security": [ { "bearerApiKey": [] } ], "parameters": [ { "schema": { "type": "string", "maxLength": 64, "description": "Unique key for safe retries on write requests (required, max 64 characters)." }, "required": true, "name": "Idempotency-Key", "in": "header" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "description": "JSON request body", "additionalProperties": true }, "example": { "name": "AWS Spend by Account", "scope": "private", "config": { "dateRange": { "start": "2026-05-31", "end": "2026-06-29" }, "groupBy": "product_product_name", "costType": "line_item_unblended_cost", "granularity": "day", "filters": [] } } } } }, "responses": { "200": { "description": "Create report", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "object", "description": "JSON object", "additionalProperties": true } }, "required": [ "data" ] }, "example": { "data": { "report": { "id": "report-1", "name": "AWS Spend by Account", "scope": "private", "config": { "dateRange": { "start": "2026-05-31", "end": "2026-06-29" }, "groupBy": "product_product_name", "costType": "line_item_unblended_cost", "granularity": "day", "filters": [] }, "organizationId": "org-1", "nopsClientId": 42, "creatorId": "user-1", "createdAt": "2026-07-17T12:00:00.000Z", "updatedAt": "2026-07-17T12:00:00.000Z", "creator": { "id": "user-1", "firstName": "FinOps", "lastName": "Analyst", "email": "finops@example.com" } } } } } } }, "401": { "description": "Unauthorized — invalid or missing API key", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PublicApiError" }, "example": { "error": { "code": "forbidden_scope", "message": "API key is missing required scope: budgets:write", "request_id": "550e8400-e29b-41d4-a716-446655440000" } } } } }, "403": { "description": "Forbidden — insufficient permissions or entitlement", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PublicApiError" }, "example": { "error": { "code": "forbidden_scope", "message": "API key is missing required scope: budgets:write", "request_id": "550e8400-e29b-41d4-a716-446655440000" } } } } } } } }, "/v1/reports/{id}": { "get": { "tags": [ "Reports" ], "summary": "Get report", "operationId": "getReport", "security": [ { "bearerApiKey": [] } ], "parameters": [ { "schema": { "type": "string", "description": "Report ID" }, "required": true, "name": "id", "in": "path" } ], "responses": { "200": { "description": "Get report", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "object", "description": "JSON object", "additionalProperties": true } }, "required": [ "data" ] }, "example": { "data": { "report": { "id": "report-1", "name": "AWS Spend by Account", "scope": "private", "config": { "dateRange": { "start": "2026-05-31", "end": "2026-06-29" }, "groupBy": "product_product_name", "costType": "line_item_unblended_cost", "granularity": "day", "filters": [] }, "organizationId": "org-1", "nopsClientId": 42, "creatorId": "user-1", "createdAt": "2026-07-17T12:00:00.000Z", "updatedAt": "2026-07-17T12:00:00.000Z", "creator": { "id": "user-1", "firstName": "FinOps", "lastName": "Analyst", "email": "finops@example.com" } } } } } } }, "401": { "description": "Unauthorized — invalid or missing API key", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PublicApiError" }, "example": { "error": { "code": "forbidden_scope", "message": "API key is missing required scope: budgets:write", "request_id": "550e8400-e29b-41d4-a716-446655440000" } } } } }, "403": { "description": "Forbidden — insufficient permissions or entitlement", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PublicApiError" }, "example": { "error": { "code": "forbidden_scope", "message": "API key is missing required scope: budgets:write", "request_id": "550e8400-e29b-41d4-a716-446655440000" } } } } } } }, "patch": { "tags": [ "Reports" ], "summary": "Update report", "operationId": "updateReport", "security": [ { "bearerApiKey": [] } ], "parameters": [ { "schema": { "type": "string", "description": "Report ID" }, "required": true, "name": "id", "in": "path" }, { "schema": { "type": "string", "maxLength": 64, "description": "Unique key for safe retries on write requests (required, max 64 characters)." }, "required": true, "name": "Idempotency-Key", "in": "header" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "description": "JSON request body", "additionalProperties": true }, "example": { "name": "AWS Spend by Account (updated)" } } } }, "responses": { "200": { "description": "Update report", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "object", "description": "JSON object", "additionalProperties": true } }, "required": [ "data" ] }, "example": { "data": { "report": { "id": "report-1", "name": "AWS Spend by Account (updated)", "scope": "private", "config": { "dateRange": { "start": "2026-05-31", "end": "2026-06-29" }, "groupBy": "product_product_name", "costType": "line_item_unblended_cost", "granularity": "day", "filters": [] }, "organizationId": "org-1", "nopsClientId": 42, "creatorId": "user-1", "createdAt": "2026-07-17T12:00:00.000Z", "updatedAt": "2026-07-17T12:00:00.000Z", "creator": { "id": "user-1", "firstName": "FinOps", "lastName": "Analyst", "email": "finops@example.com" } } } } } } }, "401": { "description": "Unauthorized — invalid or missing API key", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PublicApiError" }, "example": { "error": { "code": "forbidden_scope", "message": "API key is missing required scope: budgets:write", "request_id": "550e8400-e29b-41d4-a716-446655440000" } } } } }, "403": { "description": "Forbidden — insufficient permissions or entitlement", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PublicApiError" }, "example": { "error": { "code": "forbidden_scope", "message": "API key is missing required scope: budgets:write", "request_id": "550e8400-e29b-41d4-a716-446655440000" } } } } } } }, "delete": { "tags": [ "Reports" ], "summary": "Delete report", "operationId": "deleteReport", "security": [ { "bearerApiKey": [] } ], "parameters": [ { "schema": { "type": "string", "description": "Report ID" }, "required": true, "name": "id", "in": "path" } ], "responses": { "200": { "description": "Delete report", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "object", "description": "JSON object", "additionalProperties": true } }, "required": [ "data" ] }, "example": { "data": { "success": true } } } } }, "401": { "description": "Unauthorized — invalid or missing API key", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PublicApiError" }, "example": { "error": { "code": "forbidden_scope", "message": "API key is missing required scope: budgets:write", "request_id": "550e8400-e29b-41d4-a716-446655440000" } } } } }, "403": { "description": "Forbidden — insufficient permissions or entitlement", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PublicApiError" }, "example": { "error": { "code": "forbidden_scope", "message": "API key is missing required scope: budgets:write", "request_id": "550e8400-e29b-41d4-a716-446655440000" } } } } } } } }, "/v1/reports/{id}/send": { "post": { "tags": [ "Reports" ], "summary": "Send report", "operationId": "sendReport", "security": [ { "bearerApiKey": [] } ], "parameters": [ { "schema": { "type": "string", "description": "Report ID" }, "required": true, "name": "id", "in": "path" }, { "schema": { "type": "string", "maxLength": 64, "description": "Unique key for safe retries on write requests (required, max 64 characters)." }, "required": true, "name": "Idempotency-Key", "in": "header" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "description": "JSON request body", "additionalProperties": true }, "example": { "recipients": [ "finops@example.com" ], "subject": "Monthly spend report" } } } }, "responses": { "200": { "description": "Send report", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "object", "description": "JSON object", "additionalProperties": true } }, "required": [ "data" ] }, "example": { "data": { "success": true } } } } }, "401": { "description": "Unauthorized — invalid or missing API key", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PublicApiError" }, "example": { "error": { "code": "forbidden_scope", "message": "API key is missing required scope: budgets:write", "request_id": "550e8400-e29b-41d4-a716-446655440000" } } } } }, "403": { "description": "Forbidden — insufficient permissions or entitlement", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PublicApiError" }, "example": { "error": { "code": "forbidden_scope", "message": "API key is missing required scope: budgets:write", "request_id": "550e8400-e29b-41d4-a716-446655440000" } } } } } } } }, "/v1/reports/{id}/render": { "post": { "tags": [ "Reports" ], "summary": "Render report", "operationId": "renderReport", "security": [ { "bearerApiKey": [] } ], "parameters": [ { "schema": { "type": "string", "description": "Report ID" }, "required": true, "name": "id", "in": "path" }, { "schema": { "type": "string", "maxLength": 64, "description": "Unique key for safe retries on write requests (required, max 64 characters)." }, "required": true, "name": "Idempotency-Key", "in": "header" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "description": "JSON request body", "additionalProperties": true }, "example": { "format": "pdf" } } } }, "responses": { "200": { "description": "Render report", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "object", "description": "JSON object", "additionalProperties": true } }, "required": [ "data" ] }, "example": { "data": { "url": "https://api.nops.io/v1/reports/report-1/render/download", "expiresAt": "2026-07-17T12:00:00.000Z" } } } } }, "401": { "description": "Unauthorized — invalid or missing API key", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PublicApiError" }, "example": { "error": { "code": "forbidden_scope", "message": "API key is missing required scope: budgets:write", "request_id": "550e8400-e29b-41d4-a716-446655440000" } } } } }, "403": { "description": "Forbidden — insufficient permissions or entitlement", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PublicApiError" }, "example": { "error": { "code": "forbidden_scope", "message": "API key is missing required scope: budgets:write", "request_id": "550e8400-e29b-41d4-a716-446655440000" } } } } } } } }, "/v1/feed": { "get": { "tags": [ "Feed" ], "summary": "List feed runs", "description": "List Clara Feed runs and schedules.", "operationId": "listFeedRuns", "security": [ { "bearerApiKey": [] } ], "parameters": [ { "schema": { "type": "integer", "minimum": 1, "maximum": 200, "description": "Maximum items to return (1–200, default 50)." }, "required": false, "name": "limit", "in": "query" }, { "schema": { "type": "string", "description": "Opaque cursor from a previous response's `pagination.next_cursor`." }, "required": false, "name": "cursor", "in": "query" } ], "responses": { "200": { "description": "List feed runs", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "array", "items": { "type": "object", "description": "JSON object", "additionalProperties": true } }, "pagination": { "$ref": "#/components/schemas/Pagination" } }, "required": [ "data", "pagination" ] }, "example": { "data": [ { "id": "clxrun01abc", "scheduledPromptId": "clxprompt01xyz", "status": "completed", "queuedAt": "2026-07-17T12:00:00.000Z", "startedAt": "2026-07-17T12:00:00.000Z", "finishedAt": "2026-07-17T12:00:00.000Z", "title": "Weekly EC2 spend summary", "summary": "Spend rose 4% week over week across production accounts.", "responsePreview": { "hasChart": true, "hasTable": false, "chartCount": 1, "tableCount": 0, "previewMarkdown": "```chart\n...\n```" }, "runtimeSessionId": "sess_abc123", "errorMessage": null, "scheduledPrompt": { "id": "clxprompt01xyz", "name": "Weekly EC2 summary", "scope": "private", "canvasId": "clxcanvas01", "category": "FinOps Analyst", "domain": "Compute" }, "canContinueInClara": true } ], "pagination": { "limit": 50, "has_more": false, "next_cursor": null } } } } }, "401": { "description": "Unauthorized — invalid or missing API key", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PublicApiError" }, "example": { "error": { "code": "forbidden_scope", "message": "API key is missing required scope: budgets:write", "request_id": "550e8400-e29b-41d4-a716-446655440000" } } } } }, "403": { "description": "Forbidden — insufficient permissions or entitlement", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PublicApiError" }, "example": { "error": { "code": "forbidden_scope", "message": "API key is missing required scope: budgets:write", "request_id": "550e8400-e29b-41d4-a716-446655440000" } } } } } } } }, "/v1/feed/{runId}": { "get": { "tags": [ "Feed" ], "summary": "Get feed run", "operationId": "getFeedRun", "security": [ { "bearerApiKey": [] } ], "parameters": [ { "schema": { "type": "string", "description": "Feed run ID" }, "required": true, "name": "runId", "in": "path" } ], "responses": { "200": { "description": "Get feed run", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "object", "description": "JSON object", "additionalProperties": true } }, "required": [ "data" ] }, "example": { "data": { "run": { "id": "clxrun01abc", "scheduledPromptId": "clxprompt01xyz", "status": "completed", "queuedAt": "2026-07-17T12:00:00.000Z", "startedAt": "2026-07-17T12:00:00.000Z", "finishedAt": "2026-07-17T12:00:00.000Z", "title": "Weekly EC2 spend summary", "summary": "Spend rose 4% week over week across production accounts.", "responsePreview": { "hasChart": true, "hasTable": false, "chartCount": 1, "tableCount": 0, "previewMarkdown": "```chart\n...\n```" }, "runtimeSessionId": "sess_abc123", "errorMessage": null, "scheduledPrompt": { "id": "clxprompt01xyz", "name": "Weekly EC2 summary", "scope": "private", "canvasId": "clxcanvas01", "category": "FinOps Analyst", "domain": "Compute" }, "canContinueInClara": true, "response": "## Weekly EC2 summary\n\nSpend rose 4% week over week.", "nopsClientId": 42, "vercelMessageId": "msg_abc123" } } } } } }, "401": { "description": "Unauthorized — invalid or missing API key", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PublicApiError" }, "example": { "error": { "code": "forbidden_scope", "message": "API key is missing required scope: budgets:write", "request_id": "550e8400-e29b-41d4-a716-446655440000" } } } } }, "403": { "description": "Forbidden — insufficient permissions or entitlement", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PublicApiError" }, "example": { "error": { "code": "forbidden_scope", "message": "API key is missing required scope: budgets:write", "request_id": "550e8400-e29b-41d4-a716-446655440000" } } } } } } } }, "/v1/scheduled-prompts": { "get": { "tags": [ "Scheduled prompts" ], "summary": "List scheduled prompts", "operationId": "listScheduledPrompts", "security": [ { "bearerApiKey": [] } ], "parameters": [ { "schema": { "type": "integer", "minimum": 1, "maximum": 200, "description": "Maximum items to return (1–200, default 50)." }, "required": false, "name": "limit", "in": "query" }, { "schema": { "type": "string", "description": "Opaque cursor from a previous response's `pagination.next_cursor`." }, "required": false, "name": "cursor", "in": "query" } ], "responses": { "200": { "description": "List scheduled prompts", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "array", "items": { "type": "object", "description": "JSON object", "additionalProperties": true } }, "pagination": { "$ref": "#/components/schemas/Pagination" } }, "required": [ "data", "pagination" ] }, "example": { "data": [ { "id": "clxprompt01xyz", "organizationId": "org-1", "nopsClientId": 42, "createdById": "user-1", "canvasId": "clxcanvas01", "scope": "private", "name": "Weekly EC2 summary", "prompt": "Summarize last week EC2 spend by account.", "enabled": true, "category": "FinOps Analyst", "domain": "Compute", "emailEnabled": true, "emailRecipients": [ "finops@example.com" ], "emailSubject": "Weekly EC2 summary", "channelTargets": [ { "provider": "slack", "channelId": "C01234567", "channelName": "finops-alerts" } ], "scheduleType": "recurring", "scheduledAt": "2026-07-20T14:00:00.000Z", "recurrenceFrequency": "weekly", "recurrenceTimezone": "America/New_York", "recurrenceWeekday": 1, "recurrenceDayOfMonth": null, "cronExpression": "0 14 * * 1", "nextRunAt": "2026-07-20T18:00:00.000Z", "lastRunAt": null, "createdAt": "2026-07-17T12:00:00.000Z", "updatedAt": "2026-07-17T12:00:00.000Z", "canvas": { "id": "clxcanvas01", "name": "FinOps Dashboard" }, "_count": { "runs": 12 } } ], "pagination": { "limit": 50, "has_more": false, "next_cursor": null } } } } }, "401": { "description": "Unauthorized — invalid or missing API key", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PublicApiError" }, "example": { "error": { "code": "forbidden_scope", "message": "API key is missing required scope: budgets:write", "request_id": "550e8400-e29b-41d4-a716-446655440000" } } } } }, "403": { "description": "Forbidden — insufficient permissions or entitlement", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PublicApiError" }, "example": { "error": { "code": "forbidden_scope", "message": "API key is missing required scope: budgets:write", "request_id": "550e8400-e29b-41d4-a716-446655440000" } } } } } } }, "post": { "tags": [ "Scheduled prompts" ], "summary": "Create scheduled prompt", "operationId": "createScheduledPrompt", "security": [ { "bearerApiKey": [] } ], "parameters": [ { "schema": { "type": "string", "maxLength": 64, "description": "Unique key for safe retries on write requests (required, max 64 characters)." }, "required": true, "name": "Idempotency-Key", "in": "header" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "description": "JSON request body", "additionalProperties": true }, "example": { "name": "Weekly EC2 summary", "prompt": "Summarize last week EC2 spend by account.", "canvasId": "clxcanvas01", "scope": "private", "enabled": true, "scheduleType": "recurring", "scheduledAt": "2026-07-20T14:00:00.000Z", "recurrence": { "frequency": "weekly", "timezone": "America/New_York", "weekday": 1, "dayOfMonth": null }, "category": "FinOps Analyst", "domain": "Compute", "emailEnabled": true, "emailRecipients": [ "finops@example.com" ], "emailSubject": "Weekly EC2 summary", "channels": [ { "provider": "slack", "channelId": "C01234567", "channelName": "finops-alerts" } ] } } } }, "responses": { "200": { "description": "Create scheduled prompt", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "object", "description": "JSON object", "additionalProperties": true } }, "required": [ "data" ] }, "example": { "data": { "prompt": { "id": "clxprompt01xyz", "organizationId": "org-1", "nopsClientId": 42, "createdById": "user-1", "canvasId": "clxcanvas01", "scope": "private", "name": "Weekly EC2 summary", "prompt": "Summarize last week EC2 spend by account.", "enabled": true, "category": "FinOps Analyst", "domain": "Compute", "emailEnabled": true, "emailRecipients": [ "finops@example.com" ], "emailSubject": "Weekly EC2 summary", "channelTargets": [ { "provider": "slack", "channelId": "C01234567", "channelName": "finops-alerts" } ], "scheduleType": "recurring", "scheduledAt": "2026-07-20T14:00:00.000Z", "recurrenceFrequency": "weekly", "recurrenceTimezone": "America/New_York", "recurrenceWeekday": 1, "recurrenceDayOfMonth": null, "cronExpression": "0 14 * * 1", "nextRunAt": "2026-07-20T18:00:00.000Z", "lastRunAt": null, "createdAt": "2026-07-17T12:00:00.000Z", "updatedAt": "2026-07-17T12:00:00.000Z" } } } } } }, "401": { "description": "Unauthorized — invalid or missing API key", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PublicApiError" }, "example": { "error": { "code": "forbidden_scope", "message": "API key is missing required scope: budgets:write", "request_id": "550e8400-e29b-41d4-a716-446655440000" } } } } }, "403": { "description": "Forbidden — insufficient permissions or entitlement", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PublicApiError" }, "example": { "error": { "code": "forbidden_scope", "message": "API key is missing required scope: budgets:write", "request_id": "550e8400-e29b-41d4-a716-446655440000" } } } } } } } }, "/v1/scheduled-prompts/{id}": { "get": { "tags": [ "Scheduled prompts" ], "summary": "Get scheduled prompt", "operationId": "getScheduledPrompt", "security": [ { "bearerApiKey": [] } ], "parameters": [ { "schema": { "type": "string", "description": "Scheduled prompt ID" }, "required": true, "name": "id", "in": "path" } ], "responses": { "200": { "description": "Get scheduled prompt", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "object", "description": "JSON object", "additionalProperties": true } }, "required": [ "data" ] }, "example": { "data": { "prompt": { "id": "clxprompt01xyz", "organizationId": "org-1", "nopsClientId": 42, "createdById": "user-1", "canvasId": "clxcanvas01", "scope": "private", "name": "Weekly EC2 summary", "prompt": "Summarize last week EC2 spend by account.", "enabled": true, "category": "FinOps Analyst", "domain": "Compute", "emailEnabled": true, "emailRecipients": [ "finops@example.com" ], "emailSubject": "Weekly EC2 summary", "channelTargets": [ { "provider": "slack", "channelId": "C01234567", "channelName": "finops-alerts" } ], "scheduleType": "recurring", "scheduledAt": "2026-07-20T14:00:00.000Z", "recurrenceFrequency": "weekly", "recurrenceTimezone": "America/New_York", "recurrenceWeekday": 1, "recurrenceDayOfMonth": null, "cronExpression": "0 14 * * 1", "nextRunAt": "2026-07-20T18:00:00.000Z", "lastRunAt": null, "createdAt": "2026-07-17T12:00:00.000Z", "updatedAt": "2026-07-17T12:00:00.000Z" } } } } } }, "401": { "description": "Unauthorized — invalid or missing API key", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PublicApiError" }, "example": { "error": { "code": "forbidden_scope", "message": "API key is missing required scope: budgets:write", "request_id": "550e8400-e29b-41d4-a716-446655440000" } } } } }, "403": { "description": "Forbidden — insufficient permissions or entitlement", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PublicApiError" }, "example": { "error": { "code": "forbidden_scope", "message": "API key is missing required scope: budgets:write", "request_id": "550e8400-e29b-41d4-a716-446655440000" } } } } } } }, "patch": { "tags": [ "Scheduled prompts" ], "summary": "Update scheduled prompt", "operationId": "updateScheduledPrompt", "security": [ { "bearerApiKey": [] } ], "parameters": [ { "schema": { "type": "string", "description": "Scheduled prompt ID" }, "required": true, "name": "id", "in": "path" }, { "schema": { "type": "string", "maxLength": 64, "description": "Unique key for safe retries on write requests (required, max 64 characters)." }, "required": true, "name": "Idempotency-Key", "in": "header" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "description": "JSON request body", "additionalProperties": true }, "example": { "name": "Weekly EC2 summary (updated)" } } } }, "responses": { "200": { "description": "Update scheduled prompt", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "object", "description": "JSON object", "additionalProperties": true } }, "required": [ "data" ] }, "example": { "data": { "prompt": { "id": "clxprompt01xyz", "organizationId": "org-1", "nopsClientId": 42, "createdById": "user-1", "canvasId": "clxcanvas01", "scope": "private", "name": "Weekly EC2 summary (updated)", "prompt": "Summarize last week EC2 spend by account.", "enabled": true, "category": "FinOps Analyst", "domain": "Compute", "emailEnabled": true, "emailRecipients": [ "finops@example.com" ], "emailSubject": "Weekly EC2 summary", "channelTargets": [ { "provider": "slack", "channelId": "C01234567", "channelName": "finops-alerts" } ], "scheduleType": "recurring", "scheduledAt": "2026-07-20T14:00:00.000Z", "recurrenceFrequency": "weekly", "recurrenceTimezone": "America/New_York", "recurrenceWeekday": 1, "recurrenceDayOfMonth": null, "cronExpression": "0 14 * * 1", "nextRunAt": "2026-07-20T18:00:00.000Z", "lastRunAt": null, "createdAt": "2026-07-17T12:00:00.000Z", "updatedAt": "2026-07-17T12:00:00.000Z" } } } } } }, "401": { "description": "Unauthorized — invalid or missing API key", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PublicApiError" }, "example": { "error": { "code": "forbidden_scope", "message": "API key is missing required scope: budgets:write", "request_id": "550e8400-e29b-41d4-a716-446655440000" } } } } }, "403": { "description": "Forbidden — insufficient permissions or entitlement", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PublicApiError" }, "example": { "error": { "code": "forbidden_scope", "message": "API key is missing required scope: budgets:write", "request_id": "550e8400-e29b-41d4-a716-446655440000" } } } } } } }, "delete": { "tags": [ "Scheduled prompts" ], "summary": "Delete scheduled prompt", "operationId": "deleteScheduledPrompt", "security": [ { "bearerApiKey": [] } ], "parameters": [ { "schema": { "type": "string", "description": "Scheduled prompt ID" }, "required": true, "name": "id", "in": "path" } ], "responses": { "200": { "description": "Delete scheduled prompt", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "object", "description": "JSON object", "additionalProperties": true } }, "required": [ "data" ] }, "example": { "data": { "ok": true } } } } }, "401": { "description": "Unauthorized — invalid or missing API key", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PublicApiError" }, "example": { "error": { "code": "forbidden_scope", "message": "API key is missing required scope: budgets:write", "request_id": "550e8400-e29b-41d4-a716-446655440000" } } } } }, "403": { "description": "Forbidden — insufficient permissions or entitlement", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PublicApiError" }, "example": { "error": { "code": "forbidden_scope", "message": "API key is missing required scope: budgets:write", "request_id": "550e8400-e29b-41d4-a716-446655440000" } } } } } } } }, "/v1/scheduled-prompts/{id}/enable": { "post": { "tags": [ "Scheduled prompts" ], "summary": "Enable scheduled prompt", "operationId": "enableScheduledPrompt", "security": [ { "bearerApiKey": [] } ], "parameters": [ { "schema": { "type": "string", "description": "Scheduled prompt ID" }, "required": true, "name": "id", "in": "path" }, { "schema": { "type": "string", "maxLength": 64, "description": "Unique key for safe retries on write requests (required, max 64 characters)." }, "required": true, "name": "Idempotency-Key", "in": "header" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "description": "JSON request body", "additionalProperties": true }, "example": { "enabled": true } } } }, "responses": { "200": { "description": "Enable scheduled prompt", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "object", "description": "JSON object", "additionalProperties": true } }, "required": [ "data" ] }, "example": { "data": { "prompt": { "id": "clxprompt01xyz", "organizationId": "org-1", "nopsClientId": 42, "createdById": "user-1", "canvasId": "clxcanvas01", "scope": "private", "name": "Weekly EC2 summary", "prompt": "Summarize last week EC2 spend by account.", "enabled": true, "category": "FinOps Analyst", "domain": "Compute", "emailEnabled": true, "emailRecipients": [ "finops@example.com" ], "emailSubject": "Weekly EC2 summary", "channelTargets": [ { "provider": "slack", "channelId": "C01234567", "channelName": "finops-alerts" } ], "scheduleType": "recurring", "scheduledAt": "2026-07-20T14:00:00.000Z", "recurrenceFrequency": "weekly", "recurrenceTimezone": "America/New_York", "recurrenceWeekday": 1, "recurrenceDayOfMonth": null, "cronExpression": "0 14 * * 1", "nextRunAt": "2026-07-20T18:00:00.000Z", "lastRunAt": null, "createdAt": "2026-07-17T12:00:00.000Z", "updatedAt": "2026-07-17T12:00:00.000Z" } } } } } }, "401": { "description": "Unauthorized — invalid or missing API key", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PublicApiError" }, "example": { "error": { "code": "forbidden_scope", "message": "API key is missing required scope: budgets:write", "request_id": "550e8400-e29b-41d4-a716-446655440000" } } } } }, "403": { "description": "Forbidden — insufficient permissions or entitlement", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PublicApiError" }, "example": { "error": { "code": "forbidden_scope", "message": "API key is missing required scope: budgets:write", "request_id": "550e8400-e29b-41d4-a716-446655440000" } } } } } } } }, "/v1/scheduled-prompts/{id}/run": { "post": { "tags": [ "Scheduled prompts" ], "summary": "Run scheduled prompt now", "operationId": "runScheduledPrompt", "security": [ { "bearerApiKey": [] } ], "parameters": [ { "schema": { "type": "string", "description": "Scheduled prompt ID" }, "required": true, "name": "id", "in": "path" }, { "schema": { "type": "string", "maxLength": 64, "description": "Unique key for safe retries on write requests (required, max 64 characters)." }, "required": true, "name": "Idempotency-Key", "in": "header" } ], "responses": { "200": { "description": "Run scheduled prompt now", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "object", "description": "JSON object", "additionalProperties": true } }, "required": [ "data" ] }, "example": { "data": { "ok": true, "runId": "clxrun01abc", "status": "queued" } } } } }, "401": { "description": "Unauthorized — invalid or missing API key", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PublicApiError" }, "example": { "error": { "code": "forbidden_scope", "message": "API key is missing required scope: budgets:write", "request_id": "550e8400-e29b-41d4-a716-446655440000" } } } } }, "403": { "description": "Forbidden — insufficient permissions or entitlement", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PublicApiError" }, "example": { "error": { "code": "forbidden_scope", "message": "API key is missing required scope: budgets:write", "request_id": "550e8400-e29b-41d4-a716-446655440000" } } } } } } } }, "/v1/notifications/schedule": { "post": { "tags": [ "Notifications" ], "summary": "Schedule notification", "operationId": "scheduleNotification", "security": [ { "bearerApiKey": [] } ], "parameters": [ { "schema": { "type": "string", "maxLength": 64, "description": "Unique key for safe retries on write requests (required, max 64 characters)." }, "required": true, "name": "Idempotency-Key", "in": "header" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "description": "JSON request body", "additionalProperties": true }, "example": { "recipientEmail": "finops@example.com", "subject": "Weekly canvas report", "body": "Attached is your scheduled canvas PDF.", "canvasId": "clxcanvas01", "scheduleType": "recurring", "scheduledAt": "2026-07-20T14:00:00.000Z", "recurrenceFrequency": "weekly", "recurrenceTimezone": "America/New_York", "recurrenceWeekday": 1, "recurrenceDayOfMonth": null, "includeClaraAnalysis": false } } } }, "responses": { "200": { "description": "Schedule notification", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "object", "description": "JSON object", "additionalProperties": true } }, "required": [ "data" ] }, "example": { "data": { "id": "clxnotif01", "recipientEmail": "finops@example.com", "scheduledAt": "2026-07-20T18:00:00.000Z", "scheduleType": "recurring", "recurrenceFrequency": "weekly", "recurrenceTimezone": "America/New_York", "recurrenceWeekday": 1, "recurrenceDayOfMonth": null, "cronExpression": "0 14 * * 1", "status": "pending", "explorerReportId": null, "canvasId": "clxcanvas01" } } } } }, "401": { "description": "Unauthorized — invalid or missing API key", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PublicApiError" }, "example": { "error": { "code": "forbidden_scope", "message": "API key is missing required scope: budgets:write", "request_id": "550e8400-e29b-41d4-a716-446655440000" } } } } }, "403": { "description": "Forbidden — insufficient permissions or entitlement", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PublicApiError" }, "example": { "error": { "code": "forbidden_scope", "message": "API key is missing required scope: budgets:write", "request_id": "550e8400-e29b-41d4-a716-446655440000" } } } } } } } }, "/v1/notifications/scheduled": { "get": { "tags": [ "Notifications" ], "summary": "List scheduled notifications", "operationId": "listScheduledNotifications", "security": [ { "bearerApiKey": [] } ], "parameters": [ { "schema": { "type": "integer", "minimum": 1, "maximum": 200, "description": "Maximum items to return (1–200, default 50)." }, "required": false, "name": "limit", "in": "query" }, { "schema": { "type": "string", "description": "Opaque cursor from a previous response's `pagination.next_cursor`." }, "required": false, "name": "cursor", "in": "query" } ], "responses": { "200": { "description": "List scheduled notifications", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "array", "items": { "type": "object", "description": "JSON object", "additionalProperties": true } }, "pagination": { "$ref": "#/components/schemas/Pagination" } }, "required": [ "data", "pagination" ] }, "example": { "data": [ { "id": "clxnotif01", "recipientEmail": "finops@example.com", "subject": "Weekly canvas report", "scheduleType": "recurring", "scheduledAt": "2026-07-20T18:00:00.000Z", "recurrenceFrequency": "weekly", "recurrenceTimezone": "America/New_York", "recurrenceWeekday": 1, "recurrenceDayOfMonth": null, "cronExpression": "0 14 * * 1", "status": "pending", "sentAt": null, "errorMessage": null, "nextAttemptAt": null, "createdAt": "2026-07-17T12:00:00.000Z", "updatedAt": "2026-07-17T12:00:00.000Z", "canvasId": "clxcanvas01", "explorerReportId": null, "includeClaraAnalysis": false } ], "pagination": { "limit": 50, "has_more": false, "next_cursor": null } } } } }, "401": { "description": "Unauthorized — invalid or missing API key", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PublicApiError" }, "example": { "error": { "code": "forbidden_scope", "message": "API key is missing required scope: budgets:write", "request_id": "550e8400-e29b-41d4-a716-446655440000" } } } } }, "403": { "description": "Forbidden — insufficient permissions or entitlement", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PublicApiError" }, "example": { "error": { "code": "forbidden_scope", "message": "API key is missing required scope: budgets:write", "request_id": "550e8400-e29b-41d4-a716-446655440000" } } } } } } } }, "/v1/notifications/scheduled/{id}": { "get": { "tags": [ "Notifications" ], "summary": "Get scheduled notification", "operationId": "getScheduledNotification", "security": [ { "bearerApiKey": [] } ], "parameters": [ { "schema": { "type": "string", "description": "Scheduled notification ID" }, "required": true, "name": "id", "in": "path" } ], "responses": { "200": { "description": "Get scheduled notification", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "object", "description": "JSON object", "additionalProperties": true } }, "required": [ "data" ] }, "example": { "data": { "id": "clxnotif01", "recipientEmail": "finops@example.com", "subject": "Weekly canvas report", "scheduleType": "recurring", "scheduledAt": "2026-07-20T18:00:00.000Z", "recurrenceFrequency": "weekly", "recurrenceTimezone": "America/New_York", "recurrenceWeekday": 1, "recurrenceDayOfMonth": null, "cronExpression": "0 14 * * 1", "status": "pending", "sentAt": null, "errorMessage": null, "nextAttemptAt": null, "createdAt": "2026-07-17T12:00:00.000Z", "updatedAt": "2026-07-17T12:00:00.000Z", "canvasId": "clxcanvas01", "explorerReportId": null, "includeClaraAnalysis": false, "body": "Attached is your scheduled canvas PDF.", "knockWorkflowId": "workflow_abc", "knockMessageId": null } } } } }, "401": { "description": "Unauthorized — invalid or missing API key", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PublicApiError" }, "example": { "error": { "code": "forbidden_scope", "message": "API key is missing required scope: budgets:write", "request_id": "550e8400-e29b-41d4-a716-446655440000" } } } } }, "403": { "description": "Forbidden — insufficient permissions or entitlement", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PublicApiError" }, "example": { "error": { "code": "forbidden_scope", "message": "API key is missing required scope: budgets:write", "request_id": "550e8400-e29b-41d4-a716-446655440000" } } } } } } }, "patch": { "tags": [ "Notifications" ], "summary": "Update scheduled notification", "operationId": "updateScheduledNotification", "security": [ { "bearerApiKey": [] } ], "parameters": [ { "schema": { "type": "string", "description": "Scheduled notification ID" }, "required": true, "name": "id", "in": "path" }, { "schema": { "type": "string", "maxLength": 64, "description": "Unique key for safe retries on write requests (required, max 64 characters)." }, "required": true, "name": "Idempotency-Key", "in": "header" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "description": "JSON request body", "additionalProperties": true }, "example": { "subject": "Updated weekly canvas report" } } } }, "responses": { "200": { "description": "Update scheduled notification", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "object", "description": "JSON object", "additionalProperties": true } }, "required": [ "data" ] }, "example": { "data": { "id": "clxnotif01", "recipientEmail": "finops@example.com", "subject": "Updated weekly canvas report", "scheduleType": "recurring", "scheduledAt": "2026-07-20T18:00:00.000Z", "recurrenceFrequency": "weekly", "recurrenceTimezone": "America/New_York", "recurrenceWeekday": 1, "recurrenceDayOfMonth": null, "cronExpression": "0 14 * * 1", "status": "pending", "sentAt": null, "errorMessage": null, "nextAttemptAt": null, "createdAt": "2026-07-17T12:00:00.000Z", "updatedAt": "2026-07-17T12:00:00.000Z", "canvasId": "clxcanvas01", "explorerReportId": null, "includeClaraAnalysis": false } } } } }, "401": { "description": "Unauthorized — invalid or missing API key", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PublicApiError" }, "example": { "error": { "code": "forbidden_scope", "message": "API key is missing required scope: budgets:write", "request_id": "550e8400-e29b-41d4-a716-446655440000" } } } } }, "403": { "description": "Forbidden — insufficient permissions or entitlement", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PublicApiError" }, "example": { "error": { "code": "forbidden_scope", "message": "API key is missing required scope: budgets:write", "request_id": "550e8400-e29b-41d4-a716-446655440000" } } } } } } }, "delete": { "tags": [ "Notifications" ], "summary": "Delete scheduled notification", "operationId": "deleteScheduledNotification", "security": [ { "bearerApiKey": [] } ], "parameters": [ { "schema": { "type": "string", "description": "Scheduled notification ID" }, "required": true, "name": "id", "in": "path" } ], "responses": { "200": { "description": "Delete scheduled notification", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "object", "description": "JSON object", "additionalProperties": true } }, "required": [ "data" ] }, "example": { "data": { "success": true } } } } }, "401": { "description": "Unauthorized — invalid or missing API key", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PublicApiError" }, "example": { "error": { "code": "forbidden_scope", "message": "API key is missing required scope: budgets:write", "request_id": "550e8400-e29b-41d4-a716-446655440000" } } } } }, "403": { "description": "Forbidden — insufficient permissions or entitlement", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PublicApiError" }, "example": { "error": { "code": "forbidden_scope", "message": "API key is missing required scope: budgets:write", "request_id": "550e8400-e29b-41d4-a716-446655440000" } } } } } } } }, "/v1/commitments": { "get": { "tags": [ "Commitments" ], "summary": "List commitments", "description": "Reserved commitments API surface. Returns 501 until commitment endpoints are generally available.", "operationId": "listCommitments", "security": [ { "bearerApiKey": [] } ], "responses": { "401": { "description": "Unauthorized — invalid or missing API key", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PublicApiError" }, "example": { "error": { "code": "forbidden_scope", "message": "API key is missing required scope: budgets:write", "request_id": "550e8400-e29b-41d4-a716-446655440000" } } } } }, "403": { "description": "Forbidden — insufficient permissions or entitlement", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PublicApiError" }, "example": { "error": { "code": "forbidden_scope", "message": "API key is missing required scope: budgets:write", "request_id": "550e8400-e29b-41d4-a716-446655440000" } } } } }, "501": { "description": "Reserved commitments API surface. Returns 501 until commitment endpoints are generally available.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PublicApiError" }, "example": { "error": { "code": "commitments_not_available", "message": "Commitments are not available via the public API", "request_id": "550e8400-e29b-41d4-a716-446655440000" } } } } } } } }, "/v1/cost-allocation": { "get": { "tags": [ "Cost allocation" ], "summary": "List showbacks", "operationId": "listCostAllocationShowbacks", "security": [ { "bearerApiKey": [] } ], "parameters": [ { "schema": { "type": "integer", "minimum": 1, "maximum": 200, "description": "Maximum items to return (1–200, default 50)." }, "required": false, "name": "limit", "in": "query" }, { "schema": { "type": "string", "description": "Opaque cursor from a previous response's `pagination.next_cursor`." }, "required": false, "name": "cursor", "in": "query" } ], "responses": { "200": { "description": "List showbacks", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "array", "items": { "type": "object", "description": "JSON object", "additionalProperties": true } }, "pagination": { "$ref": "#/components/schemas/Pagination" } }, "required": [ "data", "pagination" ] }, "example": { "data": [ { "id": 1, "name": "Engineering", "active": true, "allocationTagType": null, "tagKeys": [], "extraValues": [], "hideValues": [], "removedShowbackValues": [], "baseFilterJson": null, "isLocked": false, "created": "2026-07-17T12:00:00.000Z", "modified": "2026-07-17T12:00:00.000Z", "ruleCount": 2 } ], "pagination": { "limit": 50, "has_more": false, "next_cursor": null } } } } }, "401": { "description": "Unauthorized — invalid or missing API key", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PublicApiError" }, "example": { "error": { "code": "forbidden_scope", "message": "API key is missing required scope: budgets:write", "request_id": "550e8400-e29b-41d4-a716-446655440000" } } } } }, "403": { "description": "Forbidden — insufficient permissions or entitlement", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PublicApiError" }, "example": { "error": { "code": "forbidden_scope", "message": "API key is missing required scope: budgets:write", "request_id": "550e8400-e29b-41d4-a716-446655440000" } } } } } } }, "post": { "tags": [ "Cost allocation" ], "summary": "Create showback", "operationId": "createCostAllocationShowback", "security": [ { "bearerApiKey": [] } ], "parameters": [ { "schema": { "type": "string", "maxLength": 64, "description": "Unique key for safe retries on write requests (required, max 64 characters)." }, "required": true, "name": "Idempotency-Key", "in": "header" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "name": { "type": "string", "minLength": 1, "maxLength": 256 }, "allocationTagType": { "type": "string", "enum": [ "tags", "labels", "cost_allocation_tags" ] }, "valueDimension": { "type": "string", "minLength": 1, "maxLength": 256 }, "tagKeys": { "type": "array", "items": { "type": "string", "maxLength": 256 }, "maxItems": 20, "default": [] }, "extraValues": { "type": "array", "items": { "type": "string", "maxLength": 256 }, "default": [] }, "baseFilters": { "type": "array", "items": { "type": "object", "properties": { "dimension": { "type": "string" }, "mode": { "type": "string", "enum": [ "include", "exclude" ] }, "values": { "type": "array", "items": { "type": "string" } }, "valueModes": { "type": "object", "additionalProperties": { "type": "string", "enum": [ "include", "exclude" ] } }, "texts": { "type": "array", "items": { "type": "object", "properties": { "mode": { "type": "string", "enum": [ "include", "exclude" ] }, "text": { "type": "string", "minLength": 1 } }, "required": [ "mode", "text" ] } }, "textCombinator": { "type": "string", "enum": [ "and", "or" ] }, "keyCombinator": { "type": "string", "enum": [ "and", "or" ] }, "tagKeyOnly": { "type": "boolean" } }, "required": [ "dimension", "mode", "values" ] }, "default": [] }, "valueSource": { "type": "string", "enum": [ "rules", "dimension", "tag_keys" ] }, "rules": { "type": "array", "items": { "type": "object", "properties": { "name": { "type": "string", "minLength": 1, "maxLength": 256 }, "showbackValue": { "type": "string", "minLength": 1, "maxLength": 256 }, "filters": { "type": "array", "items": { "type": "object", "properties": { "dimension": { "type": "string" }, "mode": { "type": "string", "enum": [ "include", "exclude" ] }, "values": { "type": "array", "items": { "type": "string" } }, "valueModes": { "type": "object", "additionalProperties": { "type": "string", "enum": [ "include", "exclude" ] } }, "texts": { "type": "array", "items": { "type": "object", "properties": { "mode": { "type": "string", "enum": [ "include", "exclude" ] }, "text": { "type": "string", "minLength": 1 } }, "required": [ "mode", "text" ] } }, "textCombinator": { "type": "string", "enum": [ "and", "or" ] }, "keyCombinator": { "type": "string", "enum": [ "and", "or" ] }, "tagKeyOnly": { "type": "boolean" } }, "required": [ "dimension", "mode", "values" ] }, "default": [] }, "distributionByPercent": { "type": "boolean" }, "percentageAllocationType": { "type": "string", "enum": [ "BY_SPEND", "CUSTOM_PERCENT", "CUSTOM_BY_SPEND", "EVENLY" ] }, "costDistribution": { "type": "object", "additionalProperties": { "type": "number", "minimum": 0, "maximum": 100 } }, "dimensionFilters": { "type": "array", "items": { "type": "object", "properties": { "dimension": { "type": "string" }, "mode": { "type": "string", "enum": [ "include", "exclude" ] }, "values": { "type": "array", "items": { "type": "string" } }, "valueModes": { "type": "object", "additionalProperties": { "type": "string", "enum": [ "include", "exclude" ] } }, "texts": { "type": "array", "items": { "type": "object", "properties": { "mode": { "type": "string", "enum": [ "include", "exclude" ] }, "text": { "type": "string", "minLength": 1 } }, "required": [ "mode", "text" ] } }, "textCombinator": { "type": "string", "enum": [ "and", "or" ] }, "keyCombinator": { "type": "string", "enum": [ "and", "or" ] }, "tagKeyOnly": { "type": "boolean" } }, "required": [ "dimension", "mode", "values" ] } }, "clearDimensionFilter": { "type": "boolean" } }, "required": [ "name" ] }, "default": [] } }, "required": [ "name", "valueSource" ] }, "example": { "name": "Engineering", "valueSource": "rules", "rules": [ { "name": "Production workloads", "showbackValue": "Production", "filters": [] } ] } } } }, "responses": { "200": { "description": "Create showback", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "object", "description": "JSON object", "additionalProperties": true } }, "required": [ "data" ] }, "example": { "data": { "showback": { "id": 1, "name": "Engineering", "active": true, "allocationTagType": null, "tagKeys": [], "extraValues": [], "hideValues": [], "removedShowbackValues": [], "baseFilterJson": null, "isLocked": false, "created": "2026-07-17T12:00:00.000Z", "modified": "2026-07-17T12:00:00.000Z", "ruleCount": 2 } } } } } }, "401": { "description": "Unauthorized — invalid or missing API key", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PublicApiError" }, "example": { "error": { "code": "forbidden_scope", "message": "API key is missing required scope: budgets:write", "request_id": "550e8400-e29b-41d4-a716-446655440000" } } } } }, "403": { "description": "Forbidden — insufficient permissions or entitlement", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PublicApiError" }, "example": { "error": { "code": "forbidden_scope", "message": "API key is missing required scope: budgets:write", "request_id": "550e8400-e29b-41d4-a716-446655440000" } } } } } } } }, "/v1/cost-allocation/summaries": { "get": { "tags": [ "Cost allocation" ], "summary": "Portfolio showback summaries", "operationId": "getCostAllocationSummaries", "security": [ { "bearerApiKey": [] } ], "responses": { "200": { "description": "Portfolio showback summaries", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "object", "description": "JSON object", "additionalProperties": true } }, "required": [ "data" ] }, "example": { "data": { "summaries": [ { "showbackId": 1, "name": "Engineering", "totalSpend": 42100.88, "allocatedSpend": 42100.88 } ] } } } } }, "401": { "description": "Unauthorized — invalid or missing API key", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PublicApiError" }, "example": { "error": { "code": "forbidden_scope", "message": "API key is missing required scope: budgets:write", "request_id": "550e8400-e29b-41d4-a716-446655440000" } } } } }, "403": { "description": "Forbidden — insufficient permissions or entitlement", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PublicApiError" }, "example": { "error": { "code": "forbidden_scope", "message": "API key is missing required scope: budgets:write", "request_id": "550e8400-e29b-41d4-a716-446655440000" } } } } } } } }, "/v1/cost-allocation/{id}": { "get": { "tags": [ "Cost allocation" ], "summary": "Get showback", "operationId": "getCostAllocationShowback", "security": [ { "bearerApiKey": [] } ], "parameters": [ { "schema": { "type": "string", "description": "Showback ID" }, "required": true, "name": "id", "in": "path" } ], "responses": { "200": { "description": "Get showback", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "object", "description": "JSON object", "additionalProperties": true } }, "required": [ "data" ] }, "example": { "data": { "showback": { "id": 1, "name": "Engineering", "active": true, "allocationTagType": null, "tagKeys": [], "extraValues": [], "hideValues": [], "removedShowbackValues": [], "baseFilterJson": null, "isLocked": false, "created": "2026-07-17T12:00:00.000Z", "modified": "2026-07-17T12:00:00.000Z", "ruleCount": 2 } } } } } }, "401": { "description": "Unauthorized — invalid or missing API key", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PublicApiError" }, "example": { "error": { "code": "forbidden_scope", "message": "API key is missing required scope: budgets:write", "request_id": "550e8400-e29b-41d4-a716-446655440000" } } } } }, "403": { "description": "Forbidden — insufficient permissions or entitlement", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PublicApiError" }, "example": { "error": { "code": "forbidden_scope", "message": "API key is missing required scope: budgets:write", "request_id": "550e8400-e29b-41d4-a716-446655440000" } } } } } } }, "patch": { "tags": [ "Cost allocation" ], "summary": "Update showback", "operationId": "updateCostAllocationShowback", "security": [ { "bearerApiKey": [] } ], "parameters": [ { "schema": { "type": "string", "description": "Showback ID" }, "required": true, "name": "id", "in": "path" }, { "schema": { "type": "string", "maxLength": 64, "description": "Unique key for safe retries on write requests (required, max 64 characters)." }, "required": true, "name": "Idempotency-Key", "in": "header" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "name": { "type": "string", "minLength": 1, "maxLength": 256 }, "active": { "type": "boolean" }, "allocationTagType": { "type": "string", "enum": [ "tags", "labels", "cost_allocation_tags" ] }, "tagKeys": { "type": "array", "items": { "type": "string", "maxLength": 256 }, "maxItems": 20 }, "extraValues": { "type": "array", "items": { "type": "string", "maxLength": 256 } }, "hideValues": { "type": "array", "items": { "type": "string", "maxLength": 256 } }, "removedShowbackValues": { "type": "array", "items": { "type": "string", "maxLength": 256 } }, "baseFilters": { "type": "array", "items": { "type": "object", "properties": { "dimension": { "type": "string" }, "mode": { "type": "string", "enum": [ "include", "exclude" ] }, "values": { "type": "array", "items": { "type": "string" } }, "valueModes": { "type": "object", "additionalProperties": { "type": "string", "enum": [ "include", "exclude" ] } }, "texts": { "type": "array", "items": { "type": "object", "properties": { "mode": { "type": "string", "enum": [ "include", "exclude" ] }, "text": { "type": "string", "minLength": 1 } }, "required": [ "mode", "text" ] } }, "textCombinator": { "type": "string", "enum": [ "and", "or" ] }, "keyCombinator": { "type": "string", "enum": [ "and", "or" ] }, "tagKeyOnly": { "type": "boolean" } }, "required": [ "dimension", "mode", "values" ] } } } }, "example": { "name": "Engineering Platform" } } } }, "responses": { "200": { "description": "Update showback", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "object", "description": "JSON object", "additionalProperties": true } }, "required": [ "data" ] }, "example": { "data": { "showback": { "id": 1, "name": "Engineering Platform", "active": true, "allocationTagType": null, "tagKeys": [], "extraValues": [], "hideValues": [], "removedShowbackValues": [], "baseFilterJson": null, "isLocked": false, "created": "2026-07-17T12:00:00.000Z", "modified": "2026-07-17T12:00:00.000Z", "ruleCount": 2 } } } } } }, "401": { "description": "Unauthorized — invalid or missing API key", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PublicApiError" }, "example": { "error": { "code": "forbidden_scope", "message": "API key is missing required scope: budgets:write", "request_id": "550e8400-e29b-41d4-a716-446655440000" } } } } }, "403": { "description": "Forbidden — insufficient permissions or entitlement", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PublicApiError" }, "example": { "error": { "code": "forbidden_scope", "message": "API key is missing required scope: budgets:write", "request_id": "550e8400-e29b-41d4-a716-446655440000" } } } } } } }, "delete": { "tags": [ "Cost allocation" ], "summary": "Delete showback", "operationId": "deleteCostAllocationShowback", "security": [ { "bearerApiKey": [] } ], "parameters": [ { "schema": { "type": "string", "description": "Showback ID" }, "required": true, "name": "id", "in": "path" } ], "responses": { "200": { "description": "Delete showback", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "object", "description": "JSON object", "additionalProperties": true } }, "required": [ "data" ] }, "example": { "data": { "success": true } } } } }, "401": { "description": "Unauthorized — invalid or missing API key", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PublicApiError" }, "example": { "error": { "code": "forbidden_scope", "message": "API key is missing required scope: budgets:write", "request_id": "550e8400-e29b-41d4-a716-446655440000" } } } } }, "403": { "description": "Forbidden — insufficient permissions or entitlement", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PublicApiError" }, "example": { "error": { "code": "forbidden_scope", "message": "API key is missing required scope: budgets:write", "request_id": "550e8400-e29b-41d4-a716-446655440000" } } } } } } } }, "/v1/cost-allocation/{id}/duplicate": { "post": { "tags": [ "Cost allocation" ], "summary": "Duplicate showback", "operationId": "duplicateCostAllocationShowback", "security": [ { "bearerApiKey": [] } ], "parameters": [ { "schema": { "type": "string", "description": "Showback ID" }, "required": true, "name": "id", "in": "path" }, { "schema": { "type": "string", "maxLength": 64, "description": "Unique key for safe retries on write requests (required, max 64 characters)." }, "required": true, "name": "Idempotency-Key", "in": "header" } ], "responses": { "200": { "description": "Duplicate showback", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "object", "description": "JSON object", "additionalProperties": true } }, "required": [ "data" ] }, "example": { "data": { "showback": { "id": 2, "name": "Engineering (copy)", "active": true, "allocationTagType": null, "tagKeys": [], "extraValues": [], "hideValues": [], "removedShowbackValues": [], "baseFilterJson": null, "isLocked": false, "created": "2026-07-17T12:00:00.000Z", "modified": "2026-07-17T12:00:00.000Z", "ruleCount": 2 } } } } } }, "401": { "description": "Unauthorized — invalid or missing API key", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PublicApiError" }, "example": { "error": { "code": "forbidden_scope", "message": "API key is missing required scope: budgets:write", "request_id": "550e8400-e29b-41d4-a716-446655440000" } } } } }, "403": { "description": "Forbidden — insufficient permissions or entitlement", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PublicApiError" }, "example": { "error": { "code": "forbidden_scope", "message": "API key is missing required scope: budgets:write", "request_id": "550e8400-e29b-41d4-a716-446655440000" } } } } } } } }, "/v1/cost-allocation/{id}/mv-builds": { "post": { "tags": [ "Cost allocation" ], "summary": "Trigger showback MV backfill", "description": "Fan out Databricks MV backfill jobs for each month in the inclusive range (max 24 months). Returns a requestId grouping the materialization ledger rows.", "operationId": "createCostAllocationShowbackMvBuilds", "security": [ { "bearerApiKey": [] } ], "parameters": [ { "schema": { "type": "string", "description": "Showback ID" }, "required": true, "name": "id", "in": "path" }, { "schema": { "type": "string", "maxLength": 64, "description": "Unique key for safe retries on write requests (required, max 64 characters)." }, "required": true, "name": "Idempotency-Key", "in": "header" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "startMonth": { "type": "string", "pattern": "^\\d{4}-\\d{2}(-\\d{2})?$" }, "endMonth": { "type": "string", "pattern": "^\\d{4}-\\d{2}(-\\d{2})?$" } }, "required": [ "startMonth", "endMonth" ] } } } }, "responses": { "201": { "description": "Fan out Databricks MV backfill jobs for each month in the inclusive range (max 24 months). Returns a requestId grouping the materialization ledger rows.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PublicApiError" } } } }, "401": { "description": "Unauthorized — invalid or missing API key", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PublicApiError" }, "example": { "error": { "code": "forbidden_scope", "message": "API key is missing required scope: budgets:write", "request_id": "550e8400-e29b-41d4-a716-446655440000" } } } } }, "403": { "description": "Forbidden — insufficient permissions or entitlement", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PublicApiError" }, "example": { "error": { "code": "forbidden_scope", "message": "API key is missing required scope: budgets:write", "request_id": "550e8400-e29b-41d4-a716-446655440000" } } } } } } }, "get": { "tags": [ "Cost allocation" ], "summary": "List showback MV build runs", "description": "Read materialization ledger rows from Postgres. Optional `requestId` filter.", "operationId": "listCostAllocationShowbackMvBuilds", "security": [ { "bearerApiKey": [] } ], "parameters": [ { "schema": { "type": "string", "description": "Showback ID" }, "required": true, "name": "id", "in": "path" }, { "schema": { "type": "integer", "minimum": 1, "maximum": 200, "description": "Maximum items to return (1–200, default 50)." }, "required": false, "name": "limit", "in": "query" }, { "schema": { "type": "string", "description": "Opaque cursor from a previous response's `pagination.next_cursor`." }, "required": false, "name": "cursor", "in": "query" } ], "responses": { "200": { "description": "List showback MV build runs", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "array", "items": { "type": "object", "description": "JSON object", "additionalProperties": true } }, "pagination": { "$ref": "#/components/schemas/Pagination" } }, "required": [ "data", "pagination" ] } } } }, "401": { "description": "Unauthorized — invalid or missing API key", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PublicApiError" }, "example": { "error": { "code": "forbidden_scope", "message": "API key is missing required scope: budgets:write", "request_id": "550e8400-e29b-41d4-a716-446655440000" } } } } }, "403": { "description": "Forbidden — insufficient permissions or entitlement", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PublicApiError" }, "example": { "error": { "code": "forbidden_scope", "message": "API key is missing required scope: budgets:write", "request_id": "550e8400-e29b-41d4-a716-446655440000" } } } } } } } }, "/v1/cost-allocation/{id}/reports": { "post": { "tags": [ "Cost allocation" ], "summary": "Create report from showback", "description": "Creates a saved Explorer report pre-scoped to this showback (groupBy and the showback overlay are derived automatically). Optional `config` overrides costType, granularity, date range, and filters. Defaults to the last 30 days when no date is given.", "operationId": "createCostAllocationShowbackReport", "security": [ { "bearerApiKey": [] } ], "parameters": [ { "schema": { "type": "string", "description": "Showback ID" }, "required": true, "name": "id", "in": "path" }, { "schema": { "type": "string", "maxLength": 64, "description": "Unique key for safe retries on write requests (required, max 64 characters)." }, "required": true, "name": "Idempotency-Key", "in": "header" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "name": { "type": "string", "minLength": 1, "maxLength": 200 }, "scope": { "type": "string", "enum": [ "private", "shared", "global" ], "default": "private" }, "config": { "type": "object", "properties": { "dateRange": { "type": "object", "properties": { "start": { "type": "string", "pattern": "^\\d{4}-\\d{2}-\\d{2}$" }, "end": { "type": "string", "pattern": "^\\d{4}-\\d{2}-\\d{2}$" } }, "required": [ "start", "end" ] }, "dateRangeMode": { "type": "string", "enum": [ "rolling", "fixed" ] }, "datePreset": { "type": "string", "enum": [ "7D", "14D", "30D", "60D", "1M", "3M", "6M", "1Y", "3Y", "MTD", "YTD", "1Y+MTD", "+0M", "+1M", "+3M", "+6M", "+1Y", "+3Y", "+4Y" ] }, "groupBy": { "type": "string" }, "costType": { "type": "string", "enum": [ "line_item_unblended_cost", "line_item_amortized_cost", "line_item_blended_cost", "pricing_public_on_demand_cost", "nops_line_item_net_unblended_cost", "nops_line_item_net_amortized_cost", "nops_pricing_net_public_on_demand_cost" ] }, "granularity": { "type": "string", "enum": [ "hour", "day", "week", "month", "quarter" ] }, "filters": { "type": "array", "items": { "type": "object", "properties": { "dimension": { "type": "string" }, "mode": { "type": "string", "enum": [ "include", "exclude" ] }, "values": { "type": "array", "items": { "type": "string" } }, "valueModes": { "type": "object", "additionalProperties": { "type": "string", "enum": [ "include", "exclude" ] } }, "texts": { "type": "array", "items": { "type": "object", "properties": { "mode": { "type": "string", "enum": [ "include", "exclude" ] }, "text": { "type": "string", "minLength": 1 } }, "required": [ "mode", "text" ] } }, "textCombinator": { "type": "string", "enum": [ "and", "or" ] }, "keyCombinator": { "type": "string", "enum": [ "and", "or" ] }, "tagKeyOnly": { "type": "boolean" } }, "required": [ "dimension", "mode", "values" ] }, "default": [] }, "tagKeyCombinators": { "type": "object", "additionalProperties": { "type": "string", "enum": [ "and", "or" ] } }, "topN": { "type": "integer", "nullable": true, "minimum": 0, "exclusiveMinimum": true }, "usageChart": { "type": "string", "enum": [ "Hide", "Usage", "Normalized Usage" ], "default": "Hide" }, "widgetChartView": { "type": "string", "enum": [ "all", "spend", "usage" ] }, "widgetTargetChartView": { "type": "string", "enum": [ "all", "spend", "target" ] }, "widgetBusinessUnitChartView": { "type": "string", "enum": [ "all", "spend", "unit" ] }, "page": { "type": "integer", "minimum": 0, "exclusiveMinimum": true }, "pageSize": { "type": "integer", "nullable": true, "minimum": 0, "exclusiveMinimum": true }, "sortColumn": { "type": "string", "enum": [ "name", "total" ] }, "sortDir": { "type": "string", "enum": [ "asc", "desc" ] }, "nameSearch": { "type": "string", "minLength": 1, "maxLength": 200 }, "budgetOverlay": { "type": "object", "nullable": true, "properties": { "budgetId": { "type": "string", "minLength": 1 }, "enabled": { "type": "boolean" } }, "required": [ "budgetId", "enabled" ] }, "bueOverlay": { "type": "object", "nullable": true, "properties": { "economicsId": { "type": "integer", "minimum": 0, "exclusiveMinimum": true }, "enabled": { "type": "boolean" } }, "required": [ "economicsId", "enabled" ] }, "showbackOverlay": { "type": "object", "nullable": true, "properties": { "showbackId": { "type": "integer", "minimum": 0, "exclusiveMinimum": true }, "enabled": { "type": "boolean" }, "dimension": { "type": "string", "nullable": true }, "grouping": { "type": "string", "enum": [ "allocation", "dimension" ] }, "valueFilter": { "type": "object", "nullable": true, "properties": { "mode": { "type": "string", "enum": [ "include", "exclude" ] }, "values": { "type": "array", "items": { "type": "string" } }, "valueModes": { "type": "object", "additionalProperties": { "type": "string", "enum": [ "include", "exclude" ] } } }, "required": [ "mode", "values" ] }, "drilldownGroupBy": { "type": "string", "nullable": true } }, "required": [ "showbackId", "enabled" ] }, "heatmap": { "type": "object", "nullable": true, "properties": { "enabled": { "type": "boolean" }, "xAxis": { "type": "string" }, "yAxis": { "type": "string" } }, "required": [ "enabled", "xAxis", "yAxis" ] }, "forecastHorizon": { "type": "integer", "minimum": 1, "maximum": 365 }, "bypassCache": { "type": "boolean" } } } }, "required": [ "name" ] }, "example": { "name": "Engineering allocation — last month", "scope": "private" } } } }, "responses": { "201": { "description": "Creates a saved Explorer report pre-scoped to this showback (groupBy and the showback overlay are derived automatically). Optional `config` overrides costType, granularity, date range, and filters. Defaults to the last 30 days when no date is given.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PublicApiError" }, "example": { "data": { "report": { "id": "report-1", "name": "Engineering allocation — last month", "scope": "private", "config": { "dateRange": { "start": "2026-05-31", "end": "2026-06-29" }, "groupBy": "product_product_name", "costType": "line_item_unblended_cost", "granularity": "day", "filters": [] }, "organizationId": "org-1", "nopsClientId": 42, "creatorId": "user-1", "createdAt": "2026-07-17T12:00:00.000Z", "updatedAt": "2026-07-17T12:00:00.000Z", "creator": { "id": "user-1", "firstName": "FinOps", "lastName": "Analyst", "email": "finops@example.com" } } } } } } }, "401": { "description": "Unauthorized — invalid or missing API key", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PublicApiError" }, "example": { "error": { "code": "forbidden_scope", "message": "API key is missing required scope: budgets:write", "request_id": "550e8400-e29b-41d4-a716-446655440000" } } } } }, "403": { "description": "Forbidden — insufficient permissions or entitlement", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PublicApiError" }, "example": { "error": { "code": "forbidden_scope", "message": "API key is missing required scope: budgets:write", "request_id": "550e8400-e29b-41d4-a716-446655440000" } } } } } } } }, "/v1/cost-allocation/{id}/preview": { "get": { "tags": [ "Cost allocation" ], "summary": "Showback spend preview", "description": "Preview allocated spend for a showback. Optional query params: startDate, endDate (YYYY-MM-DD), and dataSource (`live` default, or `processed` for materialized showback views).", "operationId": "getCostAllocationShowbackPreview", "security": [ { "bearerApiKey": [] } ], "parameters": [ { "schema": { "type": "string", "description": "Showback ID" }, "required": true, "name": "id", "in": "path" } ], "responses": { "200": { "description": "Showback spend preview", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "object", "description": "JSON object", "additionalProperties": true } }, "required": [ "data" ] }, "example": { "data": { "totalSpend": 42100.88, "values": [ { "name": "Production", "spend": 32000 }, { "name": "Staging", "spend": 10100.88 } ] } } } } }, "401": { "description": "Unauthorized — invalid or missing API key", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PublicApiError" }, "example": { "error": { "code": "forbidden_scope", "message": "API key is missing required scope: budgets:write", "request_id": "550e8400-e29b-41d4-a716-446655440000" } } } } }, "403": { "description": "Forbidden — insufficient permissions or entitlement", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PublicApiError" }, "example": { "error": { "code": "forbidden_scope", "message": "API key is missing required scope: budgets:write", "request_id": "550e8400-e29b-41d4-a716-446655440000" } } } } } } } }, "/v1/cost-allocation/{id}/dimension-values": { "post": { "tags": [ "Cost allocation" ], "summary": "Discover dimension values", "operationId": "getCostAllocationDimensionValues", "security": [ { "bearerApiKey": [] } ], "parameters": [ { "schema": { "type": "string", "description": "Showback ID" }, "required": true, "name": "id", "in": "path" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "dimensionKey": { "type": "string", "minLength": 1, "maxLength": 256 }, "tagKey": { "type": "string", "minLength": 1, "maxLength": 256 }, "start": { "type": "string", "pattern": "^\\d{4}-\\d{2}-\\d{2}$" }, "end": { "type": "string", "pattern": "^\\d{4}-\\d{2}-\\d{2}$" }, "costType": { "type": "string", "minLength": 1, "maxLength": 128, "default": "line_item_unblended_cost" }, "search": { "type": "string", "maxLength": 256 }, "draftFilters": { "type": "array", "items": { "type": "object", "properties": { "dimension": { "type": "string" }, "mode": { "type": "string", "enum": [ "include", "exclude" ] }, "values": { "type": "array", "items": { "type": "string" } }, "valueModes": { "type": "object", "additionalProperties": { "type": "string", "enum": [ "include", "exclude" ] } }, "texts": { "type": "array", "items": { "type": "object", "properties": { "mode": { "type": "string", "enum": [ "include", "exclude" ] }, "text": { "type": "string", "minLength": 1 } }, "required": [ "mode", "text" ] } }, "textCombinator": { "type": "string", "enum": [ "and", "or" ] }, "keyCombinator": { "type": "string", "enum": [ "and", "or" ] }, "tagKeyOnly": { "type": "boolean" } }, "required": [ "dimension", "mode", "values" ] }, "default": [] }, "editingRuleId": { "type": "integer", "minimum": 0, "exclusiveMinimum": true }, "tagKeyCombinators": { "type": "object", "additionalProperties": { "type": "string", "enum": [ "and", "or" ] } }, "showbackValue": { "type": "string", "minLength": 1, "maxLength": 256 }, "excludeAllocationRules": { "type": "boolean", "default": true } }, "required": [ "dimensionKey", "start", "end" ] }, "example": { "dimension": "billing_account_name", "start": "2026-05-31", "end": "2026-06-29" } } } }, "responses": { "200": { "description": "Discover dimension values", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "object", "description": "JSON object", "additionalProperties": true } }, "required": [ "data" ] }, "example": { "data": { "values": [ "Production", "Staging", "Sandbox" ] } } } } }, "401": { "description": "Unauthorized — invalid or missing API key", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PublicApiError" }, "example": { "error": { "code": "forbidden_scope", "message": "API key is missing required scope: budgets:write", "request_id": "550e8400-e29b-41d4-a716-446655440000" } } } } }, "403": { "description": "Forbidden — insufficient permissions or entitlement", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PublicApiError" }, "example": { "error": { "code": "forbidden_scope", "message": "API key is missing required scope: budgets:write", "request_id": "550e8400-e29b-41d4-a716-446655440000" } } } } } } } }, "/v1/cost-allocation/{id}/allocation-history": { "post": { "tags": [ "Cost allocation" ], "summary": "Allocation history time series", "operationId": "getCostAllocationAllocationHistory", "security": [ { "bearerApiKey": [] } ], "parameters": [ { "schema": { "type": "string", "description": "Showback ID" }, "required": true, "name": "id", "in": "path" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "query": { "nullable": true } } }, "example": { "start": "2026-05-31", "end": "2026-06-29", "granularity": "day" } } } }, "responses": { "200": { "description": "Allocation history time series", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "object", "description": "JSON object", "additionalProperties": true } }, "required": [ "data" ] }, "example": { "data": { "series": [ { "date": "2026-06-01", "Production": 1200.5, "Staging": 400.25 } ] } } } } }, "401": { "description": "Unauthorized — invalid or missing API key", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PublicApiError" }, "example": { "error": { "code": "forbidden_scope", "message": "API key is missing required scope: budgets:write", "request_id": "550e8400-e29b-41d4-a716-446655440000" } } } } }, "403": { "description": "Forbidden — insufficient permissions or entitlement", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PublicApiError" }, "example": { "error": { "code": "forbidden_scope", "message": "API key is missing required scope: budgets:write", "request_id": "550e8400-e29b-41d4-a716-446655440000" } } } } } } } }, "/v1/cost-allocation/{id}/value-breakdown": { "post": { "tags": [ "Cost allocation" ], "summary": "Drill into one allocation value", "operationId": "getCostAllocationValueBreakdown", "security": [ { "bearerApiKey": [] } ], "parameters": [ { "schema": { "type": "string", "description": "Showback ID" }, "required": true, "name": "id", "in": "path" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "query": { "nullable": true }, "showbackValue": { "type": "string", "minLength": 1, "maxLength": 256 }, "drillGroupBy": { "type": "string", "minLength": 1, "maxLength": 256 }, "includeValueTotalCost": { "type": "boolean", "default": false } }, "required": [ "showbackValue", "drillGroupBy" ] } } } }, "responses": { "200": { "description": "Drill into one allocation value", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "object", "description": "JSON object", "additionalProperties": true } }, "required": [ "data" ] } } } }, "401": { "description": "Unauthorized — invalid or missing API key", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PublicApiError" }, "example": { "error": { "code": "forbidden_scope", "message": "API key is missing required scope: budgets:write", "request_id": "550e8400-e29b-41d4-a716-446655440000" } } } } }, "403": { "description": "Forbidden — insufficient permissions or entitlement", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PublicApiError" }, "example": { "error": { "code": "forbidden_scope", "message": "API key is missing required scope: budgets:write", "request_id": "550e8400-e29b-41d4-a716-446655440000" } } } } } } } }, "/v1/cost-allocation/draft/preview": { "post": { "tags": [ "Cost allocation" ], "summary": "Preview a proposed (unsaved) rule set", "operationId": "previewCostAllocationDraft", "security": [ { "bearerApiKey": [] } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "baseFilters": { "type": "array", "items": { "type": "object", "properties": { "dimension": { "type": "string" }, "mode": { "type": "string", "enum": [ "include", "exclude" ] }, "values": { "type": "array", "items": { "type": "string" } }, "valueModes": { "type": "object", "additionalProperties": { "type": "string", "enum": [ "include", "exclude" ] } }, "texts": { "type": "array", "items": { "type": "object", "properties": { "mode": { "type": "string", "enum": [ "include", "exclude" ] }, "text": { "type": "string", "minLength": 1 } }, "required": [ "mode", "text" ] } }, "textCombinator": { "type": "string", "enum": [ "and", "or" ] }, "keyCombinator": { "type": "string", "enum": [ "and", "or" ] }, "tagKeyOnly": { "type": "boolean" } }, "required": [ "dimension", "mode", "values" ] }, "default": [] }, "draftValues": { "type": "array", "items": { "type": "object", "properties": { "ruleIndex": { "type": "integer", "minimum": 0 }, "name": { "type": "string", "maxLength": 256 }, "filters": { "type": "array", "items": { "type": "object", "properties": { "dimension": { "type": "string" }, "mode": { "type": "string", "enum": [ "include", "exclude" ] }, "values": { "type": "array", "items": { "type": "string" } }, "valueModes": { "type": "object", "additionalProperties": { "type": "string", "enum": [ "include", "exclude" ] } }, "texts": { "type": "array", "items": { "type": "object", "properties": { "mode": { "type": "string", "enum": [ "include", "exclude" ] }, "text": { "type": "string", "minLength": 1 } }, "required": [ "mode", "text" ] } }, "textCombinator": { "type": "string", "enum": [ "and", "or" ] }, "keyCombinator": { "type": "string", "enum": [ "and", "or" ] }, "tagKeyOnly": { "type": "boolean" } }, "required": [ "dimension", "mode", "values" ] } }, "distributionByPercent": { "type": "boolean" }, "percentageAllocationType": { "type": "string", "enum": [ "BY_SPEND", "CUSTOM_PERCENT", "CUSTOM_BY_SPEND", "EVENLY" ] }, "costDistribution": { "type": "object", "additionalProperties": { "type": "number", "minimum": 0, "maximum": 100 } }, "dimensionFilters": { "type": "array", "items": { "type": "object", "properties": { "dimension": { "type": "string" }, "mode": { "type": "string", "enum": [ "include", "exclude" ] }, "values": { "type": "array", "items": { "type": "string" } }, "valueModes": { "type": "object", "additionalProperties": { "type": "string", "enum": [ "include", "exclude" ] } }, "texts": { "type": "array", "items": { "type": "object", "properties": { "mode": { "type": "string", "enum": [ "include", "exclude" ] }, "text": { "type": "string", "minLength": 1 } }, "required": [ "mode", "text" ] } }, "textCombinator": { "type": "string", "enum": [ "and", "or" ] }, "keyCombinator": { "type": "string", "enum": [ "and", "or" ] }, "tagKeyOnly": { "type": "boolean" } }, "required": [ "dimension", "mode", "values" ] } }, "clearDimensionFilter": { "type": "boolean" } }, "required": [ "ruleIndex", "name", "filters" ] }, "default": [] }, "startDate": { "type": "string", "pattern": "^\\d{4}-\\d{2}-\\d{2}$" }, "endDate": { "type": "string", "pattern": "^\\d{4}-\\d{2}-\\d{2}$" } } } } } }, "responses": { "200": { "description": "Preview a proposed (unsaved) rule set", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "object", "description": "JSON object", "additionalProperties": true } }, "required": [ "data" ] } } } }, "401": { "description": "Unauthorized — invalid or missing API key", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PublicApiError" }, "example": { "error": { "code": "forbidden_scope", "message": "API key is missing required scope: budgets:write", "request_id": "550e8400-e29b-41d4-a716-446655440000" } } } } }, "403": { "description": "Forbidden — insufficient permissions or entitlement", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PublicApiError" }, "example": { "error": { "code": "forbidden_scope", "message": "API key is missing required scope: budgets:write", "request_id": "550e8400-e29b-41d4-a716-446655440000" } } } } } } } }, "/v1/cost-allocation/{id}/rules": { "get": { "tags": [ "Cost allocation" ], "summary": "List allocation rules", "operationId": "listCostAllocationRules", "security": [ { "bearerApiKey": [] } ], "parameters": [ { "schema": { "type": "string", "description": "Showback ID" }, "required": true, "name": "id", "in": "path" }, { "schema": { "type": "integer", "minimum": 1, "maximum": 200, "description": "Maximum items to return (1–200, default 50)." }, "required": false, "name": "limit", "in": "query" }, { "schema": { "type": "string", "description": "Opaque cursor from a previous response's `pagination.next_cursor`." }, "required": false, "name": "cursor", "in": "query" } ], "responses": { "200": { "description": "List allocation rules", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "array", "items": { "type": "object", "description": "JSON object", "additionalProperties": true } }, "pagination": { "$ref": "#/components/schemas/Pagination" } }, "required": [ "data", "pagination" ] }, "example": { "data": [ { "id": "rule-1", "showbackId": 1, "name": "Production workloads", "showbackValue": "Production", "orderIndex": 0, "active": true } ], "pagination": { "limit": 50, "has_more": false, "next_cursor": null } } } } }, "401": { "description": "Unauthorized — invalid or missing API key", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PublicApiError" }, "example": { "error": { "code": "forbidden_scope", "message": "API key is missing required scope: budgets:write", "request_id": "550e8400-e29b-41d4-a716-446655440000" } } } } }, "403": { "description": "Forbidden — insufficient permissions or entitlement", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PublicApiError" }, "example": { "error": { "code": "forbidden_scope", "message": "API key is missing required scope: budgets:write", "request_id": "550e8400-e29b-41d4-a716-446655440000" } } } } } } }, "post": { "tags": [ "Cost allocation" ], "summary": "Create allocation rule", "operationId": "createCostAllocationRule", "security": [ { "bearerApiKey": [] } ], "parameters": [ { "schema": { "type": "string", "description": "Showback ID" }, "required": true, "name": "id", "in": "path" }, { "schema": { "type": "string", "maxLength": 64, "description": "Unique key for safe retries on write requests (required, max 64 characters)." }, "required": true, "name": "Idempotency-Key", "in": "header" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "name": { "type": "string", "minLength": 1, "maxLength": 256 }, "showbackValue": { "type": "string", "minLength": 1, "maxLength": 256 }, "filters": { "type": "array", "items": { "type": "object", "properties": { "dimension": { "type": "string" }, "mode": { "type": "string", "enum": [ "include", "exclude" ] }, "values": { "type": "array", "items": { "type": "string" } }, "valueModes": { "type": "object", "additionalProperties": { "type": "string", "enum": [ "include", "exclude" ] } }, "texts": { "type": "array", "items": { "type": "object", "properties": { "mode": { "type": "string", "enum": [ "include", "exclude" ] }, "text": { "type": "string", "minLength": 1 } }, "required": [ "mode", "text" ] } }, "textCombinator": { "type": "string", "enum": [ "and", "or" ] }, "keyCombinator": { "type": "string", "enum": [ "and", "or" ] }, "tagKeyOnly": { "type": "boolean" } }, "required": [ "dimension", "mode", "values" ] }, "default": [] }, "active": { "type": "boolean", "default": true }, "distributionByPercent": { "type": "boolean" }, "percentageAllocationType": { "type": "string", "enum": [ "BY_SPEND", "CUSTOM_PERCENT", "CUSTOM_BY_SPEND", "EVENLY" ] }, "costDistribution": { "type": "object", "additionalProperties": { "type": "number", "minimum": 0, "maximum": 100 } }, "dimensionFilters": { "type": "array", "items": { "type": "object", "properties": { "dimension": { "type": "string" }, "mode": { "type": "string", "enum": [ "include", "exclude" ] }, "values": { "type": "array", "items": { "type": "string" } }, "valueModes": { "type": "object", "additionalProperties": { "type": "string", "enum": [ "include", "exclude" ] } }, "texts": { "type": "array", "items": { "type": "object", "properties": { "mode": { "type": "string", "enum": [ "include", "exclude" ] }, "text": { "type": "string", "minLength": 1 } }, "required": [ "mode", "text" ] } }, "textCombinator": { "type": "string", "enum": [ "and", "or" ] }, "keyCombinator": { "type": "string", "enum": [ "and", "or" ] }, "tagKeyOnly": { "type": "boolean" } }, "required": [ "dimension", "mode", "values" ] } }, "clearDimensionFilter": { "type": "boolean" } }, "required": [ "name" ] }, "example": { "name": "Production workloads", "showbackValue": "Production", "filters": [ { "dimension": "billing_account_name", "mode": "include", "values": [ "Production" ] } ] } } } }, "responses": { "200": { "description": "Create allocation rule", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "object", "description": "JSON object", "additionalProperties": true } }, "required": [ "data" ] }, "example": { "data": { "rule": { "id": "rule-1", "showbackId": 1, "name": "Production workloads", "showbackValue": "Production", "orderIndex": 0, "active": true } } } } } }, "401": { "description": "Unauthorized — invalid or missing API key", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PublicApiError" }, "example": { "error": { "code": "forbidden_scope", "message": "API key is missing required scope: budgets:write", "request_id": "550e8400-e29b-41d4-a716-446655440000" } } } } }, "403": { "description": "Forbidden — insufficient permissions or entitlement", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PublicApiError" }, "example": { "error": { "code": "forbidden_scope", "message": "API key is missing required scope: budgets:write", "request_id": "550e8400-e29b-41d4-a716-446655440000" } } } } } } } }, "/v1/cost-allocation/{id}/rules/{ruleId}": { "patch": { "tags": [ "Cost allocation" ], "summary": "Update allocation rule", "operationId": "updateCostAllocationRule", "security": [ { "bearerApiKey": [] } ], "parameters": [ { "schema": { "type": "string", "description": "Showback ID" }, "required": true, "name": "id", "in": "path" }, { "schema": { "type": "string", "description": "Rule ID" }, "required": true, "name": "ruleId", "in": "path" }, { "schema": { "type": "string", "maxLength": 64, "description": "Unique key for safe retries on write requests (required, max 64 characters)." }, "required": true, "name": "Idempotency-Key", "in": "header" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "name": { "type": "string", "minLength": 1, "maxLength": 256 }, "showbackValue": { "type": "string", "minLength": 1, "maxLength": 256 }, "filters": { "type": "array", "items": { "type": "object", "properties": { "dimension": { "type": "string" }, "mode": { "type": "string", "enum": [ "include", "exclude" ] }, "values": { "type": "array", "items": { "type": "string" } }, "valueModes": { "type": "object", "additionalProperties": { "type": "string", "enum": [ "include", "exclude" ] } }, "texts": { "type": "array", "items": { "type": "object", "properties": { "mode": { "type": "string", "enum": [ "include", "exclude" ] }, "text": { "type": "string", "minLength": 1 } }, "required": [ "mode", "text" ] } }, "textCombinator": { "type": "string", "enum": [ "and", "or" ] }, "keyCombinator": { "type": "string", "enum": [ "and", "or" ] }, "tagKeyOnly": { "type": "boolean" } }, "required": [ "dimension", "mode", "values" ] } }, "active": { "type": "boolean" }, "distributionByPercent": { "type": "boolean" }, "percentageAllocationType": { "type": "string", "enum": [ "BY_SPEND", "CUSTOM_PERCENT", "CUSTOM_BY_SPEND", "EVENLY" ] }, "costDistribution": { "type": "object", "additionalProperties": { "type": "number", "minimum": 0, "maximum": 100 } }, "dimensionFilters": { "type": "array", "items": { "type": "object", "properties": { "dimension": { "type": "string" }, "mode": { "type": "string", "enum": [ "include", "exclude" ] }, "values": { "type": "array", "items": { "type": "string" } }, "valueModes": { "type": "object", "additionalProperties": { "type": "string", "enum": [ "include", "exclude" ] } }, "texts": { "type": "array", "items": { "type": "object", "properties": { "mode": { "type": "string", "enum": [ "include", "exclude" ] }, "text": { "type": "string", "minLength": 1 } }, "required": [ "mode", "text" ] } }, "textCombinator": { "type": "string", "enum": [ "and", "or" ] }, "keyCombinator": { "type": "string", "enum": [ "and", "or" ] }, "tagKeyOnly": { "type": "boolean" } }, "required": [ "dimension", "mode", "values" ] } }, "clearDimensionFilter": { "type": "boolean" } } }, "example": { "name": "Production workloads (updated)" } } } }, "responses": { "200": { "description": "Update allocation rule", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "object", "description": "JSON object", "additionalProperties": true } }, "required": [ "data" ] }, "example": { "data": { "rule": { "id": "rule-1", "showbackId": 1, "name": "Production workloads (updated)", "showbackValue": "Production", "orderIndex": 0, "active": true } } } } } }, "401": { "description": "Unauthorized — invalid or missing API key", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PublicApiError" }, "example": { "error": { "code": "forbidden_scope", "message": "API key is missing required scope: budgets:write", "request_id": "550e8400-e29b-41d4-a716-446655440000" } } } } }, "403": { "description": "Forbidden — insufficient permissions or entitlement", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PublicApiError" }, "example": { "error": { "code": "forbidden_scope", "message": "API key is missing required scope: budgets:write", "request_id": "550e8400-e29b-41d4-a716-446655440000" } } } } } } }, "delete": { "tags": [ "Cost allocation" ], "summary": "Delete allocation rule", "operationId": "deleteCostAllocationRule", "security": [ { "bearerApiKey": [] } ], "parameters": [ { "schema": { "type": "string", "description": "Showback ID" }, "required": true, "name": "id", "in": "path" }, { "schema": { "type": "string", "description": "Rule ID" }, "required": true, "name": "ruleId", "in": "path" } ], "responses": { "200": { "description": "Delete allocation rule", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "object", "description": "JSON object", "additionalProperties": true } }, "required": [ "data" ] }, "example": { "data": { "success": true } } } } }, "401": { "description": "Unauthorized — invalid or missing API key", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PublicApiError" }, "example": { "error": { "code": "forbidden_scope", "message": "API key is missing required scope: budgets:write", "request_id": "550e8400-e29b-41d4-a716-446655440000" } } } } }, "403": { "description": "Forbidden — insufficient permissions or entitlement", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PublicApiError" }, "example": { "error": { "code": "forbidden_scope", "message": "API key is missing required scope: budgets:write", "request_id": "550e8400-e29b-41d4-a716-446655440000" } } } } } } } }, "/v1/cost-allocation/{id}/rules/{ruleId}/move": { "post": { "tags": [ "Cost allocation" ], "summary": "Reorder allocation rule", "operationId": "moveCostAllocationRule", "security": [ { "bearerApiKey": [] } ], "parameters": [ { "schema": { "type": "string", "description": "Showback ID" }, "required": true, "name": "id", "in": "path" }, { "schema": { "type": "string", "description": "Rule ID" }, "required": true, "name": "ruleId", "in": "path" }, { "schema": { "type": "string", "maxLength": 64, "description": "Unique key for safe retries on write requests (required, max 64 characters)." }, "required": true, "name": "Idempotency-Key", "in": "header" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "beforeRuleId": { "type": "integer", "nullable": true, "minimum": 0, "exclusiveMinimum": true } } }, "example": { "direction": "up" } } } }, "responses": { "200": { "description": "Reorder allocation rule", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "object", "description": "JSON object", "additionalProperties": true } }, "required": [ "data" ] }, "example": { "data": { "success": true } } } } }, "401": { "description": "Unauthorized — invalid or missing API key", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PublicApiError" }, "example": { "error": { "code": "forbidden_scope", "message": "API key is missing required scope: budgets:write", "request_id": "550e8400-e29b-41d4-a716-446655440000" } } } } }, "403": { "description": "Forbidden — insufficient permissions or entitlement", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PublicApiError" }, "example": { "error": { "code": "forbidden_scope", "message": "API key is missing required scope: budgets:write", "request_id": "550e8400-e29b-41d4-a716-446655440000" } } } } } } } }, "/v1/cost-allocation/{id}/rules/sync": { "post": { "tags": [ "Cost allocation" ], "summary": "Sync dimension-discovered rules", "operationId": "syncCostAllocationRules", "security": [ { "bearerApiKey": [] } ], "parameters": [ { "schema": { "type": "string", "description": "Showback ID" }, "required": true, "name": "id", "in": "path" }, { "schema": { "type": "string", "maxLength": 64, "description": "Unique key for safe retries on write requests (required, max 64 characters)." }, "required": true, "name": "Idempotency-Key", "in": "header" } ], "responses": { "200": { "description": "Sync dimension-discovered rules", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "object", "description": "JSON object", "additionalProperties": true } }, "required": [ "data" ] }, "example": { "data": { "created": 2, "updated": 0 } } } } }, "401": { "description": "Unauthorized — invalid or missing API key", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PublicApiError" }, "example": { "error": { "code": "forbidden_scope", "message": "API key is missing required scope: budgets:write", "request_id": "550e8400-e29b-41d4-a716-446655440000" } } } } }, "403": { "description": "Forbidden — insufficient permissions or entitlement", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PublicApiError" }, "example": { "error": { "code": "forbidden_scope", "message": "API key is missing required scope: budgets:write", "request_id": "550e8400-e29b-41d4-a716-446655440000" } } } } } } } }, "/v1/cost-allocation/{id}/rules/dimension-preview": { "post": { "tags": [ "Cost allocation" ], "summary": "Percent distribution preview", "operationId": "getCostAllocationDimensionPreview", "security": [ { "bearerApiKey": [] } ], "parameters": [ { "schema": { "type": "string", "description": "Showback ID" }, "required": true, "name": "id", "in": "path" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "description": "JSON request body", "additionalProperties": true }, "example": { "dimension": "billing_account_name", "costDistribution": { "Production": 75, "Staging": 25 } } } } }, "responses": { "200": { "description": "Percent distribution preview", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "object", "description": "JSON object", "additionalProperties": true } }, "required": [ "data" ] }, "example": { "data": { "preview": [ { "value": "Production", "percent": 75, "spend": 31575.66 }, { "value": "Staging", "percent": 25, "spend": 10525.22 } ] } } } } }, "401": { "description": "Unauthorized — invalid or missing API key", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PublicApiError" }, "example": { "error": { "code": "forbidden_scope", "message": "API key is missing required scope: budgets:write", "request_id": "550e8400-e29b-41d4-a716-446655440000" } } } } }, "403": { "description": "Forbidden — insufficient permissions or entitlement", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PublicApiError" }, "example": { "error": { "code": "forbidden_scope", "message": "API key is missing required scope: budgets:write", "request_id": "550e8400-e29b-41d4-a716-446655440000" } } } } } } } }, "/v1/cost-allocation/{id}/value-combinations": { "get": { "tags": [ "Cost allocation" ], "summary": "List value combinations", "operationId": "listCostAllocationValueCombinations", "security": [ { "bearerApiKey": [] } ], "parameters": [ { "schema": { "type": "string", "description": "Showback ID" }, "required": true, "name": "id", "in": "path" }, { "schema": { "type": "integer", "minimum": 1, "maximum": 200, "description": "Maximum items to return (1–200, default 50)." }, "required": false, "name": "limit", "in": "query" }, { "schema": { "type": "string", "description": "Opaque cursor from a previous response's `pagination.next_cursor`." }, "required": false, "name": "cursor", "in": "query" } ], "responses": { "200": { "description": "List value combinations", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "array", "items": { "type": "object", "description": "JSON object", "additionalProperties": true } }, "pagination": { "$ref": "#/components/schemas/Pagination" } }, "required": [ "data", "pagination" ] } } } }, "401": { "description": "Unauthorized — invalid or missing API key", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PublicApiError" }, "example": { "error": { "code": "forbidden_scope", "message": "API key is missing required scope: budgets:write", "request_id": "550e8400-e29b-41d4-a716-446655440000" } } } } }, "403": { "description": "Forbidden — insufficient permissions or entitlement", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PublicApiError" }, "example": { "error": { "code": "forbidden_scope", "message": "API key is missing required scope: budgets:write", "request_id": "550e8400-e29b-41d4-a716-446655440000" } } } } } } }, "post": { "tags": [ "Cost allocation" ], "summary": "Create value combination", "operationId": "createCostAllocationValueCombination", "security": [ { "bearerApiKey": [] } ], "parameters": [ { "schema": { "type": "string", "description": "Showback ID" }, "required": true, "name": "id", "in": "path" }, { "schema": { "type": "string", "maxLength": 64, "description": "Unique key for safe retries on write requests (required, max 64 characters)." }, "required": true, "name": "Idempotency-Key", "in": "header" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "name": { "type": "string", "minLength": 1, "maxLength": 256 }, "combinedValues": { "type": "array", "items": { "type": "string", "minLength": 1, "maxLength": 256 }, "minItems": 2 } }, "required": [ "name", "combinedValues" ] } } } }, "responses": { "200": { "description": "Create value combination", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "object", "description": "JSON object", "additionalProperties": true } }, "required": [ "data" ] } } } }, "401": { "description": "Unauthorized — invalid or missing API key", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PublicApiError" }, "example": { "error": { "code": "forbidden_scope", "message": "API key is missing required scope: budgets:write", "request_id": "550e8400-e29b-41d4-a716-446655440000" } } } } }, "403": { "description": "Forbidden — insufficient permissions or entitlement", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PublicApiError" }, "example": { "error": { "code": "forbidden_scope", "message": "API key is missing required scope: budgets:write", "request_id": "550e8400-e29b-41d4-a716-446655440000" } } } } } } } }, "/v1/cost-allocation/{id}/value-combinations/{combinationId}": { "patch": { "tags": [ "Cost allocation" ], "summary": "Update value combination", "operationId": "updateCostAllocationValueCombination", "security": [ { "bearerApiKey": [] } ], "parameters": [ { "schema": { "type": "string", "description": "Showback ID" }, "required": true, "name": "id", "in": "path" }, { "schema": { "type": "string", "description": "Value combination ID" }, "required": true, "name": "combinationId", "in": "path" }, { "schema": { "type": "string", "maxLength": 64, "description": "Unique key for safe retries on write requests (required, max 64 characters)." }, "required": true, "name": "Idempotency-Key", "in": "header" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "name": { "type": "string", "minLength": 1, "maxLength": 256 }, "combinedValues": { "type": "array", "items": { "type": "string", "minLength": 1, "maxLength": 256 }, "minItems": 2 } } } } } }, "responses": { "200": { "description": "Update value combination", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "object", "description": "JSON object", "additionalProperties": true } }, "required": [ "data" ] } } } }, "401": { "description": "Unauthorized — invalid or missing API key", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PublicApiError" }, "example": { "error": { "code": "forbidden_scope", "message": "API key is missing required scope: budgets:write", "request_id": "550e8400-e29b-41d4-a716-446655440000" } } } } }, "403": { "description": "Forbidden — insufficient permissions or entitlement", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PublicApiError" }, "example": { "error": { "code": "forbidden_scope", "message": "API key is missing required scope: budgets:write", "request_id": "550e8400-e29b-41d4-a716-446655440000" } } } } } } }, "delete": { "tags": [ "Cost allocation" ], "summary": "Delete value combination", "operationId": "deleteCostAllocationValueCombination", "security": [ { "bearerApiKey": [] } ], "parameters": [ { "schema": { "type": "string", "description": "Showback ID" }, "required": true, "name": "id", "in": "path" }, { "schema": { "type": "string", "description": "Value combination ID" }, "required": true, "name": "combinationId", "in": "path" } ], "responses": { "200": { "description": "Delete value combination", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "object", "description": "JSON object", "additionalProperties": true } }, "required": [ "data" ] } } } }, "401": { "description": "Unauthorized — invalid or missing API key", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PublicApiError" }, "example": { "error": { "code": "forbidden_scope", "message": "API key is missing required scope: budgets:write", "request_id": "550e8400-e29b-41d4-a716-446655440000" } } } } }, "403": { "description": "Forbidden — insufficient permissions or entitlement", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PublicApiError" }, "example": { "error": { "code": "forbidden_scope", "message": "API key is missing required scope: budgets:write", "request_id": "550e8400-e29b-41d4-a716-446655440000" } } } } } } } }, "/v1/explorer/dashboards": { "get": { "tags": [ "Explorer dashboards" ], "summary": "List Explorer dashboards", "operationId": "listExplorerDashboards", "security": [ { "bearerApiKey": [] } ], "parameters": [ { "schema": { "type": "integer", "minimum": 1, "maximum": 200, "description": "Maximum items to return (1–200, default 50)." }, "required": false, "name": "limit", "in": "query" }, { "schema": { "type": "string", "description": "Opaque cursor from a previous response's `pagination.next_cursor`." }, "required": false, "name": "cursor", "in": "query" } ], "responses": { "200": { "description": "List Explorer dashboards", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "array", "items": { "type": "object", "description": "JSON object", "additionalProperties": true } }, "pagination": { "$ref": "#/components/schemas/Pagination" } }, "required": [ "data", "pagination" ] }, "example": { "data": [ { "id": "dashboard-1", "name": "Spend Overview", "scope": "shared", "category": "General", "widgets": [], "dashboardConfig": null, "organizationId": "org-1", "nopsClientId": 42, "creatorId": "user-1", "createdAt": "2026-07-17T12:00:00.000Z", "updatedAt": "2026-07-17T12:00:00.000Z", "creator": { "firstName": "FinOps", "lastName": "Analyst", "email": "finops@example.com" } } ], "pagination": { "limit": 50, "has_more": false, "next_cursor": null } } } } }, "401": { "description": "Unauthorized — invalid or missing API key", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PublicApiError" }, "example": { "error": { "code": "forbidden_scope", "message": "API key is missing required scope: budgets:write", "request_id": "550e8400-e29b-41d4-a716-446655440000" } } } } }, "403": { "description": "Forbidden — insufficient permissions or entitlement", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PublicApiError" }, "example": { "error": { "code": "forbidden_scope", "message": "API key is missing required scope: budgets:write", "request_id": "550e8400-e29b-41d4-a716-446655440000" } } } } } } }, "post": { "tags": [ "Explorer dashboards" ], "summary": "Create Explorer dashboard", "operationId": "createExplorerDashboard", "security": [ { "bearerApiKey": [] } ], "parameters": [ { "schema": { "type": "string", "maxLength": 64, "description": "Unique key for safe retries on write requests (required, max 64 characters)." }, "required": true, "name": "Idempotency-Key", "in": "header" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "name": { "type": "string", "minLength": 1, "maxLength": 200 }, "scope": { "type": "string", "enum": [ "private", "shared", "global" ] }, "category": { "type": "string", "minLength": 1, "maxLength": 100 }, "widgets": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string", "minLength": 1, "maxLength": 64 }, "explorerReportId": { "type": "string", "minLength": 1, "maxLength": 64 }, "name": { "type": "string", "minLength": 1, "maxLength": 200 }, "position": { "type": "integer", "minimum": 0 }, "config": { "type": "object", "properties": { "dateRange": { "type": "object", "properties": { "start": { "type": "string", "pattern": "^\\d{4}-\\d{2}-\\d{2}$" }, "end": { "type": "string", "pattern": "^\\d{4}-\\d{2}-\\d{2}$" } }, "required": [ "start", "end" ] }, "dateRangeMode": { "type": "string", "enum": [ "rolling", "fixed" ] }, "datePreset": { "type": "string", "enum": [ "7D", "14D", "30D", "60D", "1M", "3M", "6M", "1Y", "3Y", "MTD", "YTD", "1Y+MTD", "+0M", "+1M", "+3M", "+6M", "+1Y", "+3Y", "+4Y" ] }, "groupBy": { "type": "string" }, "costType": { "type": "string", "enum": [ "line_item_unblended_cost", "line_item_amortized_cost", "line_item_blended_cost", "pricing_public_on_demand_cost", "nops_line_item_net_unblended_cost", "nops_line_item_net_amortized_cost", "nops_pricing_net_public_on_demand_cost" ] }, "granularity": { "type": "string", "enum": [ "hour", "day", "week", "month", "quarter" ] }, "filters": { "type": "array", "items": { "type": "object", "properties": { "dimension": { "type": "string" }, "mode": { "type": "string", "enum": [ "include", "exclude" ] }, "values": { "type": "array", "items": { "type": "string" } }, "valueModes": { "type": "object", "additionalProperties": { "type": "string", "enum": [ "include", "exclude" ] } }, "texts": { "type": "array", "items": { "type": "object", "properties": { "mode": { "type": "string", "enum": [ "include", "exclude" ] }, "text": { "type": "string", "minLength": 1 } }, "required": [ "mode", "text" ] } }, "textCombinator": { "type": "string", "enum": [ "and", "or" ] }, "keyCombinator": { "type": "string", "enum": [ "and", "or" ] }, "tagKeyOnly": { "type": "boolean" } }, "required": [ "dimension", "mode", "values" ] }, "default": [] }, "tagKeyCombinators": { "type": "object", "additionalProperties": { "type": "string", "enum": [ "and", "or" ] } }, "topN": { "type": "integer", "nullable": true, "minimum": 0, "exclusiveMinimum": true }, "usageChart": { "type": "string", "enum": [ "Hide", "Usage", "Normalized Usage" ], "default": "Hide" }, "widgetChartView": { "type": "string", "enum": [ "all", "spend", "usage" ] }, "widgetTargetChartView": { "type": "string", "enum": [ "all", "spend", "target" ] }, "widgetBusinessUnitChartView": { "type": "string", "enum": [ "all", "spend", "unit" ] }, "page": { "type": "integer", "minimum": 0, "exclusiveMinimum": true }, "pageSize": { "type": "integer", "nullable": true, "minimum": 0, "exclusiveMinimum": true }, "sortColumn": { "type": "string", "enum": [ "name", "total" ] }, "sortDir": { "type": "string", "enum": [ "asc", "desc" ] }, "nameSearch": { "type": "string", "minLength": 1, "maxLength": 200 }, "budgetOverlay": { "type": "object", "nullable": true, "properties": { "budgetId": { "type": "string", "minLength": 1 }, "enabled": { "type": "boolean" } }, "required": [ "budgetId", "enabled" ] }, "bueOverlay": { "type": "object", "nullable": true, "properties": { "economicsId": { "type": "integer", "minimum": 0, "exclusiveMinimum": true }, "enabled": { "type": "boolean" } }, "required": [ "economicsId", "enabled" ] }, "showbackOverlay": { "type": "object", "nullable": true, "properties": { "showbackId": { "type": "integer", "minimum": 0, "exclusiveMinimum": true }, "enabled": { "type": "boolean" }, "dimension": { "type": "string", "nullable": true }, "grouping": { "type": "string", "enum": [ "allocation", "dimension" ] }, "valueFilter": { "type": "object", "nullable": true, "properties": { "mode": { "type": "string", "enum": [ "include", "exclude" ] }, "values": { "type": "array", "items": { "type": "string" } }, "valueModes": { "type": "object", "additionalProperties": { "type": "string", "enum": [ "include", "exclude" ] } } }, "required": [ "mode", "values" ] }, "drilldownGroupBy": { "type": "string", "nullable": true } }, "required": [ "showbackId", "enabled" ] }, "heatmap": { "type": "object", "nullable": true, "properties": { "enabled": { "type": "boolean" }, "xAxis": { "type": "string" }, "yAxis": { "type": "string" } }, "required": [ "enabled", "xAxis", "yAxis" ] }, "forecastHorizon": { "type": "integer", "minimum": 1, "maximum": 365 }, "bypassCache": { "type": "boolean" } } }, "showback": { "type": "integer", "nullable": true, "minimum": 0, "exclusiveMinimum": true } }, "required": [ "id", "explorerReportId", "name", "position" ] }, "maxItems": 50 } }, "required": [ "name", "scope" ] }, "example": { "name": "Spend Overview", "scope": "private" } } } }, "responses": { "201": { "description": "Create Explorer dashboard", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PublicApiError" }, "example": { "data": { "dashboard": { "id": "dashboard-1", "name": "Spend Overview", "scope": "private", "category": "General", "widgets": [] } } } } } }, "401": { "description": "Unauthorized — invalid or missing API key", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PublicApiError" }, "example": { "error": { "code": "forbidden_scope", "message": "API key is missing required scope: budgets:write", "request_id": "550e8400-e29b-41d4-a716-446655440000" } } } } }, "403": { "description": "Forbidden — insufficient permissions or entitlement", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PublicApiError" }, "example": { "error": { "code": "forbidden_scope", "message": "API key is missing required scope: budgets:write", "request_id": "550e8400-e29b-41d4-a716-446655440000" } } } } } } } }, "/v1/explorer/dashboards/{id}": { "get": { "tags": [ "Explorer dashboards" ], "summary": "Get Explorer dashboard", "operationId": "getExplorerDashboard", "security": [ { "bearerApiKey": [] } ], "parameters": [ { "schema": { "type": "string", "description": "Dashboard ID" }, "required": true, "name": "id", "in": "path" } ], "responses": { "200": { "description": "Get Explorer dashboard", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "object", "description": "JSON object", "additionalProperties": true } }, "required": [ "data" ] }, "example": { "data": { "dashboard": { "id": "dashboard-1", "name": "Spend Overview", "scope": "shared", "category": "General", "widgets": [] } } } } } }, "401": { "description": "Unauthorized — invalid or missing API key", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PublicApiError" }, "example": { "error": { "code": "forbidden_scope", "message": "API key is missing required scope: budgets:write", "request_id": "550e8400-e29b-41d4-a716-446655440000" } } } } }, "403": { "description": "Forbidden — insufficient permissions or entitlement", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PublicApiError" }, "example": { "error": { "code": "forbidden_scope", "message": "API key is missing required scope: budgets:write", "request_id": "550e8400-e29b-41d4-a716-446655440000" } } } } } } }, "patch": { "tags": [ "Explorer dashboards" ], "summary": "Update Explorer dashboard", "operationId": "updateExplorerDashboard", "security": [ { "bearerApiKey": [] } ], "parameters": [ { "schema": { "type": "string", "description": "Dashboard ID" }, "required": true, "name": "id", "in": "path" }, { "schema": { "type": "string", "maxLength": 64, "description": "Unique key for safe retries on write requests (required, max 64 characters)." }, "required": true, "name": "Idempotency-Key", "in": "header" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "name": { "type": "string", "minLength": 1, "maxLength": 200 }, "scope": { "type": "string", "enum": [ "private", "shared", "global" ] }, "category": { "type": "string", "minLength": 1, "maxLength": 100 }, "widgets": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string", "minLength": 1, "maxLength": 64 }, "explorerReportId": { "type": "string", "minLength": 1, "maxLength": 64 }, "name": { "type": "string", "minLength": 1, "maxLength": 200 }, "position": { "type": "integer", "minimum": 0 }, "config": { "type": "object", "properties": { "dateRange": { "type": "object", "properties": { "start": { "type": "string", "pattern": "^\\d{4}-\\d{2}-\\d{2}$" }, "end": { "type": "string", "pattern": "^\\d{4}-\\d{2}-\\d{2}$" } }, "required": [ "start", "end" ] }, "dateRangeMode": { "type": "string", "enum": [ "rolling", "fixed" ] }, "datePreset": { "type": "string", "enum": [ "7D", "14D", "30D", "60D", "1M", "3M", "6M", "1Y", "3Y", "MTD", "YTD", "1Y+MTD", "+0M", "+1M", "+3M", "+6M", "+1Y", "+3Y", "+4Y" ] }, "groupBy": { "type": "string" }, "costType": { "type": "string", "enum": [ "line_item_unblended_cost", "line_item_amortized_cost", "line_item_blended_cost", "pricing_public_on_demand_cost", "nops_line_item_net_unblended_cost", "nops_line_item_net_amortized_cost", "nops_pricing_net_public_on_demand_cost" ] }, "granularity": { "type": "string", "enum": [ "hour", "day", "week", "month", "quarter" ] }, "filters": { "type": "array", "items": { "type": "object", "properties": { "dimension": { "type": "string" }, "mode": { "type": "string", "enum": [ "include", "exclude" ] }, "values": { "type": "array", "items": { "type": "string" } }, "valueModes": { "type": "object", "additionalProperties": { "type": "string", "enum": [ "include", "exclude" ] } }, "texts": { "type": "array", "items": { "type": "object", "properties": { "mode": { "type": "string", "enum": [ "include", "exclude" ] }, "text": { "type": "string", "minLength": 1 } }, "required": [ "mode", "text" ] } }, "textCombinator": { "type": "string", "enum": [ "and", "or" ] }, "keyCombinator": { "type": "string", "enum": [ "and", "or" ] }, "tagKeyOnly": { "type": "boolean" } }, "required": [ "dimension", "mode", "values" ] }, "default": [] }, "tagKeyCombinators": { "type": "object", "additionalProperties": { "type": "string", "enum": [ "and", "or" ] } }, "topN": { "type": "integer", "nullable": true, "minimum": 0, "exclusiveMinimum": true }, "usageChart": { "type": "string", "enum": [ "Hide", "Usage", "Normalized Usage" ], "default": "Hide" }, "widgetChartView": { "type": "string", "enum": [ "all", "spend", "usage" ] }, "widgetTargetChartView": { "type": "string", "enum": [ "all", "spend", "target" ] }, "widgetBusinessUnitChartView": { "type": "string", "enum": [ "all", "spend", "unit" ] }, "page": { "type": "integer", "minimum": 0, "exclusiveMinimum": true }, "pageSize": { "type": "integer", "nullable": true, "minimum": 0, "exclusiveMinimum": true }, "sortColumn": { "type": "string", "enum": [ "name", "total" ] }, "sortDir": { "type": "string", "enum": [ "asc", "desc" ] }, "nameSearch": { "type": "string", "minLength": 1, "maxLength": 200 }, "budgetOverlay": { "type": "object", "nullable": true, "properties": { "budgetId": { "type": "string", "minLength": 1 }, "enabled": { "type": "boolean" } }, "required": [ "budgetId", "enabled" ] }, "bueOverlay": { "type": "object", "nullable": true, "properties": { "economicsId": { "type": "integer", "minimum": 0, "exclusiveMinimum": true }, "enabled": { "type": "boolean" } }, "required": [ "economicsId", "enabled" ] }, "showbackOverlay": { "type": "object", "nullable": true, "properties": { "showbackId": { "type": "integer", "minimum": 0, "exclusiveMinimum": true }, "enabled": { "type": "boolean" }, "dimension": { "type": "string", "nullable": true }, "grouping": { "type": "string", "enum": [ "allocation", "dimension" ] }, "valueFilter": { "type": "object", "nullable": true, "properties": { "mode": { "type": "string", "enum": [ "include", "exclude" ] }, "values": { "type": "array", "items": { "type": "string" } }, "valueModes": { "type": "object", "additionalProperties": { "type": "string", "enum": [ "include", "exclude" ] } } }, "required": [ "mode", "values" ] }, "drilldownGroupBy": { "type": "string", "nullable": true } }, "required": [ "showbackId", "enabled" ] }, "heatmap": { "type": "object", "nullable": true, "properties": { "enabled": { "type": "boolean" }, "xAxis": { "type": "string" }, "yAxis": { "type": "string" } }, "required": [ "enabled", "xAxis", "yAxis" ] }, "forecastHorizon": { "type": "integer", "minimum": 1, "maximum": 365 }, "bypassCache": { "type": "boolean" } } }, "showback": { "type": "integer", "nullable": true, "minimum": 0, "exclusiveMinimum": true } }, "required": [ "id", "explorerReportId", "name", "position" ] }, "maxItems": 50 }, "dashboardConfig": { "type": "object", "nullable": true, "properties": { "showback": { "type": "integer", "nullable": true, "minimum": 0, "exclusiveMinimum": true }, "showbackValues": { "type": "array", "nullable": true, "items": { "type": "string", "minLength": 1, "maxLength": 256 }, "maxItems": 200 } }, "required": [ "showback", "showbackValues" ] } } }, "example": { "name": "Spend Overview (updated)" } } } }, "responses": { "200": { "description": "Update Explorer dashboard", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "object", "description": "JSON object", "additionalProperties": true } }, "required": [ "data" ] }, "example": { "data": { "dashboard": { "id": "dashboard-1", "name": "Spend Overview (updated)", "scope": "shared" } } } } } }, "401": { "description": "Unauthorized — invalid or missing API key", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PublicApiError" }, "example": { "error": { "code": "forbidden_scope", "message": "API key is missing required scope: budgets:write", "request_id": "550e8400-e29b-41d4-a716-446655440000" } } } } }, "403": { "description": "Forbidden — insufficient permissions or entitlement", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PublicApiError" }, "example": { "error": { "code": "forbidden_scope", "message": "API key is missing required scope: budgets:write", "request_id": "550e8400-e29b-41d4-a716-446655440000" } } } } } } }, "delete": { "tags": [ "Explorer dashboards" ], "summary": "Delete Explorer dashboard", "operationId": "deleteExplorerDashboard", "security": [ { "bearerApiKey": [] } ], "parameters": [ { "schema": { "type": "string", "description": "Dashboard ID" }, "required": true, "name": "id", "in": "path" } ], "responses": { "200": { "description": "Delete Explorer dashboard", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "object", "description": "JSON object", "additionalProperties": true } }, "required": [ "data" ] }, "example": { "data": { "success": true } } } } }, "401": { "description": "Unauthorized — invalid or missing API key", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PublicApiError" }, "example": { "error": { "code": "forbidden_scope", "message": "API key is missing required scope: budgets:write", "request_id": "550e8400-e29b-41d4-a716-446655440000" } } } } }, "403": { "description": "Forbidden — insufficient permissions or entitlement", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PublicApiError" }, "example": { "error": { "code": "forbidden_scope", "message": "API key is missing required scope: budgets:write", "request_id": "550e8400-e29b-41d4-a716-446655440000" } } } } } } } }, "/v1/explorer/dashboards/{id}/clone": { "post": { "tags": [ "Explorer dashboards" ], "summary": "Clone Explorer dashboard", "operationId": "cloneExplorerDashboard", "security": [ { "bearerApiKey": [] } ], "parameters": [ { "schema": { "type": "string", "description": "Dashboard ID" }, "required": true, "name": "id", "in": "path" }, { "schema": { "type": "string", "maxLength": 64, "description": "Unique key for safe retries on write requests (required, max 64 characters)." }, "required": true, "name": "Idempotency-Key", "in": "header" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "name": { "type": "string", "minLength": 1, "maxLength": 200 }, "scope": { "type": "string", "enum": [ "private", "shared", "global" ] }, "dashboardConfig": { "type": "object", "nullable": true, "properties": { "showback": { "type": "integer", "nullable": true, "minimum": 0, "exclusiveMinimum": true }, "showbackValues": { "type": "array", "nullable": true, "items": { "type": "string", "minLength": 1, "maxLength": 256 }, "maxItems": 200 } }, "required": [ "showback", "showbackValues" ] } } }, "example": { "name": "Spend Overview (Copy)", "scope": "private" } } } }, "responses": { "201": { "description": "Clone Explorer dashboard", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PublicApiError" }, "example": { "data": { "dashboard": { "id": "dashboard-2", "name": "Spend Overview (Copy)", "scope": "private" } } } } } }, "401": { "description": "Unauthorized — invalid or missing API key", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PublicApiError" }, "example": { "error": { "code": "forbidden_scope", "message": "API key is missing required scope: budgets:write", "request_id": "550e8400-e29b-41d4-a716-446655440000" } } } } }, "403": { "description": "Forbidden — insufficient permissions or entitlement", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PublicApiError" }, "example": { "error": { "code": "forbidden_scope", "message": "API key is missing required scope: budgets:write", "request_id": "550e8400-e29b-41d4-a716-446655440000" } } } } } } } }, "/v1/ai-optimization/default-dashboard": { "get": { "tags": [ "AI optimization" ], "summary": "Get AI Optimization default dashboard", "operationId": "getAiOptimizationDefaultDashboard", "security": [ { "bearerApiKey": [] } ], "responses": { "200": { "description": "Get AI Optimization default dashboard", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "object", "description": "JSON object", "additionalProperties": true } }, "required": [ "data" ] }, "example": { "data": { "dashboardId": "dashboard-1", "orgDefaultDashboardId": "dashboard-1", "globalDefaultDashboardId": "global-dashboard-1", "hasOrgOverride": true, "canManageOrgDefault": true, "canManageGlobalDefault": false } } } } }, "401": { "description": "Unauthorized — invalid or missing API key", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PublicApiError" }, "example": { "error": { "code": "forbidden_scope", "message": "API key is missing required scope: budgets:write", "request_id": "550e8400-e29b-41d4-a716-446655440000" } } } } }, "403": { "description": "Forbidden — insufficient permissions or entitlement", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PublicApiError" }, "example": { "error": { "code": "forbidden_scope", "message": "API key is missing required scope: budgets:write", "request_id": "550e8400-e29b-41d4-a716-446655440000" } } } } } } }, "patch": { "tags": [ "AI optimization" ], "summary": "Set organization AI Optimization default dashboard", "description": "Requires an admin-equivalent API key service user.", "operationId": "updateAiOptimizationDefaultDashboard", "security": [ { "bearerApiKey": [] } ], "parameters": [ { "schema": { "type": "string", "maxLength": 64, "description": "Unique key for safe retries on write requests (required, max 64 characters)." }, "required": true, "name": "Idempotency-Key", "in": "header" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "description": "JSON request body", "additionalProperties": true }, "example": { "dashboardId": "dashboard-1" } } } }, "responses": { "200": { "description": "Set organization AI Optimization default dashboard", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "object", "description": "JSON object", "additionalProperties": true } }, "required": [ "data" ] }, "example": { "data": { "orgDefaultDashboardId": "dashboard-1", "dashboardName": "Spend Overview" } } } } }, "401": { "description": "Unauthorized — invalid or missing API key", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PublicApiError" }, "example": { "error": { "code": "forbidden_scope", "message": "API key is missing required scope: budgets:write", "request_id": "550e8400-e29b-41d4-a716-446655440000" } } } } }, "403": { "description": "Forbidden — insufficient permissions or entitlement", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PublicApiError" }, "example": { "error": { "code": "forbidden_scope", "message": "API key is missing required scope: budgets:write", "request_id": "550e8400-e29b-41d4-a716-446655440000" } } } } } } } }, "/v1/ai-optimization/anomalies": { "get": { "tags": [ "AI optimization" ], "summary": "List AI-detected anomalies", "operationId": "listAiOptimizationAnomalies", "security": [ { "bearerApiKey": [] } ], "parameters": [ { "schema": { "type": "integer", "minimum": 1, "maximum": 200, "description": "Maximum items to return (1–200, default 50)." }, "required": false, "name": "limit", "in": "query" }, { "schema": { "type": "string", "description": "Opaque cursor from a previous response's `pagination.next_cursor`." }, "required": false, "name": "cursor", "in": "query" } ], "responses": { "200": { "description": "List AI-detected anomalies", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "array", "items": { "type": "object", "description": "JSON object", "additionalProperties": true } }, "pagination": { "$ref": "#/components/schemas/Pagination" } }, "required": [ "data", "pagination" ] }, "example": { "data": { "processing_time": 12, "anomalies": [ { "anomaly_id": "a1", "service": "Amazon Bedrock", "cost_impact": 420.5, "detected_at": "2026-07-17T12:00:00.000Z" } ], "servedFromCache": false } } } } }, "401": { "description": "Unauthorized — invalid or missing API key", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PublicApiError" }, "example": { "error": { "code": "forbidden_scope", "message": "API key is missing required scope: budgets:write", "request_id": "550e8400-e29b-41d4-a716-446655440000" } } } } }, "403": { "description": "Forbidden — insufficient permissions or entitlement", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PublicApiError" }, "example": { "error": { "code": "forbidden_scope", "message": "API key is missing required scope: budgets:write", "request_id": "550e8400-e29b-41d4-a716-446655440000" } } } } } } } }, "/v1/map-manager": { "get": { "tags": [ "MAP Manager" ], "summary": "List MAP projects", "operationId": "listMapManagerProjects", "security": [ { "bearerApiKey": [] } ], "responses": { "200": { "description": "List MAP projects", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "object", "description": "JSON object", "additionalProperties": true } }, "required": [ "data" ] }, "example": { "data": { "projects": [ { "id": 1, "name": "2026 MAP Migration", "migrationId": "M12345", "totalTaggedSpend": 125000, "benefitsRealized": 8000 } ], "totals": { "mapTaggedSpend": 125000, "totalTaggedSpend": 125000, "benefitsRealized": 8000, "estimatedBenefits": 15000, "creditAchievable": 12000 } } } } } }, "401": { "description": "Unauthorized — invalid or missing API key", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PublicApiError" }, "example": { "error": { "code": "forbidden_scope", "message": "API key is missing required scope: budgets:write", "request_id": "550e8400-e29b-41d4-a716-446655440000" } } } } }, "403": { "description": "Forbidden — insufficient permissions or entitlement", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PublicApiError" }, "example": { "error": { "code": "forbidden_scope", "message": "API key is missing required scope: budgets:write", "request_id": "550e8400-e29b-41d4-a716-446655440000" } } } } } } }, "post": { "tags": [ "MAP Manager" ], "summary": "Create MAP project", "operationId": "createMapManagerProject", "security": [ { "bearerApiKey": [] } ], "parameters": [ { "schema": { "type": "string", "maxLength": 64, "description": "Unique key for safe retries on write requests (required, max 64 characters)." }, "required": true, "name": "Idempotency-Key", "in": "header" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "migrationId": { "type": "string", "minLength": 1 }, "name": { "type": "string", "minLength": 1 }, "tagKey": { "type": "string", "minLength": 1, "default": "map-migrated" }, "tagValue": { "type": "string", "minLength": 1 }, "creditPercent": { "type": "number", "minimum": 0, "maximum": 100 }, "dateStart": { "type": "string", "pattern": "^\\d{4}-\\d{2}-\\d{2}$" }, "dateEnd": { "type": "string", "pattern": "^\\d{4}-\\d{2}-\\d{2}$" }, "mapCreditCap": { "type": "integer", "minimum": 0, "exclusiveMinimum": true }, "targetSpending": { "type": "integer", "minimum": 0, "exclusiveMinimum": true }, "windowsOptimization": { "type": "string", "enum": [ "yes", "no", "not_applicable" ] }, "entities": { "type": "array", "items": { "type": "object", "properties": { "migrationType": { "type": "string" }, "label": { "type": "string" }, "isEnabled": { "type": "boolean" }, "creditPercent": { "type": "number" }, "tagValue": { "type": "string" }, "mapDba": { "type": "string", "nullable": true } }, "required": [ "migrationType", "label", "isEnabled", "creditPercent" ] } }, "extraFilters": { "type": "object", "properties": { "aws_accounts": { "type": "array", "items": { "type": "string", "minLength": 1 } }, "regions": { "type": "array", "items": { "type": "string", "minLength": 1 } }, "aws_managed_services": { "type": "array", "items": { "type": "string", "minLength": 1 } } } } }, "required": [ "migrationId", "name", "tagValue", "creditPercent", "dateStart", "dateEnd", "mapCreditCap", "targetSpending", "windowsOptimization", "entities" ] }, "example": { "name": "2026 MAP Migration", "migrationId": "M12345", "tagKey": "map-migrated", "tagValue": "migrated", "creditPercent": 25, "dateStart": "2026-01-01", "dateEnd": "2026-12-31", "targetSpending": 500000, "mapCreditCap": 100000, "windowsOptimization": false, "entities": [] } } } }, "responses": { "201": { "description": "Create MAP project", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PublicApiError" }, "example": { "data": { "project": { "id": 1, "name": "2026 MAP Migration" } } } } } }, "401": { "description": "Unauthorized — invalid or missing API key", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PublicApiError" }, "example": { "error": { "code": "forbidden_scope", "message": "API key is missing required scope: budgets:write", "request_id": "550e8400-e29b-41d4-a716-446655440000" } } } } }, "403": { "description": "Forbidden — insufficient permissions or entitlement", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PublicApiError" }, "example": { "error": { "code": "forbidden_scope", "message": "API key is missing required scope: budgets:write", "request_id": "550e8400-e29b-41d4-a716-446655440000" } } } } } } } }, "/v1/map-manager/{id}": { "get": { "tags": [ "MAP Manager" ], "summary": "Get MAP project detail", "operationId": "getMapManagerProject", "security": [ { "bearerApiKey": [] } ], "parameters": [ { "schema": { "type": "string", "description": "MAP project ID" }, "required": true, "name": "id", "in": "path" } ], "responses": { "200": { "description": "Get MAP project detail", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "object", "description": "JSON object", "additionalProperties": true } }, "required": [ "data" ] }, "example": { "data": { "detail": { "project": { "id": 1, "name": "2026 MAP Migration" }, "summary": { "benefitsRealized": 8000 } } } } } } }, "401": { "description": "Unauthorized — invalid or missing API key", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PublicApiError" }, "example": { "error": { "code": "forbidden_scope", "message": "API key is missing required scope: budgets:write", "request_id": "550e8400-e29b-41d4-a716-446655440000" } } } } }, "403": { "description": "Forbidden — insufficient permissions or entitlement", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PublicApiError" }, "example": { "error": { "code": "forbidden_scope", "message": "API key is missing required scope: budgets:write", "request_id": "550e8400-e29b-41d4-a716-446655440000" } } } } } } }, "patch": { "tags": [ "MAP Manager" ], "summary": "Update MAP project", "operationId": "updateMapManagerProject", "security": [ { "bearerApiKey": [] } ], "parameters": [ { "schema": { "type": "string", "description": "MAP project ID" }, "required": true, "name": "id", "in": "path" }, { "schema": { "type": "string", "maxLength": 64, "description": "Unique key for safe retries on write requests (required, max 64 characters)." }, "required": true, "name": "Idempotency-Key", "in": "header" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "migrationId": { "type": "string", "minLength": 1 }, "name": { "type": "string", "minLength": 1 }, "tagKey": { "type": "string", "minLength": 1, "default": "map-migrated" }, "tagValue": { "type": "string", "minLength": 1 }, "creditPercent": { "type": "number", "minimum": 0, "maximum": 100 }, "dateStart": { "type": "string", "pattern": "^\\d{4}-\\d{2}-\\d{2}$" }, "dateEnd": { "type": "string", "pattern": "^\\d{4}-\\d{2}-\\d{2}$" }, "mapCreditCap": { "type": "integer", "minimum": 0, "exclusiveMinimum": true }, "targetSpending": { "type": "integer", "minimum": 0, "exclusiveMinimum": true }, "windowsOptimization": { "type": "string", "enum": [ "yes", "no", "not_applicable" ] }, "entities": { "type": "array", "items": { "type": "object", "properties": { "migrationType": { "type": "string" }, "label": { "type": "string" }, "isEnabled": { "type": "boolean" }, "creditPercent": { "type": "number" }, "tagValue": { "type": "string" }, "mapDba": { "type": "string", "nullable": true } }, "required": [ "migrationType", "label", "isEnabled", "creditPercent" ] } }, "extraFilters": { "type": "object", "properties": { "aws_accounts": { "type": "array", "items": { "type": "string", "minLength": 1 } }, "regions": { "type": "array", "items": { "type": "string", "minLength": 1 } }, "aws_managed_services": { "type": "array", "items": { "type": "string", "minLength": 1 } } } } }, "required": [ "migrationId", "name", "tagValue", "creditPercent", "dateStart", "dateEnd", "mapCreditCap", "targetSpending", "windowsOptimization", "entities" ] }, "example": { "name": "2026 MAP Migration (updated)" } } } }, "responses": { "200": { "description": "Update MAP project", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "object", "description": "JSON object", "additionalProperties": true } }, "required": [ "data" ] }, "example": { "data": { "project": { "id": 1, "name": "2026 MAP Migration (updated)" } } } } } }, "401": { "description": "Unauthorized — invalid or missing API key", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PublicApiError" }, "example": { "error": { "code": "forbidden_scope", "message": "API key is missing required scope: budgets:write", "request_id": "550e8400-e29b-41d4-a716-446655440000" } } } } }, "403": { "description": "Forbidden — insufficient permissions or entitlement", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PublicApiError" }, "example": { "error": { "code": "forbidden_scope", "message": "API key is missing required scope: budgets:write", "request_id": "550e8400-e29b-41d4-a716-446655440000" } } } } } } }, "delete": { "tags": [ "MAP Manager" ], "summary": "Delete MAP project", "operationId": "deleteMapManagerProject", "security": [ { "bearerApiKey": [] } ], "parameters": [ { "schema": { "type": "string", "description": "MAP project ID" }, "required": true, "name": "id", "in": "path" } ], "responses": { "200": { "description": "Delete MAP project", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "object", "description": "JSON object", "additionalProperties": true } }, "required": [ "data" ] }, "example": { "data": { "success": true } } } } }, "401": { "description": "Unauthorized — invalid or missing API key", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PublicApiError" }, "example": { "error": { "code": "forbidden_scope", "message": "API key is missing required scope: budgets:write", "request_id": "550e8400-e29b-41d4-a716-446655440000" } } } } }, "403": { "description": "Forbidden — insufficient permissions or entitlement", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PublicApiError" }, "example": { "error": { "code": "forbidden_scope", "message": "API key is missing required scope: budgets:write", "request_id": "550e8400-e29b-41d4-a716-446655440000" } } } } } } } }, "/v1/map-manager/{id}/resources": { "get": { "tags": [ "MAP Manager" ], "summary": "List MAP project resources", "operationId": "listMapManagerProjectResources", "security": [ { "bearerApiKey": [] } ], "parameters": [ { "schema": { "type": "string", "description": "MAP project ID" }, "required": true, "name": "id", "in": "path" } ], "responses": { "200": { "description": "List MAP project resources", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "object", "description": "JSON object", "additionalProperties": true } }, "required": [ "data" ] }, "example": { "data": { "resources": [ { "resourceId": "i-abc123", "accountId": "111122223333", "region": "us-east-1" } ], "fromCache": true } } } } }, "401": { "description": "Unauthorized — invalid or missing API key", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PublicApiError" }, "example": { "error": { "code": "forbidden_scope", "message": "API key is missing required scope: budgets:write", "request_id": "550e8400-e29b-41d4-a716-446655440000" } } } } }, "403": { "description": "Forbidden — insufficient permissions or entitlement", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PublicApiError" }, "example": { "error": { "code": "forbidden_scope", "message": "API key is missing required scope: budgets:write", "request_id": "550e8400-e29b-41d4-a716-446655440000" } } } } } } } }, "/v1/map-manager/accounts": { "get": { "tags": [ "MAP Manager" ], "summary": "List AWS accounts for MAP Manager", "operationId": "listMapManagerAccounts", "security": [ { "bearerApiKey": [] } ], "responses": { "200": { "description": "List AWS accounts for MAP Manager", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "object", "description": "JSON object", "additionalProperties": true } }, "required": [ "data" ] }, "example": { "data": { "accounts": [ { "value": "111122223333", "label": "Production - 111122223333" } ] } } } } }, "401": { "description": "Unauthorized — invalid or missing API key", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PublicApiError" }, "example": { "error": { "code": "forbidden_scope", "message": "API key is missing required scope: budgets:write", "request_id": "550e8400-e29b-41d4-a716-446655440000" } } } } }, "403": { "description": "Forbidden — insufficient permissions or entitlement", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PublicApiError" }, "example": { "error": { "code": "forbidden_scope", "message": "API key is missing required scope: budgets:write", "request_id": "550e8400-e29b-41d4-a716-446655440000" } } } } } } } }, "/v1/business-unit-economics": { "get": { "tags": [ "Business unit economics" ], "summary": "List business unit economics models", "operationId": "listBusinessUnitEconomics", "security": [ { "bearerApiKey": [] } ], "parameters": [ { "schema": { "type": "integer", "minimum": 1, "maximum": 200, "description": "Maximum items to return (1–200, default 50)." }, "required": false, "name": "limit", "in": "query" }, { "schema": { "type": "string", "description": "Opaque cursor from a previous response's `pagination.next_cursor`." }, "required": false, "name": "cursor", "in": "query" } ], "responses": { "200": { "description": "List business unit economics models", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "array", "items": { "type": "object", "description": "JSON object", "additionalProperties": true } }, "pagination": { "$ref": "#/components/schemas/Pagination" } }, "required": [ "data", "pagination" ] }, "example": { "data": { "records": [ { "id": 5, "explorerReportId": "report-1", "explorerReportName": "Spend by Service", "unitId": 3, "unit": "Customers", "startDate": "2026-01-01", "selectedDate": "2026-06-01", "granularity": "month" } ] } } } } }, "401": { "description": "Unauthorized — invalid or missing API key", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PublicApiError" }, "example": { "error": { "code": "forbidden_scope", "message": "API key is missing required scope: budgets:write", "request_id": "550e8400-e29b-41d4-a716-446655440000" } } } } }, "403": { "description": "Forbidden — insufficient permissions or entitlement", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PublicApiError" }, "example": { "error": { "code": "forbidden_scope", "message": "API key is missing required scope: budgets:write", "request_id": "550e8400-e29b-41d4-a716-446655440000" } } } } } } }, "post": { "tags": [ "Business unit economics" ], "summary": "Create business unit economics model", "operationId": "createBusinessUnitEconomics", "security": [ { "bearerApiKey": [] } ], "parameters": [ { "schema": { "type": "string", "maxLength": 64, "description": "Unique key for safe retries on write requests (required, max 64 characters)." }, "required": true, "name": "Idempotency-Key", "in": "header" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "explorerReportId": { "type": "string", "minLength": 1 }, "unitId": { "type": "integer", "minimum": 0, "exclusiveMinimum": true }, "startDate": { "type": "string", "pattern": "^\\d{4}-\\d{2}(-\\d{2})?$" }, "selectedDate": { "type": "string", "pattern": "^\\d{4}-\\d{2}(-\\d{2})?$" }, "granularity": { "type": "string", "minLength": 1, "maxLength": 32 } }, "required": [ "explorerReportId", "unitId", "startDate", "selectedDate" ] }, "example": { "explorerReportId": "report-1", "unitId": 3, "startDate": "2026-01-01", "selectedDate": "2026-06-01" } } } }, "responses": { "201": { "description": "Create business unit economics model", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PublicApiError" }, "example": { "data": { "record": { "id": 5, "unit": "Customers", "explorerReportName": "Spend by Service" }, "items": [] } } } } }, "401": { "description": "Unauthorized — invalid or missing API key", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PublicApiError" }, "example": { "error": { "code": "forbidden_scope", "message": "API key is missing required scope: budgets:write", "request_id": "550e8400-e29b-41d4-a716-446655440000" } } } } }, "403": { "description": "Forbidden — insufficient permissions or entitlement", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PublicApiError" }, "example": { "error": { "code": "forbidden_scope", "message": "API key is missing required scope: budgets:write", "request_id": "550e8400-e29b-41d4-a716-446655440000" } } } } } } } }, "/v1/business-unit-economics/{id}": { "get": { "tags": [ "Business unit economics" ], "summary": "Get business unit economics model", "operationId": "getBusinessUnitEconomics", "security": [ { "bearerApiKey": [] } ], "parameters": [ { "schema": { "type": "string", "description": "Business unit economics ID" }, "required": true, "name": "id", "in": "path" } ], "responses": { "200": { "description": "Get business unit economics model", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "object", "description": "JSON object", "additionalProperties": true } }, "required": [ "data" ] }, "example": { "data": { "record": { "id": 5, "unit": "Customers", "explorerReportName": "Spend by Service" }, "items": [] } } } } }, "401": { "description": "Unauthorized — invalid or missing API key", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PublicApiError" }, "example": { "error": { "code": "forbidden_scope", "message": "API key is missing required scope: budgets:write", "request_id": "550e8400-e29b-41d4-a716-446655440000" } } } } }, "403": { "description": "Forbidden — insufficient permissions or entitlement", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PublicApiError" }, "example": { "error": { "code": "forbidden_scope", "message": "API key is missing required scope: budgets:write", "request_id": "550e8400-e29b-41d4-a716-446655440000" } } } } } } }, "patch": { "tags": [ "Business unit economics" ], "summary": "Update business unit economics model", "operationId": "updateBusinessUnitEconomics", "security": [ { "bearerApiKey": [] } ], "parameters": [ { "schema": { "type": "string", "description": "Business unit economics ID" }, "required": true, "name": "id", "in": "path" }, { "schema": { "type": "string", "maxLength": 64, "description": "Unique key for safe retries on write requests (required, max 64 characters)." }, "required": true, "name": "Idempotency-Key", "in": "header" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "explorerReportId": { "type": "string", "minLength": 1 }, "unitId": { "type": "integer", "minimum": 0, "exclusiveMinimum": true }, "startDate": { "type": "string", "pattern": "^\\d{4}-\\d{2}(-\\d{2})?$" }, "selectedDate": { "type": "string", "pattern": "^\\d{4}-\\d{2}(-\\d{2})?$" }, "granularity": { "type": "string", "minLength": 1, "maxLength": 32 } } }, "example": { "selectedDate": "2026-07-01" } } } }, "responses": { "200": { "description": "Update business unit economics model", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "object", "description": "JSON object", "additionalProperties": true } }, "required": [ "data" ] }, "example": { "data": { "record": { "id": 5, "unit": "Customers", "selectedDate": "2026-07-01" }, "items": [] } } } } }, "401": { "description": "Unauthorized — invalid or missing API key", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PublicApiError" }, "example": { "error": { "code": "forbidden_scope", "message": "API key is missing required scope: budgets:write", "request_id": "550e8400-e29b-41d4-a716-446655440000" } } } } }, "403": { "description": "Forbidden — insufficient permissions or entitlement", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PublicApiError" }, "example": { "error": { "code": "forbidden_scope", "message": "API key is missing required scope: budgets:write", "request_id": "550e8400-e29b-41d4-a716-446655440000" } } } } } } }, "delete": { "tags": [ "Business unit economics" ], "summary": "Delete business unit economics model", "operationId": "deleteBusinessUnitEconomics", "security": [ { "bearerApiKey": [] } ], "parameters": [ { "schema": { "type": "string", "description": "Business unit economics ID" }, "required": true, "name": "id", "in": "path" } ], "responses": { "200": { "description": "Delete business unit economics model", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "object", "description": "JSON object", "additionalProperties": true } }, "required": [ "data" ] }, "example": { "data": { "success": true } } } } }, "401": { "description": "Unauthorized — invalid or missing API key", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PublicApiError" }, "example": { "error": { "code": "forbidden_scope", "message": "API key is missing required scope: budgets:write", "request_id": "550e8400-e29b-41d4-a716-446655440000" } } } } }, "403": { "description": "Forbidden — insufficient permissions or entitlement", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PublicApiError" }, "example": { "error": { "code": "forbidden_scope", "message": "API key is missing required scope: budgets:write", "request_id": "550e8400-e29b-41d4-a716-446655440000" } } } } } } } }, "/v1/business-unit-economics/{id}/items": { "get": { "tags": [ "Business unit economics" ], "summary": "List business unit economics items", "operationId": "listBusinessUnitEconomicsItems", "security": [ { "bearerApiKey": [] } ], "parameters": [ { "schema": { "type": "string", "description": "Business unit economics ID" }, "required": true, "name": "id", "in": "path" }, { "schema": { "type": "integer", "minimum": 1, "maximum": 200, "description": "Maximum items to return (1–200, default 50)." }, "required": false, "name": "limit", "in": "query" }, { "schema": { "type": "string", "description": "Opaque cursor from a previous response's `pagination.next_cursor`." }, "required": false, "name": "cursor", "in": "query" } ], "responses": { "200": { "description": "List business unit economics items", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "array", "items": { "type": "object", "description": "JSON object", "additionalProperties": true } }, "pagination": { "$ref": "#/components/schemas/Pagination" } }, "required": [ "data", "pagination" ] }, "example": { "data": [ { "segmentValue": "Production", "date": "2026-06-01", "units": 1200 } ], "pagination": { "limit": 50, "has_more": false, "next_cursor": null } } } } }, "401": { "description": "Unauthorized — invalid or missing API key", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PublicApiError" }, "example": { "error": { "code": "forbidden_scope", "message": "API key is missing required scope: budgets:write", "request_id": "550e8400-e29b-41d4-a716-446655440000" } } } } }, "403": { "description": "Forbidden — insufficient permissions or entitlement", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PublicApiError" }, "example": { "error": { "code": "forbidden_scope", "message": "API key is missing required scope: budgets:write", "request_id": "550e8400-e29b-41d4-a716-446655440000" } } } } } } }, "post": { "tags": [ "Business unit economics" ], "summary": "Upsert business unit economics items", "operationId": "upsertBusinessUnitEconomicsItems", "security": [ { "bearerApiKey": [] } ], "parameters": [ { "schema": { "type": "string", "description": "Business unit economics ID" }, "required": true, "name": "id", "in": "path" }, { "schema": { "type": "string", "maxLength": 64, "description": "Unique key for safe retries on write requests (required, max 64 characters)." }, "required": true, "name": "Idempotency-Key", "in": "header" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "items": { "type": "array", "items": { "type": "object", "properties": { "segmentValue": { "type": "string", "maxLength": 256 }, "date": { "type": "string", "pattern": "^\\d{4}-\\d{2}(-\\d{2})?$" }, "units": { "type": "number", "minimum": 0 } }, "required": [ "segmentValue", "date", "units" ] }, "minItems": 1 } }, "required": [ "items" ] }, "example": { "items": [ { "segmentValue": "Production", "date": "2026-06-01", "units": 1200 } ] } } } }, "responses": { "200": { "description": "Upsert business unit economics items", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "object", "description": "JSON object", "additionalProperties": true } }, "required": [ "data" ] }, "example": { "data": { "record": { "id": 5, "unit": "Customers" }, "items": [ { "segmentValue": "Production", "date": "2026-06-01", "units": 1200 } ] } } } } }, "401": { "description": "Unauthorized — invalid or missing API key", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PublicApiError" }, "example": { "error": { "code": "forbidden_scope", "message": "API key is missing required scope: budgets:write", "request_id": "550e8400-e29b-41d4-a716-446655440000" } } } } }, "403": { "description": "Forbidden — insufficient permissions or entitlement", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PublicApiError" }, "example": { "error": { "code": "forbidden_scope", "message": "API key is missing required scope: budgets:write", "request_id": "550e8400-e29b-41d4-a716-446655440000" } } } } } } } }, "/v1/business-unit-economics/{id}/send": { "post": { "tags": [ "Business unit economics" ], "summary": "Send business unit economics report", "operationId": "sendBusinessUnitEconomicsReport", "security": [ { "bearerApiKey": [] } ], "parameters": [ { "schema": { "type": "string", "description": "Business unit economics ID" }, "required": true, "name": "id", "in": "path" }, { "schema": { "type": "string", "maxLength": 64, "description": "Unique key for safe retries on write requests (required, max 64 characters)." }, "required": true, "name": "Idempotency-Key", "in": "header" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "recipients": { "type": "array", "items": { "type": "string", "format": "email" } }, "channels": { "type": "array", "items": { "type": "object", "properties": { "provider": { "type": "string", "enum": [ "slack", "teams" ] }, "channelId": { "type": "string", "minLength": 1 }, "channelName": { "type": "string" }, "teamId": { "type": "string" } }, "required": [ "provider", "channelId" ] } }, "subject": { "type": "string", "maxLength": 200 }, "body": { "type": "string", "maxLength": 5000 } } }, "example": { "recipients": [ "finops@example.com" ], "subject": "Customers · Spend by Service" } } } }, "responses": { "202": { "description": "Send business unit economics report", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PublicApiError" }, "example": { "data": { "notificationIds": [ "notif-1" ], "scheduledAt": "2026-07-17T12:00:00.000Z", "deliveredInline": true, "enqueueFailures": 0 } } } } }, "401": { "description": "Unauthorized — invalid or missing API key", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PublicApiError" }, "example": { "error": { "code": "forbidden_scope", "message": "API key is missing required scope: budgets:write", "request_id": "550e8400-e29b-41d4-a716-446655440000" } } } } }, "403": { "description": "Forbidden — insufficient permissions or entitlement", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PublicApiError" }, "example": { "error": { "code": "forbidden_scope", "message": "API key is missing required scope: budgets:write", "request_id": "550e8400-e29b-41d4-a716-446655440000" } } } } } } } }, "/v1/business-unit-economics/units": { "get": { "tags": [ "Business unit economics" ], "summary": "List business units", "operationId": "listBusinessUnitEconomicsUnits", "security": [ { "bearerApiKey": [] } ], "parameters": [ { "schema": { "type": "integer", "minimum": 1, "maximum": 200, "description": "Maximum items to return (1–200, default 50)." }, "required": false, "name": "limit", "in": "query" }, { "schema": { "type": "string", "description": "Opaque cursor from a previous response's `pagination.next_cursor`." }, "required": false, "name": "cursor", "in": "query" } ], "responses": { "200": { "description": "List business units", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "array", "items": { "type": "object", "description": "JSON object", "additionalProperties": true } }, "pagination": { "$ref": "#/components/schemas/Pagination" } }, "required": [ "data", "pagination" ] }, "example": { "data": { "units": [ { "id": 3, "name": "Customers", "economicsCount": 1 } ] } } } } }, "401": { "description": "Unauthorized — invalid or missing API key", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PublicApiError" }, "example": { "error": { "code": "forbidden_scope", "message": "API key is missing required scope: budgets:write", "request_id": "550e8400-e29b-41d4-a716-446655440000" } } } } }, "403": { "description": "Forbidden — insufficient permissions or entitlement", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PublicApiError" }, "example": { "error": { "code": "forbidden_scope", "message": "API key is missing required scope: budgets:write", "request_id": "550e8400-e29b-41d4-a716-446655440000" } } } } } } }, "post": { "tags": [ "Business unit economics" ], "summary": "Create business unit", "operationId": "createBusinessUnitEconomicsUnit", "security": [ { "bearerApiKey": [] } ], "parameters": [ { "schema": { "type": "string", "maxLength": 64, "description": "Unique key for safe retries on write requests (required, max 64 characters)." }, "required": true, "name": "Idempotency-Key", "in": "header" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "name": { "type": "string", "minLength": 1, "maxLength": 256 } }, "required": [ "name" ] }, "example": { "name": "Customers" } } } }, "responses": { "201": { "description": "Create business unit", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PublicApiError" }, "example": { "data": { "unit": { "id": 3, "name": "Customers", "economicsCount": 0 } } } } } }, "401": { "description": "Unauthorized — invalid or missing API key", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PublicApiError" }, "example": { "error": { "code": "forbidden_scope", "message": "API key is missing required scope: budgets:write", "request_id": "550e8400-e29b-41d4-a716-446655440000" } } } } }, "403": { "description": "Forbidden — insufficient permissions or entitlement", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PublicApiError" }, "example": { "error": { "code": "forbidden_scope", "message": "API key is missing required scope: budgets:write", "request_id": "550e8400-e29b-41d4-a716-446655440000" } } } } } } } }, "/v1/business-unit-economics/units/{id}": { "patch": { "tags": [ "Business unit economics" ], "summary": "Update business unit", "operationId": "updateBusinessUnitEconomicsUnit", "security": [ { "bearerApiKey": [] } ], "parameters": [ { "schema": { "type": "string", "description": "Business unit ID" }, "required": true, "name": "id", "in": "path" }, { "schema": { "type": "string", "maxLength": 64, "description": "Unique key for safe retries on write requests (required, max 64 characters)." }, "required": true, "name": "Idempotency-Key", "in": "header" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "name": { "type": "string", "minLength": 1, "maxLength": 256 } }, "required": [ "name" ] }, "example": { "name": "Enterprise Customers" } } } }, "responses": { "200": { "description": "Update business unit", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "object", "description": "JSON object", "additionalProperties": true } }, "required": [ "data" ] }, "example": { "data": { "unit": { "id": 3, "name": "Enterprise Customers", "economicsCount": 1 } } } } } }, "401": { "description": "Unauthorized — invalid or missing API key", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PublicApiError" }, "example": { "error": { "code": "forbidden_scope", "message": "API key is missing required scope: budgets:write", "request_id": "550e8400-e29b-41d4-a716-446655440000" } } } } }, "403": { "description": "Forbidden — insufficient permissions or entitlement", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PublicApiError" }, "example": { "error": { "code": "forbidden_scope", "message": "API key is missing required scope: budgets:write", "request_id": "550e8400-e29b-41d4-a716-446655440000" } } } } } } }, "delete": { "tags": [ "Business unit economics" ], "summary": "Delete business unit", "operationId": "deleteBusinessUnitEconomicsUnit", "security": [ { "bearerApiKey": [] } ], "parameters": [ { "schema": { "type": "string", "description": "Business unit ID" }, "required": true, "name": "id", "in": "path" } ], "responses": { "200": { "description": "Delete business unit", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "object", "description": "JSON object", "additionalProperties": true } }, "required": [ "data" ] }, "example": { "data": { "success": true } } } } }, "401": { "description": "Unauthorized — invalid or missing API key", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PublicApiError" }, "example": { "error": { "code": "forbidden_scope", "message": "API key is missing required scope: budgets:write", "request_id": "550e8400-e29b-41d4-a716-446655440000" } } } } }, "403": { "description": "Forbidden — insufficient permissions or entitlement", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PublicApiError" }, "example": { "error": { "code": "forbidden_scope", "message": "API key is missing required scope: budgets:write", "request_id": "550e8400-e29b-41d4-a716-446655440000" } } } } } } } }, "/v1/business-unit-economics/spend-preview": { "get": { "tags": [ "Business unit economics" ], "summary": "Preview business unit economics spend", "description": "Query params: explorerReportId (required), startDate, endDate (YYYY-MM-DD).", "operationId": "getBusinessUnitEconomicsSpendPreview", "security": [ { "bearerApiKey": [] } ], "responses": { "200": { "description": "Preview business unit economics spend", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "object", "description": "JSON object", "additionalProperties": true } }, "required": [ "data" ] }, "example": { "data": { "totalSpend": 42100.88, "months": [ { "date": "2026-06-01", "spend": 12400.5 } ] } } } } }, "401": { "description": "Unauthorized — invalid or missing API key", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PublicApiError" }, "example": { "error": { "code": "forbidden_scope", "message": "API key is missing required scope: budgets:write", "request_id": "550e8400-e29b-41d4-a716-446655440000" } } } } }, "403": { "description": "Forbidden — insufficient permissions or entitlement", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PublicApiError" }, "example": { "error": { "code": "forbidden_scope", "message": "API key is missing required scope: budgets:write", "request_id": "550e8400-e29b-41d4-a716-446655440000" } } } } } } } }, "/v1/business-unit-economics/summaries": { "get": { "tags": [ "Business unit economics" ], "summary": "Portfolio summaries for business unit economics", "operationId": "getBusinessUnitEconomicsSummaries", "security": [ { "bearerApiKey": [] } ], "responses": { "200": { "description": "Portfolio summaries for business unit economics", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "object", "description": "JSON object", "additionalProperties": true } }, "required": [ "data" ] }, "example": { "data": { "summaries": [ { "economicsId": 5, "unit": "Customers", "totalSpend": 42100.88 } ] } } } } }, "401": { "description": "Unauthorized — invalid or missing API key", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PublicApiError" }, "example": { "error": { "code": "forbidden_scope", "message": "API key is missing required scope: budgets:write", "request_id": "550e8400-e29b-41d4-a716-446655440000" } } } } }, "403": { "description": "Forbidden — insufficient permissions or entitlement", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PublicApiError" }, "example": { "error": { "code": "forbidden_scope", "message": "API key is missing required scope: budgets:write", "request_id": "550e8400-e29b-41d4-a716-446655440000" } } } } } } } }, "/v1/contract-tracker": { "get": { "tags": [ "Contract tracker" ], "summary": "List contracts", "operationId": "listContractTrackerContracts", "security": [ { "bearerApiKey": [] } ], "parameters": [ { "schema": { "type": "integer", "minimum": 1, "maximum": 200, "description": "Maximum items to return (1–200, default 50)." }, "required": false, "name": "limit", "in": "query" }, { "schema": { "type": "string", "description": "Opaque cursor from a previous response's `pagination.next_cursor`." }, "required": false, "name": "cursor", "in": "query" } ], "responses": { "200": { "description": "List contracts", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "array", "items": { "type": "object", "description": "JSON object", "additionalProperties": true } }, "pagination": { "$ref": "#/components/schemas/Pagination" } }, "required": [ "data", "pagination" ] }, "example": { "data": { "contracts": [ { "id": "contract-1", "name": "AWS Enterprise Discount", "service": "Amazon EC2", "startDate": "2025-01-01", "endDate": "2027-12-31" } ] } } } } }, "401": { "description": "Unauthorized — invalid or missing API key", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PublicApiError" }, "example": { "error": { "code": "forbidden_scope", "message": "API key is missing required scope: budgets:write", "request_id": "550e8400-e29b-41d4-a716-446655440000" } } } } }, "403": { "description": "Forbidden — insufficient permissions or entitlement", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PublicApiError" }, "example": { "error": { "code": "forbidden_scope", "message": "API key is missing required scope: budgets:write", "request_id": "550e8400-e29b-41d4-a716-446655440000" } } } } } } }, "post": { "tags": [ "Contract tracker" ], "summary": "Create contract", "operationId": "createContractTrackerContract", "security": [ { "bearerApiKey": [] } ], "parameters": [ { "schema": { "type": "string", "maxLength": 64, "description": "Unique key for safe retries on write requests (required, max 64 characters)." }, "required": true, "name": "Idempotency-Key", "in": "header" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "name": { "type": "string", "minLength": 1, "maxLength": 255 }, "service": { "type": "string", "nullable": true }, "costEntityName": { "type": "string", "nullable": true }, "startDate": { "type": "string", "pattern": "^\\d{4}-\\d{2}-\\d{2}$" }, "endDate": { "type": "string", "pattern": "^\\d{4}-\\d{2}-\\d{2}$" }, "yearlySpend": { "type": "object", "additionalProperties": { "type": "number", "nullable": true, "minimum": 0 } }, "yearlyUsage": { "type": "object", "nullable": true, "additionalProperties": { "type": "number", "nullable": true, "minimum": 0 } }, "commitmentPeriod": { "type": "string", "enum": [ "MONTHLY", "QUARTERLY", "ANNUALLY" ], "default": "ANNUALLY" }, "discountPercentage": { "type": "number", "nullable": true, "minimum": 0, "maximum": 100, "default": 25 }, "marketplacePercentage": { "type": "number", "nullable": true, "minimum": 0, "maximum": 100, "default": 0 }, "isCrossService": { "type": "boolean", "default": false }, "isUsageBased": { "type": "boolean", "default": false }, "costUnit": { "type": "string", "nullable": true }, "selectedAwsServices": { "type": "array", "items": { "type": "string" }, "default": [] }, "selectedCostEntities": { "type": "array", "items": { "type": "string" }, "default": [] }, "selectedBillingEntities": { "type": "array", "items": { "type": "string" }, "default": [] }, "selectedMarketplaceEntities": { "type": "array", "items": { "type": "string" }, "default": [] } }, "required": [ "name", "startDate", "endDate", "yearlySpend" ] }, "example": { "name": "AWS Enterprise Discount", "service": "Amazon EC2", "startDate": "2025-01-01", "endDate": "2027-12-31", "yearlySpend": { "2025": 1000000 }, "discountPercentage": 10, "marketplacePercentage": 0, "isCrossService": false, "isUsageBased": false } } } }, "responses": { "201": { "description": "Create contract", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PublicApiError" }, "example": { "data": { "contract": { "id": "contract-1", "name": "AWS Enterprise Discount" } } } } } }, "401": { "description": "Unauthorized — invalid or missing API key", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PublicApiError" }, "example": { "error": { "code": "forbidden_scope", "message": "API key is missing required scope: budgets:write", "request_id": "550e8400-e29b-41d4-a716-446655440000" } } } } }, "403": { "description": "Forbidden — insufficient permissions or entitlement", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PublicApiError" }, "example": { "error": { "code": "forbidden_scope", "message": "API key is missing required scope: budgets:write", "request_id": "550e8400-e29b-41d4-a716-446655440000" } } } } } } } }, "/v1/contract-tracker/{id}": { "get": { "tags": [ "Contract tracker" ], "summary": "Get contract", "operationId": "getContractTrackerContract", "security": [ { "bearerApiKey": [] } ], "parameters": [ { "schema": { "type": "string", "description": "Contract ID" }, "required": true, "name": "id", "in": "path" } ], "responses": { "200": { "description": "Get contract", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "object", "description": "JSON object", "additionalProperties": true } }, "required": [ "data" ] }, "example": { "data": { "contract": { "id": "contract-1", "name": "AWS Enterprise Discount", "service": "Amazon EC2" } } } } } }, "401": { "description": "Unauthorized — invalid or missing API key", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PublicApiError" }, "example": { "error": { "code": "forbidden_scope", "message": "API key is missing required scope: budgets:write", "request_id": "550e8400-e29b-41d4-a716-446655440000" } } } } }, "403": { "description": "Forbidden — insufficient permissions or entitlement", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PublicApiError" }, "example": { "error": { "code": "forbidden_scope", "message": "API key is missing required scope: budgets:write", "request_id": "550e8400-e29b-41d4-a716-446655440000" } } } } } } }, "patch": { "tags": [ "Contract tracker" ], "summary": "Update contract", "operationId": "updateContractTrackerContract", "security": [ { "bearerApiKey": [] } ], "parameters": [ { "schema": { "type": "string", "description": "Contract ID" }, "required": true, "name": "id", "in": "path" }, { "schema": { "type": "string", "maxLength": 64, "description": "Unique key for safe retries on write requests (required, max 64 characters)." }, "required": true, "name": "Idempotency-Key", "in": "header" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "name": { "type": "string", "minLength": 1, "maxLength": 255 }, "service": { "type": "string", "nullable": true }, "costEntityName": { "type": "string", "nullable": true }, "startDate": { "type": "string", "pattern": "^\\d{4}-\\d{2}-\\d{2}$" }, "endDate": { "type": "string", "pattern": "^\\d{4}-\\d{2}-\\d{2}$" }, "yearlySpend": { "type": "object", "additionalProperties": { "type": "number", "nullable": true, "minimum": 0 } }, "yearlyUsage": { "type": "object", "nullable": true, "additionalProperties": { "type": "number", "nullable": true, "minimum": 0 } }, "commitmentPeriod": { "type": "string", "enum": [ "MONTHLY", "QUARTERLY", "ANNUALLY" ], "default": "ANNUALLY" }, "discountPercentage": { "type": "number", "nullable": true, "minimum": 0, "maximum": 100, "default": 25 }, "marketplacePercentage": { "type": "number", "nullable": true, "minimum": 0, "maximum": 100, "default": 0 }, "isCrossService": { "type": "boolean", "default": false }, "isUsageBased": { "type": "boolean", "default": false }, "costUnit": { "type": "string", "nullable": true }, "selectedAwsServices": { "type": "array", "items": { "type": "string" }, "default": [] }, "selectedCostEntities": { "type": "array", "items": { "type": "string" }, "default": [] }, "selectedBillingEntities": { "type": "array", "items": { "type": "string" }, "default": [] }, "selectedMarketplaceEntities": { "type": "array", "items": { "type": "string" }, "default": [] } } }, "example": { "name": "AWS Enterprise Discount (updated)" } } } }, "responses": { "200": { "description": "Update contract", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "object", "description": "JSON object", "additionalProperties": true } }, "required": [ "data" ] }, "example": { "data": { "contract": { "id": "contract-1", "name": "AWS Enterprise Discount (updated)" } } } } } }, "401": { "description": "Unauthorized — invalid or missing API key", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PublicApiError" }, "example": { "error": { "code": "forbidden_scope", "message": "API key is missing required scope: budgets:write", "request_id": "550e8400-e29b-41d4-a716-446655440000" } } } } }, "403": { "description": "Forbidden — insufficient permissions or entitlement", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PublicApiError" }, "example": { "error": { "code": "forbidden_scope", "message": "API key is missing required scope: budgets:write", "request_id": "550e8400-e29b-41d4-a716-446655440000" } } } } } } }, "delete": { "tags": [ "Contract tracker" ], "summary": "Delete contract", "operationId": "deleteContractTrackerContract", "security": [ { "bearerApiKey": [] } ], "parameters": [ { "schema": { "type": "string", "description": "Contract ID" }, "required": true, "name": "id", "in": "path" } ], "responses": { "200": { "description": "Delete contract", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "object", "description": "JSON object", "additionalProperties": true } }, "required": [ "data" ] }, "example": { "data": { "success": true } } } } }, "401": { "description": "Unauthorized — invalid or missing API key", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PublicApiError" }, "example": { "error": { "code": "forbidden_scope", "message": "API key is missing required scope: budgets:write", "request_id": "550e8400-e29b-41d4-a716-446655440000" } } } } }, "403": { "description": "Forbidden — insufficient permissions or entitlement", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PublicApiError" }, "example": { "error": { "code": "forbidden_scope", "message": "API key is missing required scope: budgets:write", "request_id": "550e8400-e29b-41d4-a716-446655440000" } } } } } } } }, "/v1/contract-tracker/{id}/burndown": { "get": { "tags": [ "Contract tracker" ], "summary": "Get contract burndown", "operationId": "getContractTrackerBurndown", "security": [ { "bearerApiKey": [] } ], "parameters": [ { "schema": { "type": "string", "description": "Contract ID" }, "required": true, "name": "id", "in": "path" } ], "responses": { "200": { "description": "Get contract burndown", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "object", "description": "JSON object", "additionalProperties": true } }, "required": [ "data" ] }, "example": { "data": { "data": { "Amazon EC2": { "granular": { "2025-01-01": 1000 }, "total": 1000 } }, "forecastMonths": [] } } } } }, "401": { "description": "Unauthorized — invalid or missing API key", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PublicApiError" }, "example": { "error": { "code": "forbidden_scope", "message": "API key is missing required scope: budgets:write", "request_id": "550e8400-e29b-41d4-a716-446655440000" } } } } }, "403": { "description": "Forbidden — insufficient permissions or entitlement", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PublicApiError" }, "example": { "error": { "code": "forbidden_scope", "message": "API key is missing required scope: budgets:write", "request_id": "550e8400-e29b-41d4-a716-446655440000" } } } } } } } } } }