{ "info": { "description": "### Welcome to the Archera.ai Beta API documentation.\n\n> **\u26a0 EXPERIMENTAL \u2014 USE WITH CAUTION**\n>\n> This API surface is **experimental** and subject to change at any time:\n>\n> * **No uptime SLA** \u2014 availability is not guaranteed.\n> * **Breaking changes may occur** without a major version bump.\n> * **Endpoints may be removed** with approximately 1-2 weeks' notice.\n> * **Not recommended for production workflows.**\n\nThis API provides early access to new features and endpoints under active development. All responses include the `X-API-Stability: experimental` header.\n\n## API Key Access\n\nTo use this API, you need an API key. Use the `x-api-key` header:\n\n```bash\ncurl -H 'x-api-key: YOUR_API_KEY' https://api.archera.ai/beta/v1/...\n```\n\n## Units Convention\n\nHow to interpret monetary values in responses:\n\n- **Per-commitment / per-plan endpoints** (e.g. `/commitments`, `/commitment-plans`, `/commitments/summary`, `/metrics/overview`): monetary fields are **monthly rates** based on a 730-hour month (8760 hours / 12 months \u2014 an annual-average month, NOT a calendar month, which varies 672-744 hours). A field labeled \"monthly\" reflects a per-730-hour figure, not a specific calendar month's total.\n- **Aggregated metrics / time-series endpoints** (e.g. `/metrics/daily-savings`, `/metrics/daily-reservable-cost`, `/commitments/metrics`): top-level monetary fields are **sums over the requested date range**, and values in `daily` rows are **sums for that day**. Neither is a monthly rate; magnitude scales with range length.\n- **`commitment_upfront_cost`** (top-level on individual commitments, plans, and plan line items \u2014 a sibling of `commitment_financials_monthly_rate`): **one-time total dollars** paid at signing \u2014 not a rate. Do not sum with monthly-rate fields. Omitted on aggregates (summary, metrics, invoices) where a summed upfront is not meaningful.\n", "title": "Archera.ai Beta API", "version": "v1.0.0" }, "paths": { "/beta/v1/org/{org_id}/reports/partner_archera_premiums_and_rebates_by_child_org": { "get": { "parameters": [ { "in": "query", "name": "format", "description": "Response format: 'json' (default) or 'csv'", "schema": { "type": "string", "default": "json", "enum": [ "json", "csv" ] }, "required": false }, { "in": "query", "name": "year", "description": "Billing year (e.g. 2026)", "schema": { "type": "integer" }, "required": true }, { "in": "query", "name": "month", "description": "Billing month (1-12)", "schema": { "type": "integer", "minimum": 1, "maximum": 12 }, "required": true } ], "responses": { "422": { "$ref": "#/components/responses/UNPROCESSABLE_CONTENT" }, "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "array", "items": { "$ref": "#/components/schemas/PartnerArcheraPremiumsAndRebatesByChildOrgOutput" } } } } }, "default": { "$ref": "#/components/responses/DEFAULT_ERROR" }, "400": { "description": "Bad request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorResponse" } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorResponse" } } } }, "403": { "description": "Forbidden", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorResponse" } } } }, "404": { "description": "Not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorResponse" } } } }, "409": { "description": "Conflict", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorResponse" } } } }, "405": { "description": "Method not allowed", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorResponse" } } } }, "500": { "description": "Internal server error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorResponse" } } } } }, "tags": [ "reports" ], "summary": "Partner Archera Premiums and Rebates by Organization", "description": "Monthly allocation of Archera premiums, rebates, and savings across child organizations for a channel partner. One row per child org with that org's invoice totals." }, "parameters": [ { "in": "path", "name": "org_id", "required": true, "schema": { "type": "string", "format": "uuid" } } ] }, "/beta/v1/org/{org_id}/reports/archera_premiums_and_rebates_by_account": { "get": { "parameters": [ { "in": "query", "name": "format", "description": "Response format: 'json' (default) or 'csv'", "schema": { "type": "string", "default": "json", "enum": [ "json", "csv" ] }, "required": false }, { "in": "query", "name": "year", "description": "Billing year (e.g. 2026)", "schema": { "type": "integer" }, "required": true }, { "in": "query", "name": "month", "description": "Billing month (1-12)", "schema": { "type": "integer", "minimum": 1, "maximum": 12 }, "required": true }, { "in": "query", "name": "provider", "description": "Cloud provider (aws, azure, gcp, kubernetes, unknown)", "schema": { "type": "string", "enum": [ "aws", "azure", "gcp", "kubernetes", "unknown" ] }, "required": true } ], "responses": { "422": { "$ref": "#/components/responses/UNPROCESSABLE_CONTENT" }, "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "array", "items": { "$ref": "#/components/schemas/ArcheraPremiumsAndRebatesByAccountOutput" } } } } }, "default": { "$ref": "#/components/responses/DEFAULT_ERROR" }, "400": { "description": "Bad request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorResponse" } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorResponse" } } } }, "403": { "description": "Forbidden", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorResponse" } } } }, "404": { "description": "Not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorResponse" } } } }, "409": { "description": "Conflict", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorResponse" } } } }, "405": { "description": "Method not allowed", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorResponse" } } } }, "500": { "description": "Internal server error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorResponse" } } } } }, "tags": [ "reports" ], "summary": "Archera Premiums and Rebates by Account", "description": "Monthly allocation of Archera premiums, rebates, and savings by cloud account." }, "parameters": [ { "in": "path", "name": "org_id", "required": true, "schema": { "type": "string", "format": "uuid" } } ] }, "/beta/v1/org/{org_id}/reports/archera_premiums_and_rebates_daily": { "get": { "parameters": [ { "in": "query", "name": "format", "description": "Response format: 'json' (default) or 'csv'", "schema": { "type": "string", "default": "json", "enum": [ "json", "csv" ] }, "required": false }, { "in": "query", "name": "year", "description": "Billing year (e.g. 2026)", "schema": { "type": "integer" }, "required": true }, { "in": "query", "name": "month", "description": "Billing month (1-12)", "schema": { "type": "integer", "minimum": 1, "maximum": 12 }, "required": true }, { "in": "query", "name": "provider", "description": "Cloud provider (aws, azure, gcp, kubernetes, unknown)", "schema": { "type": "string", "enum": [ "aws", "azure", "gcp", "kubernetes", "unknown" ] }, "required": true } ], "responses": { "422": { "$ref": "#/components/responses/UNPROCESSABLE_CONTENT" }, "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "array", "items": { "$ref": "#/components/schemas/ArcheraPremiumsAndRebatesDailyOutput" } } } } }, "default": { "$ref": "#/components/responses/DEFAULT_ERROR" }, "400": { "description": "Bad request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorResponse" } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorResponse" } } } }, "403": { "description": "Forbidden", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorResponse" } } } }, "404": { "description": "Not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorResponse" } } } }, "409": { "description": "Conflict", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorResponse" } } } }, "405": { "description": "Method not allowed", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorResponse" } } } }, "500": { "description": "Internal server error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorResponse" } } } } }, "tags": [ "reports" ], "summary": "Archera Premiums and Rebates Daily", "description": "Daily allocation of Archera premiums, rebates, and savings over a calendar month." }, "parameters": [ { "in": "path", "name": "org_id", "required": true, "schema": { "type": "string", "format": "uuid" } } ] }, "/beta/v1/org/{org_id}/reports/archera_premiums_and_rebates_by_account_daily": { "get": { "parameters": [ { "in": "query", "name": "format", "description": "Response format: 'json' (default) or 'csv'", "schema": { "type": "string", "default": "json", "enum": [ "json", "csv" ] }, "required": false }, { "in": "query", "name": "year", "description": "Billing year (e.g. 2026)", "schema": { "type": "integer" }, "required": true }, { "in": "query", "name": "month", "description": "Billing month (1-12)", "schema": { "type": "integer", "minimum": 1, "maximum": 12 }, "required": true }, { "in": "query", "name": "provider", "description": "Cloud provider (aws, azure, gcp, kubernetes, unknown)", "schema": { "type": "string", "enum": [ "aws", "azure", "gcp", "kubernetes", "unknown" ] }, "required": true } ], "responses": { "422": { "$ref": "#/components/responses/UNPROCESSABLE_CONTENT" }, "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "array", "items": { "$ref": "#/components/schemas/ArcheraPremiumsAndRebatesByAccountDailyOutput" } } } } }, "default": { "$ref": "#/components/responses/DEFAULT_ERROR" }, "400": { "description": "Bad request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorResponse" } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorResponse" } } } }, "403": { "description": "Forbidden", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorResponse" } } } }, "404": { "description": "Not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorResponse" } } } }, "409": { "description": "Conflict", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorResponse" } } } }, "405": { "description": "Method not allowed", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorResponse" } } } }, "500": { "description": "Internal server error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorResponse" } } } } }, "tags": [ "reports" ], "summary": "Archera Premiums and Rebates by Account Daily", "description": "Daily allocation of Archera premiums, rebates, and savings by cloud account over a calendar month." }, "parameters": [ { "in": "path", "name": "org_id", "required": true, "schema": { "type": "string", "format": "uuid" } } ] }, "/beta/v1/org/{org_id}/allocation-reports": { "get": { "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "array", "items": { "$ref": "#/components/schemas/AllocationReportDescriptor" } } } } }, "default": { "$ref": "#/components/responses/DEFAULT_ERROR" }, "400": { "description": "Bad request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorResponse" } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorResponse" } } } }, "403": { "description": "Forbidden", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorResponse" } } } }, "404": { "description": "Not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorResponse" } } } }, "409": { "description": "Conflict", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorResponse" } } } }, "405": { "description": "Method not allowed", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorResponse" } } } }, "500": { "description": "Internal server error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorResponse" } } } } }, "tags": [ "Allocation Reports (Beta)" ], "summary": "List available allocation reports", "description": "Catalog of allocation/showback reports a caller can fetch via `GET /allocation-reports/`. Each entry declares the query parameters it accepts and the columns its rows will contain." }, "parameters": [ { "in": "path", "name": "org_id", "required": true, "schema": { "type": "string", "format": "uuid" } } ] }, "/beta/v1/org/{org_id}/allocation-reports/{report_type}": { "get": { "responses": { "default": { "$ref": "#/components/responses/DEFAULT_ERROR" }, "400": { "description": "Bad request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorResponse" } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorResponse" } } } }, "403": { "description": "Forbidden", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorResponse" } } } }, "404": { "description": "Not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorResponse" } } } }, "409": { "description": "Conflict", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorResponse" } } } }, "405": { "description": "Method not allowed", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorResponse" } } } }, "500": { "description": "Internal server error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorResponse" } } } } }, "tags": [ "Allocation Reports (Beta)" ], "summary": "Fetch one allocation report", "description": "Returns one report's rows for the requested calendar month. Accepted query parameters and returned columns vary by `report_type` \u2014 call the list endpoint to discover them. Pass `?format=csv` for a CSV download (default is JSON). Returns 404 for unknown or per-org-hidden reports, and 404 with `code: period_not_available` when the requested (year, month) isn't in this report's available periods \u2014 call the /periods endpoint to enumerate what is. marshmallow.ValidationError on bad query params is handled globally as a 400." }, "parameters": [ { "in": "path", "name": "org_id", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "in": "path", "name": "report_type", "required": true, "schema": { "type": "string", "minLength": 1 } } ] }, "/beta/v1/org/{org_id}/allocation-reports/{report_type}/periods": { "get": { "responses": { "default": { "$ref": "#/components/responses/DEFAULT_ERROR" }, "400": { "description": "Bad request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorResponse" } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorResponse" } } } }, "403": { "description": "Forbidden", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorResponse" } } } }, "404": { "description": "Not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorResponse" } } } }, "409": { "description": "Conflict", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorResponse" } } } }, "405": { "description": "Method not allowed", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorResponse" } } } }, "500": { "description": "Internal server error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorResponse" } } } } }, "tags": [ "Allocation Reports (Beta)" ], "summary": "List periods available for an allocation report", "description": "Returns the (year, month) periods this report can be queried for, given the supplied filter params (same shape as the get endpoint minus year/month \u2014 those are the dimensions being enumerated). Each entry has `status: \"finalized\"` for past months backed by an invoice, or `\"in_progress\"` for the current calendar month when the report's update_cadence is \"daily\". Sorted most-recent first." }, "parameters": [ { "in": "path", "name": "org_id", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "in": "path", "name": "report_type", "required": true, "schema": { "type": "string", "minLength": 1 } } ] }, "/beta/v1/org/{org_id}/commitment-plans": { "get": { "parameters": [ { "in": "query", "name": "provider", "description": "Cloud provider (aws, azure, gcp)", "schema": { "example": "aws", "type": "string", "enum": [ "aws", "azure", "gcp", "kubernetes", "unknown" ] }, "required": true }, { "in": "query", "name": "segment_id", "description": "Optional segment ID to scope results. Defaults to the provider resources segment if not specified.", "schema": { "type": "string", "format": "uuid", "default": null, "nullable": true }, "required": false }, { "in": "query", "name": "template_id", "description": "Filter to plans generated from this template (GET /commitment-plan-templates)", "schema": { "type": "string", "format": "uuid", "default": null, "nullable": true }, "required": false }, { "in": "query", "name": "status", "description": "Filter by plan status (e.g. 'draft', 'in_progress')", "schema": { "default": null, "type": "string", "enum": [ "new", "reviewed", "scheduled", "completed", "draft", "needs_review", "in_progress", null ], "nullable": true }, "required": false }, { "in": "query", "name": "is_recommended", "description": "Filter to the flagged recommended plan", "schema": { "type": "boolean", "default": null, "nullable": true }, "required": false }, { "in": "query", "name": "is_system_generated", "description": "Filter to system-generated (default) plans \u2014 the three built-ins (Recommended / Balanced / High Savings) vs. user-created plans.", "schema": { "type": "boolean", "default": null, "nullable": true }, "required": false }, { "in": "query", "name": "is_renewal", "description": "Switch which flavor the list returns. Omitted (default) and false both return segment-scoped non-renewal plans \u2014 backward-compatible with the pre-renewal contract. Set to true to fetch renewal plans (which aren't segment-scoped \u2014 `segment_id` is ignored). There's no combined view; renewals and non-renewals are queried separately.", "schema": { "type": "boolean", "default": null, "nullable": true }, "required": false } ], "responses": { "422": { "$ref": "#/components/responses/UNPROCESSABLE_CONTENT" }, "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "array", "items": { "$ref": "#/components/schemas/CommitmentPlanList" } } } } }, "default": { "$ref": "#/components/responses/DEFAULT_ERROR" }, "400": { "description": "Bad request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorResponse" } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorResponse" } } } }, "403": { "description": "Forbidden", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorResponse" } } } }, "404": { "description": "Not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorResponse" } } } }, "409": { "description": "Conflict", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorResponse" } } } }, "405": { "description": "Method not allowed", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorResponse" } } } }, "500": { "description": "Internal server error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorResponse" } } } } }, "tags": [ "Commitment Plans (Beta)" ], "summary": "List commitment plans", "description": "Returns commitment plans scoped to one segment for the given provider. `segment_id` defaults to the provider-resources segment \u2014 same fallback as POST/PUT \u2014 so the typical caller sees the plans tied to their default segment without cross-segment duplicates. Further filters (template, status, flags) narrow within that scope. Coverage metrics (current_coverage / projected_coverage) are omitted here for speed; fetch the detail endpoint for those." }, "post": { "responses": { "422": { "$ref": "#/components/responses/UNPROCESSABLE_CONTENT" }, "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CommitmentPlanList" } } } }, "default": { "$ref": "#/components/responses/DEFAULT_ERROR" }, "400": { "description": "Bad request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorResponse" } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorResponse" } } } }, "403": { "description": "Forbidden", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorResponse" } } } }, "404": { "description": "Not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorResponse" } } } }, "409": { "description": "Conflict", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorResponse" } } } }, "405": { "description": "Method not allowed", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorResponse" } } } }, "500": { "description": "Internal server error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorResponse" } } } } }, "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CreateCommitmentPlanArgs" } } } }, "tags": [ "Commitment Plans (Beta)" ], "summary": "Create a commitment plan", "description": "Creates a new commitment plan for the given segment. The plan is generated asynchronously; the response echoes the initial plan with is_calculating=true and omits coverage fields (meaningless mid-recalc). Poll GET /commitment-plans/{plan_id} once is_calculating=false to get the full detail including coverage and per-service breakdowns." }, "parameters": [ { "in": "path", "name": "org_id", "required": true, "schema": { "type": "string", "format": "uuid" } } ] }, "/beta/v1/org/{org_id}/commitment-plans/renewals": { "post": { "responses": { "422": { "$ref": "#/components/responses/UNPROCESSABLE_CONTENT" }, "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CommitmentPlanList" } } } }, "default": { "$ref": "#/components/responses/DEFAULT_ERROR" }, "400": { "description": "Bad request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorResponse" } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorResponse" } } } }, "403": { "description": "Forbidden", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorResponse" } } } }, "404": { "description": "Not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorResponse" } } } }, "409": { "description": "Conflict", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorResponse" } } } }, "405": { "description": "Method not allowed", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorResponse" } } } }, "500": { "description": "Internal server error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorResponse" } } } } }, "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CreateRenewalCommitmentPlanArgs" } } } }, "tags": [ "Commitment Plans (Beta)" ], "summary": "Create a renewal commitment plan", "description": "Creates a new commitment plan that renews a set of expiring commitments. The plan covers the same resources the source commitments were covering, with the contract specs supplied in `configuration` driving the renewal recommendation. The plan is generated asynchronously \u2014 the response echoes the initial plan with `is_calculating=true`; poll GET /commitment-plans/{plan_id} until that flips to see the generated line items.\n\nRenewal plans always sit on the provider-resources segment; `segment_id` is not accepted. The usage window the recommender feeds on is derived automatically from the source commitments' end dates, so `configuration.lookback_days` is omitted (the field is rejected if sent). `configuration.resource_ids` is also rejected \u2014 `configuration.renewal_commitment_ids` carries the scope for a renewal plan, parallel to how `configuration.resource_ids` scopes an infrastructure plan on the regular create endpoint.\n\nEach generated line item carries a `renewal_commitment_id` linking it back to the source commitment it is proposed to replace. Pair with GET /commitment-plans/{plan_id}/renewal-commitments to see the source commitments side-by-side." }, "parameters": [ { "in": "path", "name": "org_id", "required": true, "schema": { "type": "string", "format": "uuid" } } ] }, "/beta/v1/org/{org_id}/commitment-plans/default": { "get": { "parameters": [ { "in": "query", "name": "provider", "description": "Cloud provider (aws, azure, gcp)", "schema": { "example": "aws", "type": "string", "enum": [ "aws", "azure", "gcp", "kubernetes", "unknown" ] }, "required": true }, { "in": "query", "name": "segment_id", "description": "Optional segment ID to scope results. Defaults to the provider resources segment if not specified.", "schema": { "type": "string", "format": "uuid", "default": null, "nullable": true }, "required": false } ], "responses": { "422": { "$ref": "#/components/responses/UNPROCESSABLE_CONTENT" }, "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "array", "items": { "$ref": "#/components/schemas/CommitmentPlan" } } } } }, "default": { "$ref": "#/components/responses/DEFAULT_ERROR" }, "400": { "description": "Bad request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorResponse" } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorResponse" } } } }, "403": { "description": "Forbidden", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorResponse" } } } }, "404": { "description": "Not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorResponse" } } } }, "409": { "description": "Conflict", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorResponse" } } } }, "405": { "description": "Method not allowed", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorResponse" } } } }, "500": { "description": "Internal server error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorResponse" } } } } }, "tags": [ "Commitment Plans (Beta)" ], "summary": "Get default commitment plans", "description": "Returns the three default Archera commitment plans: Recommended (30-day), Balanced (1-year), and High Savings (3-year)." }, "parameters": [ { "in": "path", "name": "org_id", "required": true, "schema": { "type": "string", "format": "uuid" } } ] }, "/beta/v1/org/{org_id}/commitment-plans/recommended": { "get": { "parameters": [ { "in": "query", "name": "provider", "description": "Cloud provider (aws, azure, gcp)", "schema": { "example": "aws", "type": "string", "enum": [ "aws", "azure", "gcp", "kubernetes", "unknown" ] }, "required": true }, { "in": "query", "name": "segment_id", "description": "Optional segment ID to scope results. Defaults to the provider resources segment if not specified.", "schema": { "type": "string", "format": "uuid", "default": null, "nullable": true }, "required": false } ], "responses": { "422": { "$ref": "#/components/responses/UNPROCESSABLE_CONTENT" }, "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CommitmentPlan" } } } }, "204": { "description": "No Content" }, "default": { "$ref": "#/components/responses/DEFAULT_ERROR" }, "400": { "description": "Bad request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorResponse" } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorResponse" } } } }, "403": { "description": "Forbidden", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorResponse" } } } }, "404": { "description": "Not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorResponse" } } } }, "409": { "description": "Conflict", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorResponse" } } } }, "405": { "description": "Method not allowed", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorResponse" } } } }, "500": { "description": "Internal server error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorResponse" } } } } }, "tags": [ "Commitment Plans (Beta)" ], "summary": "Get recommended commitment plan", "description": "Returns the single recommended commitment plan for the organization. This is typically the 30-day Recommended plan. Returns 204 if no plan is available." }, "parameters": [ { "in": "path", "name": "org_id", "required": true, "schema": { "type": "string", "format": "uuid" } } ] }, "/beta/v1/org/{org_id}/commitment-plans/{plan_id}": { "get": { "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CommitmentPlanDetail" } } } }, "404": { "description": "Not Found" }, "default": { "$ref": "#/components/responses/DEFAULT_ERROR" }, "400": { "description": "Bad request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorResponse" } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorResponse" } } } }, "403": { "description": "Forbidden", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorResponse" } } } }, "409": { "description": "Conflict", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorResponse" } } } }, "405": { "description": "Method not allowed", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorResponse" } } } }, "500": { "description": "Internal server error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorResponse" } } } } }, "tags": [ "Commitment Plans (Beta)" ], "summary": "Get commitment plan details", "description": "Returns details for a specific commitment plan by ID, including per-service breakdowns." }, "put": { "responses": { "422": { "$ref": "#/components/responses/UNPROCESSABLE_CONTENT" }, "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CommitmentPlanList" } } } }, "404": { "description": "Not Found" }, "default": { "$ref": "#/components/responses/DEFAULT_ERROR" }, "400": { "description": "Bad request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorResponse" } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorResponse" } } } }, "403": { "description": "Forbidden", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorResponse" } } } }, "409": { "description": "Conflict", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorResponse" } } } }, "405": { "description": "Method not allowed", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorResponse" } } } }, "500": { "description": "Internal server error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorResponse" } } } } }, "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UpdateCommitmentPlanArgs" } } } }, "tags": [ "Commitment Plans (Beta)" ], "summary": "Update a commitment plan", "description": "Update the plan's name and/or configuration. Replacing `configuration` triggers a recalculation \u2014 the response will have is_calculating=true and line-item financials are invalid until generation completes. Rejected if the plan is currently calculating, is a system-generated default, or is locked for purchase." }, "delete": { "responses": { "204": { "description": "No Content" }, "404": { "description": "Not Found" }, "default": { "$ref": "#/components/responses/DEFAULT_ERROR" }, "400": { "description": "Bad request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorResponse" } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorResponse" } } } }, "403": { "description": "Forbidden", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorResponse" } } } }, "409": { "description": "Conflict", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorResponse" } } } }, "405": { "description": "Method not allowed", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorResponse" } } } }, "500": { "description": "Internal server error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorResponse" } } } } }, "tags": [ "Commitment Plans (Beta)" ], "summary": "Delete a commitment plan", "description": "Delete a commitment plan. Rejected if the plan is currently calculating, is a system-generated default, or is locked for purchase. Irreversible." }, "parameters": [ { "in": "path", "name": "org_id", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "in": "path", "name": "plan_id", "required": true, "schema": { "type": "string", "format": "uuid" } } ] }, "/beta/v1/org/{org_id}/commitment-plans/{plan_id}/apply": { "post": { "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CommitmentPlanDetail" } } } }, "404": { "description": "Not Found" }, "default": { "$ref": "#/components/responses/DEFAULT_ERROR" }, "400": { "description": "Bad request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorResponse" } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorResponse" } } } }, "403": { "description": "Forbidden", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorResponse" } } } }, "409": { "description": "Conflict", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorResponse" } } } }, "405": { "description": "Method not allowed", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorResponse" } } } }, "500": { "description": "Internal server error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorResponse" } } } } }, "tags": [ "Commitment Plans (Beta)" ], "summary": "Apply (purchase) a commitment plan", "description": "Executes the plan's selected line items as actual commitment purchases. Marks the plan as edited and records the initiating user. The plan is then processed by the commitment-purchase workflow \u2014 inspect the plan status afterwards for progress. Rejected if the plan is currently calculating or already locked." }, "parameters": [ { "in": "path", "name": "org_id", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "in": "path", "name": "plan_id", "required": true, "schema": { "type": "string", "format": "uuid" } } ] }, "/beta/v1/org/{org_id}/commitment-plans/{plan_id}/copy": { "post": { "responses": { "422": { "$ref": "#/components/responses/UNPROCESSABLE_CONTENT" }, "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PlanLineItemUpdateResponse" } } } }, "400": { "description": "Bad Request" }, "404": { "description": "Not Found" }, "default": { "$ref": "#/components/responses/DEFAULT_ERROR" }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorResponse" } } } }, "403": { "description": "Forbidden", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorResponse" } } } }, "409": { "description": "Conflict", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorResponse" } } } }, "405": { "description": "Method not allowed", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorResponse" } } } }, "500": { "description": "Internal server error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorResponse" } } } } }, "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CopyCommitmentPlanArgs" } } } }, "tags": [ "Commitment Plans (Beta)" ], "summary": "Copy a commitment plan, optionally applying line-item edits", "description": "Creates a draft copy of an existing commitment plan, including its line items and resource matches. The copy is a regular user-created plan (is_default=false, is_recommended=false) and is editable via PUT /commitment-plans/{plan_id}. Useful for forking a system-generated default plan (Recommended / Balanced / High Savings) so it can be modified \u2014 defaults themselves are read-only. The copy inherits the source plan's already-computed line items and financials, so it is ready immediately (is_calculating=false).\n\nOptionally apply line-item edits during the copy via two mutually exclusive modes:\n\n- Explicit: pass `line_item_updates` referencing the SOURCE plan's line_item_ids; the server translates them to the copy's new IDs internally and applies them atomically.\n- Resolution: pass `target_contract_term` (+ optional `target_payment_option` / `target_line_item_ids`) and the server swaps every selected (or scoped) line item on the copy to the closest candidate at or below the target term. Saves the LLM having to enumerate per-line edits when the user wants a uniform shape change on the new plan.\n\nIf any edit fails (unknown source line_item_id, invalid offer, integer-coercion error on a unit-basis offer's `selected_amount`, duplicate line_item_id within `line_item_updates`), the entire copy + updates rolls back \u2014 no orphan copy persists. This is the canonical 'copy to edit' workflow; saves the round trip and ID-translation logic vs a separate copy + update sequence.\n\nReturns the new plan in CommitmentPlanListSchema shape \u2014 id + headline financials + configuration; covered_services and coverage fields are intentionally omitted because computing them eagerly loads per-service summaries (expensive) and the typical caller just needs the post-edit totals to confirm the copy. Follow up with `commitment_plan_details` on the returned id if you need the full breakdown. In resolution mode the response additionally carries a `resolution` array with one entry per scoped line item (`actual_term` / `actual_payment_option` / `actual_term_reason` of `exact_match`, `fallback_closest_shorter`, or `no_alternative`). Surface no_alternative outcomes to the user so they understand why coverage may be partial.\n\nRejected if the source plan is currently being calculated." }, "parameters": [ { "in": "path", "name": "org_id", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "in": "path", "name": "plan_id", "required": true, "schema": { "type": "string", "format": "uuid" } } ] }, "/beta/v1/org/{org_id}/commitment-plans/{plan_id}/line-items": { "get": { "parameters": [ { "in": "query", "name": "line_item_ids", "description": "Optional list of line-item ids to scope the response to. When omitted, returns every line item in the plan.", "schema": { "type": "array", "default": null, "items": { "type": "string", "format": "uuid" }, "nullable": true }, "required": false, "explode": true, "style": "form" }, { "in": "query", "name": "renewal_commitment_ids", "description": "Renewal plans only: scope to line items proposed as the replacement for these specific expiring commitments. Useful for \"show me what's being proposed to replace commitment X.\" Rejected with 400 on non-renewal plans (their line items have no renewal linkage; this guards against stale/wrong plan ids silently returning unrelated rows).", "schema": { "type": "array", "default": null, "items": { "type": "string", "format": "uuid" }, "nullable": true }, "required": false, "explode": true, "style": "form" }, { "in": "query", "name": "order_by", "description": "Field to order results by", "schema": { "type": "string", "default": "monthly_net_savings", "enum": [ "monthly_net_savings", "monthly_total_cost", "breakeven_days", "discount_rate", "upfront_cost" ] }, "required": false }, { "in": "query", "name": "desc", "description": "Sort descending (default true)", "schema": { "type": "boolean", "default": true }, "required": false }, { "in": "query", "name": "page", "schema": { "type": "integer", "default": 1, "minimum": 1 }, "required": false }, { "in": "query", "name": "page_size", "schema": { "type": "integer", "default": 20, "minimum": 1, "maximum": 10000 }, "required": false } ], "responses": { "422": { "$ref": "#/components/responses/UNPROCESSABLE_CONTENT" }, "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "array", "items": { "$ref": "#/components/schemas/CommitmentLineItem" } } } }, "headers": { "X-Pagination": { "$ref": "#/components/headers/PAGINATION" } } }, "default": { "$ref": "#/components/responses/DEFAULT_ERROR" }, "400": { "description": "Bad request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorResponse" } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorResponse" } } } }, "403": { "description": "Forbidden", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorResponse" } } } }, "404": { "description": "Not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorResponse" } } } }, "409": { "description": "Conflict", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorResponse" } } } }, "405": { "description": "Method not allowed", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorResponse" } } } }, "500": { "description": "Internal server error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorResponse" } } } } }, "tags": [ "Commitment Plans (Beta)" ], "summary": "Get commitment plan line items", "description": "Returns individual commitment recommendations within a plan, including offer details, per-line-item savings, and costs. Each line item has an is_selected field: if false, the line item is excluded from the plan and its costs/savings are NOT included in the plan's top-level metrics. Pass `line_item_ids` to fetch a specific subset (e.g. a single line item)." }, "parameters": [ { "in": "path", "name": "org_id", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "in": "path", "name": "plan_id", "required": true, "schema": { "type": "string", "format": "uuid" } } ] }, "/beta/v1/org/{org_id}/commitment-plans/{plan_id}/line-items/update": { "post": { "responses": { "422": { "$ref": "#/components/responses/UNPROCESSABLE_CONTENT" }, "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PlanLineItemUpdateResponse" } } } }, "400": { "description": "Bad Request" }, "404": { "description": "Not Found" }, "default": { "$ref": "#/components/responses/DEFAULT_ERROR" }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorResponse" } } } }, "403": { "description": "Forbidden", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorResponse" } } } }, "409": { "description": "Conflict", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorResponse" } } } }, "405": { "description": "Method not allowed", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorResponse" } } } }, "500": { "description": "Internal server error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorResponse" } } } } }, "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UpdateLineItemsArgs" } } } }, "tags": [ "Commitment Plans (Beta)" ], "summary": "Update commitment plan line items", "description": "Atomically apply line-item edits in a single request. Two modes:\n\n- Explicit: pass `updates`, a list where each entry carries the same fields the singular line-item update would accept (selection, account, offer-swap triple) plus the `line_item_id` selector.\n- Resolution: pass `target_contract_term` (+ optional `target_payment_option` / `target_line_item_ids`) and the server swaps every selected (or scoped) line item to the closest candidate at or below the target term. Saves the LLM having to enumerate many edits when the user wants a uniform shape change.\n\nModes are mutually exclusive. All updates are applied within a single transaction \u2014 if any fails (unknown line item, invalid offer, integer-coercion error on a unit-basis offer's `selected_amount`), the whole call is rejected and no changes persist.\n\nReturns the updated plan in CommitmentPlanListSchema shape \u2014 id + headline financials + configuration; covered_services and coverage fields are intentionally omitted because computing them eagerly loads per-service summaries (expensive) and the typical caller just needs the post-edit totals to confirm the change. Follow up with `commitment_plan_details` on the returned id if you need the full breakdown. In resolution mode the response additionally carries a `resolution` array with one entry per scoped line item: the `actual_term` / `actual_payment_option` applied and an `actual_term_reason` of `exact_match`, `fallback_closest_shorter`, or `no_alternative` (the latter were left untouched). Surface no_alternative outcomes to the user so they understand why coverage may be partial.\n\nRejected if the parent plan is currently calculating, is a system-generated default, or is locked for purchase." }, "parameters": [ { "in": "path", "name": "org_id", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "in": "path", "name": "plan_id", "required": true, "schema": { "type": "string", "format": "uuid" } } ] }, "/beta/v1/org/{org_id}/commitment-plans/{plan_id}/renewal-commitments": { "get": { "parameters": [ { "in": "query", "name": "line_item_ids", "description": "Optional list of line-item ids to scope to. When supplied, returns only the source commitments whose renewing line items are in this set.", "schema": { "type": "array", "default": null, "items": { "type": "string", "format": "uuid" }, "nullable": true }, "required": false, "explode": true, "style": "form" }, { "in": "query", "name": "page", "schema": { "type": "integer", "default": 1, "minimum": 1 }, "required": false }, { "in": "query", "name": "page_size", "schema": { "type": "integer", "default": 50, "minimum": 1, "maximum": 200 }, "required": false } ], "responses": { "422": { "$ref": "#/components/responses/UNPROCESSABLE_CONTENT" }, "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "array", "items": { "$ref": "#/components/schemas/Commitment" } } } }, "headers": { "X-Pagination": { "$ref": "#/components/headers/PAGINATION" } } }, "default": { "$ref": "#/components/responses/DEFAULT_ERROR" }, "400": { "description": "Bad request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorResponse" } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorResponse" } } } }, "403": { "description": "Forbidden", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorResponse" } } } }, "404": { "description": "Not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorResponse" } } } }, "409": { "description": "Conflict", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorResponse" } } } }, "405": { "description": "Method not allowed", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorResponse" } } } }, "500": { "description": "Internal server error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorResponse" } } } } }, "tags": [ "Commitment Plans (Beta)" ], "summary": "List the commitments being renewed by a renewal plan", "description": "Returns the expiring commitments that a renewal plan is proposed to replace \u2014 identity, dates, guarantee info, and contract term. Ordered by `end_date` ascending (earliest-expiring first) so the caller surfaces the most-urgent renewals first.\n\nRejected with 400 if the plan is not a renewal plan \u2014 for non-renewal plans use /line-items or /covered-resources instead.\n\nTo filter to the commitments tied to a subset of line items, pass `line_item_ids`. To go the other direction (line items proposed as replacements for a given source commitment), use the `renewal_commitment_ids` filter on /line-items." }, "parameters": [ { "in": "path", "name": "org_id", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "in": "path", "name": "plan_id", "required": true, "schema": { "type": "string", "format": "uuid" } } ] }, "/beta/v1/org/{org_id}/commitment-plans/{plan_id}/comparison": { "get": { "parameters": [ { "in": "query", "name": "line_item_ids", "description": "Optional subset of line items to compare. If omitted, defaults to all selected line items in the plan.", "schema": { "type": "array", "default": null, "items": { "type": "string", "format": "uuid" }, "nullable": true }, "required": false, "explode": true, "style": "form" }, { "in": "query", "name": "contract_terms", "description": "Optional list of target terms to roll up. If omitted, the response includes a hypothetical for every distinct contract_term that appears in any line item's candidates after the payment-option filter.", "schema": { "type": "array", "default": null, "items": { "type": "string", "enum": [ "one_year_gris", "thirty_day_gris", "two_month_gris", "three_month_gris", "four_month_gris", "five_month_gris", "six_month_gris", "seven_month_gris", "eight_month_gris", "nine_month_gris", "ten_month_gris", "eleven_month_gris", "twelve_month_gris", "thirteen_month_gris", "fourteen_month_gris", "fifteen_month_gris", "sixteen_month_gris", "seventeen_month_gris", "eighteen_month_gris", "nineteen_month_gris", "twenty_month_gris", "twenty_one_month_gris", "twenty_two_month_gris", "twenty_three_month_gris", "twenty_four_month_gris", "twenty_five_month_gris", "twenty_six_month_gris", "twenty_seven_month_gris", "twenty_eight_month_gris", "twenty_nine_month_gris", "thirty_month_gris", "thirty_one_month_gris", "thirty_two_month_gris", "thirty_three_month_gris", "thirty_four_month_gris", "thirty_five_month_gris", "one_year", "two_year", "three_year", "five_year", "zero_day", "thirty_day", "two_month", "three_month", "four_month", "five_month", "six_month", "seven_month", "eight_month", "nine_month", "ten_month", "eleven_month", "thirteen_month", "fourteen_month", "fifteen_month", "sixteen_month", "seventeen_month", "eighteen_month", "nineteen_month", "twenty_month", "twenty_one_month", "twenty_two_month", "twenty_three_month", "twenty_five_month", "twenty_six_month", "twenty_seven_month", "twenty_eight_month", "twenty_nine_month", "thirty_month", "thirty_one_month", "thirty_two_month", "thirty_three_month", "thirty_four_month", "thirty_five_month" ] }, "nullable": true }, "required": false, "explode": true, "style": "form" }, { "in": "query", "name": "payment_options", "description": "Payment options to include. Defaults to no_upfront only \u2014 most users are uncomfortable with cash at signing, so this matches the default framing for plan comparisons. Pass partial_upfront / all_upfront explicitly to surface those.", "schema": { "type": "array", "items": { "type": "string", "enum": [ "no_upfront", "partial_upfront", "all_upfront" ] } }, "required": false, "explode": true, "style": "form" } ], "responses": { "422": { "$ref": "#/components/responses/UNPROCESSABLE_CONTENT" }, "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/LineItemOfferComparisonResponse" } } } }, "400": { "description": "Bad Request" }, "404": { "description": "Not Found" }, "default": { "$ref": "#/components/responses/DEFAULT_ERROR" }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorResponse" } } } }, "403": { "description": "Forbidden", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorResponse" } } } }, "409": { "description": "Conflict", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorResponse" } } } }, "405": { "description": "Method not allowed", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorResponse" } } } }, "500": { "description": "Internal server error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorResponse" } } } } }, "tags": [ "Commitment Plans (Beta)" ], "summary": "Compare commitment offers across a plan's line items", "description": "Returns per-line-item offer alternatives plus plan-wide rollups for each (contract_term, payment_option) hypothetical. Designed to answer 'what would the plan look like at 3-year' in a single call: hypothetical_totals carries the rolled-up financials and delta_vs_current, with per-line-item resolution exposed for transparency. Each line item lands at the target term when available, else the longest available term <= target with the same payment option (GRI preferred within tier), else its current term. Defaults: line_item_ids=all selected, contract_terms=all distinct in candidates, payment_options=[no_upfront]." }, "parameters": [ { "in": "path", "name": "org_id", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "in": "path", "name": "plan_id", "required": true, "schema": { "type": "string", "format": "uuid" } } ] }, "/beta/v1/org/{org_id}/commitment-plans/{plan_id}/covered-resources/attributes": { "get": { "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "array", "items": { "$ref": "#/components/schemas/BaseAttribute" } } } } }, "default": { "$ref": "#/components/responses/DEFAULT_ERROR" }, "400": { "description": "Bad request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorResponse" } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorResponse" } } } }, "403": { "description": "Forbidden", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorResponse" } } } }, "404": { "description": "Not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorResponse" } } } }, "409": { "description": "Conflict", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorResponse" } } } }, "405": { "description": "Method not allowed", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorResponse" } } } }, "500": { "description": "Internal server error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorResponse" } } } } }, "summary": "List filterable covered-resource attributes for a plan", "tags": [ "Commitment Plans (Beta)" ], "description": "Returns the fields that can be used in the `filter` parameter of /commitment-plans//covered-resources, scoped to the resources the plan actually covers." }, "parameters": [ { "in": "path", "name": "org_id", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "in": "path", "name": "plan_id", "required": true, "schema": { "type": "string", "format": "uuid" } } ] }, "/beta/v1/org/{org_id}/commitment-plans/{plan_id}/covered-resources/attributes/{field}": { "get": { "parameters": [ { "in": "query", "name": "line_item_ids", "description": "Filter to matches from specific line items", "schema": { "type": "array", "default": null, "items": { "type": "string", "format": "uuid" }, "nullable": true }, "required": false, "explode": true, "style": "form" }, { "in": "query", "name": "only_selected_line_items", "description": "Only include matches from selected line items (default true)", "schema": { "type": "boolean", "default": true }, "required": false }, { "in": "query", "name": "search", "description": "Free-text ILIKE search across the resource SKU's identity and classification fields (resource id, name, account ids, service, region, instance_type, etc.). Mirrors the search lane on /resources/skus.", "schema": { "type": "string", "default": null, "nullable": true }, "required": false }, { "in": "query", "name": "filter", "description": "JSON filter object \u2014 same {field, op, value} tree accepted by /resources/skus. Filterable on the resource SKU side: identity, tags (`has` with nested key/value filters), SKU classification, and the trailing-30-day spend/usage aggregates: `total_cost`, `ondemand_cost`, `gross_savings` (TOTAL summed over the trailing 30 days, NOT a monthly rate \u2014 same basis as /resources/skus), `coverage` (fraction of usage covered by ALL existing commitments \u2014 current actuals, NOT this plan's projected coverage; that's the response's per-match `projected_coverage`), and `uptime` (fraction). All warehouse aggregates here are actuals across existing commitments, NOT plan-scoped projections. Call /covered-resources/attributes for the full filterable surface.", "schema": { "type": "object", "default": null, "additionalProperties": {}, "nullable": true }, "required": false }, { "in": "query", "name": "order_by", "description": "Field to order results by. Defaults to monthly_net_savings. All numeric axes are 730-hour monthly rates on the per-match plan economics, net of the Archera premium where applicable (NOT the resource's warehouse trailing-30-day actuals \u2014 those are filterable but not orderable here, on purpose, to keep sort and response framing on the same monthly basis).", "schema": { "type": "string", "default": "monthly_net_savings", "enum": [ "id", "projected_coverage", "monthly_net_savings", "monthly_before_cost", "monthly_after_cost", "monthly_after_ondemand_cost" ] }, "required": false }, { "in": "query", "name": "desc", "description": "Sort descending (default true)", "schema": { "type": "boolean", "default": true }, "required": false } ], "responses": { "422": { "$ref": "#/components/responses/UNPROCESSABLE_CONTENT" }, "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Attribute" } } } }, "default": { "$ref": "#/components/responses/DEFAULT_ERROR" }, "400": { "description": "Bad request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorResponse" } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorResponse" } } } }, "403": { "description": "Forbidden", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorResponse" } } } }, "404": { "description": "Not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorResponse" } } } }, "409": { "description": "Conflict", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorResponse" } } } }, "405": { "description": "Method not allowed", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorResponse" } } } }, "500": { "description": "Internal server error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorResponse" } } } } }, "summary": "Get valid values for a filterable covered-resource attribute", "tags": [ "Commitment Plans (Beta)" ], "description": "Returns the distinct values for a given field, restricted to the resources the plan covers (and further narrowed by any search/filter passed). Use to discover valid filter values without paginating through the covered-resources list." }, "parameters": [ { "in": "path", "name": "org_id", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "in": "path", "name": "plan_id", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "in": "path", "name": "field", "required": true, "schema": { "type": "string", "minLength": 1 } } ] }, "/beta/v1/org/{org_id}/commitment-plans/{plan_id}/covered-resources/summary": { "get": { "parameters": [ { "in": "query", "name": "line_item_ids", "description": "Filter to matches from specific line items", "schema": { "type": "array", "default": null, "items": { "type": "string", "format": "uuid" }, "nullable": true }, "required": false, "explode": true, "style": "form" }, { "in": "query", "name": "only_selected_line_items", "description": "Only include matches from selected line items (default true)", "schema": { "type": "boolean", "default": true }, "required": false } ], "responses": { "422": { "$ref": "#/components/responses/UNPROCESSABLE_CONTENT" }, "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "array", "items": { "$ref": "#/components/schemas/ResourceMatchSummary" } } } } }, "default": { "$ref": "#/components/responses/DEFAULT_ERROR" }, "400": { "description": "Bad request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorResponse" } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorResponse" } } } }, "403": { "description": "Forbidden", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorResponse" } } } }, "404": { "description": "Not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorResponse" } } } }, "409": { "description": "Conflict", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorResponse" } } } }, "405": { "description": "Method not allowed", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorResponse" } } } }, "500": { "description": "Internal server error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorResponse" } } } } }, "tags": [ "Commitment Plans (Beta)" ], "summary": "Aggregated covered-resources summary for a commitment plan", "description": "Returns the resources a commitment plan covers, aggregated by (service, account, region, resource_type). Each row is one group: rolled-up costs, savings, mean coverage, and resource count. Sorted by net savings descending. For per-resource detail, use the paginated /covered-resources endpoint." }, "parameters": [ { "in": "path", "name": "org_id", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "in": "path", "name": "plan_id", "required": true, "schema": { "type": "string", "format": "uuid" } } ] }, "/beta/v1/org/{org_id}/commitment-plans/{plan_id}/covered-resources": { "get": { "parameters": [ { "in": "query", "name": "line_item_ids", "description": "Filter to matches from specific line items", "schema": { "type": "array", "default": null, "items": { "type": "string", "format": "uuid" }, "nullable": true }, "required": false, "explode": true, "style": "form" }, { "in": "query", "name": "only_selected_line_items", "description": "Only include matches from selected line items (default true)", "schema": { "type": "boolean", "default": true }, "required": false }, { "in": "query", "name": "search", "description": "Free-text ILIKE search across the resource SKU's identity and classification fields (resource id, name, account ids, service, region, instance_type, etc.). Mirrors the search lane on /resources/skus.", "schema": { "type": "string", "default": null, "nullable": true }, "required": false }, { "in": "query", "name": "filter", "description": "JSON filter object \u2014 same {field, op, value} tree accepted by /resources/skus. Filterable on the resource SKU side: identity, tags (`has` with nested key/value filters), SKU classification, and the trailing-30-day spend/usage aggregates: `total_cost`, `ondemand_cost`, `gross_savings` (TOTAL summed over the trailing 30 days, NOT a monthly rate \u2014 same basis as /resources/skus), `coverage` (fraction of usage covered by ALL existing commitments \u2014 current actuals, NOT this plan's projected coverage; that's the response's per-match `projected_coverage`), and `uptime` (fraction). All warehouse aggregates here are actuals across existing commitments, NOT plan-scoped projections. Call /covered-resources/attributes for the full filterable surface.", "schema": { "type": "object", "default": null, "additionalProperties": {}, "nullable": true }, "required": false }, { "in": "query", "name": "order_by", "description": "Field to order results by. Defaults to monthly_net_savings. All numeric axes are 730-hour monthly rates on the per-match plan economics, net of the Archera premium where applicable (NOT the resource's warehouse trailing-30-day actuals \u2014 those are filterable but not orderable here, on purpose, to keep sort and response framing on the same monthly basis).", "schema": { "type": "string", "default": "monthly_net_savings", "enum": [ "id", "projected_coverage", "monthly_net_savings", "monthly_before_cost", "monthly_after_cost", "monthly_after_ondemand_cost" ] }, "required": false }, { "in": "query", "name": "desc", "description": "Sort descending (default true)", "schema": { "type": "boolean", "default": true }, "required": false }, { "in": "query", "name": "page", "schema": { "type": "integer", "default": 1, "minimum": 1 }, "required": false }, { "in": "query", "name": "page_size", "schema": { "type": "integer", "default": 20, "minimum": 1, "maximum": 100 }, "required": false } ], "responses": { "422": { "$ref": "#/components/responses/UNPROCESSABLE_CONTENT" }, "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "array", "items": { "$ref": "#/components/schemas/ResourceMatchDetail" } } } }, "headers": { "X-Pagination": { "$ref": "#/components/headers/PAGINATION" } } }, "default": { "$ref": "#/components/responses/DEFAULT_ERROR" }, "400": { "description": "Bad request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorResponse" } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorResponse" } } } }, "403": { "description": "Forbidden", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorResponse" } } } }, "404": { "description": "Not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorResponse" } } } }, "409": { "description": "Conflict", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorResponse" } } } }, "405": { "description": "Method not allowed", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorResponse" } } } }, "500": { "description": "Internal server error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorResponse" } } } } }, "tags": [ "Commitment Plans (Beta)" ], "summary": "Paginated covered resources for a commitment plan", "description": "Returns one row per resource the plan covers, with the plan's economics scoped to that resource (coverage, monthly savings, before/after cost) and full ResourceSKU detail. Supports search, structured filter, sort, and cursor pagination \u2014 same surface idiom as /resources/skus, but scoped to the plan's matched resources. Use /covered-resources/summary for the aggregated breakdown." }, "parameters": [ { "in": "path", "name": "org_id", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "in": "path", "name": "plan_id", "required": true, "schema": { "type": "string", "format": "uuid" } } ] }, "/beta/v1/org/{org_id}/commitment-plan-templates": { "get": { "parameters": [ { "in": "query", "name": "provider", "description": "Cloud provider (aws, azure, gcp)", "schema": { "example": "aws", "type": "string", "enum": [ "aws", "azure", "gcp", "kubernetes", "unknown" ] }, "required": true }, { "in": "query", "name": "segment_id", "description": "Optional segment ID to scope results. Defaults to the provider resources segment if not specified.", "schema": { "type": "string", "format": "uuid", "default": null, "nullable": true }, "required": false } ], "responses": { "422": { "$ref": "#/components/responses/UNPROCESSABLE_CONTENT" }, "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "array", "items": { "$ref": "#/components/schemas/CommitmentPlanTemplate" } } } } }, "default": { "$ref": "#/components/responses/DEFAULT_ERROR" }, "400": { "description": "Bad request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorResponse" } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorResponse" } } } }, "403": { "description": "Forbidden", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorResponse" } } } }, "404": { "description": "Not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorResponse" } } } }, "409": { "description": "Conflict", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorResponse" } } } }, "405": { "description": "Method not allowed", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorResponse" } } } }, "500": { "description": "Internal server error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorResponse" } } } } }, "tags": [ "Commitment Plan Templates (Beta)" ], "summary": "List commitment plan templates", "description": "Returns commitment plan templates scoped to one segment for the given provider. `segment_id` defaults to the provider-resources segment \u2014 same fallback as POST/PUT \u2014 so the typical caller sees exactly the templates tied to their default segment without cross-segment duplicates." }, "post": { "responses": { "422": { "$ref": "#/components/responses/UNPROCESSABLE_CONTENT" }, "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CommitmentPlanTemplate" } } } }, "default": { "$ref": "#/components/responses/DEFAULT_ERROR" }, "400": { "description": "Bad request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorResponse" } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorResponse" } } } }, "403": { "description": "Forbidden", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorResponse" } } } }, "404": { "description": "Not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorResponse" } } } }, "409": { "description": "Conflict", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorResponse" } } } }, "405": { "description": "Method not allowed", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorResponse" } } } }, "500": { "description": "Internal server error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorResponse" } } } } }, "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CreateCommitmentPlanTemplateArgs" } } } }, "tags": [ "Commitment Plan Templates (Beta)" ], "summary": "Create a commitment plan template", "description": "Creates a reusable commitment plan template. If `auto_purchase` is provided, the system will regenerate and optionally purchase plans from this template on the given schedule." }, "parameters": [ { "in": "path", "name": "org_id", "required": true, "schema": { "type": "string", "format": "uuid" } } ] }, "/beta/v1/org/{org_id}/commitment-plan-templates/{template_id}": { "get": { "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CommitmentPlanTemplate" } } } }, "404": { "description": "Not Found" }, "default": { "$ref": "#/components/responses/DEFAULT_ERROR" }, "400": { "description": "Bad request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorResponse" } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorResponse" } } } }, "403": { "description": "Forbidden", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorResponse" } } } }, "409": { "description": "Conflict", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorResponse" } } } }, "405": { "description": "Method not allowed", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorResponse" } } } }, "500": { "description": "Internal server error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorResponse" } } } } }, "tags": [ "Commitment Plan Templates (Beta)" ], "summary": "Get a commitment plan template", "description": "Returns a single template by ID." }, "put": { "responses": { "422": { "$ref": "#/components/responses/UNPROCESSABLE_CONTENT" }, "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CommitmentPlanTemplate" } } } }, "404": { "description": "Not Found" }, "default": { "$ref": "#/components/responses/DEFAULT_ERROR" }, "400": { "description": "Bad request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorResponse" } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorResponse" } } } }, "403": { "description": "Forbidden", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorResponse" } } } }, "409": { "description": "Conflict", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorResponse" } } } }, "405": { "description": "Method not allowed", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorResponse" } } } }, "500": { "description": "Internal server error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorResponse" } } } } }, "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UpdateCommitmentPlanTemplateArgs" } } } }, "tags": [ "Commitment Plan Templates (Beta)" ], "summary": "Update a commitment plan template", "description": "Merge-semantic update: only keys present in the body are applied. Pass `auto_purchase: null` to clear an existing schedule; omit the key to leave it untouched. System-generated templates can have their `auto_purchase` schedule edited but not their `name` or `configuration`." }, "delete": { "responses": { "204": { "description": "No Content" }, "404": { "description": "Not Found" }, "default": { "$ref": "#/components/responses/DEFAULT_ERROR" }, "400": { "description": "Bad request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorResponse" } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorResponse" } } } }, "403": { "description": "Forbidden", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorResponse" } } } }, "409": { "description": "Conflict", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorResponse" } } } }, "405": { "description": "Method not allowed", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorResponse" } } } }, "500": { "description": "Internal server error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorResponse" } } } } }, "tags": [ "Commitment Plan Templates (Beta)" ], "summary": "Delete a commitment plan template", "description": "Delete a template. System-generated templates cannot be deleted." }, "parameters": [ { "in": "path", "name": "org_id", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "in": "path", "name": "template_id", "required": true, "schema": { "type": "string", "format": "uuid" } } ] }, "/beta/v1/org/{org_id}/commitment-types": { "get": { "parameters": [ { "in": "query", "name": "provider", "description": "Cloud provider to list commitment types for (aws, azure, gcp).", "schema": { "type": "string", "enum": [ "aws", "azure", "gcp", "kubernetes", "unknown" ] }, "required": true } ], "responses": { "422": { "$ref": "#/components/responses/UNPROCESSABLE_CONTENT" }, "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "array", "items": { "$ref": "#/components/schemas/AvailableCommitmentType" } } } } }, "default": { "$ref": "#/components/responses/DEFAULT_ERROR" }, "400": { "description": "Bad request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorResponse" } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorResponse" } } } }, "403": { "description": "Forbidden", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorResponse" } } } }, "404": { "description": "Not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorResponse" } } } }, "409": { "description": "Conflict", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorResponse" } } } }, "405": { "description": "Method not allowed", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorResponse" } } } }, "500": { "description": "Internal server error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorResponse" } } } } }, "tags": [ "Commitment Types (Beta)" ], "summary": "List available commitment types", "description": "Returns the commitment types available for the specified provider. Each type lists its supported contract terms, and each term lists the payment options that are actually offered for that (type, term) pair \u2014 the cross product of terms x payment options is NOT implied. Every leaf field (`commitment_type`, `contract_terms[*].contract_term`, `contract_terms[*].payment_options[*]`) is the exact value you pass into a plan's `configuration.contract_specs`." }, "parameters": [ { "in": "path", "name": "org_id", "required": true, "schema": { "type": "string", "format": "uuid" } } ] }, "/beta/v1/org/{org_id}/commitments/attributes": { "get": { "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "array", "items": { "$ref": "#/components/schemas/BaseAttribute" } } } } }, "default": { "$ref": "#/components/responses/DEFAULT_ERROR" }, "400": { "description": "Bad request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorResponse" } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorResponse" } } } }, "403": { "description": "Forbidden", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorResponse" } } } }, "404": { "description": "Not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorResponse" } } } }, "409": { "description": "Conflict", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorResponse" } } } }, "405": { "description": "Method not allowed", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorResponse" } } } }, "500": { "description": "Internal server error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorResponse" } } } } }, "summary": "List filterable commitment attributes", "tags": [ "Commitments (Beta)" ], "description": "Returns all fields that can be used in the 'filter' parameter of the commitments and commitments metrics endpoints, along with their types." }, "parameters": [ { "in": "path", "name": "org_id", "required": true, "schema": { "type": "string", "format": "uuid" } } ] }, "/beta/v1/org/{org_id}/commitments/attributes/{field}": { "get": { "parameters": [ { "in": "query", "name": "provider", "description": "Cloud provider (aws, azure, gcp)", "schema": { "example": "aws", "type": "string", "enum": [ "aws", "azure", "gcp", "kubernetes", "unknown" ] }, "required": true }, { "in": "query", "name": "only_active", "description": "Only return active commitments (default true)", "schema": { "type": "boolean", "default": true }, "required": false }, { "in": "query", "name": "search", "description": "Text search across commitment fields", "schema": { "type": "string", "default": null, "nullable": true }, "required": false }, { "in": "query", "name": "filter", "description": "JSON filter object \u2014 tree of {field, op, value} leaves combined with and / or / not. Supported ops: `=`, `!=`, `in` on any field; `>`, `>=`, `<`, `<=` on numeric fields and date fields (`start_date`, `end_date`). Examples: {\"field\": \"type\", \"op\": \"=\", \"value\": \"Compute\"} \u2014 categorical; {\"field\": \"end_date\", \"op\": \"<\", \"value\": \"2026-06-01\"} \u2014 expiring before June 2026; {\"field\": \"monthly_net_savings\", \"op\": \">\", \"value\": 1000} \u2014 saving more than $1000/month. Date-dependent metric fields are 730-hour monthly rates matching `commitment_financials_monthly_rate.*` in the response: `monthly_net_savings`, `monthly_gross_savings`, `monthly_premiums`, `monthly_estimated_rebate`. `utilization` is a 0-1 fraction averaged over the window.", "schema": { "type": "object", "default": null, "additionalProperties": {}, "nullable": true }, "required": false }, { "in": "query", "name": "order_by", "description": "Field to order results by. Includes the monthly-rate metrics (`monthly_net_savings`, `monthly_gross_savings`, `monthly_premiums`, `monthly_estimated_rebate`) and `utilization`.", "schema": { "type": "string", "default": "end_date", "enum": [ "start_date", "end_date", "type", "account_id", "upfront_cost", "monthly_cloud_provider_cost", "monthly_recurring_cost", "is_archera_guaranteed", "duration_seconds", "is_active", "utilization", "monthly_net_savings", "monthly_gross_savings", "monthly_premiums", "monthly_estimated_rebate" ] }, "required": false }, { "in": "query", "name": "desc", "description": "Sort descending. Default false \u2014 combined with the default order_by=end_date this surfaces the earliest-expiring commitments first, which is the common drilldown.", "schema": { "type": "boolean", "default": false }, "required": false } ], "responses": { "422": { "$ref": "#/components/responses/UNPROCESSABLE_CONTENT" }, "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Attribute" } } } }, "default": { "$ref": "#/components/responses/DEFAULT_ERROR" }, "400": { "description": "Bad request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorResponse" } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorResponse" } } } }, "403": { "description": "Forbidden", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorResponse" } } } }, "404": { "description": "Not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorResponse" } } } }, "409": { "description": "Conflict", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorResponse" } } } }, "405": { "description": "Method not allowed", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorResponse" } } } }, "500": { "description": "Internal server error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorResponse" } } } } }, "summary": "Get valid values for a filterable commitment attribute", "tags": [ "Commitments (Beta)" ], "description": "Returns the valid values for a specific filterable field. Use this to discover what values can be passed in a filter object. For example, calling with field='type' returns all commitment types like 'Compute', 'EC2Instance', etc." }, "parameters": [ { "in": "path", "name": "org_id", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "in": "path", "name": "field", "required": true, "schema": { "type": "string", "minLength": 1 } } ] }, "/beta/v1/org/{org_id}/commitments": { "get": { "parameters": [ { "in": "query", "name": "provider", "description": "Cloud provider (aws, azure, gcp)", "schema": { "example": "aws", "type": "string", "enum": [ "aws", "azure", "gcp", "kubernetes", "unknown" ] }, "required": true }, { "in": "query", "name": "only_active", "description": "Only return active commitments (default true)", "schema": { "type": "boolean", "default": true }, "required": false }, { "in": "query", "name": "search", "description": "Text search across commitment fields", "schema": { "type": "string", "default": null, "nullable": true }, "required": false }, { "in": "query", "name": "filter", "description": "JSON filter object \u2014 tree of {field, op, value} leaves combined with and / or / not. Supported ops: `=`, `!=`, `in` on any field; `>`, `>=`, `<`, `<=` on numeric fields and date fields (`start_date`, `end_date`). Examples: {\"field\": \"type\", \"op\": \"=\", \"value\": \"Compute\"} \u2014 categorical; {\"field\": \"end_date\", \"op\": \"<\", \"value\": \"2026-06-01\"} \u2014 expiring before June 2026; {\"field\": \"monthly_net_savings\", \"op\": \">\", \"value\": 1000} \u2014 saving more than $1000/month. Date-dependent metric fields are 730-hour monthly rates matching `commitment_financials_monthly_rate.*` in the response: `monthly_net_savings`, `monthly_gross_savings`, `monthly_premiums`, `monthly_estimated_rebate`. `utilization` is a 0-1 fraction averaged over the window.", "schema": { "type": "object", "default": null, "additionalProperties": {}, "nullable": true }, "required": false }, { "in": "query", "name": "order_by", "description": "Field to order results by. Includes the monthly-rate metrics (`monthly_net_savings`, `monthly_gross_savings`, `monthly_premiums`, `monthly_estimated_rebate`) and `utilization`.", "schema": { "type": "string", "default": "end_date", "enum": [ "start_date", "end_date", "type", "account_id", "upfront_cost", "monthly_cloud_provider_cost", "monthly_recurring_cost", "is_archera_guaranteed", "duration_seconds", "is_active", "utilization", "monthly_net_savings", "monthly_gross_savings", "monthly_premiums", "monthly_estimated_rebate" ] }, "required": false }, { "in": "query", "name": "desc", "description": "Sort descending. Default false \u2014 combined with the default order_by=end_date this surfaces the earliest-expiring commitments first, which is the common drilldown.", "schema": { "type": "boolean", "default": false }, "required": false }, { "in": "query", "name": "page", "schema": { "type": "integer", "default": 1, "minimum": 1 }, "required": false }, { "in": "query", "name": "page_size", "schema": { "type": "integer", "default": 20, "minimum": 1, "maximum": 10000 }, "required": false } ], "responses": { "422": { "$ref": "#/components/responses/UNPROCESSABLE_CONTENT" }, "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "array", "items": { "$ref": "#/components/schemas/CommitmentWithMetrics" } } } }, "headers": { "X-Pagination": { "$ref": "#/components/headers/PAGINATION" } } }, "default": { "$ref": "#/components/responses/DEFAULT_ERROR" }, "400": { "description": "Bad request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorResponse" } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorResponse" } } } }, "403": { "description": "Forbidden", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorResponse" } } } }, "404": { "description": "Not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorResponse" } } } }, "409": { "description": "Conflict", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorResponse" } } } }, "405": { "description": "Method not allowed", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorResponse" } } } }, "500": { "description": "Internal server error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorResponse" } } } } }, "tags": [ "Commitments (Beta)" ], "summary": "Get commitment inventory", "description": "Returns the organization's commitment inventory for the specified provider. By default returns only active commitments. Set only_active=false to include expired and other non-active commitments." }, "parameters": [ { "in": "path", "name": "org_id", "required": true, "schema": { "type": "string", "format": "uuid" } } ] }, "/beta/v1/org/{org_id}/commitments/summary": { "get": { "parameters": [ { "in": "query", "name": "provider", "description": "Cloud provider (aws, azure, gcp)", "schema": { "example": "aws", "type": "string", "enum": [ "aws", "azure", "gcp", "kubernetes", "unknown" ] }, "required": true } ], "responses": { "422": { "$ref": "#/components/responses/UNPROCESSABLE_CONTENT" }, "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CommitmentSummary" } } } }, "default": { "$ref": "#/components/responses/DEFAULT_ERROR" }, "400": { "description": "Bad request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorResponse" } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorResponse" } } } }, "403": { "description": "Forbidden", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorResponse" } } } }, "404": { "description": "Not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorResponse" } } } }, "409": { "description": "Conflict", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorResponse" } } } }, "405": { "description": "Method not allowed", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorResponse" } } } }, "500": { "description": "Internal server error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorResponse" } } } } }, "tags": [ "Commitments (Beta)" ], "summary": "Get commitment portfolio summary", "description": "Returns an aggregated summary of the organization's active commitment portfolio including total savings, costs, utilization, and breakdowns by term length and commitment type. All metrics are based on the most recent day of usage data." }, "parameters": [ { "in": "path", "name": "org_id", "required": true, "schema": { "type": "string", "format": "uuid" } } ] }, "/beta/v1/org/{org_id}/commitments/{commitment_id}": { "get": { "parameters": [ { "in": "query", "name": "start_date", "description": "Start date for utilization/attribution data (YYYY-MM-DD). Defaults to 1 day ago.", "schema": { "type": "string", "format": "date", "default": null, "nullable": true }, "required": false }, { "in": "query", "name": "end_date", "description": "End date for utilization/attribution data (YYYY-MM-DD). Defaults to today.", "schema": { "type": "string", "format": "date", "default": null, "nullable": true }, "required": false } ], "responses": { "422": { "$ref": "#/components/responses/UNPROCESSABLE_CONTENT" }, "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CommitmentDetail" } } } }, "default": { "$ref": "#/components/responses/DEFAULT_ERROR" }, "400": { "description": "Bad request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorResponse" } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorResponse" } } } }, "403": { "description": "Forbidden", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorResponse" } } } }, "404": { "description": "Not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorResponse" } } } }, "409": { "description": "Conflict", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorResponse" } } } }, "405": { "description": "Method not allowed", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorResponse" } } } }, "500": { "description": "Internal server error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorResponse" } } } } }, "tags": [ "Commitments (Beta)" ], "summary": "Get commitment details", "description": "Returns detailed information about a specific commitment including daily utilization data and an attribution summary showing which resources are covered. Optionally specify start_date/end_date for the utilization and attribution data; defaults to the most recent day." }, "parameters": [ { "in": "path", "name": "org_id", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "in": "path", "name": "commitment_id", "required": true, "schema": { "type": "string", "format": "uuid" } } ] }, "/beta/v1/org/{org_id}/commitments/comparison": { "get": { "parameters": [ { "in": "query", "name": "provider", "description": "Cloud provider (aws, azure, gcp)", "schema": { "example": "aws", "type": "string", "enum": [ "aws", "azure", "gcp", "kubernetes", "unknown" ] }, "required": true }, { "in": "query", "name": "commitment_ids", "description": "Optional subset of commitments to compare. If omitted, defaults to all currently-active commitments for the provider.", "schema": { "type": "array", "default": null, "items": { "type": "string", "format": "uuid" }, "nullable": true }, "required": false, "explode": true, "style": "form" }, { "in": "query", "name": "contract_terms", "description": "Optional list of target terms to roll up. If omitted, the response includes a hypothetical for every distinct contract_term that appears in any commitment's candidates after the payment-option filter.", "schema": { "type": "array", "default": null, "items": { "type": "string", "enum": [ "one_year_gris", "thirty_day_gris", "two_month_gris", "three_month_gris", "four_month_gris", "five_month_gris", "six_month_gris", "seven_month_gris", "eight_month_gris", "nine_month_gris", "ten_month_gris", "eleven_month_gris", "twelve_month_gris", "thirteen_month_gris", "fourteen_month_gris", "fifteen_month_gris", "sixteen_month_gris", "seventeen_month_gris", "eighteen_month_gris", "nineteen_month_gris", "twenty_month_gris", "twenty_one_month_gris", "twenty_two_month_gris", "twenty_three_month_gris", "twenty_four_month_gris", "twenty_five_month_gris", "twenty_six_month_gris", "twenty_seven_month_gris", "twenty_eight_month_gris", "twenty_nine_month_gris", "thirty_month_gris", "thirty_one_month_gris", "thirty_two_month_gris", "thirty_three_month_gris", "thirty_four_month_gris", "thirty_five_month_gris", "one_year", "two_year", "three_year", "five_year", "zero_day", "thirty_day", "two_month", "three_month", "four_month", "five_month", "six_month", "seven_month", "eight_month", "nine_month", "ten_month", "eleven_month", "thirteen_month", "fourteen_month", "fifteen_month", "sixteen_month", "seventeen_month", "eighteen_month", "nineteen_month", "twenty_month", "twenty_one_month", "twenty_two_month", "twenty_three_month", "twenty_five_month", "twenty_six_month", "twenty_seven_month", "twenty_eight_month", "twenty_nine_month", "thirty_month", "thirty_one_month", "thirty_two_month", "thirty_three_month", "thirty_four_month", "thirty_five_month" ] }, "nullable": true }, "required": false, "explode": true, "style": "form" }, { "in": "query", "name": "payment_options", "description": "Payment options to include. Defaults to no_upfront only \u2014 most users are uncomfortable with cash at signing, so this matches the default framing for portfolio comparisons. Pass partial_upfront / all_upfront explicitly to surface those.", "schema": { "type": "array", "items": { "type": "string", "enum": [ "no_upfront", "partial_upfront", "all_upfront" ] } }, "required": false, "explode": true, "style": "form" } ], "responses": { "422": { "$ref": "#/components/responses/UNPROCESSABLE_CONTENT" }, "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CommitmentOfferComparisonResponse" } } } }, "400": { "description": "Bad Request" }, "404": { "description": "Not Found" }, "default": { "$ref": "#/components/responses/DEFAULT_ERROR" }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorResponse" } } } }, "403": { "description": "Forbidden", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorResponse" } } } }, "409": { "description": "Conflict", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorResponse" } } } }, "405": { "description": "Method not allowed", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorResponse" } } } }, "500": { "description": "Internal server error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorResponse" } } } } }, "tags": [ "Commitments (Beta)" ], "summary": "Compare offer alternatives across commitments in a portfolio", "description": "Returns per-commitment offer alternatives plus portfolio-wide rollups for each (contract_term, payment_option) hypothetical. Designed to answer 'how much have I left on the table' / 'what if my portfolio were all 3-year' in a single call: hypothetical_totals carries the rolled-up financials and delta_vs_current, with per-commitment resolution exposed for transparency. Each commitment lands at the target term when available, else the longest available term <= target with the same payment option (GRI preferred within tier), else its current term. Read-only and informational: there is no follow-up write action \u2014 active commitments cannot be swapped programmatically. To actually change term length or offer, the user should reach out to support.\n\n**Single-commitment drilldown**: pass `commitment_ids=[single_id]` to scope the response to one commitment. Same shape, just one entry in `data` and per-(term,payment) rollups that span only that commitment.\n\n**Sizing & underutilization caveat**: candidate grids per commitment are sized from each commitment's SKU usage in the most recent fully-recorded day, NOT from nominal capacity. Per-commitment `utilization_warning` and the rollup-level `low_utilization_commitment_count` flag commitments below 50% utilization \u2014 for those rows, candidate financials are projected against hours that aren't actually consumed and the comparison is structurally less informative. Surface the count when non-zero so totals are framed honestly.\n\n**Rebate handling**: `current.commitment_financials_monthly_rate.commitment_savings.net` is `gross - premium` (no rebate), apples-to-apples with candidates which have no rebate concept. For an active commitment earning rebate income this differs from `commitment_details`'s net (which includes rebate). For true current economics including rebate, use `commitment_details`.\n\n**Skipped commitments**: commitments that fail to build a grid (typically 'no recent SKU usage') are listed in `skipped_commitments` with a reason, NOT silently dropped. They contribute to neither current_totals nor hypothetical_totals.\n\n**Presentation note**: `partial_upfront` and `all_upfront` candidate offers should be de-emphasized by default \u2014 only surface them when an in-scope commitment already has an upfront component or the caller has signaled interest in upfront trades. Use the `payment_options` query arg to filter." }, "parameters": [ { "in": "path", "name": "org_id", "required": true, "schema": { "type": "string", "format": "uuid" } } ] }, "/beta/v1/org/{org_id}/commitments/metrics": { "get": { "parameters": [ { "in": "query", "name": "provider", "description": "Cloud provider (aws, azure, gcp)", "schema": { "example": "aws", "type": "string", "enum": [ "aws", "azure", "gcp", "kubernetes", "unknown" ] }, "required": true }, { "in": "query", "name": "start_date", "description": "Start date (YYYY-MM-DD)", "schema": { "type": "string", "format": "date" }, "required": true }, { "in": "query", "name": "end_date", "description": "End date (YYYY-MM-DD, exclusive)", "schema": { "type": "string", "format": "date" }, "required": true }, { "in": "query", "name": "search", "description": "Text search across commitment fields", "schema": { "type": "string", "default": null, "nullable": true }, "required": false }, { "in": "query", "name": "filter", "description": "JSON filter object \u2014 same shape as `/commitments`. Supported ops: `=`, `!=`, `in` on any field; `>`, `>=`, `<`, `<=` on numeric fields and date fields (`start_date`, `end_date`). Date-dependent metric fields are 730-hour monthly rates evaluated over the requested `start_date` / `end_date` window: `monthly_net_savings`, `monthly_gross_savings`, `monthly_premiums`, `monthly_estimated_rebate`. `utilization` is a 0-1 fraction averaged over the window. Note that the RESPONSE on this endpoint reports period totals (`commitment_financials_period_total.*`), not monthly rates \u2014 so a filter like `{\"field\": \"monthly_net_savings\", \"op\": \">\", \"value\": 1000}` selects commitments saving at >$1000/month rate during the window, even though the response will show the dollar total accumulated over the window itself.", "schema": { "type": "object", "default": null, "additionalProperties": {}, "nullable": true }, "required": false } ], "responses": { "422": { "$ref": "#/components/responses/UNPROCESSABLE_CONTENT" }, "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/MetricsResponse" } } } }, "default": { "$ref": "#/components/responses/DEFAULT_ERROR" }, "400": { "description": "Bad request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorResponse" } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorResponse" } } } }, "403": { "description": "Forbidden", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorResponse" } } } }, "404": { "description": "Not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorResponse" } } } }, "409": { "description": "Conflict", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorResponse" } } } }, "405": { "description": "Method not allowed", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorResponse" } } } }, "500": { "description": "Internal server error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorResponse" } } } } }, "tags": [ "Commitments (Beta)" ], "summary": "Get commitment portfolio metrics over time", "description": "Returns daily commitment metrics (savings, costs, utilization, premiums, rebates) over a time period. Includes per-day data points and period totals. Note: coverage is not included here \u2014 coverage is a segment-level metric. Use the /metrics/daily-coverage endpoint for coverage trends." }, "parameters": [ { "in": "path", "name": "org_id", "required": true, "schema": { "type": "string", "format": "uuid" } } ] }, "/beta/v1/org/{org_id}/metrics/overview": { "get": { "parameters": [ { "in": "query", "name": "provider", "description": "Cloud provider (aws, azure, gcp)", "schema": { "example": "aws", "type": "string", "enum": [ "aws", "azure", "gcp", "kubernetes", "unknown" ] }, "required": true } ], "responses": { "422": { "$ref": "#/components/responses/UNPROCESSABLE_CONTENT" }, "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Overview" } } } }, "default": { "$ref": "#/components/responses/DEFAULT_ERROR" }, "400": { "description": "Bad request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorResponse" } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorResponse" } } } }, "403": { "description": "Forbidden", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorResponse" } } } }, "404": { "description": "Not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorResponse" } } } }, "409": { "description": "Conflict", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorResponse" } } } }, "405": { "description": "Method not allowed", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorResponse" } } } }, "500": { "description": "Internal server error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorResponse" } } } } }, "tags": [ "Metrics (Beta)" ], "summary": "Get organization overview", "description": "Returns a high-level overview of the organization's commitment performance including savings, coverage, utilization, missed savings opportunities, automation status, and prioritized recommended actions." }, "parameters": [ { "in": "path", "name": "org_id", "required": true, "schema": { "type": "string", "format": "uuid" } } ] }, "/beta/v1/org/{org_id}/metrics/daily-coverage": { "get": { "parameters": [ { "in": "query", "name": "provider", "description": "Cloud provider (aws, azure, gcp)", "schema": { "example": "aws", "type": "string", "enum": [ "aws", "azure", "gcp", "kubernetes", "unknown" ] }, "required": true }, { "in": "query", "name": "segment_id", "description": "Optional segment ID to scope results. Defaults to the provider resources segment if not specified.", "schema": { "type": "string", "format": "uuid", "default": null, "nullable": true }, "required": false }, { "in": "query", "name": "start_date", "description": "Start date (YYYY-MM-DD)", "schema": { "type": "string", "format": "date" }, "required": true }, { "in": "query", "name": "end_date", "description": "End date (YYYY-MM-DD, exclusive)", "schema": { "type": "string", "format": "date" }, "required": true } ], "responses": { "422": { "$ref": "#/components/responses/UNPROCESSABLE_CONTENT" }, "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DailyCoverageResponse" } } } }, "default": { "$ref": "#/components/responses/DEFAULT_ERROR" }, "400": { "description": "Bad request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorResponse" } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorResponse" } } } }, "403": { "description": "Forbidden", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorResponse" } } } }, "404": { "description": "Not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorResponse" } } } }, "409": { "description": "Conflict", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorResponse" } } } }, "405": { "description": "Method not allowed", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorResponse" } } } }, "500": { "description": "Internal server error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorResponse" } } } } }, "tags": [ "Metrics (Beta)" ], "summary": "Get daily coverage", "description": "Returns the mean commitment coverage over the requested date range, plus per-day values for trend analysis." }, "parameters": [ { "in": "path", "name": "org_id", "required": true, "schema": { "type": "string", "format": "uuid" } } ] }, "/beta/v1/org/{org_id}/metrics/daily-savings": { "get": { "parameters": [ { "in": "query", "name": "provider", "description": "Cloud provider (aws, azure, gcp)", "schema": { "example": "aws", "type": "string", "enum": [ "aws", "azure", "gcp", "kubernetes", "unknown" ] }, "required": true }, { "in": "query", "name": "segment_id", "description": "Optional segment ID to scope results. Defaults to the provider resources segment if not specified.", "schema": { "type": "string", "format": "uuid", "default": null, "nullable": true }, "required": false }, { "in": "query", "name": "start_date", "description": "Start date (YYYY-MM-DD)", "schema": { "type": "string", "format": "date" }, "required": true }, { "in": "query", "name": "end_date", "description": "End date (YYYY-MM-DD, exclusive)", "schema": { "type": "string", "format": "date" }, "required": true } ], "responses": { "422": { "$ref": "#/components/responses/UNPROCESSABLE_CONTENT" }, "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DailySavingsResponse" } } } }, "default": { "$ref": "#/components/responses/DEFAULT_ERROR" }, "400": { "description": "Bad request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorResponse" } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorResponse" } } } }, "403": { "description": "Forbidden", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorResponse" } } } }, "404": { "description": "Not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorResponse" } } } }, "409": { "description": "Conflict", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorResponse" } } } }, "405": { "description": "Method not allowed", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorResponse" } } } }, "500": { "description": "Internal server error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorResponse" } } } } }, "tags": [ "Metrics (Beta)" ], "summary": "Get daily savings", "description": "Returns daily commitment savings with cost and savings grouped, plus period-level totals." }, "parameters": [ { "in": "path", "name": "org_id", "required": true, "schema": { "type": "string", "format": "uuid" } } ] }, "/beta/v1/org/{org_id}/metrics/daily-reservable-cost": { "get": { "parameters": [ { "in": "query", "name": "provider", "description": "Cloud provider (aws, azure, gcp)", "schema": { "example": "aws", "type": "string", "enum": [ "aws", "azure", "gcp", "kubernetes", "unknown" ] }, "required": true }, { "in": "query", "name": "segment_id", "description": "Optional segment ID to scope results. Defaults to the provider resources segment if not specified.", "schema": { "type": "string", "format": "uuid", "default": null, "nullable": true }, "required": false }, { "in": "query", "name": "start_date", "description": "Start date (YYYY-MM-DD)", "schema": { "type": "string", "format": "date" }, "required": true }, { "in": "query", "name": "end_date", "description": "End date (YYYY-MM-DD, exclusive)", "schema": { "type": "string", "format": "date" }, "required": true } ], "responses": { "422": { "$ref": "#/components/responses/UNPROCESSABLE_CONTENT" }, "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DailyReservableCostResponse" } } } }, "default": { "$ref": "#/components/responses/DEFAULT_ERROR" }, "400": { "description": "Bad request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorResponse" } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorResponse" } } } }, "403": { "description": "Forbidden", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorResponse" } } } }, "404": { "description": "Not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorResponse" } } } }, "409": { "description": "Conflict", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorResponse" } } } }, "405": { "description": "Method not allowed", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorResponse" } } } }, "500": { "description": "Internal server error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorResponse" } } } } }, "tags": [ "Metrics (Beta)" ], "summary": "Get daily reservable cost breakdown", "description": "Returns daily cost for reservable services over the date range, split by pricing type (on-demand, commitment-covered, spot). The commitment bucket is further split into cloud_provider_cost + archera_premium. Includes period-level totals and total savings vs on-demand baseline." }, "parameters": [ { "in": "path", "name": "org_id", "required": true, "schema": { "type": "string", "format": "uuid" } } ] }, "/beta/v1/org/{org_id}/segments/filters": { "get": { "parameters": [ { "in": "query", "name": "provider", "description": "Cloud provider (aws, azure, gcp)", "schema": { "example": "aws", "type": "string", "enum": [ "aws", "azure", "gcp", "kubernetes", "unknown" ] }, "required": true } ], "responses": { "422": { "$ref": "#/components/responses/UNPROCESSABLE_CONTENT" }, "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "array", "items": { "$ref": "#/components/schemas/BaseAttribute" } } } } }, "default": { "$ref": "#/components/responses/DEFAULT_ERROR" }, "400": { "description": "Bad request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorResponse" } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorResponse" } } } }, "403": { "description": "Forbidden", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorResponse" } } } }, "404": { "description": "Not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorResponse" } } } }, "409": { "description": "Conflict", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorResponse" } } } }, "405": { "description": "Method not allowed", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorResponse" } } } }, "500": { "description": "Internal server error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorResponse" } } } } }, "tags": [ "Segments (Beta)" ], "summary": "List filterable segment fields", "description": "Returns the fields that can be used in segment filter expressions. Call /segments/filters/ for valid values within the provider scope." }, "parameters": [ { "in": "path", "name": "org_id", "required": true, "schema": { "type": "string", "format": "uuid" } } ] }, "/beta/v1/org/{org_id}/segments/filters/{field}": { "get": { "parameters": [ { "in": "query", "name": "provider", "description": "Cloud provider (aws, azure, gcp)", "schema": { "example": "aws", "type": "string", "enum": [ "aws", "azure", "gcp", "kubernetes", "unknown" ] }, "required": true } ], "responses": { "422": { "$ref": "#/components/responses/UNPROCESSABLE_CONTENT" }, "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Attribute" } } } }, "default": { "$ref": "#/components/responses/DEFAULT_ERROR" }, "400": { "description": "Bad request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorResponse" } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorResponse" } } } }, "403": { "description": "Forbidden", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorResponse" } } } }, "404": { "description": "Not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorResponse" } } } }, "409": { "description": "Conflict", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorResponse" } } } }, "405": { "description": "Method not allowed", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorResponse" } } } }, "500": { "description": "Internal server error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorResponse" } } } } }, "tags": [ "Segments (Beta)" ], "summary": "Get valid values for a segment filter field", "description": "Returns the distinct values for a given segment filter field, scoped to the provider, org, current attribution, and active integrations." }, "parameters": [ { "in": "path", "name": "org_id", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "in": "path", "name": "field", "required": true, "schema": { "type": "string", "minLength": 1 } } ] }, "/beta/v1/org/{org_id}/segments": { "get": { "parameters": [ { "in": "query", "name": "provider", "description": "Cloud provider (aws, azure, gcp)", "schema": { "example": "aws", "type": "string", "enum": [ "aws", "azure", "gcp", "kubernetes", "unknown" ] }, "required": true } ], "responses": { "422": { "$ref": "#/components/responses/UNPROCESSABLE_CONTENT" }, "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "array", "items": { "$ref": "#/components/schemas/Segment" } } } } }, "default": { "$ref": "#/components/responses/DEFAULT_ERROR" }, "400": { "description": "Bad request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorResponse" } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorResponse" } } } }, "403": { "description": "Forbidden", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorResponse" } } } }, "404": { "description": "Not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorResponse" } } } }, "409": { "description": "Conflict", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorResponse" } } } }, "405": { "description": "Method not allowed", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorResponse" } } } }, "500": { "description": "Internal server error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorResponse" } } } } }, "tags": [ "Segments (Beta)" ], "summary": "List segments", "description": "Returns all segments for the specified provider with pre-aggregated monthly metrics." }, "post": { "responses": { "422": { "$ref": "#/components/responses/UNPROCESSABLE_CONTENT" }, "201": { "description": "Created", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Segment" } } } }, "default": { "$ref": "#/components/responses/DEFAULT_ERROR" }, "400": { "description": "Bad request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorResponse" } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorResponse" } } } }, "403": { "description": "Forbidden", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorResponse" } } } }, "404": { "description": "Not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorResponse" } } } }, "409": { "description": "Conflict", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorResponse" } } } }, "405": { "description": "Method not allowed", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorResponse" } } } }, "500": { "description": "Internal server error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorResponse" } } } } }, "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CreateSegmentArgs" } } } }, "tags": [ "Segments (Beta)" ], "summary": "Create a new segment", "description": "Creates a new segment with the specified filter configuration. The provider filter is injected automatically \u2014 only include filters for resource attributes you want to narrow on." }, "parameters": [ { "in": "path", "name": "org_id", "required": true, "schema": { "type": "string", "format": "uuid" } } ] }, "/beta/v1/org/{org_id}/segments/{segment_id}": { "get": { "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Segment" } } } }, "default": { "$ref": "#/components/responses/DEFAULT_ERROR" }, "400": { "description": "Bad request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorResponse" } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorResponse" } } } }, "403": { "description": "Forbidden", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorResponse" } } } }, "404": { "description": "Not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorResponse" } } } }, "409": { "description": "Conflict", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorResponse" } } } }, "405": { "description": "Method not allowed", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorResponse" } } } }, "500": { "description": "Internal server error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorResponse" } } } } }, "tags": [ "Segments (Beta)" ], "summary": "Get segment details", "description": "Returns details for a single segment including monthly metrics." }, "parameters": [ { "in": "path", "name": "org_id", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "in": "path", "name": "segment_id", "required": true, "schema": { "type": "string", "format": "uuid" } } ] }, "/beta/v1/org/{org_id}/invoices": { "get": { "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "array", "items": { "$ref": "#/components/schemas/InvoiceList" } } } } }, "default": { "$ref": "#/components/responses/DEFAULT_ERROR" }, "400": { "description": "Bad request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorResponse" } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorResponse" } } } }, "403": { "description": "Forbidden", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorResponse" } } } }, "404": { "description": "Not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorResponse" } } } }, "409": { "description": "Conflict", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorResponse" } } } }, "405": { "description": "Method not allowed", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorResponse" } } } }, "500": { "description": "Internal server error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorResponse" } } } } }, "tags": [ "Invoices (Beta)" ], "summary": "List invoices", "description": "Returns all invoices for the organization, most recent first. Invoices are generated monthly once cloud provider bills are finalized and are the source of truth for Archera premiums and rebates. Per-term breakdowns are only included on the detail endpoint." }, "parameters": [ { "in": "path", "name": "org_id", "required": true, "schema": { "type": "string", "format": "uuid" } } ] }, "/beta/v1/org/{org_id}/invoices/{year}/{month}": { "get": { "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Invoice" } } } }, "default": { "$ref": "#/components/responses/DEFAULT_ERROR" }, "400": { "description": "Bad request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorResponse" } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorResponse" } } } }, "403": { "description": "Forbidden", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorResponse" } } } }, "404": { "description": "Not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorResponse" } } } }, "409": { "description": "Conflict", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorResponse" } } } }, "405": { "description": "Method not allowed", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorResponse" } } } }, "500": { "description": "Internal server error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorResponse" } } } } }, "tags": [ "Invoices (Beta)" ], "summary": "Get invoice by year and month", "description": "Returns a single invoice for the specified year and month. Invoices are the source of truth for Archera fees and premiums charged during each billing cycle." }, "parameters": [ { "in": "path", "name": "org_id", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "in": "path", "name": "year", "required": true, "schema": { "type": "integer", "minimum": 0 } }, { "in": "path", "name": "month", "required": true, "schema": { "type": "integer", "minimum": 0 } } ] }, "/beta/v1/org/{org_id}/invoices/{year}/{month}/line-items": { "get": { "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "array", "items": { "$ref": "#/components/schemas/InvoiceLineItem" } } } } }, "default": { "$ref": "#/components/responses/DEFAULT_ERROR" }, "400": { "description": "Bad request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorResponse" } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorResponse" } } } }, "403": { "description": "Forbidden", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorResponse" } } } }, "404": { "description": "Not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorResponse" } } } }, "409": { "description": "Conflict", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorResponse" } } } }, "405": { "description": "Method not allowed", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorResponse" } } } }, "500": { "description": "Internal server error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorResponse" } } } } }, "tags": [ "Invoices (Beta)" ], "summary": "Get invoice line items", "description": "Returns all line items for the specified invoice, showing per-commitment charges, savings, premiums, and rebates." }, "parameters": [ { "in": "path", "name": "org_id", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "in": "path", "name": "year", "required": true, "schema": { "type": "integer", "minimum": 0 } }, { "in": "path", "name": "month", "required": true, "schema": { "type": "integer", "minimum": 0 } } ] }, "/beta/v1/org/{org_id}/cost-explorer": { "get": { "parameters": [ { "in": "query", "name": "provider", "description": "Cloud provider (aws, azure, gcp)", "schema": { "example": "aws", "type": "string", "enum": [ "aws", "azure", "gcp", "kubernetes", "unknown" ] }, "required": true }, { "in": "query", "name": "segment_id", "description": "Optional segment ID to scope results. Defaults to the provider resources segment if not specified.", "schema": { "type": "string", "format": "uuid", "default": null, "nullable": true }, "required": false }, { "in": "query", "name": "start_date", "description": "Start date (YYYY-MM-DD)", "schema": { "type": "string", "format": "date" }, "required": true }, { "in": "query", "name": "end_date", "description": "End date (YYYY-MM-DD, exclusive)", "schema": { "type": "string", "format": "date" }, "required": true }, { "in": "query", "name": "group_by", "description": "Dimension to group costs by: 'service', 'account', or 'region'. If omitted, returns total spend without grouping.", "schema": { "default": null, "type": "string", "enum": [ "service", "account", "region", null ], "nullable": true }, "required": false }, { "in": "query", "name": "granularity", "description": "Time granularity: 'daily' or 'monthly' (default 'daily')", "schema": { "default": "daily", "type": "string", "enum": [ "daily", "monthly" ] }, "required": false }, { "in": "query", "name": "metric", "description": "Cost metric to use. 'amortized' (default): includes upfront costs spread over commitment term. 'unblended' (AWS only): actual charges as they appear on the bill. 'actual' (Azure/GCP only): equivalent to unblended for Azure and GCP.", "schema": { "default": "amortized", "type": "string", "enum": [ "amortized", "unblended", "actual" ] }, "required": false }, { "in": "query", "name": "top_n", "description": "Return only the top N groups by cost, with remaining groups combined into 'Other'. If omitted, returns all groups.", "schema": { "type": "integer", "default": null, "minimum": 1, "nullable": true }, "required": false }, { "in": "query", "name": "include_discounts_and_credits", "description": "Include credits, refunds, and enterprise discounts (AWS EDP/PPA, Azure MACC, GCP commit agreements) in the cost data. Default false (shows spend before credits and discounts).", "schema": { "type": "boolean", "default": false }, "required": false }, { "in": "query", "name": "include_time_series", "description": "Include time-series data points for each group. Default true. Set to false for compact summary-only responses.", "schema": { "type": "boolean", "default": true }, "required": false }, { "in": "query", "name": "filter", "description": "Pre-query filter applied before grouping. Uses field/op/value with and/or/not combinators. Supported operators: = (equals), != (not equals), in (list of values). Available fields: service, account_id, region, instance_type, instance_family, operating_system, tenancy. Example: {\"field\": \"service\", \"op\": \"!=\", \"value\": \"Tax\"}", "schema": { "type": "object", "default": null, "additionalProperties": {}, "nullable": true }, "required": false } ], "responses": { "422": { "$ref": "#/components/responses/UNPROCESSABLE_CONTENT" }, "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CostExplorerResponse" } } } }, "default": { "$ref": "#/components/responses/DEFAULT_ERROR" }, "400": { "description": "Bad request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorResponse" } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorResponse" } } } }, "403": { "description": "Forbidden", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorResponse" } } } }, "404": { "description": "Not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorResponse" } } } }, "409": { "description": "Conflict", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorResponse" } } } }, "405": { "description": "Method not allowed", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorResponse" } } } }, "500": { "description": "Internal server error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorResponse" } } } } }, "tags": [ "Cost Explorer (Beta)" ], "summary": "Explore total cloud spend", "description": "Returns total cloud spend over a date range, optionally grouped by service, account, or region. Includes all cost types (not just reservable). Data comes from cloud provider Cost Explorer APIs." }, "parameters": [ { "in": "path", "name": "org_id", "required": true, "schema": { "type": "string", "format": "uuid" } } ] }, "/beta/v1/org/{org_id}/cost-explorer/filters": { "get": { "parameters": [ { "in": "query", "name": "provider", "description": "Cloud provider (aws, azure, gcp)", "schema": { "example": "aws", "type": "string", "enum": [ "aws", "azure", "gcp", "kubernetes", "unknown" ] }, "required": true } ], "responses": { "422": { "$ref": "#/components/responses/UNPROCESSABLE_CONTENT" }, "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CostExplorerFilters" } } } }, "default": { "$ref": "#/components/responses/DEFAULT_ERROR" }, "400": { "description": "Bad request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorResponse" } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorResponse" } } } }, "403": { "description": "Forbidden", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorResponse" } } } }, "404": { "description": "Not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorResponse" } } } }, "409": { "description": "Conflict", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorResponse" } } } }, "405": { "description": "Method not allowed", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorResponse" } } } }, "500": { "description": "Internal server error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorResponse" } } } } }, "tags": [ "Cost Explorer (Beta)" ], "summary": "Get available cost-explorer filter fields and values", "description": "Returns the valid filter fields and their possible values for building cost-explorer filter parameters. Field names in the response can be used directly as the 'field' value in filter expressions." }, "parameters": [ { "in": "path", "name": "org_id", "required": true, "schema": { "type": "string", "format": "uuid" } } ] }, "/beta/v1/org/{org_id}/integrations": { "get": { "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "array", "items": { "$ref": "#/components/schemas/Integration" } } } } }, "default": { "$ref": "#/components/responses/DEFAULT_ERROR" }, "400": { "description": "Bad request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorResponse" } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorResponse" } } } }, "403": { "description": "Forbidden", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorResponse" } } } }, "404": { "description": "Not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorResponse" } } } }, "409": { "description": "Conflict", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorResponse" } } } }, "405": { "description": "Method not allowed", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorResponse" } } } }, "500": { "description": "Internal server error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorResponse" } } } } }, "tags": [ "Integrations (Beta)" ], "summary": "List integrations", "description": "Returns all active cloud provider integrations for the organization." }, "parameters": [ { "in": "path", "name": "org_id", "required": true, "schema": { "type": "string", "format": "uuid" } } ] }, "/beta/v1/org/{org_id}/integrations/{integration_id}": { "get": { "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/IntegrationDetail" } } } }, "default": { "$ref": "#/components/responses/DEFAULT_ERROR" }, "400": { "description": "Bad request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorResponse" } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorResponse" } } } }, "403": { "description": "Forbidden", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorResponse" } } } }, "404": { "description": "Not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorResponse" } } } }, "409": { "description": "Conflict", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorResponse" } } } }, "405": { "description": "Method not allowed", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorResponse" } } } }, "500": { "description": "Internal server error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorResponse" } } } } }, "tags": [ "Integrations (Beta)" ], "summary": "Get integration details", "description": "Returns details for a single integration including its cloud accounts." }, "parameters": [ { "in": "path", "name": "org_id", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "in": "path", "name": "integration_id", "required": true, "schema": { "type": "string", "format": "uuid" } } ] }, "/beta/v1/org/{org_id}/resources/skus/attributes": { "get": { "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "array", "items": { "$ref": "#/components/schemas/BaseAttribute" } } } } }, "default": { "$ref": "#/components/responses/DEFAULT_ERROR" }, "400": { "description": "Bad request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorResponse" } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorResponse" } } } }, "403": { "description": "Forbidden", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorResponse" } } } }, "404": { "description": "Not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorResponse" } } } }, "409": { "description": "Conflict", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorResponse" } } } }, "405": { "description": "Method not allowed", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorResponse" } } } }, "500": { "description": "Internal server error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorResponse" } } } } }, "summary": "List filterable resource SKU attributes", "tags": [ "Resources (Beta)" ], "description": "Returns the fields that can be used in the 'filter' parameter of the /resources/skus list endpoint, along with their types." }, "parameters": [ { "in": "path", "name": "org_id", "required": true, "schema": { "type": "string", "format": "uuid" } } ] }, "/beta/v1/org/{org_id}/resources/skus/attributes/{field}": { "get": { "parameters": [ { "in": "query", "name": "provider", "description": "Cloud provider (aws, azure, gcp)", "schema": { "example": "aws", "type": "string", "enum": [ "aws", "azure", "gcp", "kubernetes", "unknown" ] }, "required": true }, { "in": "query", "name": "segment_id", "description": "Optional segment ID to scope results. Defaults to the provider resources segment if not specified.", "schema": { "type": "string", "format": "uuid", "default": null, "nullable": true }, "required": false }, { "in": "query", "name": "search", "description": "Text search across resource id, name, provider_resource_id, account ids, and the curated SKU attribute fields (service, region_code, instance_type, etc.). Use for fuzzy id/name lookups; use `filter` for structured queries.", "schema": { "type": "string", "default": null, "nullable": true }, "required": false }, { "in": "query", "name": "filter", "description": "JSON filter object \u2014 tree of {field, op, value} leaves combined with and / or / not. Supported ops: `=`, `!=`, `in` on scalar fields; `has` on `tags` with nested key/value filters; `>`, `>=`, `<`, `<=` on numeric/percent fields (`total_cost`, `ondemand_cost`, `gross_savings`, `coverage`, `uptime`) and date fields (`usage_start`, `usage_end`). Examples: {\"and\": [{\"field\": \"service\", \"op\": \"=\", \"value\": \"Amazon Elastic Compute Cloud - Compute\"}, {\"field\": \"instance_type\", \"op\": \"=\", \"value\": \"m5.large\"}]} \u2014 categorical; {\"field\": \"tags\", \"op\": \"has\", \"value\": {\"and\": [{\"field\": \"key\", \"op\": \"=\", \"value\": \"Environment\"}, {\"field\": \"value\", \"op\": \"=\", \"value\": \"production\"}]}} \u2014 tag match; {\"field\": \"total_cost\", \"op\": \">\", \"value\": 1000} \u2014 spend > $1k; {\"field\": \"coverage\", \"op\": \"<\", \"value\": 0.5} \u2014 under-covered. Call /resources/skus/attributes for filterable fields and /resources/skus/attributes/ for valid categorical values within the current scope. Trailing-30-day spend/usage aggregates pair well with `order_by` for 'highest cost in service X' / 'lowest uptime' style queries.", "schema": { "type": "object", "default": null, "additionalProperties": {}, "nullable": true }, "required": false }, { "in": "query", "name": "order_by", "description": "Field to order results by. Includes the trailing-30-day spend/usage aggregates (`total_cost`, `ondemand_cost`, `gross_savings`, `coverage`, `uptime`).", "schema": { "type": "string", "default": "id", "enum": [ "id", "usage_start", "usage_end", "instance_type", "service", "region_code", "total_cost", "ondemand_cost", "gross_savings", "coverage", "uptime" ] }, "required": false }, { "in": "query", "name": "desc", "description": "Sort descending", "schema": { "type": "boolean", "default": false }, "required": false } ], "responses": { "422": { "$ref": "#/components/responses/UNPROCESSABLE_CONTENT" }, "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Attribute" } } } }, "default": { "$ref": "#/components/responses/DEFAULT_ERROR" }, "400": { "description": "Bad request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorResponse" } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorResponse" } } } }, "403": { "description": "Forbidden", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorResponse" } } } }, "404": { "description": "Not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorResponse" } } } }, "409": { "description": "Conflict", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorResponse" } } } }, "405": { "description": "Method not allowed", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorResponse" } } } }, "500": { "description": "Internal server error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorResponse" } } } } }, "summary": "Get valid values for a filterable resource SKU attribute", "tags": [ "Resources (Beta)" ], "description": "Returns the distinct values for a given field, scoped to the same provider/segment/filter as the list endpoint. Use this to narrow refinements (e.g. ask for valid instance_type values for a given service+region before issuing a list call) without paginating through SKU rows." }, "parameters": [ { "in": "path", "name": "org_id", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "in": "path", "name": "field", "required": true, "schema": { "type": "string", "minLength": 1 } } ] }, "/beta/v1/org/{org_id}/resources/skus": { "get": { "parameters": [ { "in": "query", "name": "provider", "description": "Cloud provider (aws, azure, gcp)", "schema": { "example": "aws", "type": "string", "enum": [ "aws", "azure", "gcp", "kubernetes", "unknown" ] }, "required": true }, { "in": "query", "name": "segment_id", "description": "Optional segment ID to scope results. Defaults to the provider resources segment if not specified.", "schema": { "type": "string", "format": "uuid", "default": null, "nullable": true }, "required": false }, { "in": "query", "name": "search", "description": "Text search across resource id, name, provider_resource_id, account ids, and the curated SKU attribute fields (service, region_code, instance_type, etc.). Use for fuzzy id/name lookups; use `filter` for structured queries.", "schema": { "type": "string", "default": null, "nullable": true }, "required": false }, { "in": "query", "name": "filter", "description": "JSON filter object \u2014 tree of {field, op, value} leaves combined with and / or / not. Supported ops: `=`, `!=`, `in` on scalar fields; `has` on `tags` with nested key/value filters; `>`, `>=`, `<`, `<=` on numeric/percent fields (`total_cost`, `ondemand_cost`, `gross_savings`, `coverage`, `uptime`) and date fields (`usage_start`, `usage_end`). Examples: {\"and\": [{\"field\": \"service\", \"op\": \"=\", \"value\": \"Amazon Elastic Compute Cloud - Compute\"}, {\"field\": \"instance_type\", \"op\": \"=\", \"value\": \"m5.large\"}]} \u2014 categorical; {\"field\": \"tags\", \"op\": \"has\", \"value\": {\"and\": [{\"field\": \"key\", \"op\": \"=\", \"value\": \"Environment\"}, {\"field\": \"value\", \"op\": \"=\", \"value\": \"production\"}]}} \u2014 tag match; {\"field\": \"total_cost\", \"op\": \">\", \"value\": 1000} \u2014 spend > $1k; {\"field\": \"coverage\", \"op\": \"<\", \"value\": 0.5} \u2014 under-covered. Call /resources/skus/attributes for filterable fields and /resources/skus/attributes/ for valid categorical values within the current scope. Trailing-30-day spend/usage aggregates pair well with `order_by` for 'highest cost in service X' / 'lowest uptime' style queries.", "schema": { "type": "object", "default": null, "additionalProperties": {}, "nullable": true }, "required": false }, { "in": "query", "name": "order_by", "description": "Field to order results by. Includes the trailing-30-day spend/usage aggregates (`total_cost`, `ondemand_cost`, `gross_savings`, `coverage`, `uptime`).", "schema": { "type": "string", "default": "id", "enum": [ "id", "usage_start", "usage_end", "instance_type", "service", "region_code", "total_cost", "ondemand_cost", "gross_savings", "coverage", "uptime" ] }, "required": false }, { "in": "query", "name": "desc", "description": "Sort descending", "schema": { "type": "boolean", "default": false }, "required": false }, { "in": "query", "name": "page", "schema": { "type": "integer", "default": 1, "minimum": 1 }, "required": false }, { "in": "query", "name": "page_size", "schema": { "type": "integer", "default": 20, "minimum": 1, "maximum": 100 }, "required": false } ], "responses": { "422": { "$ref": "#/components/responses/UNPROCESSABLE_CONTENT" }, "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "array", "items": { "$ref": "#/components/schemas/ResourceSKUWithMetrics" } } } }, "headers": { "X-Pagination": { "$ref": "#/components/headers/PAGINATION" } } }, "default": { "$ref": "#/components/responses/DEFAULT_ERROR" }, "400": { "description": "Bad request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorResponse" } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorResponse" } } } }, "403": { "description": "Forbidden", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorResponse" } } } }, "404": { "description": "Not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorResponse" } } } }, "409": { "description": "Conflict", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorResponse" } } } }, "405": { "description": "Method not allowed", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorResponse" } } } }, "500": { "description": "Internal server error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorResponse" } } } } }, "tags": [ "Resources (Beta)" ], "summary": "List resource SKU rows in the customer's environment", "description": "Returns ResourceSKU rows (resource x SKU x time-window) scoped to the specified provider segment and the org's current attribution. Each row is one observation period of a resource running with a specific SKU; the same underlying resource may appear multiple times if it changed SKUs. Cross-reference catalog SKUs via (catalog_sku_org_id, catalog_sku_id). Cursor-paginated: `X-Pagination` includes `page`, `first_page`, `previous_page`, and `next_page` \u2014 no `total` / `total_pages` (skipped to avoid a slow Snowflake COUNT(*) on large customers)." }, "parameters": [ { "in": "path", "name": "org_id", "required": true, "schema": { "type": "string", "format": "uuid" } } ] }, "/beta/v1/org/{org_id}/resources/skus/{resource_sku_id}": { "get": { "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ResourceSKUDetail" } } } }, "404": { "description": "Not Found" }, "default": { "$ref": "#/components/responses/DEFAULT_ERROR" }, "400": { "description": "Bad request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorResponse" } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorResponse" } } } }, "403": { "description": "Forbidden", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorResponse" } } } }, "409": { "description": "Conflict", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorResponse" } } } }, "405": { "description": "Method not allowed", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorResponse" } } } }, "500": { "description": "Internal server error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorResponse" } } } } }, "tags": [ "Resources (Beta)" ], "summary": "Get a single resource SKU row's full detail", "description": "Returns the full ResourceSKU record \u2014 list-view fields plus hardware specs, the raw catalog attribute blob, and SKU lifecycle dates. The id is the composite `||` returned by the list endpoint; pass it through verbatim. Scope: org + current attribution + the org's integrations \u2014 intentionally NOT narrowed by segment, unlike the list endpoint. Detail is an id-based fetch, not a browse query, so once a row's id is known it resolves regardless of which segment surfaced it. The asymmetry is one-directional: any row visible in the list (segment-scoped) is also visible here (org-scoped), so the list-then-detail flow never 404s on scope alone." }, "parameters": [ { "in": "path", "name": "org_id", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "in": "path", "name": "resource_sku_id", "required": true, "schema": { "type": "string", "minLength": 1 } } ] }, "/beta/v1/org/{org_id}/catalog/skus/attributes": { "get": { "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "array", "items": { "$ref": "#/components/schemas/BaseAttribute" } } } } }, "default": { "$ref": "#/components/responses/DEFAULT_ERROR" }, "400": { "description": "Bad request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorResponse" } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorResponse" } } } }, "403": { "description": "Forbidden", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorResponse" } } } }, "404": { "description": "Not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorResponse" } } } }, "409": { "description": "Conflict", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorResponse" } } } }, "405": { "description": "Method not allowed", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorResponse" } } } }, "500": { "description": "Internal server error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorResponse" } } } } }, "summary": "List filterable catalog SKU attributes", "tags": [ "Catalog (Beta)" ], "description": "Returns the fields that can be used in the 'filter' parameter of the catalog SKU list endpoint, along with their types." }, "parameters": [ { "in": "path", "name": "org_id", "required": true, "schema": { "type": "string", "format": "uuid" } } ] }, "/beta/v1/org/{org_id}/catalog/skus/attributes/{field}": { "get": { "parameters": [ { "in": "query", "name": "provider", "description": "Cloud provider (aws, azure, gcp)", "schema": { "example": "aws", "type": "string", "enum": [ "aws", "azure", "gcp", "kubernetes", "unknown" ] }, "required": true }, { "in": "query", "name": "search", "description": "Text search across SKU name, description, service, and the curated attribute fields (e.g. instance_type, region_code).", "schema": { "type": "string", "default": null, "nullable": true }, "required": false }, { "in": "query", "name": "filter", "description": "JSON filter object \u2014 tree of {field, op, value} leaves combined with and / or / not. Supported ops: `=`, `!=`, `in` on any field; `>`, `>=`, `<`, `<=` on numeric fields (`ondemand_usage_price`, `vcpu`, `memory`). Examples: {\"and\": [{\"field\": \"service\", \"op\": \"=\", \"value\": \"Amazon Elastic Compute Cloud - Compute\"}, {\"field\": \"instance_type\", \"op\": \"=\", \"value\": \"m5.large\"}]} \u2014 categorical; {\"field\": \"ondemand_usage_price\", \"op\": \"<\", \"value\": 0.10} \u2014 under $0.10/hr; {\"field\": \"vcpu\", \"op\": \">=\", \"value\": 16} \u2014 \u226516 vCPU. `memory` is in BYTES \u2014 divide by 2**30 for GiB / 1e9 for GB before comparing. Call /attributes for the filterable fields and /attributes/ for valid categorical values within the current scope.", "schema": { "type": "object", "default": null, "additionalProperties": {}, "nullable": true }, "required": false }, { "in": "query", "name": "order_by", "description": "Field to order results by. Includes the numeric specs (`ondemand_usage_price`, `vcpu`, `memory`) for sorting by price or size.", "schema": { "type": "string", "default": "instance_type", "enum": [ "instance_type", "service", "region_code", "ondemand_usage_price", "vcpu", "memory" ] }, "required": false }, { "in": "query", "name": "desc", "description": "Sort descending", "schema": { "type": "boolean", "default": false }, "required": false } ], "responses": { "422": { "$ref": "#/components/responses/UNPROCESSABLE_CONTENT" }, "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Attribute" } } } }, "default": { "$ref": "#/components/responses/DEFAULT_ERROR" }, "400": { "description": "Bad request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorResponse" } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorResponse" } } } }, "403": { "description": "Forbidden", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorResponse" } } } }, "404": { "description": "Not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorResponse" } } } }, "409": { "description": "Conflict", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorResponse" } } } }, "405": { "description": "Method not allowed", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorResponse" } } } }, "500": { "description": "Internal server error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorResponse" } } } } }, "summary": "Get valid values for a filterable catalog SKU attribute", "tags": [ "Catalog (Beta)" ], "description": "Returns the distinct values for a given field, scoped to the same filters that would be applied on the list endpoint. Use this to narrow refinements (e.g. ask for valid instance_type values for a given service+region before issuing a list call)." }, "parameters": [ { "in": "path", "name": "org_id", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "in": "path", "name": "field", "required": true, "schema": { "type": "string", "minLength": 1 } } ] }, "/beta/v1/org/{org_id}/catalog/skus": { "get": { "parameters": [ { "in": "query", "name": "provider", "description": "Cloud provider (aws, azure, gcp)", "schema": { "example": "aws", "type": "string", "enum": [ "aws", "azure", "gcp", "kubernetes", "unknown" ] }, "required": true }, { "in": "query", "name": "search", "description": "Text search across SKU name, description, service, and the curated attribute fields (e.g. instance_type, region_code).", "schema": { "type": "string", "default": null, "nullable": true }, "required": false }, { "in": "query", "name": "filter", "description": "JSON filter object \u2014 tree of {field, op, value} leaves combined with and / or / not. Supported ops: `=`, `!=`, `in` on any field; `>`, `>=`, `<`, `<=` on numeric fields (`ondemand_usage_price`, `vcpu`, `memory`). Examples: {\"and\": [{\"field\": \"service\", \"op\": \"=\", \"value\": \"Amazon Elastic Compute Cloud - Compute\"}, {\"field\": \"instance_type\", \"op\": \"=\", \"value\": \"m5.large\"}]} \u2014 categorical; {\"field\": \"ondemand_usage_price\", \"op\": \"<\", \"value\": 0.10} \u2014 under $0.10/hr; {\"field\": \"vcpu\", \"op\": \">=\", \"value\": 16} \u2014 \u226516 vCPU. `memory` is in BYTES \u2014 divide by 2**30 for GiB / 1e9 for GB before comparing. Call /attributes for the filterable fields and /attributes/ for valid categorical values within the current scope.", "schema": { "type": "object", "default": null, "additionalProperties": {}, "nullable": true }, "required": false }, { "in": "query", "name": "order_by", "description": "Field to order results by. Includes the numeric specs (`ondemand_usage_price`, `vcpu`, `memory`) for sorting by price or size.", "schema": { "type": "string", "default": "instance_type", "enum": [ "instance_type", "service", "region_code", "ondemand_usage_price", "vcpu", "memory" ] }, "required": false }, { "in": "query", "name": "desc", "description": "Sort descending", "schema": { "type": "boolean", "default": false }, "required": false }, { "in": "query", "name": "page", "schema": { "type": "integer", "default": 1, "minimum": 1 }, "required": false }, { "in": "query", "name": "page_size", "schema": { "type": "integer", "default": 20, "minimum": 1, "maximum": 100 }, "required": false } ], "responses": { "422": { "$ref": "#/components/responses/UNPROCESSABLE_CONTENT" }, "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "array", "items": { "$ref": "#/components/schemas/CatalogSKU" } } } }, "headers": { "X-Pagination": { "$ref": "#/components/headers/PAGINATION" } } }, "default": { "$ref": "#/components/responses/DEFAULT_ERROR" }, "400": { "description": "Bad request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorResponse" } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorResponse" } } } }, "403": { "description": "Forbidden", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorResponse" } } } }, "404": { "description": "Not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorResponse" } } } }, "409": { "description": "Conflict", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorResponse" } } } }, "405": { "description": "Method not allowed", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorResponse" } } } }, "500": { "description": "Internal server error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorResponse" } } } } }, "tags": [ "Catalog (Beta)" ], "summary": "List catalog SKUs", "description": "Returns SKUs from the public catalog plus the org's custom-priced SKUs, filtered to USD on-demand prices. To restrict to reservable SKUs, pass is_reservable through the filter arg ({\"field\": \"is_reservable\", \"op\": \"=\", \"value\": true})." }, "parameters": [ { "in": "path", "name": "org_id", "required": true, "schema": { "type": "string", "format": "uuid" } } ] }, "/beta/v1/org/{org_id}/catalog/skus/{sku_id}": { "get": { "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CatalogSKUDetail" } } } }, "404": { "description": "Not Found" }, "default": { "$ref": "#/components/responses/DEFAULT_ERROR" }, "400": { "description": "Bad request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorResponse" } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorResponse" } } } }, "403": { "description": "Forbidden", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorResponse" } } } }, "409": { "description": "Conflict", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorResponse" } } } }, "405": { "description": "Method not allowed", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorResponse" } } } }, "500": { "description": "Internal server error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorResponse" } } } } }, "tags": [ "Catalog (Beta)" ], "summary": "Get catalog SKU detail", "description": "Returns the full SKU record including hardware specs and (when available) the on-demand pricing terms with tiered price dimensions. Direct-id lookup doesn't apply the list endpoint's `has_ondemand_terms`/`price_currency=USD` guards, so `ondemand_terms` may be null and `price_currency` may be non-USD for SKUs that wouldn't surface in the list. The SKU must be in the public catalog or owned by the requesting org." }, "parameters": [ { "in": "path", "name": "org_id", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "in": "path", "name": "sku_id", "required": true, "schema": { "type": "string", "format": "uuid" } } ] }, "/beta/v1/org/{org_id}/catalog/skus/{sku_id}/offer-comparison": { "get": { "parameters": [ { "in": "query", "name": "quantity", "description": "Number of SKU units to hypothetically commit to (\u22651). Defaults to 1 \u2014 discount rates and breakeven days are quantity-invariant, so default=1 answers pricing-comparison questions cleanly. Pass an explicit quantity when the user wants absolute dollar figures (monthly savings, upfront cost) sized to a real purchase. For compute this is instance count; for non-compute SKUs the unit is the SKU's `ondemand_usage_unit`.", "schema": { "type": "integer", "default": 1, "minimum": 1 }, "required": false }, { "in": "query", "name": "contract_terms", "description": "Optional list of contract terms to include (e.g. ['one_year_gris', 'three_year']). If omitted, includes every distinct term that appears in this SKU's candidates after the payment-option filter.", "schema": { "type": "array", "default": null, "items": { "type": "string", "enum": [ "one_year_gris", "thirty_day_gris", "two_month_gris", "three_month_gris", "four_month_gris", "five_month_gris", "six_month_gris", "seven_month_gris", "eight_month_gris", "nine_month_gris", "ten_month_gris", "eleven_month_gris", "twelve_month_gris", "thirteen_month_gris", "fourteen_month_gris", "fifteen_month_gris", "sixteen_month_gris", "seventeen_month_gris", "eighteen_month_gris", "nineteen_month_gris", "twenty_month_gris", "twenty_one_month_gris", "twenty_two_month_gris", "twenty_three_month_gris", "twenty_four_month_gris", "twenty_five_month_gris", "twenty_six_month_gris", "twenty_seven_month_gris", "twenty_eight_month_gris", "twenty_nine_month_gris", "thirty_month_gris", "thirty_one_month_gris", "thirty_two_month_gris", "thirty_three_month_gris", "thirty_four_month_gris", "thirty_five_month_gris", "one_year", "two_year", "three_year", "five_year", "zero_day", "thirty_day", "two_month", "three_month", "four_month", "five_month", "six_month", "seven_month", "eight_month", "nine_month", "ten_month", "eleven_month", "thirteen_month", "fourteen_month", "fifteen_month", "sixteen_month", "seventeen_month", "eighteen_month", "nineteen_month", "twenty_month", "twenty_one_month", "twenty_two_month", "twenty_three_month", "twenty_five_month", "twenty_six_month", "twenty_seven_month", "twenty_eight_month", "twenty_nine_month", "thirty_month", "thirty_one_month", "thirty_two_month", "thirty_three_month", "thirty_four_month", "thirty_five_month" ] }, "nullable": true }, "required": false, "explode": true, "style": "form" }, { "in": "query", "name": "payment_options", "description": "Payment options to include. Defaults to no_upfront only \u2014 matches the framing of the other beta comparison endpoints. Pass partial_upfront / all_upfront explicitly to surface those.", "schema": { "type": "array", "items": { "type": "string", "enum": [ "no_upfront", "partial_upfront", "all_upfront" ] } }, "required": false, "explode": true, "style": "form" }, { "in": "query", "name": "only_most_flexible_commitment_type", "description": "When true (default), `candidates[]` and `targets[]` are restricted to the most flexible commitment type available for the SKU's service. For EC2 SKUs that means Compute Savings Plans only \u2014 EC2 Reserved Instances and EC2 Instance Savings Plans are excluded because they bind to a single instance family + region, while Compute SPs cover any EC2 / Fargate / Lambda usage. For Azure Virtual Machines SKUs that means Azure Savings Plans only. Azure reservations are excluded because they bind more narrowly than Savings Plans. Same default-deemphasize spirit as `payment_options=['no_upfront']`. Pass false when the user explicitly asks about RIs/reservations, instance-family commitments, standard vs convertible, or 'all options.' For other SKUs this is a no-op today.", "schema": { "type": "boolean", "default": true }, "required": false } ], "responses": { "422": { "$ref": "#/components/responses/UNPROCESSABLE_CONTENT" }, "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CatalogSKUOfferComparisonResponse" } } } }, "400": { "description": "Bad Request" }, "404": { "description": "Not Found" }, "default": { "$ref": "#/components/responses/DEFAULT_ERROR" }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorResponse" } } } }, "403": { "description": "Forbidden", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorResponse" } } } }, "409": { "description": "Conflict", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorResponse" } } } }, "405": { "description": "Method not allowed", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorResponse" } } } }, "500": { "description": "Internal server error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorResponse" } } } } }, "tags": [ "Catalog (Beta)" ], "summary": "Compare commitment offers for a hypothetical CatalogSKU + quantity", "description": "Returns every (offer, lease) candidate available for the SKU, sized to the requested quantity, with monthly-rate financials, discount rate, breakeven days, and upfront cost. Hypothetical and not tied to existing commitments \u2014 for swapping a line item's offer, use `/commitment-plans/{plan_id}/comparison`. Returns 400 when the SKU is not reservable (`is_reservable=false`) or has no on-demand price (`ondemand_usage_price` null/zero) \u2014 savings can't be quoted against a missing baseline." }, "parameters": [ { "in": "path", "name": "org_id", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "in": "path", "name": "sku_id", "required": true, "schema": { "type": "string", "format": "uuid" } } ] }, "/beta/v1/organizations": { "get": { "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "array", "items": { "$ref": "#/components/schemas/OrganizationMembership" } } } } }, "default": { "$ref": "#/components/responses/DEFAULT_ERROR" }, "400": { "description": "Bad request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorResponse" } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorResponse" } } } }, "403": { "description": "Forbidden", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorResponse" } } } }, "404": { "description": "Not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorResponse" } } } }, "409": { "description": "Conflict", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorResponse" } } } }, "405": { "description": "Method not allowed", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorResponse" } } } }, "500": { "description": "Internal server error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorResponse" } } } } }, "tags": [ "Organizations (Beta)" ], "summary": "List organizations the caller can access", "description": "Returns every organization the authenticated user / API key can act in, ordered with the primary (default-fallback) org first. Use this to discover valid `org_id` values to pass into other beta tools \u2014 required for users who belong to multiple orgs and want to scope a particular call to a non-primary org." } }, "/beta/v1/organizations/{org_id}": { "get": { "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/OrganizationDetail" } } } }, "default": { "$ref": "#/components/responses/DEFAULT_ERROR" }, "400": { "description": "Bad request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorResponse" } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorResponse" } } } }, "403": { "description": "Forbidden", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorResponse" } } } }, "404": { "description": "Not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorResponse" } } } }, "409": { "description": "Conflict", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorResponse" } } } }, "405": { "description": "Method not allowed", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorResponse" } } } }, "500": { "description": "Internal server error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorResponse" } } } } }, "tags": [ "Organizations (Beta)" ], "summary": "Get an organization's management details", "description": "Returns the org-management view of a single organization: name, domain, primary address, deactivation flag, and created_at. For the cross-org list of orgs the caller can access (with role / kind / denied_permissions), use `GET /organizations`." }, "patch": { "responses": { "422": { "$ref": "#/components/responses/UNPROCESSABLE_CONTENT" }, "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/OrganizationDetail" } } } }, "default": { "$ref": "#/components/responses/DEFAULT_ERROR" }, "400": { "description": "Bad request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorResponse" } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorResponse" } } } }, "403": { "description": "Forbidden", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorResponse" } } } }, "404": { "description": "Not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorResponse" } } } }, "409": { "description": "Conflict", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorResponse" } } } }, "405": { "description": "Method not allowed", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorResponse" } } } }, "500": { "description": "Internal server error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorResponse" } } } } }, "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UpdateOrganization" } } } }, "tags": [ "Organizations (Beta)" ], "summary": "Update an organization's management details", "description": "Partial-update: every field is optional. Send only the fields you want to change. Sending `primary_address` replaces the existing address in full; pass null to clear it. Deactivation is intentionally not exposed here \u2014 use `POST /organizations//deactivate`. Requires the caller to have admin role on the org (the `Organization:write` casbin permission)." }, "parameters": [ { "in": "path", "name": "org_id", "required": true, "schema": { "type": "string", "format": "uuid" } } ] }, "/beta/v1/organizations/{org_id}/deactivate": { "post": { "responses": { "204": { "description": "No Content" }, "default": { "$ref": "#/components/responses/DEFAULT_ERROR" }, "400": { "description": "Bad request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorResponse" } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorResponse" } } } }, "403": { "description": "Forbidden", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorResponse" } } } }, "404": { "description": "Not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorResponse" } } } }, "409": { "description": "Conflict", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorResponse" } } } }, "405": { "description": "Method not allowed", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorResponse" } } } }, "500": { "description": "Internal server error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorResponse" } } } } }, "tags": [ "Organizations (Beta)" ], "summary": "Deactivate an organization", "description": "Soft-disables the organization: it stops appearing in `list_organizations` results and members lose access. Intentionally a one-way door from this API surface \u2014 there is no corresponding reactivate endpoint, and once deactivated the org cannot be reached via these admin endpoints at all (the auth layer filters deactivated orgs). Reactivation requires reaching out to Archera support. Returns 204 with no body \u2014 there is no further state the caller can read post-deactivation. Requires the caller to have admin role on the org (the `Organization:write` casbin permission)." }, "parameters": [ { "in": "path", "name": "org_id", "required": true, "schema": { "type": "string", "format": "uuid" } } ] } }, "tags": [ { "name": "reports", "description": "Report download operations" }, { "name": "Allocation Reports (Beta)", "description": "Calendar-month tabular breakdowns that spread Archera premiums, rebates, savings, and commitment costs across accounts, services, or child orgs." }, { "name": "Commitment Plans (Beta)", "description": "Agent-friendly commitment plan endpoints" }, { "name": "Commitment Plan Templates (Beta)", "description": "Agent-friendly commitment plan template endpoints" }, { "name": "Commitment Types (Beta)", "description": "Agent-friendly commitment type lookup" }, { "name": "Commitments (Beta)", "description": "Agent-friendly commitment inventory endpoints" }, { "name": "Metrics (Beta)", "description": "Organization-level metrics and overview" }, { "name": "Segments (Beta)", "description": "Segment management endpoints" }, { "name": "Invoices (Beta)", "description": "Invoice history endpoints" }, { "name": "Cost Explorer (Beta)", "description": "Total cloud spend exploration" }, { "name": "Integrations (Beta)", "description": "Cloud provider integration endpoints" }, { "name": "Resources (Beta)", "description": "Per-customer resource inventory \u2014 attribute filters, free-text search, and per-resource detail. Cross-references catalog SKUs via (catalog_sku_org_id, catalog_sku_id)." }, { "name": "Catalog (Beta)", "description": "Cloud SKU catalog \u2014 attribute filters, search, and per-SKU detail. Returns the public catalog plus the org's own custom-priced SKUs." }, { "name": "Organizations (Beta)", "description": "List and manage organizations the authenticated caller can access." } ], "openapi": "3.0.2", "components": { "schemas": { "Error": { "type": "object", "properties": { "code": { "type": "integer", "description": "Error code" }, "status": { "type": "string", "description": "Error name" }, "message": { "type": "string", "description": "Error message" }, "errors": { "type": "object", "description": "Errors", "additionalProperties": {} } }, "additionalProperties": false }, "PaginationMetadata": { "type": "object", "properties": { "total": { "type": "integer", "description": "Total number of items." }, "total_pages": { "type": "integer", "description": "Total number of pages." }, "first_page": { "type": "integer", "description": "First available page number." }, "last_page": { "type": "integer", "description": "Last available page number." }, "page": { "type": "integer", "description": "Current page number." }, "previous_page": { "type": "integer", "description": "Previous page number." }, "next_page": { "type": "integer", "description": "Next page number." } }, "additionalProperties": false }, "ApiErrorResponse": { "type": "object", "properties": { "message": { "type": "string" }, "detail": { "nullable": true }, "code": { "type": "string", "nullable": true }, "url": { "type": "string", "nullable": true }, "timestamp": { "type": "string" }, "type": { "type": "string" } }, "required": [ "message", "timestamp", "type" ] }, "PartnerArcheraPremiumsAndRebatesByChildOrgOutput": { "type": "object", "properties": { "org_id": { "type": "string", "description": "Child organization identifier" }, "org_name": { "type": "string", "description": "Child organization name" }, "archera_premiums": { "type": "number", "description": "Archera premiums for this organization" }, "rebates": { "type": "number", "description": "Rebates for this organization" }, "gross_savings": { "type": "number", "description": "Gross savings for this organization" }, "net_savings": { "type": "number", "description": "Net savings for this organization" } }, "additionalProperties": false }, "ArcheraPremiumsAndRebatesByAccountOutput": { "type": "object", "properties": { "account_id": { "type": "string", "description": "Cloud account identifier" }, "account_name": { "type": "string", "description": "Human-readable account name" }, "archera_premiums": { "type": "number", "description": "Archera premiums allocated to this account" }, "rebates": { "type": "number", "description": "Rebates allocated to this account" }, "gross_savings": { "type": "number", "description": "Gross savings allocated to this account" }, "net_savings": { "type": "number", "description": "Net savings allocated to this account" } }, "additionalProperties": false }, "ArcheraPremiumsAndRebatesDailyOutput": { "type": "object", "properties": { "date": { "type": "string", "format": "date", "description": "Calendar date within the requested month" }, "gross_savings": { "type": "number", "description": "Gross savings allocated to this date" }, "archera_premiums": { "type": "number", "description": "Archera premiums allocated to this date" }, "rebates": { "type": "number", "description": "Rebates allocated to this date" }, "net_savings": { "type": "number", "description": "Net savings allocated to this date" } }, "additionalProperties": false }, "ArcheraPremiumsAndRebatesByAccountDailyOutput": { "type": "object", "properties": { "date": { "type": "string", "format": "date", "description": "Calendar date within the requested month" }, "account_id": { "type": "string", "description": "Cloud account identifier" }, "account_name": { "type": "string", "description": "Human-readable account name" }, "gross_savings": { "type": "number", "description": "Gross savings allocated to this account on this date" }, "archera_premiums": { "type": "number", "description": "Archera premiums allocated to this account on this date" }, "rebates": { "type": "number", "description": "Rebates allocated to this account on this date" }, "net_savings": { "type": "number", "description": "Net savings allocated to this account on this date" } }, "additionalProperties": false }, "AllocationReportParamDescriptor": { "type": "object", "properties": { "name": { "type": "string", "description": "Query parameter name." }, "type": { "type": "string", "description": "JSON type: 'integer', 'number', 'string', or 'boolean'." }, "required": { "type": "boolean", "description": "Whether the parameter must be supplied." }, "description": { "type": "string", "description": "What the parameter controls." } }, "additionalProperties": false }, "AllocationReportFieldDescriptor": { "type": "object", "properties": { "name": { "type": "string", "description": "Output column name (snake_case in JSON)." }, "type": { "type": "string", "description": "JSON type of the column value." }, "description": { "type": "string", "description": "What the column represents." } }, "additionalProperties": false }, "AllocationReportDescriptor": { "type": "object", "properties": { "report_type": { "type": "string", "description": "Identifier used as the path segment on the get endpoint (`/allocation-reports/`)." }, "name": { "type": "string", "description": "Human-readable report title." }, "description": { "type": "string", "description": "What the report contains." }, "category": { "type": "string", "description": "Allocation tier. 'premiums_and_rebates' = Archera-side overlay only. 'commitment' = commitment cost redistributed from holding to usage accounts (typically with overlay alongside). 'cloud_bill' = full cloud bill including commitment + on-demand + Archera adjustments." }, "row_grain": { "type": "string", "description": "Time grain each row represents: 'monthly' (one row per calendar month, usually paired with another dim) or 'daily' (one row per calendar date)." }, "update_cadence": { "type": "string", "description": "When the report's underlying data changes. 'daily' = refreshes each day as new utilization lands; current-period previews are available and freeze after the period's invoice closes. 'on_period_close' = single snapshot when the invoice generates; calling for the current period returns empty until close. 'static' = never changes." }, "params": { "type": "array", "description": "Query parameters this report accepts.", "items": { "$ref": "#/components/schemas/AllocationReportParamDescriptor" } }, "output_fields": { "type": "array", "description": "Columns each row of the report contains.", "items": { "$ref": "#/components/schemas/AllocationReportFieldDescriptor" } } }, "additionalProperties": false }, "CloudProviderCostBreakdown": { "type": "object", "properties": { "recurring": { "type": "number", "description": "Recurring monthly payment to the cloud provider." }, "amortized_upfront": { "type": "number", "description": "Monthly share of the upfront payment, amortized over the term." } }, "additionalProperties": false }, "CloudProviderCost": { "type": "object", "properties": { "total": { "type": "number", "description": "Amortized cost paid to the cloud provider. Sums with archera_premium to reach cost.total." }, "breakdown": { "description": "Optional. Additive payment-cadence decomposition of total (recurring + amortized_upfront). Present only when purchase-term structure is known (individual commitment or plan).", "allOf": [ { "$ref": "#/components/schemas/CloudProviderCostBreakdown" } ] } }, "additionalProperties": false }, "CommitmentCostBreakdown": { "type": "object", "properties": { "cloud_provider_cost": { "$ref": "#/components/schemas/CloudProviderCost" }, "archera_premium": { "type": "number", "description": "Archera premium \u2014 paid to Archera, equal to a portion of the savings Archera generates for this commitment (fee_rate * gross savings, only charged when gross > 0). Already included in commitment_cost.total (don't add on top). Because premium is only a fraction of gross, whenever archera_premium > 0 the commitment is net-positive after the fee. Native (non-Archera) commitments have premium = 0 and offer no such guarantee; an underutilized guaranteed commitment pre-lockin can also show net < 0 (the rebate that covers this kicks in post-lockin)." } }, "additionalProperties": false }, "CommitmentCost": { "type": "object", "properties": { "total": { "type": "number", "description": "Total paid (cloud_provider_cost.total + archera_premium). Headline 'cost'." }, "breakdown": { "$ref": "#/components/schemas/CommitmentCostBreakdown" } }, "additionalProperties": false }, "CommitmentSavings_Exclude_Rebate": { "type": "object", "properties": { "net": { "type": "number", "description": "Net savings after Archera premium, including any rebate. Actual bill reduction. Headline 'savings'." }, "gross": { "type": "number", "description": "Savings before Archera premium. Equals covered_ondemand_cost - commitment_cost.breakdown.cloud_provider_cost.total." } }, "additionalProperties": false }, "CommitmentFinancialsNoRebate": { "type": "object", "properties": { "commitment_cost": { "$ref": "#/components/schemas/CommitmentCost" }, "commitment_savings": { "$ref": "#/components/schemas/CommitmentSavings_Exclude_Rebate" }, "covered_ondemand_cost": { "type": "number", "description": "On-demand cost of usage covered by commitments \u2014 baseline for savings. NOT a cost paid by the user. Equals commitment_cost.breakdown.cloud_provider_cost.total + commitment_savings.gross." } }, "additionalProperties": false }, "ConfigurationContractSpec": { "type": "object", "properties": { "commitment_type": { "type": "string", "description": "Commitment type identifier \u2014 e.g. 'aws/savingsplan/Compute', 'aws/AmazonEC2', 'aws/AmazonRDS'. Values are provider-prefixed; fetch the exact list from GET /commitment-types and pass through verbatim. Rejected with 422 if the identifier is unknown across all providers; the validator does not enforce that the type belongs to the request's `provider` (a mismatched-but-real type will pass schema validation and produce a plan with no line items)." }, "contract_term": { "description": "Commitment term (e.g. 'thirty_day_gris', 'one_year_gris', 'one_year', 'three_year'). Validated against the catalog entry for the supplied commitment_type \u2014 invalid (type, term) pairs are rejected with 422. Validation is cross-provider (see `commitment_type`).", "type": "string", "enum": [ "one_year_gris", "thirty_day_gris", "two_month_gris", "three_month_gris", "four_month_gris", "five_month_gris", "six_month_gris", "seven_month_gris", "eight_month_gris", "nine_month_gris", "ten_month_gris", "eleven_month_gris", "twelve_month_gris", "thirteen_month_gris", "fourteen_month_gris", "fifteen_month_gris", "sixteen_month_gris", "seventeen_month_gris", "eighteen_month_gris", "nineteen_month_gris", "twenty_month_gris", "twenty_one_month_gris", "twenty_two_month_gris", "twenty_three_month_gris", "twenty_four_month_gris", "twenty_five_month_gris", "twenty_six_month_gris", "twenty_seven_month_gris", "twenty_eight_month_gris", "twenty_nine_month_gris", "thirty_month_gris", "thirty_one_month_gris", "thirty_two_month_gris", "thirty_three_month_gris", "thirty_four_month_gris", "thirty_five_month_gris", "one_year", "two_year", "three_year", "five_year", "zero_day", "thirty_day", "two_month", "three_month", "four_month", "five_month", "six_month", "seven_month", "eight_month", "nine_month", "ten_month", "eleven_month", "thirteen_month", "fourteen_month", "fifteen_month", "sixteen_month", "seventeen_month", "eighteen_month", "nineteen_month", "twenty_month", "twenty_one_month", "twenty_two_month", "twenty_three_month", "twenty_five_month", "twenty_six_month", "twenty_seven_month", "twenty_eight_month", "twenty_nine_month", "thirty_month", "thirty_one_month", "thirty_two_month", "thirty_three_month", "thirty_four_month", "thirty_five_month" ] }, "payment_option": { "description": "Payment option (e.g. 'no_upfront', 'partial_upfront', 'all_upfront'). Validated against the catalog entry for the supplied (commitment_type, contract_term) pair \u2014 invalid triples are rejected with 422. Validation is cross-provider (see `commitment_type`).", "type": "string", "enum": [ "no_upfront", "partial_upfront", "all_upfront" ] } }, "required": [ "commitment_type", "contract_term", "payment_option" ], "additionalProperties": false }, "CommitmentPlanConfiguration": { "type": "object", "properties": { "max_upfront_cost": { "type": "number", "default": 0.0, "description": "Cap on the one-time upfront dollars the generated plan is allowed to include. Defaults to 0 \u2014 the recommender excludes any line item with an upfront cost. Pass null to lift the cap entirely. Otherwise, line items with upfront costs are excluded if adding them would exceed the cap.", "nullable": true }, "lookback_days": { "type": "integer", "default": null, "description": "How many days of historical usage to feed into plan generation. Defaults to 7 when omitted \u2014 matches the recommender's default and gives a representative recent-week baseline. Increase for workloads with weekly/seasonal variance. NULL on renewal plans: renewals derive their usage window from the source commitments' end dates, so this field has no effect. Sending a non-null value to a renewal plan PUT is rejected so round-tripping is honest.", "nullable": true }, "contract_specs": { "description": "List of contract specs to consider when generating the plan. Each spec is a triple of (commitment_type, contract_term, payment_option). The plan generator will pick the best mix of offerings matching these specs.", "type": "array", "items": { "$ref": "#/components/schemas/ConfigurationContractSpec" } }, "resource_ids": { "type": "array", "default": null, "description": "Optional list of resource composite ids (`||`, the same form returned as `id` on resource-SKU responses) to scope the generated plan to specific resources. When non-empty, the plan's coverage is restricted to these resources and the plan is created as an infrastructure plan \u2014 line items only attempt to cover the listed resources rather than the whole segment. Mutually exclusive with `renewal_commitment_ids` (a plan can be scoped by resources OR scoped by renewing commitments, not both). Usually omitted; supply only when the user has explicitly named the resources to cover. Templates do not accept this field \u2014 supplying it on a template create/update is rejected.", "items": {}, "nullable": true }, "renewal_commitment_ids": { "type": "array", "default": null, "description": "Optional list of expiring commitment ids the plan is renewing. When non-empty, the plan is a renewal: coverage is built from the source commitments' historical usage, and each generated line item carries a `renewal_commitment_id` linking back to the source it proposes to replace. Mutually exclusive with `resource_ids`. On a renewal plan PUT this re-targets which commitments are being renewed (recalc); on a non-renewal plan PUT, sending this is rejected (use the dedicated POST /commitment-plans/renewals to create a renewal). Read-back unchanged from a GET so the configuration round-trips through PUT.", "items": { "type": "string", "format": "uuid" }, "nullable": true } }, "required": [ "contract_specs" ], "additionalProperties": false }, "CommitmentPlanList": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid", "description": "Unique plan identifier" }, "provider": { "description": "Cloud provider (aws, azure, gcp)", "type": "string", "enum": [ "aws", "azure", "gcp", "kubernetes", "unknown" ] }, "name": { "type": "string", "description": "Plan name (e.g. 'Recommended', 'Balanced', 'High Savings')" }, "description": { "type": "string", "description": "Human-readable summary of the plan", "nullable": true }, "is_renewal": { "type": "boolean", "description": "True if this plan was created to renew a set of expiring commitments \u2014 `configuration.renewal_commitment_ids` is populated when true. False otherwise (covers both purchase and infrastructure flavors \u2014 the distinction is not user-meaningful, both cover uncovered resources with new commitments)." }, "status": { "description": "Plan status (e.g. 'draft', 'in_progress', 'completed')", "type": "string", "enum": [ "new", "reviewed", "scheduled", "completed", "draft", "needs_review", "in_progress" ] }, "is_calculating": { "type": "boolean", "description": "True if the plan is still being computed" }, "created_at": { "type": "string", "format": "date-time", "description": "When the plan was generated" }, "usage_start_date": { "type": "string", "format": "date-time", "description": "Start of the usage window the plan was computed from. Null on renewal plans \u2014 renewals derive their window from the source commitments' end dates, not from a lookback (see configuration.renewal_commitment_ids).", "nullable": true }, "usage_end_date": { "type": "string", "format": "date-time", "description": "End of the usage window the plan was computed from. Null on renewal plans (see usage_start_date).", "nullable": true }, "max_term": { "type": "string", "description": "Maximum commitment term (e.g. '30_DAY', '1_YEAR', '3_YEAR')", "nullable": true }, "minimum_commitment": { "type": "number", "description": "Minimum total spend being committed to" }, "breakeven_days": { "readOnly": true, "description": "Days until the plan pays for itself. If commitments are kept for at least this many days, the plan is a more profitable decision than running on-demand." }, "commitment_upfront_cost": { "type": "number", "description": "One-time total dollars required at signing if this plan is applied. NOT a rate \u2014 do not sum with monthly-rate fields. Typically 0 for the Recommended plan; can be significant for High Savings / All Upfront plans. Always mention explicitly to the user when non-zero." }, "commitment_financials_monthly_rate": { "description": "Projected plan economics as 730-hour monthly rates. cloud_provider_cost includes full purchase-term detail (recurring, amortized_upfront). commitment_savings has no rebate field \u2014 plans are proposals, no rebates accumulated.", "allOf": [ { "$ref": "#/components/schemas/CommitmentFinancialsNoRebate" } ] }, "configuration": { "description": "The inputs that drove plan generation \u2014 the max_upfront_cost cap and the list of contract specs considered. Round-trips: a GET response can be round-tripped to PUT to re-run generation after editing.", "allOf": [ { "$ref": "#/components/schemas/CommitmentPlanConfiguration" } ] } }, "required": [ "created_at", "id", "is_calculating", "is_renewal", "max_term", "minimum_commitment", "name", "provider", "status" ], "additionalProperties": false }, "CreateCommitmentPlanArgs": { "type": "object", "properties": { "provider": { "description": "Cloud provider (aws, azure, gcp)", "example": "aws", "type": "string", "enum": [ "aws", "azure", "gcp", "kubernetes", "unknown" ] }, "segment_id": { "type": "string", "format": "uuid", "default": null, "description": "Optional segment ID to scope results. Defaults to the provider resources segment if not specified.", "nullable": true }, "name": { "type": "string", "description": "Human-readable plan name" }, "configuration": { "description": "Inputs that drive plan generation", "allOf": [ { "$ref": "#/components/schemas/CommitmentPlanConfiguration" } ] } }, "required": [ "configuration", "name", "provider" ], "additionalProperties": false }, "RenewalCommitmentPlanConfiguration": { "type": "object", "properties": { "max_upfront_cost": { "type": "number", "default": 0.0, "description": "Cap on the one-time upfront dollars the generated plan is allowed to include. Defaults to 0 \u2014 the recommender excludes any line item with an upfront cost. Pass null to lift the cap entirely.", "nullable": true }, "contract_specs": { "description": "List of contract specs to consider when generating renewal line items. Each spec is a (commitment_type, contract_term, payment_option) triple \u2014 the recommender picks the best mix matching these specs against the expiring commitments' usage.", "type": "array", "items": { "$ref": "#/components/schemas/ConfigurationContractSpec" } }, "renewal_commitment_ids": { "type": "array", "minItems": 1, "description": "Expiring commitment ids to renew. Required and non-empty. All ids must belong to the caller's org and the supplied provider, and each must have a non-null end_date (used to derive the usage-window for the renewal recommendation).", "items": { "type": "string", "format": "uuid" } } }, "required": [ "contract_specs", "renewal_commitment_ids" ], "additionalProperties": false }, "CreateRenewalCommitmentPlanArgs": { "type": "object", "properties": { "provider": { "description": "Cloud provider (aws, azure, gcp)", "example": "aws", "type": "string", "enum": [ "aws", "azure", "gcp", "kubernetes", "unknown" ] }, "name": { "type": "string", "description": "Human-readable plan name" }, "configuration": { "description": "Inputs that drive plan generation, including the source `renewal_commitment_ids`. Renewal config omits `lookback_days` (derived from source commitments' end dates) and `resource_ids` (replaced by `renewal_commitment_ids` inside this same object).", "allOf": [ { "$ref": "#/components/schemas/RenewalCommitmentPlanConfiguration" } ] } }, "required": [ "configuration", "name", "provider" ], "additionalProperties": false }, "CommitmentPlan": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid", "description": "Unique plan identifier" }, "provider": { "description": "Cloud provider (aws, azure, gcp)", "type": "string", "enum": [ "aws", "azure", "gcp", "kubernetes", "unknown" ] }, "name": { "type": "string", "description": "Plan name (e.g. 'Recommended', 'Balanced', 'High Savings')" }, "description": { "type": "string", "description": "Human-readable summary of the plan", "nullable": true }, "is_renewal": { "type": "boolean", "description": "True if this plan was created to renew a set of expiring commitments \u2014 `configuration.renewal_commitment_ids` is populated when true. False otherwise (covers both purchase and infrastructure flavors \u2014 the distinction is not user-meaningful, both cover uncovered resources with new commitments)." }, "status": { "description": "Plan status (e.g. 'draft', 'in_progress', 'completed')", "type": "string", "enum": [ "new", "reviewed", "scheduled", "completed", "draft", "needs_review", "in_progress" ] }, "is_calculating": { "type": "boolean", "description": "True if the plan is still being computed" }, "created_at": { "type": "string", "format": "date-time", "description": "When the plan was generated" }, "usage_start_date": { "type": "string", "format": "date-time", "description": "Start of the usage window the plan was computed from. Null on renewal plans \u2014 renewals derive their window from the source commitments' end dates, not from a lookback (see configuration.renewal_commitment_ids).", "nullable": true }, "usage_end_date": { "type": "string", "format": "date-time", "description": "End of the usage window the plan was computed from. Null on renewal plans (see usage_start_date).", "nullable": true }, "max_term": { "type": "string", "description": "Maximum commitment term (e.g. '30_DAY', '1_YEAR', '3_YEAR')", "nullable": true }, "minimum_commitment": { "type": "number", "description": "Minimum total spend being committed to" }, "breakeven_days": { "readOnly": true, "description": "Days until the plan pays for itself. If commitments are kept for at least this many days, the plan is a more profitable decision than running on-demand." }, "commitment_upfront_cost": { "type": "number", "description": "One-time total dollars required at signing if this plan is applied. NOT a rate \u2014 do not sum with monthly-rate fields. Typically 0 for the Recommended plan; can be significant for High Savings / All Upfront plans. Always mention explicitly to the user when non-zero." }, "commitment_financials_monthly_rate": { "description": "Projected plan economics as 730-hour monthly rates. cloud_provider_cost includes full purchase-term detail (recurring, amortized_upfront). commitment_savings has no rebate field \u2014 plans are proposals, no rebates accumulated.", "allOf": [ { "$ref": "#/components/schemas/CommitmentFinancialsNoRebate" } ] }, "configuration": { "description": "The inputs that drove plan generation \u2014 the max_upfront_cost cap and the list of contract specs considered. Round-trips: a GET response can be round-tripped to PUT to re-run generation after editing.", "allOf": [ { "$ref": "#/components/schemas/CommitmentPlanConfiguration" } ] }, "current_coverage": { "type": "number", "description": "Commitment coverage of reservable spend today, from existing commitments (0-1) \u2014 the BEFORE picture, pre-plan." }, "projected_coverage": { "type": "number", "description": "Commitment coverage of reservable spend if this plan is applied (0-1) \u2014 the AFTER picture, post-plan." } }, "required": [ "created_at", "current_coverage", "id", "is_calculating", "is_renewal", "max_term", "minimum_commitment", "name", "projected_coverage", "provider", "status" ], "additionalProperties": false }, "CoveredService": { "type": "object", "properties": { "service_name": { "type": "string", "description": "Cloud service name (e.g. 'Amazon EC2', 'Amazon RDS')" }, "num_commitments": { "type": "integer", "description": "Number of individual commitments covering this service" }, "current_coverage": { "type": "number", "description": "Commitment coverage of this service's reservable spend today, from existing commitments (0-1) \u2014 the BEFORE picture, pre-plan." }, "projected_coverage": { "type": "number", "description": "Commitment coverage of this service's reservable spend if this plan is applied (0-1) \u2014 the AFTER picture, post-plan." }, "commitment_financials_monthly_rate": { "description": "730-hour monthly-rate financials for this service. cloud_provider_cost is `{total}` only (no recurring/amortized split at per-service level). commitment_savings has no rebate field on plans.", "allOf": [ { "$ref": "#/components/schemas/CommitmentFinancialsNoRebate" } ] } }, "required": [ "current_coverage", "num_commitments", "projected_coverage", "service_name" ], "additionalProperties": false }, "CommitmentPlanDetail": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid", "description": "Unique plan identifier" }, "provider": { "description": "Cloud provider (aws, azure, gcp)", "type": "string", "enum": [ "aws", "azure", "gcp", "kubernetes", "unknown" ] }, "name": { "type": "string", "description": "Plan name (e.g. 'Recommended', 'Balanced', 'High Savings')" }, "description": { "type": "string", "description": "Human-readable summary of the plan", "nullable": true }, "is_renewal": { "type": "boolean", "description": "True if this plan was created to renew a set of expiring commitments \u2014 `configuration.renewal_commitment_ids` is populated when true. False otherwise (covers both purchase and infrastructure flavors \u2014 the distinction is not user-meaningful, both cover uncovered resources with new commitments)." }, "status": { "description": "Plan status (e.g. 'draft', 'in_progress', 'completed')", "type": "string", "enum": [ "new", "reviewed", "scheduled", "completed", "draft", "needs_review", "in_progress" ] }, "is_calculating": { "type": "boolean", "description": "True if the plan is still being computed" }, "created_at": { "type": "string", "format": "date-time", "description": "When the plan was generated" }, "usage_start_date": { "type": "string", "format": "date-time", "description": "Start of the usage window the plan was computed from. Null on renewal plans \u2014 renewals derive their window from the source commitments' end dates, not from a lookback (see configuration.renewal_commitment_ids).", "nullable": true }, "usage_end_date": { "type": "string", "format": "date-time", "description": "End of the usage window the plan was computed from. Null on renewal plans (see usage_start_date).", "nullable": true }, "max_term": { "type": "string", "description": "Maximum commitment term (e.g. '30_DAY', '1_YEAR', '3_YEAR')", "nullable": true }, "minimum_commitment": { "type": "number", "description": "Minimum total spend being committed to" }, "breakeven_days": { "readOnly": true, "description": "Days until the plan pays for itself. If commitments are kept for at least this many days, the plan is a more profitable decision than running on-demand." }, "commitment_upfront_cost": { "type": "number", "description": "One-time total dollars required at signing if this plan is applied. NOT a rate \u2014 do not sum with monthly-rate fields. Typically 0 for the Recommended plan; can be significant for High Savings / All Upfront plans. Always mention explicitly to the user when non-zero." }, "commitment_financials_monthly_rate": { "description": "Projected plan economics as 730-hour monthly rates. cloud_provider_cost includes full purchase-term detail (recurring, amortized_upfront). commitment_savings has no rebate field \u2014 plans are proposals, no rebates accumulated.", "allOf": [ { "$ref": "#/components/schemas/CommitmentFinancialsNoRebate" } ] }, "configuration": { "description": "The inputs that drove plan generation \u2014 the max_upfront_cost cap and the list of contract specs considered. Round-trips: a GET response can be round-tripped to PUT to re-run generation after editing.", "allOf": [ { "$ref": "#/components/schemas/CommitmentPlanConfiguration" } ] }, "current_coverage": { "type": "number", "description": "Commitment coverage of reservable spend today, from existing commitments (0-1) \u2014 the BEFORE picture, pre-plan." }, "projected_coverage": { "type": "number", "description": "Commitment coverage of reservable spend if this plan is applied (0-1) \u2014 the AFTER picture, post-plan." }, "covered_services": { "type": "array", "description": "List of cloud services covered by this plan, with per-service savings and commitment breakdowns", "items": { "$ref": "#/components/schemas/CoveredService" } } }, "required": [ "created_at", "current_coverage", "id", "is_calculating", "is_renewal", "max_term", "minimum_commitment", "name", "projected_coverage", "provider", "status" ], "additionalProperties": false }, "UpdateCommitmentPlanArgs": { "type": "object", "properties": { "name": { "type": "string", "description": "New plan name" }, "configuration": { "description": "New plan configuration. Replacing this triggers a full regeneration of the plan's line items and financials. The plan's scope axis lives here too \u2014 `resource_ids` for infrastructure scope, `renewal_commitment_ids` for renewal scope (mutually exclusive). Sending the wrong scope field for the plan type is rejected; convert plan types by deleting and re-creating.", "allOf": [ { "$ref": "#/components/schemas/CommitmentPlanConfiguration" } ] } }, "additionalProperties": false }, "LineItemUpdateEntry": { "type": "object", "properties": { "line_item_id": { "type": "string", "format": "uuid", "description": "ID of the line item to update." }, "is_selected": { "type": "boolean", "description": "Include this line item in the plan's top-level financials and apply it when the plan is purchased." }, "account_id": { "type": "string", "description": "Cloud account ID this commitment is scoped to.", "nullable": true }, "offer_id": { "type": "string", "format": "uuid", "description": "Swap this line item's offer. Pair with `lease_menu_item_id` and `selected_amount` from the same comparison entry." }, "lease_menu_item_id": { "type": "string", "format": "uuid", "description": "Lease attached to the chosen offer. Must come from the same comparison entry as `offer_id`. NULL VS OMITTED MATTERS: explicitly passing `null` clears the existing lease (converting a leased Archera-guaranteed commitment into a native one); omitting the field leaves the existing lease in place. To switch a leased GRI line item to a native offer, you MUST pass `null` here \u2014 otherwise the old lease stays attached and the line item's effective `contract_term` (derived from the lease's lockin hours) won't change.", "nullable": true }, "selected_amount": { "type": "number", "description": "Commitment amount for the offer \u2014 unit count for RIs / unit-based CUDs, dollar-basis for Savings Plans / spend-based CUDs." } }, "required": [ "line_item_id" ], "additionalProperties": false }, "CopyCommitmentPlanArgs": { "type": "object", "properties": { "target_contract_term": { "default": null, "description": "Server-side resolution mode. Set to a target contract term and the server resolves the per-line-item update set using the same fallback rule the comparison endpoint projects: exact match on (term, payment) where available, else closest shorter term with the same payment option (GRI preferred within tier). Mutually exclusive with explicit per-line-item updates \u2014 pass one OR the other, not both. Preferred over enumerating updates manually because the server can't silently omit entries from a list it builds itself.", "type": "string", "enum": [ "one_year_gris", "thirty_day_gris", "two_month_gris", "three_month_gris", "four_month_gris", "five_month_gris", "six_month_gris", "seven_month_gris", "eight_month_gris", "nine_month_gris", "ten_month_gris", "eleven_month_gris", "twelve_month_gris", "thirteen_month_gris", "fourteen_month_gris", "fifteen_month_gris", "sixteen_month_gris", "seventeen_month_gris", "eighteen_month_gris", "nineteen_month_gris", "twenty_month_gris", "twenty_one_month_gris", "twenty_two_month_gris", "twenty_three_month_gris", "twenty_four_month_gris", "twenty_five_month_gris", "twenty_six_month_gris", "twenty_seven_month_gris", "twenty_eight_month_gris", "twenty_nine_month_gris", "thirty_month_gris", "thirty_one_month_gris", "thirty_two_month_gris", "thirty_three_month_gris", "thirty_four_month_gris", "thirty_five_month_gris", "one_year", "two_year", "three_year", "five_year", "zero_day", "thirty_day", "two_month", "three_month", "four_month", "five_month", "six_month", "seven_month", "eight_month", "nine_month", "ten_month", "eleven_month", "thirteen_month", "fourteen_month", "fifteen_month", "sixteen_month", "seventeen_month", "eighteen_month", "nineteen_month", "twenty_month", "twenty_one_month", "twenty_two_month", "twenty_three_month", "twenty_five_month", "twenty_six_month", "twenty_seven_month", "twenty_eight_month", "twenty_nine_month", "thirty_month", "thirty_one_month", "thirty_two_month", "thirty_three_month", "thirty_four_month", "thirty_five_month", null ], "nullable": true }, "target_payment_option": { "default": "no_upfront", "description": "Target payment option for resolution mode. Defaults to no_upfront \u2014 most users are uncomfortable with cash at signing, so this matches the default framing for plan comparisons. Ignored when `target_contract_term` is null.", "type": "string", "enum": [ "no_upfront", "partial_upfront", "all_upfront" ] }, "target_line_item_ids": { "type": "array", "default": null, "description": "Optional subset of line items to update under resolution mode. If omitted, applies to all selected line items in the plan. Ignored when `target_contract_term` is null.", "items": { "type": "string", "format": "uuid" }, "nullable": true }, "name": { "type": "string", "default": null, "description": "Name for the copied plan. If omitted, defaults to ' '.", "nullable": true }, "line_item_updates": { "type": "array", "default": null, "description": "Optional list of line-item edits to apply during the copy. Each entry has the same shape as `update_commitment_plan_line_items`'s `updates` (line_item_id + optional is_selected / account_id / offer-swap triple). Entries reference the SOURCE plan's line_item_ids; the server translates them to the copy's new IDs internally and applies them atomically. If any edit fails, the entire copy + updates rolls back. Use this for the canonical 'copy to edit' workflow \u2014 saves the round trip and ID-translation logic that would otherwise live on the client. Mutually exclusive with `target_contract_term` (resolution mode).", "items": { "$ref": "#/components/schemas/LineItemUpdateEntry" }, "nullable": true } }, "additionalProperties": false }, "HypotheticalLineItem": { "type": "object", "properties": { "line_item_id": { "type": "string", "format": "uuid", "description": "Line item ID." }, "actual_term": { "description": "The contract term this line item actually contributes to the rollup at. Equals the target term when an exact match exists; otherwise the longest available term <= target with the same payment option, or the line item's current term as a last resort.", "type": "string", "enum": [ "one_year_gris", "thirty_day_gris", "two_month_gris", "three_month_gris", "four_month_gris", "five_month_gris", "six_month_gris", "seven_month_gris", "eight_month_gris", "nine_month_gris", "ten_month_gris", "eleven_month_gris", "twelve_month_gris", "thirteen_month_gris", "fourteen_month_gris", "fifteen_month_gris", "sixteen_month_gris", "seventeen_month_gris", "eighteen_month_gris", "nineteen_month_gris", "twenty_month_gris", "twenty_one_month_gris", "twenty_two_month_gris", "twenty_three_month_gris", "twenty_four_month_gris", "twenty_five_month_gris", "twenty_six_month_gris", "twenty_seven_month_gris", "twenty_eight_month_gris", "twenty_nine_month_gris", "thirty_month_gris", "thirty_one_month_gris", "thirty_two_month_gris", "thirty_three_month_gris", "thirty_four_month_gris", "thirty_five_month_gris", "one_year", "two_year", "three_year", "five_year", "zero_day", "thirty_day", "two_month", "three_month", "four_month", "five_month", "six_month", "seven_month", "eight_month", "nine_month", "ten_month", "eleven_month", "thirteen_month", "fourteen_month", "fifteen_month", "sixteen_month", "seventeen_month", "eighteen_month", "nineteen_month", "twenty_month", "twenty_one_month", "twenty_two_month", "twenty_three_month", "twenty_five_month", "twenty_six_month", "twenty_seven_month", "twenty_eight_month", "twenty_nine_month", "thirty_month", "thirty_one_month", "thirty_two_month", "thirty_three_month", "thirty_four_month", "thirty_five_month", null ], "nullable": true }, "actual_payment_option": { "description": "Payment option of the candidate this line item contributes. Equals the target payment option except when actual_term_reason='no_alternative' (falls back to current, which may have a different payment option).", "type": "string", "enum": [ "no_upfront", "partial_upfront", "all_upfront", null ], "nullable": true }, "actual_term_reason": { "type": "string", "enum": [ "exact_match", "fallback_closest_shorter", "no_alternative" ], "description": "Why this line item landed at actual_term. exact_match = target available; fallback_closest_shorter = used the longest available term <= target with same payment option; no_alternative = nothing qualified, kept at current." } }, "required": [ "actual_payment_option", "actual_term", "actual_term_reason", "line_item_id" ], "additionalProperties": false }, "PlanLineItemUpdateResponse": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid", "description": "Unique plan identifier" }, "provider": { "description": "Cloud provider (aws, azure, gcp)", "type": "string", "enum": [ "aws", "azure", "gcp", "kubernetes", "unknown" ] }, "name": { "type": "string", "description": "Plan name (e.g. 'Recommended', 'Balanced', 'High Savings')" }, "description": { "type": "string", "description": "Human-readable summary of the plan", "nullable": true }, "is_renewal": { "type": "boolean", "description": "True if this plan was created to renew a set of expiring commitments \u2014 `configuration.renewal_commitment_ids` is populated when true. False otherwise (covers both purchase and infrastructure flavors \u2014 the distinction is not user-meaningful, both cover uncovered resources with new commitments)." }, "status": { "description": "Plan status (e.g. 'draft', 'in_progress', 'completed')", "type": "string", "enum": [ "new", "reviewed", "scheduled", "completed", "draft", "needs_review", "in_progress" ] }, "is_calculating": { "type": "boolean", "description": "True if the plan is still being computed" }, "created_at": { "type": "string", "format": "date-time", "description": "When the plan was generated" }, "usage_start_date": { "type": "string", "format": "date-time", "description": "Start of the usage window the plan was computed from. Null on renewal plans \u2014 renewals derive their window from the source commitments' end dates, not from a lookback (see configuration.renewal_commitment_ids).", "nullable": true }, "usage_end_date": { "type": "string", "format": "date-time", "description": "End of the usage window the plan was computed from. Null on renewal plans (see usage_start_date).", "nullable": true }, "max_term": { "type": "string", "description": "Maximum commitment term (e.g. '30_DAY', '1_YEAR', '3_YEAR')", "nullable": true }, "minimum_commitment": { "type": "number", "description": "Minimum total spend being committed to" }, "breakeven_days": { "readOnly": true, "description": "Days until the plan pays for itself. If commitments are kept for at least this many days, the plan is a more profitable decision than running on-demand." }, "commitment_upfront_cost": { "type": "number", "description": "One-time total dollars required at signing if this plan is applied. NOT a rate \u2014 do not sum with monthly-rate fields. Typically 0 for the Recommended plan; can be significant for High Savings / All Upfront plans. Always mention explicitly to the user when non-zero." }, "commitment_financials_monthly_rate": { "description": "Projected plan economics as 730-hour monthly rates. cloud_provider_cost includes full purchase-term detail (recurring, amortized_upfront). commitment_savings has no rebate field \u2014 plans are proposals, no rebates accumulated.", "allOf": [ { "$ref": "#/components/schemas/CommitmentFinancialsNoRebate" } ] }, "configuration": { "description": "The inputs that drove plan generation \u2014 the max_upfront_cost cap and the list of contract specs considered. Round-trips: a GET response can be round-tripped to PUT to re-run generation after editing.", "allOf": [ { "$ref": "#/components/schemas/CommitmentPlanConfiguration" } ] }, "resolution": { "type": "array", "description": "Per-line-item resolution outcome when `target_contract_term` was passed. One entry per line item that was IN SCOPE for the request (covers `no_alternative` items too \u2014 those are not in the applied updates but are surfaced here so callers can see what the server couldn't satisfy). `actual_term_reason` is one of: `exact_match` (landed at target), `fallback_closest_shorter` (used the longest available term \u2264 target with same payment option), `no_alternative` (no candidate satisfied \u2014 line item left unchanged). Absent / null on explicit-mode calls.", "items": { "$ref": "#/components/schemas/HypotheticalLineItem" }, "nullable": true } }, "required": [ "created_at", "id", "is_calculating", "is_renewal", "max_term", "minimum_commitment", "name", "provider", "status" ], "additionalProperties": false }, "ContractSpec": { "type": "object", "properties": { "commitment_type": { "type": "string", "description": "Commitment type identifier" }, "properties": { "type": "object", "default": {}, "description": "Additional contract properties", "additionalProperties": {} }, "term": { "description": "Contract term", "type": "string", "enum": [ "one_year_gris", "thirty_day_gris", "two_month_gris", "three_month_gris", "four_month_gris", "five_month_gris", "six_month_gris", "seven_month_gris", "eight_month_gris", "nine_month_gris", "ten_month_gris", "eleven_month_gris", "twelve_month_gris", "thirteen_month_gris", "fourteen_month_gris", "fifteen_month_gris", "sixteen_month_gris", "seventeen_month_gris", "eighteen_month_gris", "nineteen_month_gris", "twenty_month_gris", "twenty_one_month_gris", "twenty_two_month_gris", "twenty_three_month_gris", "twenty_four_month_gris", "twenty_five_month_gris", "twenty_six_month_gris", "twenty_seven_month_gris", "twenty_eight_month_gris", "twenty_nine_month_gris", "thirty_month_gris", "thirty_one_month_gris", "thirty_two_month_gris", "thirty_three_month_gris", "thirty_four_month_gris", "thirty_five_month_gris", "one_year", "two_year", "three_year", "five_year", "zero_day", "thirty_day", "two_month", "three_month", "four_month", "five_month", "six_month", "seven_month", "eight_month", "nine_month", "ten_month", "eleven_month", "thirteen_month", "fourteen_month", "fifteen_month", "sixteen_month", "seventeen_month", "eighteen_month", "nineteen_month", "twenty_month", "twenty_one_month", "twenty_two_month", "twenty_three_month", "twenty_five_month", "twenty_six_month", "twenty_seven_month", "twenty_eight_month", "twenty_nine_month", "thirty_month", "thirty_one_month", "thirty_two_month", "thirty_three_month", "thirty_four_month", "thirty_five_month", null ], "nullable": true }, "payment_option": { "description": "Payment option", "type": "string", "enum": [ "no_upfront", "partial_upfront", "all_upfront", null ], "nullable": true } }, "additionalProperties": false }, "CommitmentOffer": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid", "description": "Offer identifier" }, "provider": { "description": "Cloud provider (aws, azure, gcp)", "type": "string", "enum": [ "aws", "azure", "gcp", "kubernetes", "unknown" ] }, "type": { "type": "string", "description": "Commitment type (e.g. 'ri', 'savings_plan', 'cud')" }, "region": { "type": "string", "description": "Cloud region (e.g. 'us-east-1')", "nullable": true }, "duration_seconds": { "type": "integer", "description": "Total commitment duration in seconds" }, "instance_type": { "type": "string", "description": "Instance type (e.g. 'm5.xlarge'), null for Savings Plans", "nullable": true }, "instance_family": { "type": "string", "description": "Instance family (e.g. 'm5'), null for some commitment types", "nullable": true }, "offering_class": { "description": "Offering class (e.g. 'standard', 'convertible')", "type": "string", "enum": [ "standard", "convertible", null ], "nullable": true }, "payment_option": { "description": "Payment option (e.g. 'no_upfront', 'partial_upfront', 'all_upfront')", "type": "string", "enum": [ "no_upfront", "partial_upfront", "all_upfront", null ], "nullable": true }, "plan_type": { "type": "string", "description": "Plan type (e.g. 'Compute', 'EC2Instance')", "nullable": true }, "product_description": { "type": "string", "description": "Product description (e.g. 'Linux/UNIX')", "nullable": true }, "display_name": { "type": "string", "description": "Human-readable offer name", "nullable": true }, "is_flexible": { "type": "boolean", "description": "Whether the commitment has instance size flexibility", "nullable": true } }, "additionalProperties": false }, "CommitmentLineItem": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid", "description": "Line item identifier" }, "is_selected": { "type": "boolean", "description": "Whether this line item is included in the plan. If false, this line item is excluded and its costs/savings are NOT reflected in the plan's top-level metrics." }, "account_id": { "type": "string", "description": "Cloud account ID this commitment applies to", "nullable": true }, "contract_term": { "description": "Commitment term (e.g. 'thirty_day_gris', 'one_year_gris', 'one_year', 'three_year')", "type": "string", "enum": [ "one_year_gris", "thirty_day_gris", "two_month_gris", "three_month_gris", "four_month_gris", "five_month_gris", "six_month_gris", "seven_month_gris", "eight_month_gris", "nine_month_gris", "ten_month_gris", "eleven_month_gris", "twelve_month_gris", "thirteen_month_gris", "fourteen_month_gris", "fifteen_month_gris", "sixteen_month_gris", "seventeen_month_gris", "eighteen_month_gris", "nineteen_month_gris", "twenty_month_gris", "twenty_one_month_gris", "twenty_two_month_gris", "twenty_three_month_gris", "twenty_four_month_gris", "twenty_five_month_gris", "twenty_six_month_gris", "twenty_seven_month_gris", "twenty_eight_month_gris", "twenty_nine_month_gris", "thirty_month_gris", "thirty_one_month_gris", "thirty_two_month_gris", "thirty_three_month_gris", "thirty_four_month_gris", "thirty_five_month_gris", "one_year", "two_year", "three_year", "five_year", "zero_day", "thirty_day", "two_month", "three_month", "four_month", "five_month", "six_month", "seven_month", "eight_month", "nine_month", "ten_month", "eleven_month", "thirteen_month", "fourteen_month", "fifteen_month", "sixteen_month", "seventeen_month", "eighteen_month", "nineteen_month", "twenty_month", "twenty_one_month", "twenty_two_month", "twenty_three_month", "twenty_five_month", "twenty_six_month", "twenty_seven_month", "twenty_eight_month", "twenty_nine_month", "thirty_month", "thirty_one_month", "thirty_two_month", "thirty_three_month", "thirty_four_month", "thirty_five_month" ] }, "contract_spec": { "description": "Detailed contract specifications including commitment type and properties", "allOf": [ { "$ref": "#/components/schemas/ContractSpec" } ] }, "offer": { "description": "Commitment offer details including type, region, and instance info", "allOf": [ { "$ref": "#/components/schemas/CommitmentOffer" } ] }, "discount_rate": { "type": "number", "description": "Discount rate vs on-demand (0-1)" }, "breakeven_days": { "readOnly": true, "description": "Days until this line item pays for itself" }, "selected_amount": { "readOnly": true, "description": "Selected commitment amount \u2014 either a quantity (for RIs) or a dollar commitment (for Savings Plans), whichever is applicable" }, "recommended_amount": { "readOnly": true, "description": "Recommended commitment amount \u2014 either a quantity (for RIs) or a dollar commitment (for Savings Plans), whichever is applicable" }, "commitment_upfront_cost": { "type": "number", "description": "One-time total dollars required at signing for this specific line item. NOT a rate \u2014 do not sum with monthly-rate fields. Summing the commitment_upfront_cost of all selected line items equals the parent plan's commitment_upfront_cost." }, "commitment_financials_monthly_rate": { "description": "Projected line item economics as 730-hour monthly rates. cloud_provider_cost includes full purchase-term detail (recurring, amortized_upfront). commitment_savings has no rebate field on plans.", "allOf": [ { "$ref": "#/components/schemas/CommitmentFinancialsNoRebate" } ] }, "covered_services": { "type": "array", "description": "Cloud service identifiers (e.g. 'AmazonEC2', 'AmazonRDS') that this line item's commitment is expected to cover. Reflects the underlying resources the recommender matched to this commitment, not the offer's raw eligibility.", "items": { "type": "string" } }, "renewal_commitment_id": { "type": "string", "format": "uuid", "description": "ID of the expiring commitment this line item is renewing. Populated only on renewal plans (`plan_type=renewal`); null on purchase / infrastructure plans. Use the `renewal_commitment_ids` query param on this endpoint to filter to the line items proposed as replacements for specific expiring commitments.", "nullable": true } }, "required": [ "id", "is_selected" ], "additionalProperties": false }, "UpdateLineItemsArgs": { "type": "object", "properties": { "target_contract_term": { "default": null, "description": "Server-side resolution mode. Set to a target contract term and the server resolves the per-line-item update set using the same fallback rule the comparison endpoint projects: exact match on (term, payment) where available, else closest shorter term with the same payment option (GRI preferred within tier). Mutually exclusive with explicit per-line-item updates \u2014 pass one OR the other, not both. Preferred over enumerating updates manually because the server can't silently omit entries from a list it builds itself.", "type": "string", "enum": [ "one_year_gris", "thirty_day_gris", "two_month_gris", "three_month_gris", "four_month_gris", "five_month_gris", "six_month_gris", "seven_month_gris", "eight_month_gris", "nine_month_gris", "ten_month_gris", "eleven_month_gris", "twelve_month_gris", "thirteen_month_gris", "fourteen_month_gris", "fifteen_month_gris", "sixteen_month_gris", "seventeen_month_gris", "eighteen_month_gris", "nineteen_month_gris", "twenty_month_gris", "twenty_one_month_gris", "twenty_two_month_gris", "twenty_three_month_gris", "twenty_four_month_gris", "twenty_five_month_gris", "twenty_six_month_gris", "twenty_seven_month_gris", "twenty_eight_month_gris", "twenty_nine_month_gris", "thirty_month_gris", "thirty_one_month_gris", "thirty_two_month_gris", "thirty_three_month_gris", "thirty_four_month_gris", "thirty_five_month_gris", "one_year", "two_year", "three_year", "five_year", "zero_day", "thirty_day", "two_month", "three_month", "four_month", "five_month", "six_month", "seven_month", "eight_month", "nine_month", "ten_month", "eleven_month", "thirteen_month", "fourteen_month", "fifteen_month", "sixteen_month", "seventeen_month", "eighteen_month", "nineteen_month", "twenty_month", "twenty_one_month", "twenty_two_month", "twenty_three_month", "twenty_five_month", "twenty_six_month", "twenty_seven_month", "twenty_eight_month", "twenty_nine_month", "thirty_month", "thirty_one_month", "thirty_two_month", "thirty_three_month", "thirty_four_month", "thirty_five_month", null ], "nullable": true }, "target_payment_option": { "default": "no_upfront", "description": "Target payment option for resolution mode. Defaults to no_upfront \u2014 most users are uncomfortable with cash at signing, so this matches the default framing for plan comparisons. Ignored when `target_contract_term` is null.", "type": "string", "enum": [ "no_upfront", "partial_upfront", "all_upfront" ] }, "target_line_item_ids": { "type": "array", "default": null, "description": "Optional subset of line items to update under resolution mode. If omitted, applies to all selected line items in the plan. Ignored when `target_contract_term` is null.", "items": { "type": "string", "format": "uuid" }, "nullable": true }, "updates": { "type": "array", "default": null, "minItems": 1, "description": "List of per-line-item updates to apply atomically. Required unless `target_contract_term` is set (resolution mode). Each entry's `line_item_id` must be on the parent plan.", "items": { "$ref": "#/components/schemas/LineItemUpdateEntry" }, "nullable": true } }, "additionalProperties": false }, "Commitment": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid", "description": "Unique commitment identifier" }, "provider_reservation_id": { "type": "string", "description": "Cloud provider's ID for this commitment (e.g. AWS reservation ID)" }, "provider": { "description": "Cloud provider (aws, azure, gcp)", "type": "string", "enum": [ "aws", "azure", "gcp", "kubernetes", "unknown" ] }, "display_name": { "type": "string", "description": "Human-readable commitment name" }, "type": { "type": "string", "description": "Commitment type (e.g. 'Compute', 'EC2Instance', 'RDS')" }, "status": { "description": "Commitment status (e.g. 'active', 'expired', 'queued')", "type": "string", "enum": [ "active", "locked", "new", "reselling", "unlocked", "unknown", "cancelled", "expired", "recently_expired", "resold", "removed" ] }, "is_active": { "type": "boolean", "description": "Whether the commitment is currently active" }, "is_archera_guaranteed": { "type": "boolean", "description": "Whether this is an Archera Guaranteed Commitment" }, "account_id": { "type": "string", "description": "Cloud account ID this commitment is in", "nullable": true }, "billing_account_id": { "type": "string", "description": "Billing/management account ID", "nullable": true }, "start_date": { "type": "string", "format": "date-time", "description": "When the commitment started", "nullable": true }, "end_date": { "type": "string", "format": "date-time", "description": "When the commitment expires", "nullable": true }, "duration_seconds": { "type": "integer", "description": "Total commitment duration in seconds", "nullable": true }, "guarantee_start": { "type": "string", "format": "date-time", "description": "When the Archera guarantee period started", "nullable": true }, "guarantee_lockin_date": { "type": "string", "format": "date-time", "description": "When the Archera guarantee lock-in period ends", "nullable": true }, "guarantee_method": { "readOnly": true, "description": "How the Archera guarantee is delivered. 'rebate': Archera rebates the cost of the unused commitment directly to the user (as cash or credit toward Archera premiums). 'release': Archera takes over the commitment along with remaining payment obligations. Null for non-guaranteed commitments." }, "region": { "type": "string", "description": "Cloud region (e.g. 'us-east-1')", "nullable": true }, "instance_type": { "type": "string", "description": "Instance type (e.g. 'm5.xlarge')", "nullable": true }, "instance_family": { "type": "string", "description": "Instance family (e.g. 'm5')", "nullable": true }, "plan_type": { "type": "string", "description": "Plan type (e.g. 'Compute', 'EC2Instance')", "nullable": true }, "payment_option": { "description": "Payment option (e.g. 'no_upfront', 'partial_upfront', 'all_upfront')", "type": "string", "enum": [ "no_upfront", "partial_upfront", "all_upfront", null ], "nullable": true }, "offering_class": { "description": "Offering class (e.g. 'standard', 'convertible')", "type": "string", "enum": [ "standard", "convertible", null ], "nullable": true }, "is_flexible": { "type": "boolean", "description": "Whether the commitment has instance size flexibility", "nullable": true }, "instance_count": { "type": "integer", "description": "Number of instances covered", "nullable": true }, "contract_term": { "description": "Contract term (e.g. 'thirty_day_gris', 'one_year')", "type": "string", "enum": [ "one_year_gris", "thirty_day_gris", "two_month_gris", "three_month_gris", "four_month_gris", "five_month_gris", "six_month_gris", "seven_month_gris", "eight_month_gris", "nine_month_gris", "ten_month_gris", "eleven_month_gris", "twelve_month_gris", "thirteen_month_gris", "fourteen_month_gris", "fifteen_month_gris", "sixteen_month_gris", "seventeen_month_gris", "eighteen_month_gris", "nineteen_month_gris", "twenty_month_gris", "twenty_one_month_gris", "twenty_two_month_gris", "twenty_three_month_gris", "twenty_four_month_gris", "twenty_five_month_gris", "twenty_six_month_gris", "twenty_seven_month_gris", "twenty_eight_month_gris", "twenty_nine_month_gris", "thirty_month_gris", "thirty_one_month_gris", "thirty_two_month_gris", "thirty_three_month_gris", "thirty_four_month_gris", "thirty_five_month_gris", "one_year", "two_year", "three_year", "five_year", "zero_day", "thirty_day", "two_month", "three_month", "four_month", "five_month", "six_month", "seven_month", "eight_month", "nine_month", "ten_month", "eleven_month", "thirteen_month", "fourteen_month", "fifteen_month", "sixteen_month", "seventeen_month", "eighteen_month", "nineteen_month", "twenty_month", "twenty_one_month", "twenty_two_month", "twenty_three_month", "twenty_five_month", "twenty_six_month", "twenty_seven_month", "twenty_eight_month", "twenty_nine_month", "thirty_month", "thirty_one_month", "thirty_two_month", "thirty_three_month", "thirty_four_month", "thirty_five_month", null ], "nullable": true } }, "required": [ "id", "provider" ], "additionalProperties": false }, "LineItemOfferComparisonTotals": { "type": "object", "properties": { "commitment_financials_monthly_rate": { "description": "730-hour monthly rate financials summed across the line items in scope. Same shape as on plans / line items.", "allOf": [ { "$ref": "#/components/schemas/CommitmentFinancialsNoRebate" } ] }, "commitment_upfront_cost": { "type": "number", "description": "Sum of one-time upfront dollars at signing across the line items in scope. NOT a rate \u2014 do not sum with monthly-rate fields." } }, "required": [ "commitment_financials_monthly_rate", "commitment_upfront_cost" ], "additionalProperties": false }, "HypotheticalDelta": { "type": "object", "properties": { "monthly_net_savings": { "type": "number", "description": "Hypothetical's monthly net savings minus current_totals'. Positive means switching saves more than the plan does today." }, "monthly_commitment_cost": { "type": "number", "description": "Hypothetical's monthly commitment cost minus current_totals'. Positive means more dollars committed monthly." }, "upfront_cost": { "type": "number", "description": "Hypothetical's one-time upfront cost minus current_totals'. NOT a rate." } }, "required": [ "monthly_commitment_cost", "monthly_net_savings", "upfront_cost" ], "additionalProperties": false }, "HypotheticalTotal": { "type": "object", "properties": { "contract_term": { "description": "Target contract term for this hypothetical.", "type": "string", "enum": [ "one_year_gris", "thirty_day_gris", "two_month_gris", "three_month_gris", "four_month_gris", "five_month_gris", "six_month_gris", "seven_month_gris", "eight_month_gris", "nine_month_gris", "ten_month_gris", "eleven_month_gris", "twelve_month_gris", "thirteen_month_gris", "fourteen_month_gris", "fifteen_month_gris", "sixteen_month_gris", "seventeen_month_gris", "eighteen_month_gris", "nineteen_month_gris", "twenty_month_gris", "twenty_one_month_gris", "twenty_two_month_gris", "twenty_three_month_gris", "twenty_four_month_gris", "twenty_five_month_gris", "twenty_six_month_gris", "twenty_seven_month_gris", "twenty_eight_month_gris", "twenty_nine_month_gris", "thirty_month_gris", "thirty_one_month_gris", "thirty_two_month_gris", "thirty_three_month_gris", "thirty_four_month_gris", "thirty_five_month_gris", "one_year", "two_year", "three_year", "five_year", "zero_day", "thirty_day", "two_month", "three_month", "four_month", "five_month", "six_month", "seven_month", "eight_month", "nine_month", "ten_month", "eleven_month", "thirteen_month", "fourteen_month", "fifteen_month", "sixteen_month", "seventeen_month", "eighteen_month", "nineteen_month", "twenty_month", "twenty_one_month", "twenty_two_month", "twenty_three_month", "twenty_five_month", "twenty_six_month", "twenty_seven_month", "twenty_eight_month", "twenty_nine_month", "thirty_month", "thirty_one_month", "thirty_two_month", "thirty_three_month", "thirty_four_month", "thirty_five_month", null ], "nullable": true }, "payment_option": { "description": "Target payment option for this hypothetical.", "type": "string", "enum": [ "no_upfront", "partial_upfront", "all_upfront" ] }, "commitment_financials_monthly_rate": { "description": "Rolled-up monthly-rate financials assuming each line item adopts its candidate per the fallback rule. Same shape as on plans / line items.", "allOf": [ { "$ref": "#/components/schemas/CommitmentFinancialsNoRebate" } ] }, "commitment_upfront_cost": { "type": "number", "description": "Sum of one-time upfront dollars across the line items under this hypothetical. NOT a rate." }, "delta_vs_current": { "description": "Axis-by-axis difference vs current_totals. The headline 'should I do this' answer is delta_vs_current.monthly_net_savings.", "allOf": [ { "$ref": "#/components/schemas/HypotheticalDelta" } ] }, "line_items": { "type": "array", "description": "Per-line-item resolution for this hypothetical. Use to call out fallbacks ('14 of 20 line items would land at 3-year; 5 would fall back to 1-year GRI; 1 has no shorter alternative and stays at current').", "items": { "$ref": "#/components/schemas/HypotheticalLineItem" } } }, "required": [ "commitment_financials_monthly_rate", "commitment_upfront_cost", "contract_term", "delta_vs_current", "line_items", "payment_option" ], "additionalProperties": false }, "OfferComparisonDelta": { "type": "object", "properties": { "monthly_net_savings": { "type": "number", "description": "Candidate's monthly net savings minus the current line item's." }, "upfront_cost": { "type": "number", "description": "Candidate's one-time upfront cost minus the current line item's. NOT a rate. Negative is less cash required at signing." }, "discount_rate": { "type": "number", "description": "Candidate's discount rate minus the current line item's (0-1 basis)." }, "breakeven_days": { "type": "number", "description": "Candidate's breakeven_days minus the current line item's. Null if either side has no finite breakeven.", "nullable": true } }, "required": [ "discount_rate", "monthly_net_savings", "upfront_cost" ], "additionalProperties": false }, "OfferComparisonEntry": { "type": "object", "properties": { "is_current": { "type": "boolean", "description": "True if this entry matches the line item's current offer + lease. Exactly one entry per response has this set; its `delta_vs_current` values are all zero." }, "offer_id": { "type": "string", "format": "uuid", "description": "Pass to PUT as `offer_id` to switch the line item to this offer." }, "offer": { "description": "Full offer details (type, region, instance, payment_option, etc).", "allOf": [ { "$ref": "#/components/schemas/CommitmentOffer" } ] }, "lease_menu_item_id": { "type": "string", "format": "uuid", "description": "Lease attached to this candidate, or null for none. Pass to PUT as `lease_menu_item_id`.", "nullable": true }, "selected_amount": { "type": "number", "description": "Commitment amount this candidate would be sized to \u2014 unit count for RIs / unit-based CUDs, dollar-per-hour rate for Savings Plans / spend-based CUDs. Pass to PUT as `selected_amount`; the server routes it to the right underlying column based on offer type." }, "contract_term": { "description": "Effective commitment term \u2014 derived from the lease lockin hours when `lease_menu_item_id` is set (e.g. '1_year_gris'), else from the offer's own duration (e.g. 'one_year', 'three_year'). This is the real lock-in period, not the offer's raw duration \u2014 a Compute Savings Plan offer with a 3-year duration paired with a 1-year lease yields `one_year_gris`, not `three_year`. Prefer this field over `offer.duration_seconds` when describing term length.", "type": "string", "enum": [ "one_year_gris", "thirty_day_gris", "two_month_gris", "three_month_gris", "four_month_gris", "five_month_gris", "six_month_gris", "seven_month_gris", "eight_month_gris", "nine_month_gris", "ten_month_gris", "eleven_month_gris", "twelve_month_gris", "thirteen_month_gris", "fourteen_month_gris", "fifteen_month_gris", "sixteen_month_gris", "seventeen_month_gris", "eighteen_month_gris", "nineteen_month_gris", "twenty_month_gris", "twenty_one_month_gris", "twenty_two_month_gris", "twenty_three_month_gris", "twenty_four_month_gris", "twenty_five_month_gris", "twenty_six_month_gris", "twenty_seven_month_gris", "twenty_eight_month_gris", "twenty_nine_month_gris", "thirty_month_gris", "thirty_one_month_gris", "thirty_two_month_gris", "thirty_three_month_gris", "thirty_four_month_gris", "thirty_five_month_gris", "one_year", "two_year", "three_year", "five_year", "zero_day", "thirty_day", "two_month", "three_month", "four_month", "five_month", "six_month", "seven_month", "eight_month", "nine_month", "ten_month", "eleven_month", "thirteen_month", "fourteen_month", "fifteen_month", "sixteen_month", "seventeen_month", "eighteen_month", "nineteen_month", "twenty_month", "twenty_one_month", "twenty_two_month", "twenty_three_month", "twenty_five_month", "twenty_six_month", "twenty_seven_month", "twenty_eight_month", "twenty_nine_month", "thirty_month", "thirty_one_month", "thirty_two_month", "thirty_three_month", "thirty_four_month", "thirty_five_month", null ], "nullable": true }, "discount_rate": { "type": "number", "description": "Discount rate vs on-demand (0-1) for this candidate." }, "breakeven_days": { "type": "number", "description": "Days until this candidate pays for itself. Null if breakeven is undefined (no net savings + no amortized cost).", "nullable": true }, "commitment_upfront_cost": { "type": "number", "description": "One-time dollars required at signing for this candidate. NOT a rate \u2014 do not sum with monthly-rate fields." }, "commitment_financials_monthly_rate": { "description": "Projected economics as 730-hour monthly rates, same shape as on line items and plans.", "allOf": [ { "$ref": "#/components/schemas/CommitmentFinancialsNoRebate" } ] }, "delta_vs_current": { "description": "Axis-by-axis difference vs the current offer. All zeros on the `is_current=true` entry.", "allOf": [ { "$ref": "#/components/schemas/OfferComparisonDelta" } ] } }, "required": [ "breakeven_days", "commitment_financials_monthly_rate", "commitment_upfront_cost", "contract_term", "delta_vs_current", "discount_rate", "is_current", "lease_menu_item_id", "offer", "offer_id", "selected_amount" ], "additionalProperties": false }, "LineItemOfferComparisonRow": { "type": "object", "properties": { "line_item_id": { "type": "string", "format": "uuid", "description": "Line item ID." }, "current": { "description": "The line item's current offer + lease, in the same shape as OfferComparisonEntrySchema. Its delta_vs_current is all zeros.", "allOf": [ { "$ref": "#/components/schemas/OfferComparisonEntry" } ] }, "candidates": { "type": "array", "description": "Alternative (offer, lease) pairs for this line item, filtered to the requested contract_terms and payment_options. Each entry carries its own contract_term and payment_option (on offer); fields offer_id, lease_menu_item_id, and selected_amount can be copied verbatim into POST /commitment-plans/{plan_id}/line-items/update (in the `updates` list) to swap the line item to that candidate.", "items": { "$ref": "#/components/schemas/OfferComparisonEntry" } } }, "required": [ "candidates", "current", "line_item_id" ], "additionalProperties": false }, "LineItemOfferComparisonResponse": { "type": "object", "properties": { "current_totals": { "description": "Plan-wide totals for the line items currently in scope (defaults to all selected, narrowed by line_item_ids if provided). Use this as the baseline when interpreting hypothetical deltas.", "allOf": [ { "$ref": "#/components/schemas/LineItemOfferComparisonTotals" } ] }, "hypothetical_totals": { "type": "array", "description": "One entry per (contract_term, payment_option) combination requested (or per distinct term present in candidates if contract_terms was omitted). Each entry's totals + delta_vs_current answer 'what's the plan-wide impact of this term?' in one place \u2014 no client-side summing across line items required.", "items": { "$ref": "#/components/schemas/HypotheticalTotal" } }, "data": { "type": "array", "description": "Per-line-item detail. Use when the user wants to drill into 'why does RDS not have a 3-year candidate' or to assemble an update payload.", "items": { "$ref": "#/components/schemas/LineItemOfferComparisonRow" } } }, "required": [ "current_totals", "data", "hypothetical_totals" ], "additionalProperties": false }, "BaseAttribute": { "type": "object", "properties": { "name": { "type": "string" }, "field": { "type": "string" }, "type": { "type": "string", "enum": [ "boolean", "integer", "float", "date", "datetime", "time", "currency", "percent", "string", "enum", "uuid", "tags" ] } }, "required": [ "field", "name", "type" ], "additionalProperties": false }, "Filter": { "type": "object", "properties": { "field": { "type": "string" }, "value": { "type": "string" }, "op": { "type": "string", "enum": [ "=", "!=", ">", ">=", "<", "<=", "in", "has", "contains" ] } }, "required": [ "field", "op", "value" ], "additionalProperties": false }, "BooleanAttribute": { "type": "object", "properties": { "name": { "type": "string" }, "field": { "type": "string" }, "type": { "type": "string", "enum": [ "boolean" ], "readOnly": true }, "filters": { "type": "array", "items": { "$ref": "#/components/schemas/Filter" } } }, "required": [ "field", "name", "type" ], "additionalProperties": false }, "UUIDAttribute": { "type": "object", "properties": { "name": { "type": "string" }, "field": { "type": "string" }, "type": { "type": "string", "enum": [ "uuid" ], "readOnly": true } }, "required": [ "field", "name", "type" ], "additionalProperties": false }, "StringAttribute": { "type": "object", "properties": { "name": { "type": "string" }, "field": { "type": "string" }, "type": { "type": "string", "enum": [ "string" ], "readOnly": true }, "filters": { "type": "array", "items": { "$ref": "#/components/schemas/Filter" } } }, "required": [ "field", "name", "type" ], "additionalProperties": false }, "IntegerAttribute": { "type": "object", "properties": { "name": { "type": "string" }, "field": { "type": "string" }, "type": { "type": "string", "enum": [ "integer" ], "readOnly": true } }, "required": [ "field", "name", "type" ], "additionalProperties": false }, "FloatAttribute": { "type": "object", "properties": { "name": { "type": "string" }, "field": { "type": "string" }, "type": { "type": "string", "enum": [ "float" ], "readOnly": true } }, "required": [ "field", "name", "type" ], "additionalProperties": false }, "CurrencyAttribute": { "type": "object", "properties": { "name": { "type": "string" }, "field": { "type": "string" }, "type": { "type": "string", "enum": [ "currency" ], "readOnly": true } }, "required": [ "field", "name", "type" ], "additionalProperties": false }, "PercentAttribute": { "type": "object", "properties": { "name": { "type": "string" }, "field": { "type": "string" }, "type": { "type": "string", "enum": [ "percent" ], "readOnly": true } }, "required": [ "field", "name", "type" ], "additionalProperties": false }, "DateTimeAttribute": { "type": "object", "properties": { "name": { "type": "string" }, "field": { "type": "string" }, "type": { "type": "string", "enum": [ "datetime" ], "readOnly": true } }, "required": [ "field", "name", "type" ], "additionalProperties": false }, "DateAttribute": { "type": "object", "properties": { "name": { "type": "string" }, "field": { "type": "string" }, "type": { "type": "string", "enum": [ "date" ], "readOnly": true } }, "required": [ "field", "name", "type" ], "additionalProperties": false }, "TimeAttribute": { "type": "object", "properties": { "name": { "type": "string" }, "field": { "type": "string" }, "type": { "type": "string", "enum": [ "time" ], "readOnly": true } }, "required": [ "field", "name", "type" ], "additionalProperties": false }, "EnumAttribute": { "type": "object", "properties": { "name": { "type": "string" }, "field": { "type": "string" }, "type": { "type": "string", "enum": [ "enum" ], "readOnly": true }, "filters": { "type": "array", "items": { "$ref": "#/components/schemas/Filter" } } }, "required": [ "field", "name", "type" ], "additionalProperties": false }, "TagsAttribute": { "type": "object", "properties": { "name": { "type": "string" }, "field": { "type": "string" }, "type": { "type": "string", "enum": [ "tags" ], "readOnly": true }, "tags": { "type": "object", "additionalProperties": { "type": "array", "items": { "type": "string" } } } }, "required": [ "field", "name", "type" ], "additionalProperties": false }, "Attribute": { "oneOf": [ { "$ref": "#/components/schemas/BooleanAttribute" }, { "$ref": "#/components/schemas/UUIDAttribute" }, { "$ref": "#/components/schemas/StringAttribute" }, { "$ref": "#/components/schemas/IntegerAttribute" }, { "$ref": "#/components/schemas/FloatAttribute" }, { "$ref": "#/components/schemas/CurrencyAttribute" }, { "$ref": "#/components/schemas/PercentAttribute" }, { "$ref": "#/components/schemas/DateTimeAttribute" }, { "$ref": "#/components/schemas/DateAttribute" }, { "$ref": "#/components/schemas/TimeAttribute" }, { "$ref": "#/components/schemas/EnumAttribute" }, { "$ref": "#/components/schemas/TagsAttribute" } ], "discriminator": { "propertyName": "type", "mapping": { "boolean": "#/components/schemas/BooleanAttribute", "uuid": "#/components/schemas/UUIDAttribute", "string": "#/components/schemas/StringAttribute", "integer": "#/components/schemas/IntegerAttribute", "float": "#/components/schemas/FloatAttribute", "currency": "#/components/schemas/CurrencyAttribute", "percent": "#/components/schemas/PercentAttribute", "datetime": "#/components/schemas/DateTimeAttribute", "date": "#/components/schemas/DateAttribute", "time": "#/components/schemas/TimeAttribute", "enum": "#/components/schemas/EnumAttribute", "tags": "#/components/schemas/TagsAttribute" } } }, "ResourceMatchSummary": { "type": "object", "properties": { "service": { "type": "string", "description": "Cloud service name (e.g. 'AmazonEC2', 'AmazonRDS')", "nullable": true }, "account_id": { "type": "string", "description": "Cloud account ID", "nullable": true }, "region": { "type": "string", "description": "Cloud region (e.g. 'us-east-1')", "nullable": true }, "resource_type": { "type": "string", "description": "Resource type within this group \u2014 instance family for compute (e.g. 'm5'), usage type for other services (e.g. 'Fargate-GB-Hours', 'Lambda-GB-Second'), or SKU name as fallback", "nullable": true }, "resource_count": { "type": "integer", "description": "Number of resources in this group" }, "projected_coverage": { "type": "number", "description": "Mean projected coverage across resources in this group (0-1) \u2014 the fraction of each resource's usage THIS plan would cover, averaged. Post-plan / projected: distinct from `resource.coverage` (the trailing-30-day actual coverage from existing commitments). For per-resource projected coverage, use the paginated /covered-resources endpoint." }, "commitment_financials_monthly_rate": { "description": "Plan economics scoped to this resource group, as 730-hour monthly rates. cloud_provider_cost has `{total}` only \u2014 per-group aggregates don't have the recurring/amortized_upfront split. commitment_savings has no rebate field on plans.", "allOf": [ { "$ref": "#/components/schemas/CommitmentFinancialsNoRebate" } ] } }, "additionalProperties": false }, "ResourceSKU": { "type": "object", "properties": { "id": { "type": "string", "description": "Composite ResourceSKU id \u2014 `||`. Pass directly to `/resources/skus/` for detail; do not parse it client-side." }, "resource_id": { "type": "string", "format": "uuid", "description": "Underlying Resource id. Stable across SKU/time variants of the same resource \u2014 multiple ResourceSKU rows can share a `resource_id` when the same resource ran with different SKUs over its lifetime." }, "catalog_sku_id": { "type": "string", "format": "uuid", "description": "Join key into `/catalog/skus/` for the public SKU record." }, "catalog_sku_org_id": { "type": "string", "description": "Org id that owns the catalog SKU \u2014 public-catalog SKUs use the public org id; custom-priced SKUs use the customer's org id." }, "provider": { "description": "Cloud provider (aws, azure, gcp)", "type": "string", "enum": [ "aws", "azure", "gcp", "kubernetes", "unknown" ] }, "provider_resource_id": { "type": "string", "description": "Provider's id for the resource (AWS ARN, Azure resource ID, GCP resource name). This is the canonical identifier the user sees in the cloud console." }, "provider_sku_id": { "type": "string", "description": "Provider's own SKU identifier", "nullable": true }, "name": { "type": "string", "description": "Resource name (Resource.name) \u2014 the user-applied label, e.g. 'prod-db-1'. Distinct from `sku_name`, which is the catalog SKU's display name.", "nullable": true }, "sku_name": { "type": "string", "description": "Catalog SKU display name (e.g. 'Amazon EC2 Instance', 'Amazon Aurora PostgreSQL Cluster'). Useful as a fallback label when `instance_type_family` and `usage_type` are both null. Distinct from `name` (the resource's user-applied label).", "nullable": true }, "integration_id": { "type": "string", "description": "Integration this resource belongs to" }, "billing_account_id": { "type": "string", "description": "Provider billing/management account id", "nullable": true }, "sub_account_id": { "type": "string", "description": "Provider account id that owns/created the resource", "nullable": true }, "resource_group": { "type": "string", "nullable": true }, "is_spot": { "type": "boolean", "nullable": true }, "availability_zone": { "type": "string", "nullable": true }, "service": { "type": "string", "description": "Full service name (e.g. 'Amazon Elastic Compute Cloud - Compute')", "nullable": true }, "provider_service": { "type": "string", "description": "Provider service code (e.g. 'AmazonEC2')", "nullable": true }, "family": { "type": "string", "description": "Product family (e.g. 'Compute Instance')", "nullable": true }, "region_code": { "type": "string", "description": "Region code (e.g. 'us-east-1')", "nullable": true }, "full_region_name": { "type": "string", "description": "Full region name (e.g. 'US East (N. Virginia)')", "nullable": true }, "instance_type": { "type": "string", "nullable": true }, "instance_type_family": { "type": "string", "nullable": true }, "usage_type": { "type": "string", "description": "Provider billing usage type (e.g. 'BoxUsage:m5.large'). The canonical join key against AWS Cost Explorer / billing line items.", "nullable": true }, "operation": { "type": "string", "description": "Provider billing operation code (e.g. 'RunInstances:0002')", "nullable": true }, "operating_system": { "type": "string", "nullable": true }, "tenancy": { "type": "string", "nullable": true }, "database_engine": { "type": "string", "nullable": true }, "database_edition": { "type": "string", "nullable": true }, "cache_engine": { "type": "string", "nullable": true }, "is_multi_az": { "type": "boolean", "nullable": true }, "is_current_generation": { "type": "boolean", "nullable": true }, "license_model": { "type": "string", "nullable": true }, "pre_installed_sw": { "type": "string", "nullable": true }, "processor_architecture": { "type": "string", "nullable": true }, "is_reservable": { "type": "boolean", "description": "Whether the SKU this resource is running has at least one reserved-term offering. Reservability is a property of the SKU, not the resource.", "nullable": true }, "is_byol": { "type": "boolean", "description": "Whether the SKU is a Bring-Your-Own-License variant. Currently set for AWS RDS BYOL only; false elsewhere.", "nullable": true }, "is_flexible": { "type": "boolean", "description": "Whether the SKU is eligible for instance-size flexibility under reserved offerings (provider+service-specific rules \u2014 see `is_flexible` on the ResourceSKU model).", "nullable": true }, "is_serverless": { "type": "boolean", "description": "Whether the SKU represents serverless usage.", "nullable": true }, "vcpu": { "type": "number", "nullable": true }, "memory": { "type": "number", "description": "Memory in bytes (not GB). Divide by 2**30 for GiB / 1e9 for GB if presenting to the user.", "nullable": true }, "ondemand_usage_unit": { "type": "string", "nullable": true }, "ondemand_usage_price": { "type": "number", "description": "On-demand unit price in `price_currency`. List price from the catalog \u2014 this is NOT the user's actual spend for this resource (see ResourceSKUWithMetricsSchema's `total_cost` or /cost-explorer for that).", "nullable": true }, "price_currency": { "type": "string", "nullable": true }, "usage_start": { "type": "string", "format": "date-time", "description": "Start of the period during which the resource was observed running this SKU. A resource that switched SKUs (e.g. instance-type resize) will have multiple ResourceSKU rows with disjoint `[usage_start, usage_end]` windows." }, "usage_end": { "type": "string", "format": "date-time", "description": "End of the period during which the resource was observed running this SKU. Within ~2 days of now generally indicates the resource is currently active with this SKU." }, "tags": { "type": "object", "description": "Merged provider + user tags (user tags take precedence). Empty when the resource has no tags. Use the `untagged` filter to find resources with no tags at all.", "additionalProperties": { "type": "string" }, "nullable": true } }, "additionalProperties": false }, "ResourceMatchDetail": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid", "description": "Match identifier \u2014 stable per (plan, line item, resource) tuple. For the resource's own id, see `resource.id`." }, "line_item_id": { "type": "string", "format": "uuid", "description": "Parent line item ID" }, "projected_coverage": { "type": "number", "description": "Fraction of this resource's usage THIS plan would cover (0-1). Post-plan / projected \u2014 distinct from `resource.coverage`, which is the trailing-30-day actual coverage from existing commitments (the BEFORE picture). For the rolled-up mean across a group, see the /covered-resources/summary endpoint." }, "commitment_financials_monthly_rate": { "description": "Plan economics scoped to this resource, as 730-hour monthly rates. cloud_provider_cost has `{total}` only \u2014 per-match data doesn't have the recurring/amortized_upfront split. commitment_savings has no rebate field on plans.", "allOf": [ { "$ref": "#/components/schemas/CommitmentFinancialsNoRebate" } ] }, "resource": { "description": "Detailed resource information including provider, service, region, instance type, account, and other infrastructure details", "anyOf": [ { "$ref": "#/components/schemas/ResourceSKU" }, { "type": "object", "nullable": true } ] } }, "required": [ "resource" ], "additionalProperties": false }, "AutoPurchase": { "type": "object", "properties": { "enabled": { "type": "boolean", "description": "Whether the schedule is currently active" }, "schedule": { "type": "string", "enum": [ "daily", "weekly", "monthly" ], "description": "Cadence: 'daily', 'weekly', or 'monthly'" }, "min_monthly_savings": { "type": "number", "description": "Dollar floor on projected monthly savings \u2014 plans that don't clear this are skipped even when the schedule fires." }, "start_date": { "type": "string", "format": "date", "description": "Earliest date the automation may fire (inclusive). Null = no lower bound.", "nullable": true }, "end_date": { "type": "string", "format": "date", "description": "Latest date the automation may fire (inclusive). Null = no upper bound.", "nullable": true }, "next_execution_date": { "type": "string", "format": "date", "description": "When the next automated run is scheduled (computed)" }, "last_executed_at": { "type": "string", "format": "date-time", "description": "When the last automated run fired, or null if it has not yet", "nullable": true } }, "required": [ "enabled", "end_date", "min_monthly_savings", "schedule", "start_date" ], "additionalProperties": false }, "CommitmentPlanTemplate": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid", "description": "Unique template identifier" }, "name": { "type": "string", "description": "Human-readable template name" }, "segment_id": { "type": "string", "format": "uuid", "description": "Segment this template generates plans for" }, "created_at": { "type": "string", "format": "date-time", "description": "When the template was created" }, "is_system_generated": { "type": "boolean", "description": "True if this template was created automatically by the system \u2014 the three built-ins that back Recommended / Balanced / High Savings. Describes origin, not role \u2014 system-generated templates are immutable." }, "configuration": { "description": "The inputs that plans generated from this template will use", "allOf": [ { "$ref": "#/components/schemas/CommitmentPlanConfiguration" } ] }, "auto_purchase": { "description": "Scheduled auto-purchase settings, or null if the template is not on a schedule.", "anyOf": [ { "$ref": "#/components/schemas/AutoPurchase" }, { "type": "object", "nullable": true } ] } }, "required": [ "auto_purchase", "configuration", "created_at", "id", "is_system_generated", "name", "segment_id" ], "additionalProperties": false }, "CreateAutoPurchase": { "type": "object", "properties": { "schedule": { "type": "string", "enum": [ "daily", "weekly", "monthly" ], "description": "Cadence: 'daily', 'weekly', or 'monthly'" }, "min_monthly_savings": { "type": "number", "default": 0.0, "description": "Dollar floor on projected monthly savings" }, "enabled": { "type": "boolean", "default": true, "description": "Whether the schedule is active" }, "start_date": { "type": "string", "format": "date", "default": null, "description": "Earliest date automation may fire. Null = no lower bound.", "nullable": true }, "end_date": { "type": "string", "format": "date", "default": null, "description": "Latest date automation may fire. Null = no upper bound.", "nullable": true } }, "required": [ "schedule" ], "additionalProperties": false }, "CreateCommitmentPlanTemplateArgs": { "type": "object", "properties": { "provider": { "description": "Cloud provider (aws, azure, gcp)", "example": "aws", "type": "string", "enum": [ "aws", "azure", "gcp", "kubernetes", "unknown" ] }, "segment_id": { "type": "string", "format": "uuid", "default": null, "description": "Optional segment ID to scope results. Defaults to the provider resources segment if not specified.", "nullable": true }, "name": { "type": "string", "description": "Template name" }, "configuration": { "description": "Plan configuration this template applies", "allOf": [ { "$ref": "#/components/schemas/CommitmentPlanConfiguration" } ] }, "auto_purchase": { "default": null, "description": "Optional auto-purchase schedule to attach", "anyOf": [ { "$ref": "#/components/schemas/CreateAutoPurchase" }, { "type": "object", "nullable": true } ] } }, "required": [ "configuration", "name", "provider" ], "additionalProperties": false }, "UpdateCommitmentPlanTemplateArgs": { "type": "object", "properties": { "name": { "type": "string", "description": "New template name" }, "configuration": { "description": "Replacement configuration", "allOf": [ { "$ref": "#/components/schemas/CommitmentPlanConfiguration" } ] }, "auto_purchase": { "description": "Replacement schedule. Pass null to clear an existing schedule. Omit the key to leave the schedule untouched.", "anyOf": [ { "$ref": "#/components/schemas/CreateAutoPurchase" }, { "type": "object", "nullable": true } ] } }, "additionalProperties": false }, "AvailableContractTerm": { "type": "object", "properties": { "contract_term": { "type": "string", "enum": [ "thirty_day_gris", "one_year_gris", "one_year", "three_year", "five_year" ], "description": "Contract term identifier (e.g. 'one_year', 'three_year', 'thirty_day_gris'). Pass directly as `contract_term` in a plan's `configuration.contract_specs`." }, "payment_options": { "type": "array", "description": "Payment options available for this specific (commitment_type, contract_term) pair. Pass one as `payment_option` in the plan's contract spec.", "items": { "type": "string", "enum": [ "no_upfront", "partial_upfront", "all_upfront" ] } } }, "required": [ "contract_term", "payment_options" ], "additionalProperties": false }, "AvailableCommitmentType": { "type": "object", "properties": { "commitment_type": { "type": "string", "description": "Commitment type identifier (e.g. 'aws/savingsplan/Compute', 'aws/AmazonEC2'). Pass directly as `commitment_type` in a plan's `configuration.contract_specs`." }, "contract_terms": { "type": "array", "description": "Contract terms this commitment type supports, each with its valid payment options. A `(contract_term, payment_option)` pair is only accepted in a plan spec if it appears here.", "items": { "$ref": "#/components/schemas/AvailableContractTerm" } } }, "required": [ "commitment_type", "contract_terms" ], "additionalProperties": false }, "CommitmentSavings": { "type": "object", "properties": { "net": { "type": "number", "description": "Net savings after Archera premium, including any rebate. Actual bill reduction. Headline 'savings'." }, "gross": { "type": "number", "description": "Savings before Archera premium. Equals covered_ondemand_cost - commitment_cost.breakdown.cloud_provider_cost.total." }, "rebate": { "type": "number", "description": "Recovery from Archera's moneyback guarantee. Non-zero only for guaranteed commitments past their lock-in date that are underperforming. Present only on commitment-level endpoints (inventory, detail, invoice line items, and commitment-level aggregates like commitments_metrics / commitments_summary) \u2014 0 when the commitment(s) have no rebate. Omitted entirely on plans and segment-level metrics. Already included in `net` when present." } }, "additionalProperties": false }, "CommitmentFinancials": { "type": "object", "properties": { "commitment_cost": { "$ref": "#/components/schemas/CommitmentCost" }, "commitment_savings": { "$ref": "#/components/schemas/CommitmentSavings" }, "covered_ondemand_cost": { "type": "number", "description": "On-demand cost of usage covered by commitments \u2014 baseline for savings. NOT a cost paid by the user. Equals commitment_cost.breakdown.cloud_provider_cost.total + commitment_savings.gross." } }, "additionalProperties": false }, "CommitmentWithMetrics": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid", "description": "Unique commitment identifier" }, "provider_reservation_id": { "type": "string", "description": "Cloud provider's ID for this commitment (e.g. AWS reservation ID)" }, "provider": { "description": "Cloud provider (aws, azure, gcp)", "type": "string", "enum": [ "aws", "azure", "gcp", "kubernetes", "unknown" ] }, "display_name": { "type": "string", "description": "Human-readable commitment name" }, "type": { "type": "string", "description": "Commitment type (e.g. 'Compute', 'EC2Instance', 'RDS')" }, "status": { "description": "Commitment status (e.g. 'active', 'expired', 'queued')", "type": "string", "enum": [ "active", "locked", "new", "reselling", "unlocked", "unknown", "cancelled", "expired", "recently_expired", "resold", "removed" ] }, "is_active": { "type": "boolean", "description": "Whether the commitment is currently active" }, "is_archera_guaranteed": { "type": "boolean", "description": "Whether this is an Archera Guaranteed Commitment" }, "account_id": { "type": "string", "description": "Cloud account ID this commitment is in", "nullable": true }, "billing_account_id": { "type": "string", "description": "Billing/management account ID", "nullable": true }, "start_date": { "type": "string", "format": "date-time", "description": "When the commitment started", "nullable": true }, "end_date": { "type": "string", "format": "date-time", "description": "When the commitment expires", "nullable": true }, "duration_seconds": { "type": "integer", "description": "Total commitment duration in seconds", "nullable": true }, "guarantee_start": { "type": "string", "format": "date-time", "description": "When the Archera guarantee period started", "nullable": true }, "guarantee_lockin_date": { "type": "string", "format": "date-time", "description": "When the Archera guarantee lock-in period ends", "nullable": true }, "guarantee_method": { "readOnly": true, "description": "How the Archera guarantee is delivered. 'rebate': Archera rebates the cost of the unused commitment directly to the user (as cash or credit toward Archera premiums). 'release': Archera takes over the commitment along with remaining payment obligations. Null for non-guaranteed commitments." }, "region": { "type": "string", "description": "Cloud region (e.g. 'us-east-1')", "nullable": true }, "instance_type": { "type": "string", "description": "Instance type (e.g. 'm5.xlarge')", "nullable": true }, "instance_family": { "type": "string", "description": "Instance family (e.g. 'm5')", "nullable": true }, "plan_type": { "type": "string", "description": "Plan type (e.g. 'Compute', 'EC2Instance')", "nullable": true }, "payment_option": { "description": "Payment option (e.g. 'no_upfront', 'partial_upfront', 'all_upfront')", "type": "string", "enum": [ "no_upfront", "partial_upfront", "all_upfront", null ], "nullable": true }, "offering_class": { "description": "Offering class (e.g. 'standard', 'convertible')", "type": "string", "enum": [ "standard", "convertible", null ], "nullable": true }, "is_flexible": { "type": "boolean", "description": "Whether the commitment has instance size flexibility", "nullable": true }, "instance_count": { "type": "integer", "description": "Number of instances covered", "nullable": true }, "contract_term": { "description": "Contract term (e.g. 'thirty_day_gris', 'one_year')", "type": "string", "enum": [ "one_year_gris", "thirty_day_gris", "two_month_gris", "three_month_gris", "four_month_gris", "five_month_gris", "six_month_gris", "seven_month_gris", "eight_month_gris", "nine_month_gris", "ten_month_gris", "eleven_month_gris", "twelve_month_gris", "thirteen_month_gris", "fourteen_month_gris", "fifteen_month_gris", "sixteen_month_gris", "seventeen_month_gris", "eighteen_month_gris", "nineteen_month_gris", "twenty_month_gris", "twenty_one_month_gris", "twenty_two_month_gris", "twenty_three_month_gris", "twenty_four_month_gris", "twenty_five_month_gris", "twenty_six_month_gris", "twenty_seven_month_gris", "twenty_eight_month_gris", "twenty_nine_month_gris", "thirty_month_gris", "thirty_one_month_gris", "thirty_two_month_gris", "thirty_three_month_gris", "thirty_four_month_gris", "thirty_five_month_gris", "one_year", "two_year", "three_year", "five_year", "zero_day", "thirty_day", "two_month", "three_month", "four_month", "five_month", "six_month", "seven_month", "eight_month", "nine_month", "ten_month", "eleven_month", "thirteen_month", "fourteen_month", "fifteen_month", "sixteen_month", "seventeen_month", "eighteen_month", "nineteen_month", "twenty_month", "twenty_one_month", "twenty_two_month", "twenty_three_month", "twenty_five_month", "twenty_six_month", "twenty_seven_month", "twenty_eight_month", "twenty_nine_month", "thirty_month", "thirty_one_month", "thirty_two_month", "thirty_three_month", "thirty_four_month", "thirty_five_month", null ], "nullable": true }, "utilization": { "type": "number", "description": "Utilization rate (0-1) over the metrics period", "nullable": true }, "commitment_upfront_cost": { "type": "number", "description": "One-time total dollars paid at signing for this commitment. NOT a rate \u2014 do not sum with monthly-rate fields. 0 for commitments with no-upfront payment options." }, "commitment_financials_monthly_rate": { "description": "Commitment economics as 730-hour monthly rates \u2014 cost, savings, and on-demand baseline. NOT a calendar month (672-744 hours). commitment_savings.rebate is populated with an actual value (possibly 0).", "allOf": [ { "$ref": "#/components/schemas/CommitmentFinancials" } ] } }, "required": [ "id", "provider" ], "additionalProperties": false }, "BreakdownEntry": { "type": "object", "properties": { "label": { "type": "string", "description": "Group label" }, "count": { "type": "integer", "description": "Number of commitments in this group" }, "average_utilization": { "type": "number", "description": "Cost-weighted average utilization within this group (0-1)" }, "commitment_financials_monthly_rate": { "description": "730-hour monthly-rate financials for this group. commitment_savings.rebate is the sum of rebates for commitments in this group.", "allOf": [ { "$ref": "#/components/schemas/CommitmentFinancials" } ] } }, "additionalProperties": false }, "CommitmentSummary": { "type": "object", "properties": { "total_active_commitments": { "type": "integer", "description": "Total number of active commitments" }, "total_guaranteed_commitments": { "type": "integer", "description": "Number of Archera Guaranteed Commitments" }, "total_native_commitments": { "type": "integer", "description": "Number of native cloud commitments (not guaranteed)" }, "average_utilization": { "type": "number", "description": "Cost-weighted average utilization across active commitments (0-1)" }, "expiring_30_days": { "type": "integer", "description": "Number of commitments expiring in the next 30 days" }, "expiring_90_days": { "type": "integer", "description": "Number of commitments expiring in the next 90 days" }, "commitment_financials_monthly_rate": { "description": "730-hour monthly-rate financials aggregated across all active commitments. commitment_savings.rebate is the sum of rebates across commitments.", "allOf": [ { "$ref": "#/components/schemas/CommitmentFinancials" } ] }, "by_term": { "type": "array", "description": "Breakdown by term length. Guaranteed commitments are grouped by their guarantee period (e.g. '30-Day Guaranteed', '1-Year Guaranteed'), native commitments by their cloud term (e.g. '1-Year Native', '3-Year Native').", "items": { "$ref": "#/components/schemas/BreakdownEntry" } }, "by_type": { "type": "array", "description": "Breakdown by commitment type (e.g. 'Compute', 'EC2Instance', 'RDS')", "items": { "$ref": "#/components/schemas/BreakdownEntry" } } }, "additionalProperties": false }, "DailyUtilization": { "type": "object", "properties": { "date": { "type": "string", "format": "date", "description": "Date of this data point" }, "active_hours": { "type": "number", "description": "Hours the commitment was active on this day (0-24)", "nullable": true }, "utilization": { "type": "number", "description": "Utilization rate for this day (0-1)" }, "commitment_financials_daily_total": { "description": "Sum of commitment economics for this single day (NOT a monthly rate). commitment_savings.rebate is the rebate accrued on this day.", "allOf": [ { "$ref": "#/components/schemas/CommitmentFinancials" } ] } }, "additionalProperties": false }, "AttributionSummaryEntry": { "type": "object", "properties": { "service": { "type": "string", "description": "Cloud service name", "nullable": true }, "account_id": { "type": "string", "description": "Cloud account ID", "nullable": true }, "region": { "type": "string", "description": "Cloud region", "nullable": true }, "resource_type": { "type": "string", "description": "Resource type \u2014 instance family for compute, usage type for other services, or SKU name as fallback", "nullable": true }, "resource_count": { "type": "integer", "description": "Number of resources in this group" }, "commitment_financials_monthly_rate": { "description": "730-hour monthly-rate financials for this group. cloud_provider_cost has `{total}` only \u2014 per-group data doesn't split into recurring / amortized_upfront. archera_premium is allocated proportionally by cloud_provider_cost share of the parent commitment; summing across groups yields the parent commitment's monthly premium. commitment_savings has no rebate field at this level \u2014 rebate is a commitment-wide concept.", "allOf": [ { "$ref": "#/components/schemas/CommitmentFinancialsNoRebate" } ] }, "attributed_utilization": { "type": "number", "description": "Share of the commitment's overall utilization attributed to this group (0-1). All groups' attributed_utilization values sum to the commitment's total utilization." } }, "additionalProperties": false }, "CommitmentDetail": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid", "description": "Unique commitment identifier" }, "provider_reservation_id": { "type": "string", "description": "Cloud provider's ID for this commitment (e.g. AWS reservation ID)" }, "provider": { "description": "Cloud provider (aws, azure, gcp)", "type": "string", "enum": [ "aws", "azure", "gcp", "kubernetes", "unknown" ] }, "display_name": { "type": "string", "description": "Human-readable commitment name" }, "type": { "type": "string", "description": "Commitment type (e.g. 'Compute', 'EC2Instance', 'RDS')" }, "status": { "description": "Commitment status (e.g. 'active', 'expired', 'queued')", "type": "string", "enum": [ "active", "locked", "new", "reselling", "unlocked", "unknown", "cancelled", "expired", "recently_expired", "resold", "removed" ] }, "is_active": { "type": "boolean", "description": "Whether the commitment is currently active" }, "is_archera_guaranteed": { "type": "boolean", "description": "Whether this is an Archera Guaranteed Commitment" }, "account_id": { "type": "string", "description": "Cloud account ID this commitment is in", "nullable": true }, "billing_account_id": { "type": "string", "description": "Billing/management account ID", "nullable": true }, "start_date": { "type": "string", "format": "date-time", "description": "When the commitment started", "nullable": true }, "end_date": { "type": "string", "format": "date-time", "description": "When the commitment expires", "nullable": true }, "duration_seconds": { "type": "integer", "description": "Total commitment duration in seconds", "nullable": true }, "guarantee_start": { "type": "string", "format": "date-time", "description": "When the Archera guarantee period started", "nullable": true }, "guarantee_lockin_date": { "type": "string", "format": "date-time", "description": "When the Archera guarantee lock-in period ends", "nullable": true }, "guarantee_method": { "readOnly": true, "description": "How the Archera guarantee is delivered. 'rebate': Archera rebates the cost of the unused commitment directly to the user (as cash or credit toward Archera premiums). 'release': Archera takes over the commitment along with remaining payment obligations. Null for non-guaranteed commitments." }, "region": { "type": "string", "description": "Cloud region (e.g. 'us-east-1')", "nullable": true }, "instance_type": { "type": "string", "description": "Instance type (e.g. 'm5.xlarge')", "nullable": true }, "instance_family": { "type": "string", "description": "Instance family (e.g. 'm5')", "nullable": true }, "plan_type": { "type": "string", "description": "Plan type (e.g. 'Compute', 'EC2Instance')", "nullable": true }, "payment_option": { "description": "Payment option (e.g. 'no_upfront', 'partial_upfront', 'all_upfront')", "type": "string", "enum": [ "no_upfront", "partial_upfront", "all_upfront", null ], "nullable": true }, "offering_class": { "description": "Offering class (e.g. 'standard', 'convertible')", "type": "string", "enum": [ "standard", "convertible", null ], "nullable": true }, "is_flexible": { "type": "boolean", "description": "Whether the commitment has instance size flexibility", "nullable": true }, "instance_count": { "type": "integer", "description": "Number of instances covered", "nullable": true }, "contract_term": { "description": "Contract term (e.g. 'thirty_day_gris', 'one_year')", "type": "string", "enum": [ "one_year_gris", "thirty_day_gris", "two_month_gris", "three_month_gris", "four_month_gris", "five_month_gris", "six_month_gris", "seven_month_gris", "eight_month_gris", "nine_month_gris", "ten_month_gris", "eleven_month_gris", "twelve_month_gris", "thirteen_month_gris", "fourteen_month_gris", "fifteen_month_gris", "sixteen_month_gris", "seventeen_month_gris", "eighteen_month_gris", "nineteen_month_gris", "twenty_month_gris", "twenty_one_month_gris", "twenty_two_month_gris", "twenty_three_month_gris", "twenty_four_month_gris", "twenty_five_month_gris", "twenty_six_month_gris", "twenty_seven_month_gris", "twenty_eight_month_gris", "twenty_nine_month_gris", "thirty_month_gris", "thirty_one_month_gris", "thirty_two_month_gris", "thirty_three_month_gris", "thirty_four_month_gris", "thirty_five_month_gris", "one_year", "two_year", "three_year", "five_year", "zero_day", "thirty_day", "two_month", "three_month", "four_month", "five_month", "six_month", "seven_month", "eight_month", "nine_month", "ten_month", "eleven_month", "thirteen_month", "fourteen_month", "fifteen_month", "sixteen_month", "seventeen_month", "eighteen_month", "nineteen_month", "twenty_month", "twenty_one_month", "twenty_two_month", "twenty_three_month", "twenty_five_month", "twenty_six_month", "twenty_seven_month", "twenty_eight_month", "twenty_nine_month", "thirty_month", "thirty_one_month", "thirty_two_month", "thirty_three_month", "thirty_four_month", "thirty_five_month", null ], "nullable": true }, "utilization": { "type": "number", "description": "Utilization rate (0-1) over the metrics period", "nullable": true }, "commitment_upfront_cost": { "type": "number", "description": "One-time total dollars paid at signing for this commitment. NOT a rate \u2014 do not sum with monthly-rate fields. 0 for commitments with no-upfront payment options." }, "commitment_financials_monthly_rate": { "description": "Commitment economics as 730-hour monthly rates \u2014 cost, savings, and on-demand baseline. NOT a calendar month (672-744 hours). commitment_savings.rebate is populated with an actual value (possibly 0).", "allOf": [ { "$ref": "#/components/schemas/CommitmentFinancials" } ] }, "period_start": { "type": "string", "description": "Effective start date of the returned data (YYYY-MM-DD). May be later than the requested start_date if the range was clamped to available data." }, "period_end": { "type": "string", "description": "Effective end date of the returned data, exclusive (YYYY-MM-DD). May be earlier than the requested end_date if the range was clamped to available data (e.g. cloud-provider cost-data lag)." }, "daily_utilizations": { "type": "array", "description": "Daily utilization data points for the effective time period", "items": { "$ref": "#/components/schemas/DailyUtilization" } }, "attribution_summary": { "type": "array", "description": "Resources covered by this commitment, aggregated by service, account, region, and resource type", "items": { "$ref": "#/components/schemas/AttributionSummaryEntry" } } }, "required": [ "id", "provider" ], "additionalProperties": false }, "CommitmentOfferComparisonTotals": { "type": "object", "properties": { "commitment_financials_monthly_rate": { "description": "730-hour monthly rate financials summed across the commitments in scope. Same shape as on plans / line items. No-rebate basis to keep totals apples-to-apples with hypothetical_totals.", "allOf": [ { "$ref": "#/components/schemas/CommitmentFinancialsNoRebate" } ] }, "commitment_upfront_cost": { "type": "number", "description": "Sum of one-time upfront dollars at signing across the commitments in scope. NOT a rate \u2014 do not sum with monthly-rate fields." } }, "required": [ "commitment_financials_monthly_rate", "commitment_upfront_cost" ], "additionalProperties": false }, "HypotheticalCommitmentDelta": { "type": "object", "properties": { "monthly_net_savings": { "type": "number", "description": "Hypothetical's monthly net savings minus current_totals'. Positive means switching saves more than the portfolio does today." }, "monthly_commitment_cost": { "type": "number", "description": "Hypothetical's monthly commitment cost minus current_totals'. Positive means more dollars committed monthly." }, "upfront_cost": { "type": "number", "description": "Hypothetical's one-time upfront cost minus current_totals'. NOT a rate." } }, "required": [ "monthly_commitment_cost", "monthly_net_savings", "upfront_cost" ], "additionalProperties": false }, "HypotheticalCommitmentEntry": { "type": "object", "properties": { "commitment_id": { "type": "string", "format": "uuid", "description": "Commitment ID." }, "actual_term": { "description": "The contract term this commitment actually contributes to the rollup at. Equals the target when an exact match exists; otherwise the longest available term <= target with the same payment option, or the commitment's current term as a last resort.", "type": "string", "enum": [ "one_year_gris", "thirty_day_gris", "two_month_gris", "three_month_gris", "four_month_gris", "five_month_gris", "six_month_gris", "seven_month_gris", "eight_month_gris", "nine_month_gris", "ten_month_gris", "eleven_month_gris", "twelve_month_gris", "thirteen_month_gris", "fourteen_month_gris", "fifteen_month_gris", "sixteen_month_gris", "seventeen_month_gris", "eighteen_month_gris", "nineteen_month_gris", "twenty_month_gris", "twenty_one_month_gris", "twenty_two_month_gris", "twenty_three_month_gris", "twenty_four_month_gris", "twenty_five_month_gris", "twenty_six_month_gris", "twenty_seven_month_gris", "twenty_eight_month_gris", "twenty_nine_month_gris", "thirty_month_gris", "thirty_one_month_gris", "thirty_two_month_gris", "thirty_three_month_gris", "thirty_four_month_gris", "thirty_five_month_gris", "one_year", "two_year", "three_year", "five_year", "zero_day", "thirty_day", "two_month", "three_month", "four_month", "five_month", "six_month", "seven_month", "eight_month", "nine_month", "ten_month", "eleven_month", "thirteen_month", "fourteen_month", "fifteen_month", "sixteen_month", "seventeen_month", "eighteen_month", "nineteen_month", "twenty_month", "twenty_one_month", "twenty_two_month", "twenty_three_month", "twenty_five_month", "twenty_six_month", "twenty_seven_month", "twenty_eight_month", "twenty_nine_month", "thirty_month", "thirty_one_month", "thirty_two_month", "thirty_three_month", "thirty_four_month", "thirty_five_month", null ], "nullable": true }, "actual_payment_option": { "description": "Payment option of the candidate this commitment contributes. Equals the target except when actual_term_reason='no_alternative' (falls back to current, which may have a different payment option).", "type": "string", "enum": [ "no_upfront", "partial_upfront", "all_upfront", null ], "nullable": true }, "actual_term_reason": { "type": "string", "enum": [ "exact_match", "fallback_closest_shorter", "no_alternative" ], "description": "Why this commitment landed at actual_term. exact_match = target available; fallback_closest_shorter = used the longest available term <= target with same payment option; no_alternative = nothing qualified, kept at current." }, "utilization_warning": { "type": "boolean", "description": "True if this commitment's recent utilization is below 50% \u2014 the comparison for it is less informative because candidates are sized from observed usage, not the commitment's nominal capacity. Surface to the user when present so the rollup is framed honestly." } }, "required": [ "actual_payment_option", "actual_term", "actual_term_reason", "commitment_id", "utilization_warning" ], "additionalProperties": false }, "HypotheticalCommitmentTotal": { "type": "object", "properties": { "contract_term": { "description": "Target contract term for this hypothetical.", "type": "string", "enum": [ "one_year_gris", "thirty_day_gris", "two_month_gris", "three_month_gris", "four_month_gris", "five_month_gris", "six_month_gris", "seven_month_gris", "eight_month_gris", "nine_month_gris", "ten_month_gris", "eleven_month_gris", "twelve_month_gris", "thirteen_month_gris", "fourteen_month_gris", "fifteen_month_gris", "sixteen_month_gris", "seventeen_month_gris", "eighteen_month_gris", "nineteen_month_gris", "twenty_month_gris", "twenty_one_month_gris", "twenty_two_month_gris", "twenty_three_month_gris", "twenty_four_month_gris", "twenty_five_month_gris", "twenty_six_month_gris", "twenty_seven_month_gris", "twenty_eight_month_gris", "twenty_nine_month_gris", "thirty_month_gris", "thirty_one_month_gris", "thirty_two_month_gris", "thirty_three_month_gris", "thirty_four_month_gris", "thirty_five_month_gris", "one_year", "two_year", "three_year", "five_year", "zero_day", "thirty_day", "two_month", "three_month", "four_month", "five_month", "six_month", "seven_month", "eight_month", "nine_month", "ten_month", "eleven_month", "thirteen_month", "fourteen_month", "fifteen_month", "sixteen_month", "seventeen_month", "eighteen_month", "nineteen_month", "twenty_month", "twenty_one_month", "twenty_two_month", "twenty_three_month", "twenty_five_month", "twenty_six_month", "twenty_seven_month", "twenty_eight_month", "twenty_nine_month", "thirty_month", "thirty_one_month", "thirty_two_month", "thirty_three_month", "thirty_four_month", "thirty_five_month", null ], "nullable": true }, "payment_option": { "description": "Target payment option for this hypothetical.", "type": "string", "enum": [ "no_upfront", "partial_upfront", "all_upfront" ] }, "commitment_financials_monthly_rate": { "description": "Rolled-up monthly-rate financials assuming each commitment adopts its candidate per the fallback rule.", "allOf": [ { "$ref": "#/components/schemas/CommitmentFinancialsNoRebate" } ] }, "commitment_upfront_cost": { "type": "number", "description": "Sum of one-time upfront dollars across the commitments under this hypothetical. NOT a rate." }, "delta_vs_current": { "description": "Axis-by-axis difference vs current_totals. The headline 'how much did I leave on the table' answer is delta_vs_current.monthly_net_savings.", "allOf": [ { "$ref": "#/components/schemas/HypotheticalCommitmentDelta" } ] }, "commitments": { "type": "array", "description": "Per-commitment resolution for this hypothetical. Use to call out fallbacks ('14 of 20 commitments would land at 3-year; 5 would fall back to 1-year GRI; 1 has no shorter alternative and stays at current') and underutilized-commitment caveats.", "items": { "$ref": "#/components/schemas/HypotheticalCommitmentEntry" } }, "low_utilization_commitment_count": { "type": "integer", "description": "Number of commitments in this rollup whose recent utilization is below 50%. Convenience aggregate of the per-row utilization_warning flags. Surface when non-zero: the rollup deltas may overstate the savings opportunity since underutilized commitments project candidate savings against hours that aren't actually consumed." } }, "required": [ "commitment_financials_monthly_rate", "commitment_upfront_cost", "commitments", "contract_term", "delta_vs_current", "low_utilization_commitment_count", "payment_option" ], "additionalProperties": false }, "CurrentCommitmentEntry": { "type": "object", "properties": { "commitment": { "description": "Full identity of the existing commitment \u2014 id, provider, type, instance/region/account, dates, payment_option, contract_term, guarantee info. Same shape as `commitment_details`'s identity fields (no metrics).", "allOf": [ { "$ref": "#/components/schemas/Commitment" } ] }, "utilization": { "type": "number", "description": "Cost-weighted utilization rate (0-1) over the recent observation period the comparison is built against. The grid sizes candidates from observed usage, so utilization context matters for framing \u2014 low utilization means candidates reflect alternatives sized for actual usage, not for the commitment's original capacity.", "nullable": true }, "discount_rate": { "type": "number", "description": "Discount rate vs on-demand (0-1), NET basis (`(gross - premium) / on-demand`) \u2014 apples-to-apples with candidates." }, "breakeven_days": { "type": "number", "description": "Days until the existing commitment paid for itself, computed from upfront_cost and hourly net savings. Null if net savings are not positive.", "nullable": true }, "commitment_upfront_cost": { "type": "number", "description": "One-time total dollars paid at signing for this commitment. NOT a rate \u2014 do not sum with monthly-rate fields. 0 for no-upfront payment options." }, "commitment_financials_monthly_rate": { "description": "730-hour monthly-rate financials for the existing commitment in the no-rebate shape used by candidates. `commitment_savings.net` here is `gross - premium`, NOT including any rebate the commitment may be accruing \u2014 kept on the no-rebate basis so deltas vs candidates are apples-to-apples. For true current economics including rebate income, call `commitment_details`.", "allOf": [ { "$ref": "#/components/schemas/CommitmentFinancialsNoRebate" } ] } }, "required": [ "commitment" ], "additionalProperties": false }, "CandidateOfferEntry_Exclude_IsCurrent": { "type": "object", "properties": { "offer_id": { "type": "string", "format": "uuid", "description": "Pass to PUT as `offer_id` to switch the line item to this offer." }, "offer": { "description": "Full offer details (type, region, instance, payment_option, etc).", "allOf": [ { "$ref": "#/components/schemas/CommitmentOffer" } ] }, "lease_menu_item_id": { "type": "string", "format": "uuid", "description": "Lease attached to this candidate, or null for none. Pass to PUT as `lease_menu_item_id`.", "nullable": true }, "selected_amount": { "type": "number", "description": "Commitment amount this candidate would be sized to \u2014 unit count for RIs / unit-based CUDs, dollar-per-hour rate for Savings Plans / spend-based CUDs. Pass to PUT as `selected_amount`; the server routes it to the right underlying column based on offer type." }, "contract_term": { "description": "Effective commitment term \u2014 derived from the lease lockin hours when `lease_menu_item_id` is set (e.g. '1_year_gris'), else from the offer's own duration (e.g. 'one_year', 'three_year'). This is the real lock-in period, not the offer's raw duration \u2014 a Compute Savings Plan offer with a 3-year duration paired with a 1-year lease yields `one_year_gris`, not `three_year`. Prefer this field over `offer.duration_seconds` when describing term length.", "type": "string", "enum": [ "one_year_gris", "thirty_day_gris", "two_month_gris", "three_month_gris", "four_month_gris", "five_month_gris", "six_month_gris", "seven_month_gris", "eight_month_gris", "nine_month_gris", "ten_month_gris", "eleven_month_gris", "twelve_month_gris", "thirteen_month_gris", "fourteen_month_gris", "fifteen_month_gris", "sixteen_month_gris", "seventeen_month_gris", "eighteen_month_gris", "nineteen_month_gris", "twenty_month_gris", "twenty_one_month_gris", "twenty_two_month_gris", "twenty_three_month_gris", "twenty_four_month_gris", "twenty_five_month_gris", "twenty_six_month_gris", "twenty_seven_month_gris", "twenty_eight_month_gris", "twenty_nine_month_gris", "thirty_month_gris", "thirty_one_month_gris", "thirty_two_month_gris", "thirty_three_month_gris", "thirty_four_month_gris", "thirty_five_month_gris", "one_year", "two_year", "three_year", "five_year", "zero_day", "thirty_day", "two_month", "three_month", "four_month", "five_month", "six_month", "seven_month", "eight_month", "nine_month", "ten_month", "eleven_month", "thirteen_month", "fourteen_month", "fifteen_month", "sixteen_month", "seventeen_month", "eighteen_month", "nineteen_month", "twenty_month", "twenty_one_month", "twenty_two_month", "twenty_three_month", "twenty_five_month", "twenty_six_month", "twenty_seven_month", "twenty_eight_month", "twenty_nine_month", "thirty_month", "thirty_one_month", "thirty_two_month", "thirty_three_month", "thirty_four_month", "thirty_five_month", null ], "nullable": true }, "discount_rate": { "type": "number", "description": "Discount rate vs on-demand (0-1) for this candidate." }, "breakeven_days": { "type": "number", "description": "Days until this candidate pays for itself. Null if breakeven is undefined (no net savings + no amortized cost).", "nullable": true }, "commitment_upfront_cost": { "type": "number", "description": "One-time dollars required at signing for this candidate. NOT a rate \u2014 do not sum with monthly-rate fields." }, "commitment_financials_monthly_rate": { "description": "Projected economics as 730-hour monthly rates, same shape as on line items and plans.", "allOf": [ { "$ref": "#/components/schemas/CommitmentFinancialsNoRebate" } ] }, "delta_vs_current": { "description": "Axis-by-axis difference vs the current offer. All zeros on the `is_current=true` entry.", "allOf": [ { "$ref": "#/components/schemas/OfferComparisonDelta" } ] } }, "required": [ "breakeven_days", "commitment_financials_monthly_rate", "commitment_upfront_cost", "contract_term", "delta_vs_current", "discount_rate", "lease_menu_item_id", "offer", "offer_id", "selected_amount" ], "additionalProperties": false }, "CommitmentOfferComparisonRow": { "type": "object", "properties": { "commitment_id": { "type": "string", "format": "uuid", "description": "Commitment ID." }, "current": { "description": "The existing commitment as the baseline \u2014 full identity, utilization, and current economics. Same shape as the singular tool's `current` block.", "allOf": [ { "$ref": "#/components/schemas/CurrentCommitmentEntry" } ] }, "candidates": { "type": "array", "description": "Candidate offer alternatives sized for the same observed usage, filtered to the requested contract_terms and payment_options. Each candidate's delta_vs_current is per-COMMITMENT (NOT portfolio-wide). Sorted by net monthly savings, best first. May be empty when no valid replacements exist.", "items": { "$ref": "#/components/schemas/CandidateOfferEntry_Exclude_IsCurrent" } } }, "required": [ "candidates", "commitment_id", "current" ], "additionalProperties": false }, "SkippedCommitment": { "type": "object", "properties": { "commitment_id": { "type": "string", "format": "uuid", "description": "Commitment ID." }, "reason": { "type": "string", "description": "Why this commitment was skipped \u2014 typically 'no recent SKU usage' (commitment has no usage attributed to it in the recent observation window, so the candidate grid can't be built). Surface to the user rather than dropping silently." } }, "required": [ "commitment_id", "reason" ], "additionalProperties": false }, "CommitmentOfferComparisonResponse": { "type": "object", "properties": { "current_totals": { "description": "Portfolio-wide totals for the commitments currently in scope today. Use as the baseline when interpreting hypothetical deltas.", "allOf": [ { "$ref": "#/components/schemas/CommitmentOfferComparisonTotals" } ] }, "hypothetical_totals": { "type": "array", "description": "One entry per (contract_term, payment_option) combination. Each entry's totals + delta_vs_current answer 'what's the portfolio-wide impact of this term?' in one place \u2014 no client-side summing across commitments required.", "items": { "$ref": "#/components/schemas/HypotheticalCommitmentTotal" } }, "data": { "type": "array", "description": "Per-commitment detail. Use when the user wants to drill into a specific commitment's alternatives.", "items": { "$ref": "#/components/schemas/CommitmentOfferComparisonRow" } }, "skipped_commitments": { "type": "array", "description": "Commitments that couldn't be compared (e.g. no recent SKU usage). Surface to the user so the rollup scope is honest \u2014 these commitments contribute neither to current_totals nor to hypothetical_totals.", "items": { "$ref": "#/components/schemas/SkippedCommitment" } } }, "required": [ "current_totals", "data", "hypothetical_totals", "skipped_commitments" ], "additionalProperties": false }, "DailyMetricsDataPoint": { "type": "object", "properties": { "date": { "type": "string", "description": "Date (YYYY-MM-DD)" }, "utilization": { "type": "number", "description": "Cost-weighted utilization rate for this day (0-1)" }, "underutilized_commitment_cost": { "type": "number", "description": "Cost of unused/underutilized commitment capacity for this day" }, "commitment_financials_daily_total": { "description": "Sum of commitment economics aggregated across commitments for this day. commitment_savings.rebate is the sum of per-commitment rebates for this day.", "allOf": [ { "$ref": "#/components/schemas/CommitmentFinancials" } ] } }, "additionalProperties": false }, "MetricsResponse": { "type": "object", "properties": { "period_start": { "type": "string", "description": "Effective start date of the returned data (YYYY-MM-DD). May be later than the requested start_date if the range was clamped to available data." }, "period_end": { "type": "string", "description": "Effective end date of the returned data, exclusive (YYYY-MM-DD). May be earlier than the requested end_date if the range was clamped to available data (e.g. cloud-provider cost-data lag)." }, "utilization": { "type": "number", "description": "Cost-weighted average utilization across the period (0-1)" }, "underutilized_commitment_cost": { "type": "number", "description": "Total cost of unused commitment capacity for the period" }, "commitment_financials_period_total": { "description": "Sum of commitment economics aggregated across commitments over the requested date range. commitment_savings.rebate is the sum of per-commitment rebates for the period.", "allOf": [ { "$ref": "#/components/schemas/CommitmentFinancials" } ] }, "data": { "type": "array", "description": "Per-day data points for trend analysis", "items": { "$ref": "#/components/schemas/DailyMetricsDataPoint" } } }, "additionalProperties": false }, "RecommendedAction": { "type": "object", "properties": { "action": { "type": "string", "description": "Action identifier (e.g. 'apply_recommended_plan')" }, "description": { "type": "string", "description": "Human-readable description of the recommended action" }, "monthly_impact": { "type": "number", "description": "Estimated monthly savings impact if action is taken", "nullable": true }, "priority": { "type": "string", "description": "Priority level: 'high', 'medium', or 'low'" } }, "additionalProperties": false }, "Overview": { "type": "object", "properties": { "monthly_net_savings": { "type": "number", "description": "Current monthly net savings rate from active commitments" }, "expiring_monthly_savings": { "type": "number", "description": "Monthly savings at risk from commitments expiring in the next 30 days" }, "coverage": { "type": "number", "description": "Overall commitment coverage ratio (0-1)", "nullable": true }, "utilization": { "type": "number", "description": "Overall commitment utilization ratio (0-1)", "nullable": true }, "purchase_missed_savings": { "type": "number", "description": "Monthly savings available by applying the recommended commitment plan. 0 if a plan has already been applied." }, "buyback_missed_savings": { "type": "number", "description": "Monthly savings available from pending buyback opportunities" }, "purchase_automation_enabled": { "type": "boolean", "description": "Whether automatic commitment purchasing is enabled" }, "buyback_automation_enabled": { "type": "boolean", "description": "Whether automatic buyback/sellback is enabled" }, "has_actioned_plan": { "type": "boolean", "description": "Whether the organization has ever applied a commitment plan" }, "data_available_since": { "type": "string", "format": "date", "description": "Earliest date cost data is available for this provider (null if no data)", "nullable": true }, "recommended_actions": { "type": "array", "description": "Prioritized list of recommended actions to improve savings", "items": { "$ref": "#/components/schemas/RecommendedAction" } } }, "additionalProperties": false }, "DailyCoveragePoint": { "type": "object", "properties": { "date": { "type": "string", "format": "date", "description": "Date of data point" }, "coverage": { "type": "number", "description": "Commitment coverage ratio for this day (0-1)" } }, "additionalProperties": false }, "DailyCoverageResponse": { "type": "object", "properties": { "period_start": { "type": "string", "description": "Effective start date of the returned data (YYYY-MM-DD). May be later than the requested start_date if the range was clamped to available data." }, "period_end": { "type": "string", "description": "Effective end date of the returned data, exclusive (YYYY-MM-DD). May be earlier than the requested end_date if the range was clamped to available data (e.g. cloud-provider cost-data lag)." }, "coverage": { "type": "number", "description": "Mean commitment coverage across the effective date range (0-1). Share of reservable spend covered by commitments.", "nullable": true }, "daily": { "type": "array", "description": "Per-day data points for trend analysis.", "items": { "$ref": "#/components/schemas/DailyCoveragePoint" } } }, "additionalProperties": false }, "DailySavingsPoint": { "type": "object", "properties": { "date": { "type": "string", "format": "date", "description": "Date of data point" }, "commitment_financials_daily_total": { "description": "Sum of commitment economics for this single day.", "allOf": [ { "$ref": "#/components/schemas/CommitmentFinancialsNoRebate" } ] } }, "additionalProperties": false }, "DailySavingsResponse": { "type": "object", "properties": { "period_start": { "type": "string", "description": "Effective start date of the returned data (YYYY-MM-DD). May be later than the requested start_date if the range was clamped to available data." }, "period_end": { "type": "string", "description": "Effective end date of the returned data, exclusive (YYYY-MM-DD). May be earlier than the requested end_date if the range was clamped to available data (e.g. cloud-provider cost-data lag)." }, "commitment_financials_period_total": { "description": "Sum of commitment economics across the effective date range.", "allOf": [ { "$ref": "#/components/schemas/CommitmentFinancialsNoRebate" } ] }, "daily": { "type": "array", "description": "Per-day data points for trend analysis.", "items": { "$ref": "#/components/schemas/DailySavingsPoint" } } }, "additionalProperties": false }, "PricingTypeBreakdown": { "type": "object", "properties": { "ondemand_cost": { "type": "number", "description": "Cost from on-demand (uncovered) usage." }, "commitment_cost": { "description": "Total cost from commitment-covered usage, with breakdown into cloud provider portion and Archera premium.", "allOf": [ { "$ref": "#/components/schemas/CommitmentCost" } ] }, "spot_cost": { "type": "number", "description": "Cost from spot instances." } }, "additionalProperties": false }, "DailyReservableCostPoint": { "type": "object", "properties": { "date": { "type": "string", "format": "date", "description": "Date of data point" }, "total_cost": { "type": "number", "description": "Total paid for reservable services this day across all pricing types (ondemand_cost + commitment_cost.total + spot_cost). Headline 'cost'." }, "if_all_ondemand_cost": { "type": "number", "description": "What total_cost would be if all reservable usage ran at on-demand prices. Baseline for total savings across all discount types." }, "by_pricing_type": { "$ref": "#/components/schemas/PricingTypeBreakdown" } }, "additionalProperties": false }, "DailyReservableCostResponse": { "type": "object", "properties": { "period_start": { "type": "string", "description": "Effective start date of the returned data (YYYY-MM-DD). May be later than the requested start_date if the range was clamped to available data." }, "period_end": { "type": "string", "description": "Effective end date of the returned data, exclusive (YYYY-MM-DD). May be earlier than the requested end_date if the range was clamped to available data (e.g. cloud-provider cost-data lag)." }, "total_cost": { "type": "number", "description": "Total paid for reservable services over the effective date range." }, "if_all_ondemand_cost": { "type": "number", "description": "On-demand baseline: what the range would cost at on-demand prices." }, "total_savings": { "type": "number", "description": "Total savings across all discount types (if_all_ondemand_cost - total_cost)." }, "by_pricing_type": { "$ref": "#/components/schemas/PricingTypeBreakdown" }, "daily": { "type": "array", "description": "Per-day data points for trend analysis.", "items": { "$ref": "#/components/schemas/DailyReservableCostPoint" } } }, "additionalProperties": false }, "Segment": { "type": "object", "properties": { "id": { "type": "string", "description": "Unique segment identifier" }, "name": { "type": "string", "description": "Segment name" }, "provider": { "description": "Cloud provider (aws, azure, gcp)", "type": "string", "enum": [ "aws", "azure", "gcp", "kubernetes", "unknown" ] }, "is_system_generated": { "type": "boolean", "description": "True if this segment was created automatically by the system (e.g. the provider-resources default segment). Describes origin, not role \u2014 system-generated segments are immutable." }, "description": { "type": "string", "description": "Human-readable description of the segment", "nullable": true }, "status": { "description": "Segment status: 'new' means the segment was just created and metrics data is not yet available; 'completed' means data has been populated and the segment can be used with daily metrics endpoints.", "type": "string", "enum": [ "new", "reviewed", "scheduled", "completed", "draft", "needs_review", "in_progress" ] }, "filters": { "readOnly": true, "description": "The segment's filter configuration, in the same format accepted by create_segment. Excludes the provider filter (already shown in the provider field)." }, "monthly_budget": { "type": "number", "description": "User-defined monthly spend budget for this segment, in USD. Null if no budget has been set.", "nullable": true } }, "additionalProperties": false }, "CreateSegmentArgs": { "type": "object", "properties": { "name": { "type": "string", "description": "Segment name" }, "provider": { "description": "Cloud provider (aws, azure, gcp)", "type": "string", "enum": [ "aws", "azure", "gcp", "kubernetes", "unknown" ] }, "filters": { "type": "object", "description": "Filter tree using and/or/not combinators with field/op/value leaves. Use `has` on `tags` with nested key/value filters for tag matches. The provider filter is injected automatically.", "additionalProperties": {} }, "description": { "type": "string", "default": null, "description": "Human-readable description", "nullable": true } }, "required": [ "filters", "name", "provider" ], "additionalProperties": false }, "PremiumDiscount": { "type": "object", "properties": { "rate": { "type": "number", "description": "Discount rate (0-1, usually 0)." }, "amount": { "type": "number", "description": "Dollars removed by the discount. Equals list_price * rate." } }, "additionalProperties": false }, "PremiumBilling": { "type": "object", "properties": { "charged": { "type": "number", "description": "Premium actually charged on the bill \u2014 post-discount, post-credits. Headline: 'how much the user paid Archera for this billing scope.'" }, "list_price": { "type": "number", "description": "Pre-discount, pre-credits premium. Starting point of the billing waterfall." }, "discount": { "description": "Discount applied to the list price (rate and precomputed amount).", "allOf": [ { "$ref": "#/components/schemas/PremiumDiscount" } ] }, "credits_applied": { "type": "number", "description": "Credits (from rebates or other sources) applied to reduce the premium." } }, "additionalProperties": false }, "InvoiceSectionList": { "type": "object", "properties": { "provider": { "description": "Cloud provider (aws, azure, gcp)", "type": "string", "enum": [ "aws", "azure", "gcp", "kubernetes", "unknown" ] }, "commitment_financials_invoice_month": { "description": "Aggregated list-price figures for this provider over the invoice's calendar month. commitment_cost.breakdown.archera_premium is the list-price premium (sums cleanly from line items); commitment_savings.net is the pre-invoice-adjustments view (gross - list_price + rebate). For the real charged premium and the discount/credits waterfall, see `premium_billing`.", "allOf": [ { "$ref": "#/components/schemas/CommitmentFinancials" } ] }, "premium_billing": { "description": "Premium waterfall for this provider \u2014 list_price, discount, credits_applied, and the charged amount that hits the bill. `charged` is the answer to 'what did the user actually pay Archera for this provider' \u2014 not the archera_premium inside commitment_financials_invoice_month, which is list-price.", "allOf": [ { "$ref": "#/components/schemas/PremiumBilling" } ] }, "total_cloud_bill": { "type": "number", "description": "Total cloud provider bill for this period, before applying any credits or enterprise discounts (AWS EDP/PPA, Azure MACC, GCP commit agreements)" } }, "additionalProperties": false }, "InvoiceList": { "type": "object", "properties": { "id": { "type": "string", "description": "Invoice identifier" }, "year": { "type": "integer", "description": "Invoice year" }, "month": { "type": "integer", "description": "Invoice month (1-12)" }, "invoice_date": { "type": "string", "format": "date", "description": "Invoice date (first of the month)" }, "commitment_financials_invoice_month": { "description": "Aggregated list-price figures across all providers for the invoice's calendar month. commitment_cost.breakdown.archera_premium is the list-price premium (sums cleanly from line items/sections); commitment_savings.net is the pre-invoice-adjustments view (gross - list_price + rebate). For the real charged premium and the discount/credits waterfall, see `premium_billing`.", "allOf": [ { "$ref": "#/components/schemas/CommitmentFinancials" } ] }, "premium_billing": { "description": "Premium waterfall across all providers \u2014 list_price, discount, credits_applied, and the charged amount. `premium_billing.charged` is the answer to 'how much did I pay Archera this month' \u2014 not the archera_premium inside commitment_financials_invoice_month, which is list-price.", "allOf": [ { "$ref": "#/components/schemas/PremiumBilling" } ] }, "total_cloud_bill": { "readOnly": true, "description": "Total cloud provider bill across all providers, before applying any credits or enterprise discounts (AWS EDP/PPA, Azure MACC, GCP commit agreements)." }, "sections": { "description": "Per-provider breakdown of the invoice", "type": "array", "items": { "$ref": "#/components/schemas/InvoiceSectionList" } } }, "additionalProperties": false }, "InvoiceBreakdown": { "type": "object", "properties": { "label": { "type": "string", "description": "Group label" }, "count": { "type": "integer", "description": "Number of line items in this group" }, "commitment_financials_invoice_month": { "description": "Aggregated list-price invoice-month financials for this group. commitment_cost.breakdown.archera_premium is list-price, matching line-item/section/invoice aggregation.", "allOf": [ { "$ref": "#/components/schemas/CommitmentFinancials" } ] } }, "additionalProperties": false }, "InvoiceSection": { "type": "object", "properties": { "provider": { "description": "Cloud provider (aws, azure, gcp)", "type": "string", "enum": [ "aws", "azure", "gcp", "kubernetes", "unknown" ] }, "commitment_financials_invoice_month": { "description": "Aggregated list-price figures for this provider over the invoice's calendar month. commitment_cost.breakdown.archera_premium is the list-price premium (sums cleanly from line items); commitment_savings.net is the pre-invoice-adjustments view (gross - list_price + rebate). For the real charged premium and the discount/credits waterfall, see `premium_billing`.", "allOf": [ { "$ref": "#/components/schemas/CommitmentFinancials" } ] }, "premium_billing": { "description": "Premium waterfall for this provider \u2014 list_price, discount, credits_applied, and the charged amount that hits the bill. `charged` is the answer to 'what did the user actually pay Archera for this provider' \u2014 not the archera_premium inside commitment_financials_invoice_month, which is list-price.", "allOf": [ { "$ref": "#/components/schemas/PremiumBilling" } ] }, "total_cloud_bill": { "type": "number", "description": "Total cloud provider bill for this period, before applying any credits or enterprise discounts (AWS EDP/PPA, Azure MACC, GCP commit agreements)" }, "by_term": { "type": "array", "description": "This provider section's invoice-month metrics broken down by contract term (from `InvoiceLineItem.contract_term`). GRI labels = Archera Guaranteed; Commitment labels = native cloud commitments. Sum across GRI labels for the insured view, across Commitment labels for the uninsured view.", "items": { "$ref": "#/components/schemas/InvoiceBreakdown" } }, "by_type": { "type": "array", "description": "This provider section's invoice-month metrics broken down by commitment type (e.g. 'Compute', 'EC2Instance', 'RDS').", "items": { "$ref": "#/components/schemas/InvoiceBreakdown" } } }, "additionalProperties": false }, "Invoice": { "type": "object", "properties": { "id": { "type": "string", "description": "Invoice identifier" }, "year": { "type": "integer", "description": "Invoice year" }, "month": { "type": "integer", "description": "Invoice month (1-12)" }, "invoice_date": { "type": "string", "format": "date", "description": "Invoice date (first of the month)" }, "commitment_financials_invoice_month": { "description": "Aggregated list-price figures across all providers for the invoice's calendar month. commitment_cost.breakdown.archera_premium is the list-price premium (sums cleanly from line items/sections); commitment_savings.net is the pre-invoice-adjustments view (gross - list_price + rebate). For the real charged premium and the discount/credits waterfall, see `premium_billing`.", "allOf": [ { "$ref": "#/components/schemas/CommitmentFinancials" } ] }, "premium_billing": { "description": "Premium waterfall across all providers \u2014 list_price, discount, credits_applied, and the charged amount. `premium_billing.charged` is the answer to 'how much did I pay Archera this month' \u2014 not the archera_premium inside commitment_financials_invoice_month, which is list-price.", "allOf": [ { "$ref": "#/components/schemas/PremiumBilling" } ] }, "total_cloud_bill": { "readOnly": true, "description": "Total cloud provider bill across all providers, before applying any credits or enterprise discounts (AWS EDP/PPA, Azure MACC, GCP commit agreements)." }, "sections": { "description": "Per-provider breakdown of the invoice", "type": "array", "items": { "$ref": "#/components/schemas/InvoiceSection" } }, "by_term": { "type": "array", "description": "Invoice-month metrics across all providers broken down by contract term (from `InvoiceLineItem.contract_term`). GRI labels = Archera Guaranteed; Commitment labels = native cloud commitments. Sum across GRI labels for the insured view, across Commitment labels for the uninsured view.", "items": { "$ref": "#/components/schemas/InvoiceBreakdown" } }, "by_type": { "type": "array", "description": "Invoice-month metrics across all providers broken down by commitment type (e.g. 'Compute', 'EC2Instance', 'RDS').", "items": { "$ref": "#/components/schemas/InvoiceBreakdown" } } }, "additionalProperties": false }, "InvoiceLineItem": { "type": "object", "properties": { "id": { "type": "string", "description": "Line item identifier" }, "commitment_id": { "type": "string", "description": "Associated commitment identifier" }, "commitment": { "description": "Full commitment details (identity, dates, guarantee info, region/instance info, contract term). Metrics (utilization/financials) aren't included here \u2014 this invoice line item has its own financials.", "allOf": [ { "$ref": "#/components/schemas/Commitment" } ] }, "utilization": { "type": "number", "description": "Average utilization for this commitment during the invoice period (0-1)" }, "contract_term": { "description": "Contract term of the commitment as it applied during this invoice's billing month \u2014 reflects the guarantee lock-in in effect at bill time. Prefer this over `commitment.contract_term`, which reflects the commitment's current term and may have shifted since (e.g. lock-in rolled over, guarantee changed).", "type": "string", "enum": [ "one_year_gris", "thirty_day_gris", "two_month_gris", "three_month_gris", "four_month_gris", "five_month_gris", "six_month_gris", "seven_month_gris", "eight_month_gris", "nine_month_gris", "ten_month_gris", "eleven_month_gris", "twelve_month_gris", "thirteen_month_gris", "fourteen_month_gris", "fifteen_month_gris", "sixteen_month_gris", "seventeen_month_gris", "eighteen_month_gris", "nineteen_month_gris", "twenty_month_gris", "twenty_one_month_gris", "twenty_two_month_gris", "twenty_three_month_gris", "twenty_four_month_gris", "twenty_five_month_gris", "twenty_six_month_gris", "twenty_seven_month_gris", "twenty_eight_month_gris", "twenty_nine_month_gris", "thirty_month_gris", "thirty_one_month_gris", "thirty_two_month_gris", "thirty_three_month_gris", "thirty_four_month_gris", "thirty_five_month_gris", "one_year", "two_year", "three_year", "five_year", "zero_day", "thirty_day", "two_month", "three_month", "four_month", "five_month", "six_month", "seven_month", "eight_month", "nine_month", "ten_month", "eleven_month", "thirteen_month", "fourteen_month", "fifteen_month", "sixteen_month", "seventeen_month", "eighteen_month", "nineteen_month", "twenty_month", "twenty_one_month", "twenty_two_month", "twenty_three_month", "twenty_five_month", "twenty_six_month", "twenty_seven_month", "twenty_eight_month", "twenty_nine_month", "thirty_month", "thirty_one_month", "thirty_two_month", "thirty_three_month", "thirty_four_month", "thirty_five_month", null ], "nullable": true }, "commitment_financials_invoice_month": { "description": "Actual dollars billed for this line item over the invoice's calendar month. commitment_cost.breakdown.archera_premium is this line item's list-price premium \u2014 invoice-wide discount/credits don't attribute per-commitment, so there's no line-item charged value. For the real charged premium on the bill and the full waterfall (list_price, discount, credits), see the parent section's or invoice's `premium_billing`.", "allOf": [ { "$ref": "#/components/schemas/CommitmentFinancials" } ] } }, "additionalProperties": false }, "CostExplorerDataPoint": { "type": "object", "properties": { "date": { "type": "string", "description": "Date or month label for this data point" }, "cost": { "type": "number", "description": "Cost for this period" } }, "additionalProperties": false }, "CostExplorerGroup": { "type": "object", "properties": { "name": { "type": "string", "description": "Group name (e.g. service name, account ID, region)" }, "total_cost": { "type": "number", "description": "Total cost for this group over the entire period" }, "percentage": { "type": "number", "description": "This group's share of total spend (0-1)" }, "data": { "type": "array", "default": null, "description": "Time-series data points for this group. Only included when include_time_series=true.", "items": { "$ref": "#/components/schemas/CostExplorerDataPoint" }, "nullable": true } }, "additionalProperties": false }, "CostExplorerResponse": { "type": "object", "properties": { "period_start": { "type": "string", "description": "Effective start date of the returned data (YYYY-MM-DD). May be later than the requested start_date if the range was clamped to available data." }, "period_end": { "type": "string", "description": "Effective end date of the returned data, exclusive (YYYY-MM-DD). May be earlier than the requested end_date if the range was clamped to available data (e.g. cloud-provider cost-data lag)." }, "total_cost": { "type": "number", "description": "Total cost across all groups over the effective date range. Headline 'cost' \u2014 the answer to 'what did I spend.' Sum of groups[*].total_cost." }, "groups": { "type": "array", "description": "Cost groups, sorted by total spend descending", "items": { "$ref": "#/components/schemas/CostExplorerGroup" } } }, "additionalProperties": false }, "CostExplorerFilters": { "type": "object", "properties": { "service": { "type": "array", "description": "Available cloud service names", "items": { "type": "string" } }, "account_id": { "type": "array", "description": "Available cloud account IDs", "items": { "type": "string" } }, "region": { "type": "array", "description": "Available cloud regions", "items": { "type": "string" } }, "instance_family": { "type": "array", "description": "Available instance families (AWS only)", "items": { "type": "string" } }, "operating_system": { "type": "array", "description": "Available operating systems (AWS only)", "items": { "type": "string" } }, "tenancy": { "type": "array", "description": "Available tenancy types (AWS only)", "items": { "type": "string" } } }, "additionalProperties": false }, "Integration": { "type": "object", "properties": { "id": { "type": "string", "description": "Integration identifier" }, "provider": { "description": "Cloud provider (aws, azure, gcp)", "type": "string", "enum": [ "aws", "azure", "gcp", "kubernetes", "unknown" ] }, "name": { "type": "string", "description": "Integration name", "nullable": true }, "provider_organization_id": { "type": "string", "description": "Cloud-provider organization/tenant identifier (AWS Organizations ID, Azure tenant ID, GCP organization ID).", "nullable": true }, "active": { "type": "boolean", "description": "Whether this integration has active credentials" }, "currency": { "type": "string", "description": "Billing currency (e.g. 'USD')", "nullable": true }, "data_available_since": { "type": "string", "format": "date-time", "description": "Earliest date cost data is available from this integration", "nullable": true }, "data_available_until": { "type": "string", "format": "date-time", "description": "Latest date cost data is available from this integration", "nullable": true } }, "additionalProperties": false }, "IntegrationDetail": { "type": "object", "properties": { "id": { "type": "string", "description": "Integration identifier" }, "provider": { "description": "Cloud provider (aws, azure, gcp)", "type": "string", "enum": [ "aws", "azure", "gcp", "kubernetes", "unknown" ] }, "name": { "type": "string", "description": "Integration name", "nullable": true }, "provider_organization_id": { "type": "string", "description": "Cloud-provider organization/tenant identifier (AWS Organizations ID, Azure tenant ID, GCP organization ID).", "nullable": true }, "active": { "type": "boolean", "description": "Whether this integration has active credentials" }, "currency": { "type": "string", "description": "Billing currency (e.g. 'USD')", "nullable": true }, "data_available_since": { "type": "string", "format": "date-time", "description": "Earliest date cost data is available from this integration", "nullable": true }, "data_available_until": { "type": "string", "format": "date-time", "description": "Latest date cost data is available from this integration", "nullable": true }, "accounts": { "readOnly": true, "description": "Cloud accounts associated with this integration" } }, "additionalProperties": false }, "ResourceSKUWithMetrics": { "type": "object", "properties": { "id": { "type": "string", "description": "Composite ResourceSKU id \u2014 `||`. Pass directly to `/resources/skus/` for detail; do not parse it client-side." }, "resource_id": { "type": "string", "format": "uuid", "description": "Underlying Resource id. Stable across SKU/time variants of the same resource \u2014 multiple ResourceSKU rows can share a `resource_id` when the same resource ran with different SKUs over its lifetime." }, "catalog_sku_id": { "type": "string", "format": "uuid", "description": "Join key into `/catalog/skus/` for the public SKU record." }, "catalog_sku_org_id": { "type": "string", "description": "Org id that owns the catalog SKU \u2014 public-catalog SKUs use the public org id; custom-priced SKUs use the customer's org id." }, "provider": { "description": "Cloud provider (aws, azure, gcp)", "type": "string", "enum": [ "aws", "azure", "gcp", "kubernetes", "unknown" ] }, "provider_resource_id": { "type": "string", "description": "Provider's id for the resource (AWS ARN, Azure resource ID, GCP resource name). This is the canonical identifier the user sees in the cloud console." }, "provider_sku_id": { "type": "string", "description": "Provider's own SKU identifier", "nullable": true }, "name": { "type": "string", "description": "Resource name (Resource.name) \u2014 the user-applied label, e.g. 'prod-db-1'. Distinct from `sku_name`, which is the catalog SKU's display name.", "nullable": true }, "sku_name": { "type": "string", "description": "Catalog SKU display name (e.g. 'Amazon EC2 Instance', 'Amazon Aurora PostgreSQL Cluster'). Useful as a fallback label when `instance_type_family` and `usage_type` are both null. Distinct from `name` (the resource's user-applied label).", "nullable": true }, "integration_id": { "type": "string", "description": "Integration this resource belongs to" }, "billing_account_id": { "type": "string", "description": "Provider billing/management account id", "nullable": true }, "sub_account_id": { "type": "string", "description": "Provider account id that owns/created the resource", "nullable": true }, "resource_group": { "type": "string", "nullable": true }, "is_spot": { "type": "boolean", "nullable": true }, "availability_zone": { "type": "string", "nullable": true }, "service": { "type": "string", "description": "Full service name (e.g. 'Amazon Elastic Compute Cloud - Compute')", "nullable": true }, "provider_service": { "type": "string", "description": "Provider service code (e.g. 'AmazonEC2')", "nullable": true }, "family": { "type": "string", "description": "Product family (e.g. 'Compute Instance')", "nullable": true }, "region_code": { "type": "string", "description": "Region code (e.g. 'us-east-1')", "nullable": true }, "full_region_name": { "type": "string", "description": "Full region name (e.g. 'US East (N. Virginia)')", "nullable": true }, "instance_type": { "type": "string", "nullable": true }, "instance_type_family": { "type": "string", "nullable": true }, "usage_type": { "type": "string", "description": "Provider billing usage type (e.g. 'BoxUsage:m5.large'). The canonical join key against AWS Cost Explorer / billing line items.", "nullable": true }, "operation": { "type": "string", "description": "Provider billing operation code (e.g. 'RunInstances:0002')", "nullable": true }, "operating_system": { "type": "string", "nullable": true }, "tenancy": { "type": "string", "nullable": true }, "database_engine": { "type": "string", "nullable": true }, "database_edition": { "type": "string", "nullable": true }, "cache_engine": { "type": "string", "nullable": true }, "is_multi_az": { "type": "boolean", "nullable": true }, "is_current_generation": { "type": "boolean", "nullable": true }, "license_model": { "type": "string", "nullable": true }, "pre_installed_sw": { "type": "string", "nullable": true }, "processor_architecture": { "type": "string", "nullable": true }, "is_reservable": { "type": "boolean", "description": "Whether the SKU this resource is running has at least one reserved-term offering. Reservability is a property of the SKU, not the resource.", "nullable": true }, "is_byol": { "type": "boolean", "description": "Whether the SKU is a Bring-Your-Own-License variant. Currently set for AWS RDS BYOL only; false elsewhere.", "nullable": true }, "is_flexible": { "type": "boolean", "description": "Whether the SKU is eligible for instance-size flexibility under reserved offerings (provider+service-specific rules \u2014 see `is_flexible` on the ResourceSKU model).", "nullable": true }, "is_serverless": { "type": "boolean", "description": "Whether the SKU represents serverless usage.", "nullable": true }, "vcpu": { "type": "number", "nullable": true }, "memory": { "type": "number", "description": "Memory in bytes (not GB). Divide by 2**30 for GiB / 1e9 for GB if presenting to the user.", "nullable": true }, "ondemand_usage_unit": { "type": "string", "nullable": true }, "ondemand_usage_price": { "type": "number", "description": "On-demand unit price in `price_currency`. List price from the catalog \u2014 this is NOT the user's actual spend for this resource (see ResourceSKUWithMetricsSchema's `total_cost` or /cost-explorer for that).", "nullable": true }, "price_currency": { "type": "string", "nullable": true }, "usage_start": { "type": "string", "format": "date-time", "description": "Start of the period during which the resource was observed running this SKU. A resource that switched SKUs (e.g. instance-type resize) will have multiple ResourceSKU rows with disjoint `[usage_start, usage_end]` windows." }, "usage_end": { "type": "string", "format": "date-time", "description": "End of the period during which the resource was observed running this SKU. Within ~2 days of now generally indicates the resource is currently active with this SKU." }, "tags": { "type": "object", "description": "Merged provider + user tags (user tags take precedence). Empty when the resource has no tags. Use the `untagged` filter to find resources with no tags at all.", "additionalProperties": { "type": "string" }, "nullable": true }, "total_cost": { "type": "number", "description": "Trailing-30-day total spend on this resource \u2014 what the user actually paid, summing the on-demand, spot, and commitment-covered portions. Reflects actuals already incurred under existing commitments, NOT a projection. Zero for resources not active in the last month.", "nullable": true }, "ondemand_cost": { "type": "number", "description": "Trailing-30-day on-demand-priced portion of `total_cost` \u2014 i.e. spend that wasn't covered by a commitment or run as spot. NOT the counterfactual 'what it would have cost at on-demand prices' (that's `if_all_ondemand_cost`).", "nullable": true }, "gross_savings": { "type": "number", "description": "Trailing-30-day savings already realized on this resource vs the on-demand baseline (`if_all_ondemand_cost - total_cost`). Actuals from existing commitments \u2014 NOT a projection of what a candidate plan would save. Per-row clamped at zero, so summing this across resources never goes negative. Archera premium is NOT subtracted on this endpoint (premium isn't attributed per resource here); for portfolio-level net savings see /commitments/metrics.", "nullable": true }, "if_all_ondemand_cost": { "readOnly": true, "description": "Trailing-30-day on-demand counterfactual \u2014 what `total_cost` would be if every hour of usage ran at on-demand prices. Equals `total_cost + gross_savings`. Headline baseline for 'how much is this commitment-covered resource saving me'." }, "coverage": { "type": "number", "description": "Trailing-30-day fraction of this resource's usage covered by ALL existing commitments (0-1). Actuals \u2014 the BEFORE picture relative to any candidate plan. When this row is nested inside a commitment plan's covered-resources response, this is distinct from the response's per-match `projected_coverage` (the AFTER picture for that specific plan).", "nullable": true }, "uptime": { "type": "number", "description": "Trailing-30-day fraction of time the resource was running (0-1). Null for non-running SKU types (storage, data transfer, etc.). Useful for rightsizing flags \u2014 low uptime on a large instance is a candidate for downsizing or termination.", "nullable": true } }, "additionalProperties": false }, "ResourceSKUDetail": { "type": "object", "properties": { "id": { "type": "string", "description": "Composite ResourceSKU id \u2014 `||`. Pass directly to `/resources/skus/` for detail; do not parse it client-side." }, "resource_id": { "type": "string", "format": "uuid", "description": "Underlying Resource id. Stable across SKU/time variants of the same resource \u2014 multiple ResourceSKU rows can share a `resource_id` when the same resource ran with different SKUs over its lifetime." }, "catalog_sku_id": { "type": "string", "format": "uuid", "description": "Join key into `/catalog/skus/` for the public SKU record." }, "catalog_sku_org_id": { "type": "string", "description": "Org id that owns the catalog SKU \u2014 public-catalog SKUs use the public org id; custom-priced SKUs use the customer's org id." }, "provider": { "description": "Cloud provider (aws, azure, gcp)", "type": "string", "enum": [ "aws", "azure", "gcp", "kubernetes", "unknown" ] }, "provider_resource_id": { "type": "string", "description": "Provider's id for the resource (AWS ARN, Azure resource ID, GCP resource name). This is the canonical identifier the user sees in the cloud console." }, "provider_sku_id": { "type": "string", "description": "Provider's own SKU identifier", "nullable": true }, "name": { "type": "string", "description": "Resource name (Resource.name) \u2014 the user-applied label, e.g. 'prod-db-1'. Distinct from `sku_name`, which is the catalog SKU's display name.", "nullable": true }, "sku_name": { "type": "string", "description": "Catalog SKU display name (e.g. 'Amazon EC2 Instance', 'Amazon Aurora PostgreSQL Cluster'). Useful as a fallback label when `instance_type_family` and `usage_type` are both null. Distinct from `name` (the resource's user-applied label).", "nullable": true }, "integration_id": { "type": "string", "description": "Integration this resource belongs to" }, "billing_account_id": { "type": "string", "description": "Provider billing/management account id", "nullable": true }, "sub_account_id": { "type": "string", "description": "Provider account id that owns/created the resource", "nullable": true }, "resource_group": { "type": "string", "nullable": true }, "is_spot": { "type": "boolean", "nullable": true }, "availability_zone": { "type": "string", "nullable": true }, "service": { "type": "string", "description": "Full service name (e.g. 'Amazon Elastic Compute Cloud - Compute')", "nullable": true }, "provider_service": { "type": "string", "description": "Provider service code (e.g. 'AmazonEC2')", "nullable": true }, "family": { "type": "string", "description": "Product family (e.g. 'Compute Instance')", "nullable": true }, "region_code": { "type": "string", "description": "Region code (e.g. 'us-east-1')", "nullable": true }, "full_region_name": { "type": "string", "description": "Full region name (e.g. 'US East (N. Virginia)')", "nullable": true }, "instance_type": { "type": "string", "nullable": true }, "instance_type_family": { "type": "string", "nullable": true }, "usage_type": { "type": "string", "description": "Provider billing usage type (e.g. 'BoxUsage:m5.large'). The canonical join key against AWS Cost Explorer / billing line items.", "nullable": true }, "operation": { "type": "string", "description": "Provider billing operation code (e.g. 'RunInstances:0002')", "nullable": true }, "operating_system": { "type": "string", "nullable": true }, "tenancy": { "type": "string", "nullable": true }, "database_engine": { "type": "string", "nullable": true }, "database_edition": { "type": "string", "nullable": true }, "cache_engine": { "type": "string", "nullable": true }, "is_multi_az": { "type": "boolean", "nullable": true }, "is_current_generation": { "type": "boolean", "nullable": true }, "license_model": { "type": "string", "nullable": true }, "pre_installed_sw": { "type": "string", "nullable": true }, "processor_architecture": { "type": "string", "nullable": true }, "is_reservable": { "type": "boolean", "description": "Whether the SKU this resource is running has at least one reserved-term offering. Reservability is a property of the SKU, not the resource.", "nullable": true }, "is_byol": { "type": "boolean", "description": "Whether the SKU is a Bring-Your-Own-License variant. Currently set for AWS RDS BYOL only; false elsewhere.", "nullable": true }, "is_flexible": { "type": "boolean", "description": "Whether the SKU is eligible for instance-size flexibility under reserved offerings (provider+service-specific rules \u2014 see `is_flexible` on the ResourceSKU model).", "nullable": true }, "is_serverless": { "type": "boolean", "description": "Whether the SKU represents serverless usage.", "nullable": true }, "vcpu": { "type": "number", "nullable": true }, "memory": { "type": "number", "description": "Memory in bytes (not GB). Divide by 2**30 for GiB / 1e9 for GB if presenting to the user.", "nullable": true }, "ondemand_usage_unit": { "type": "string", "nullable": true }, "ondemand_usage_price": { "type": "number", "description": "On-demand unit price in `price_currency`. List price from the catalog \u2014 this is NOT the user's actual spend for this resource (see ResourceSKUWithMetricsSchema's `total_cost` or /cost-explorer for that).", "nullable": true }, "price_currency": { "type": "string", "nullable": true }, "usage_start": { "type": "string", "format": "date-time", "description": "Start of the period during which the resource was observed running this SKU. A resource that switched SKUs (e.g. instance-type resize) will have multiple ResourceSKU rows with disjoint `[usage_start, usage_end]` windows." }, "usage_end": { "type": "string", "format": "date-time", "description": "End of the period during which the resource was observed running this SKU. Within ~2 days of now generally indicates the resource is currently active with this SKU." }, "tags": { "type": "object", "description": "Merged provider + user tags (user tags take precedence). Empty when the resource has no tags. Use the `untagged` filter to find resources with no tags at all.", "additionalProperties": { "type": "string" }, "nullable": true }, "total_cost": { "type": "number", "description": "Trailing-30-day total spend on this resource \u2014 what the user actually paid, summing the on-demand, spot, and commitment-covered portions. Reflects actuals already incurred under existing commitments, NOT a projection. Zero for resources not active in the last month.", "nullable": true }, "ondemand_cost": { "type": "number", "description": "Trailing-30-day on-demand-priced portion of `total_cost` \u2014 i.e. spend that wasn't covered by a commitment or run as spot. NOT the counterfactual 'what it would have cost at on-demand prices' (that's `if_all_ondemand_cost`).", "nullable": true }, "gross_savings": { "type": "number", "description": "Trailing-30-day savings already realized on this resource vs the on-demand baseline (`if_all_ondemand_cost - total_cost`). Actuals from existing commitments \u2014 NOT a projection of what a candidate plan would save. Per-row clamped at zero, so summing this across resources never goes negative. Archera premium is NOT subtracted on this endpoint (premium isn't attributed per resource here); for portfolio-level net savings see /commitments/metrics.", "nullable": true }, "if_all_ondemand_cost": { "readOnly": true, "description": "Trailing-30-day on-demand counterfactual \u2014 what `total_cost` would be if every hour of usage ran at on-demand prices. Equals `total_cost + gross_savings`. Headline baseline for 'how much is this commitment-covered resource saving me'." }, "coverage": { "type": "number", "description": "Trailing-30-day fraction of this resource's usage covered by ALL existing commitments (0-1). Actuals \u2014 the BEFORE picture relative to any candidate plan. When this row is nested inside a commitment plan's covered-resources response, this is distinct from the response's per-match `projected_coverage` (the AFTER picture for that specific plan).", "nullable": true }, "uptime": { "type": "number", "description": "Trailing-30-day fraction of time the resource was running (0-1). Null for non-running SKU types (storage, data transfer, etc.). Useful for rightsizing flags \u2014 low uptime on a large instance is a candidate for downsizing or termination.", "nullable": true }, "parent_resource_id": { "type": "string", "format": "uuid", "description": "Parent Resource id (e.g. the spot fleet / autoscaling group / RDS cluster that owns this resource). Sparse \u2014 only populated when the cloud provider exposes a parent relationship. Use this to traverse resource hierarchies.", "nullable": true }, "description": { "type": "string", "nullable": true }, "location_type": { "type": "string", "nullable": true }, "physical_processor": { "type": "string", "nullable": true }, "clock_speed": { "type": "string", "nullable": true }, "processor_features": { "type": "string", "nullable": true }, "network_performance": { "type": "string", "nullable": true }, "storage": { "type": "string", "nullable": true }, "dedicated_ebs_throughput": { "type": "string", "nullable": true }, "io": { "type": "string", "nullable": true }, "tax_type": { "type": "string", "nullable": true }, "has_ondemand_terms": { "type": "boolean", "nullable": true }, "normalization_size_factor": { "type": "number", "description": "AWS instance-size flexibility unit. Used internally to size convertible RIs across the family; not generally user-facing.", "nullable": true }, "publication_date": { "type": "string", "format": "date-time", "description": "When the catalog SKU version was published by the provider.", "nullable": true }, "end_date": { "type": "string", "format": "date-time", "description": "Date after which the catalog SKU is no longer available.", "nullable": true }, "attributes": { "description": "Raw provider-specific attribute blob from the catalog SKU \u2014 usually a JSON object, but can be any JSON value (string, list, etc.) since the underlying column is a Snowflake VARIANT. May overlap with the structured fields above; prefer the structured fields when they're populated.", "nullable": true }, "provider_tags": { "type": "object", "description": "Tags assigned by the cloud provider, before user overrides are merged.", "additionalProperties": { "type": "string" } }, "user_tags": { "type": "object", "description": "Tags applied via the Archera UI/API on top of the provider tags.", "additionalProperties": { "type": "string" } } }, "additionalProperties": false }, "CatalogSKU": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid", "description": "Catalog SKU id" }, "provider": { "description": "Cloud provider (aws, azure, gcp)", "type": "string", "enum": [ "aws", "azure", "gcp", "kubernetes", "unknown" ] }, "provider_sku_id": { "type": "string", "description": "Provider's own SKU identifier" }, "name": { "type": "string", "nullable": true }, "family": { "type": "string", "description": "Product family (e.g. 'Compute Instance')", "nullable": true }, "service": { "type": "string", "description": "Full service name (e.g. 'Amazon Elastic Compute Cloud - Compute')", "nullable": true }, "provider_service": { "type": "string", "description": "Provider service code (e.g. 'AmazonEC2')", "nullable": true }, "region_code": { "type": "string", "description": "Region code (e.g. 'us-east-1')", "nullable": true }, "full_region_name": { "type": "string", "description": "Full region name (e.g. 'US East (N. Virginia)')", "nullable": true }, "instance_type": { "type": "string", "nullable": true }, "instance_type_family": { "type": "string", "nullable": true }, "usage_type": { "type": "string", "description": "Provider billing usage type (e.g. 'BoxUsage:m5.large'). The canonical join key against AWS Cost Explorer / billing line items \u2014 useful for crossing between catalog and cost data.", "nullable": true }, "operation": { "type": "string", "description": "Provider billing operation code (e.g. 'RunInstances:0002'). Lets the agent spot at-a-glance whether a SKU is the plain default operation or a more specific variant within a usage_type.", "nullable": true }, "operating_system": { "type": "string", "nullable": true }, "tenancy": { "type": "string", "nullable": true }, "database_engine": { "type": "string", "nullable": true }, "database_edition": { "type": "string", "nullable": true }, "cache_engine": { "type": "string", "nullable": true }, "is_multi_az": { "type": "boolean", "nullable": true }, "is_current_generation": { "type": "boolean", "nullable": true }, "license_model": { "type": "string", "nullable": true }, "pre_installed_sw": { "type": "string", "nullable": true }, "processor_architecture": { "type": "string", "description": "CPU architecture (e.g. 'x86_64', 'arm64')", "nullable": true }, "vcpu": { "type": "number", "nullable": true }, "memory": { "type": "number", "description": "Memory in bytes (not GB). Divide by 2**30 for GiB / 1e9 for GB if presenting to the user.", "nullable": true }, "is_reservable": { "type": "boolean", "description": "Whether this SKU has at least one reserved-term offering" }, "is_public": { "type": "boolean", "description": "True for public-catalog SKUs (the standard provider catalog). False when this row is the requesting org's own custom-priced SKU (tied to a specific integration; drill into `catalog_sku_details` for the integration_id)." }, "ondemand_usage_unit": { "type": "string", "nullable": true }, "ondemand_usage_price": { "type": "number", "description": "On-demand unit price in price_currency", "nullable": true }, "price_currency": { "type": "string", "nullable": true } }, "additionalProperties": false }, "PriceDimension": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "description": { "type": "string", "nullable": true }, "usage_unit": { "type": "string", "nullable": true }, "price_currency": { "type": "string", "nullable": true }, "usage_unit_price": { "type": "number", "nullable": true }, "begin_range": { "type": "number", "description": "Tier lower bound (in usage units)", "nullable": true }, "end_range": { "type": "number", "description": "Tier upper bound (in usage units); null means infinite", "nullable": true } }, "additionalProperties": false }, "SKUTerms": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "name": { "type": "string", "nullable": true }, "description": { "type": "string", "nullable": true }, "effective_date": { "type": "string", "format": "date-time", "nullable": true }, "price_currency": { "type": "string", "nullable": true }, "usage_unit": { "type": "string", "nullable": true }, "usage_unit_price": { "type": "number", "nullable": true }, "price_dimensions": { "type": "array", "items": { "$ref": "#/components/schemas/PriceDimension" } } }, "additionalProperties": false }, "CatalogSKUDetail": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid", "description": "Catalog SKU id" }, "provider": { "description": "Cloud provider (aws, azure, gcp)", "type": "string", "enum": [ "aws", "azure", "gcp", "kubernetes", "unknown" ] }, "provider_sku_id": { "type": "string", "description": "Provider's own SKU identifier" }, "name": { "type": "string", "nullable": true }, "family": { "type": "string", "description": "Product family (e.g. 'Compute Instance')", "nullable": true }, "service": { "type": "string", "description": "Full service name (e.g. 'Amazon Elastic Compute Cloud - Compute')", "nullable": true }, "provider_service": { "type": "string", "description": "Provider service code (e.g. 'AmazonEC2')", "nullable": true }, "region_code": { "type": "string", "description": "Region code (e.g. 'us-east-1')", "nullable": true }, "full_region_name": { "type": "string", "description": "Full region name (e.g. 'US East (N. Virginia)')", "nullable": true }, "instance_type": { "type": "string", "nullable": true }, "instance_type_family": { "type": "string", "nullable": true }, "usage_type": { "type": "string", "description": "Provider billing usage type (e.g. 'BoxUsage:m5.large'). The canonical join key against AWS Cost Explorer / billing line items \u2014 useful for crossing between catalog and cost data.", "nullable": true }, "operation": { "type": "string", "description": "Provider billing operation code (e.g. 'RunInstances:0002'). Lets the agent spot at-a-glance whether a SKU is the plain default operation or a more specific variant within a usage_type.", "nullable": true }, "operating_system": { "type": "string", "nullable": true }, "tenancy": { "type": "string", "nullable": true }, "database_engine": { "type": "string", "nullable": true }, "database_edition": { "type": "string", "nullable": true }, "cache_engine": { "type": "string", "nullable": true }, "is_multi_az": { "type": "boolean", "nullable": true }, "is_current_generation": { "type": "boolean", "nullable": true }, "license_model": { "type": "string", "nullable": true }, "pre_installed_sw": { "type": "string", "nullable": true }, "processor_architecture": { "type": "string", "description": "CPU architecture (e.g. 'x86_64', 'arm64')", "nullable": true }, "vcpu": { "type": "number", "nullable": true }, "memory": { "type": "number", "description": "Memory in bytes (not GB). Divide by 2**30 for GiB / 1e9 for GB if presenting to the user.", "nullable": true }, "is_reservable": { "type": "boolean", "description": "Whether this SKU has at least one reserved-term offering" }, "is_public": { "type": "boolean", "description": "True for public-catalog SKUs (the standard provider catalog). False when this row is the requesting org's own custom-priced SKU (tied to a specific integration; drill into `catalog_sku_details` for the integration_id)." }, "ondemand_usage_unit": { "type": "string", "nullable": true }, "ondemand_usage_price": { "type": "number", "description": "On-demand unit price in price_currency", "nullable": true }, "price_currency": { "type": "string", "nullable": true }, "description": { "type": "string", "nullable": true }, "location_type": { "type": "string", "nullable": true }, "availability_zone": { "type": "string", "nullable": true }, "physical_processor": { "type": "string", "nullable": true }, "clock_speed": { "type": "string", "nullable": true }, "processor_features": { "type": "string", "nullable": true }, "network_performance": { "type": "string", "nullable": true }, "storage": { "type": "string", "nullable": true }, "dedicated_ebs_throughput": { "type": "string", "nullable": true }, "io": { "type": "string", "nullable": true }, "tax_type": { "type": "string", "nullable": true }, "has_ondemand_terms": { "type": "boolean" }, "normalization_size_factor": { "type": "number", "description": "AWS instance-size flexibility unit. Used internally to size convertible RIs across the family; not generally user-facing.", "nullable": true }, "is_byol": { "type": "boolean", "description": "Whether this SKU is a Bring-Your-Own-License variant. Derived from license_model." }, "integration_id": { "type": "string", "format": "uuid", "description": "Integration this SKU's custom pricing is tied to. Null for public-catalog SKUs (the default scope of the list endpoint). Set when the SKU id resolves to a custom-priced SKU on the requesting org \u2014 direct-id detail lookups support both public and the org's own custom-priced SKUs.", "nullable": true }, "end_date": { "type": "string", "format": "date-time", "description": "Date after which this SKU is no longer available.", "nullable": true }, "publication_date": { "type": "string", "format": "date-time", "description": "When this SKU version was published by the provider.", "nullable": true }, "updated_at": { "type": "string", "format": "date", "description": "When this SKU was last refreshed in our catalog.", "nullable": true }, "attributes": { "type": "object", "description": "Raw provider-specific attribute blob. May overlap with the structured fields above; prefer the structured fields when they're populated.", "additionalProperties": {}, "nullable": true }, "ondemand_terms": { "anyOf": [ { "type": "object", "nullable": true }, { "$ref": "#/components/schemas/SKUTerms" } ] } }, "additionalProperties": false }, "CatalogSKUOndemandBaseline": { "type": "object", "properties": { "monthly_cost": { "type": "number", "description": "Monthly on-demand cost (730-hour rate) for the requested quantity. Equals `ondemand_usage_price * quantity * 730`." }, "ondemand_usage_unit": { "type": "string", "description": "Unit of measurement for on-demand usage (e.g. 'Hrs').", "nullable": true }, "ondemand_usage_price": { "type": "number", "description": "Per-unit on-demand price in USD." } }, "required": [ "monthly_cost", "ondemand_usage_price" ], "additionalProperties": false }, "CatalogSKUOfferComparisonEntry": { "type": "object", "properties": { "offer_id": { "type": "string", "format": "uuid", "description": "Commitment offer id." }, "offer": { "description": "Full offer details (type, region, instance, payment_option, etc).", "allOf": [ { "$ref": "#/components/schemas/CommitmentOffer" } ] }, "lease_menu_item_id": { "type": "string", "format": "uuid", "description": "Lease attached to this candidate, or null for a native (non-Archera) commitment.", "nullable": true }, "selected_amount": { "type": "number", "description": "Commitment amount this candidate would be sized to \u2014 unit count for RIs / unit-based CUDs, dollar-per-hour rate for Savings Plans / spend-based CUDs. Match the underlying offer.type to interpret." }, "contract_term": { "description": "Effective commitment term \u2014 derived from the lease lockin hours when `lease_menu_item_id` is set (e.g. 'one_year_gris'), else from the offer's own duration (e.g. 'one_year', 'three_year'). The real lock-in period, not the offer's raw duration.", "type": "string", "enum": [ "one_year_gris", "thirty_day_gris", "two_month_gris", "three_month_gris", "four_month_gris", "five_month_gris", "six_month_gris", "seven_month_gris", "eight_month_gris", "nine_month_gris", "ten_month_gris", "eleven_month_gris", "twelve_month_gris", "thirteen_month_gris", "fourteen_month_gris", "fifteen_month_gris", "sixteen_month_gris", "seventeen_month_gris", "eighteen_month_gris", "nineteen_month_gris", "twenty_month_gris", "twenty_one_month_gris", "twenty_two_month_gris", "twenty_three_month_gris", "twenty_four_month_gris", "twenty_five_month_gris", "twenty_six_month_gris", "twenty_seven_month_gris", "twenty_eight_month_gris", "twenty_nine_month_gris", "thirty_month_gris", "thirty_one_month_gris", "thirty_two_month_gris", "thirty_three_month_gris", "thirty_four_month_gris", "thirty_five_month_gris", "one_year", "two_year", "three_year", "five_year", "zero_day", "thirty_day", "two_month", "three_month", "four_month", "five_month", "six_month", "seven_month", "eight_month", "nine_month", "ten_month", "eleven_month", "thirteen_month", "fourteen_month", "fifteen_month", "sixteen_month", "seventeen_month", "eighteen_month", "nineteen_month", "twenty_month", "twenty_one_month", "twenty_two_month", "twenty_three_month", "twenty_five_month", "twenty_six_month", "twenty_seven_month", "twenty_eight_month", "twenty_nine_month", "thirty_month", "thirty_one_month", "thirty_two_month", "thirty_three_month", "thirty_four_month", "thirty_five_month", null ], "nullable": true }, "payment_option": { "description": "Payment option (no_upfront / partial_upfront / all_upfront).", "type": "string", "enum": [ "no_upfront", "partial_upfront", "all_upfront", null ], "nullable": true }, "discount_rate": { "type": "number", "description": "Discount rate vs on-demand (0-1)." }, "breakeven_days": { "type": "number", "description": "Days until this candidate pays for itself; null if undefined.", "nullable": true }, "commitment_upfront_cost": { "type": "number", "description": "One-time dollars at signing for this candidate. NOT a rate \u2014 do not sum with monthly-rate fields." }, "commitment_financials_monthly_rate": { "description": "Projected economics as 730-hour monthly rates, same shape as line items / plans. `commitment_savings.net` is the headline savings vs running on-demand.", "allOf": [ { "$ref": "#/components/schemas/CommitmentFinancialsNoRebate" } ] } }, "required": [ "breakeven_days", "commitment_financials_monthly_rate", "commitment_upfront_cost", "contract_term", "discount_rate", "lease_menu_item_id", "offer", "offer_id", "payment_option", "selected_amount" ], "additionalProperties": false }, "CatalogSKUTargetDelta": { "type": "object", "properties": { "monthly_net_savings": { "type": "number", "description": "Monthly net savings under this target's resolved candidate vs running on-demand. Equals `commitment_financials_monthly_rate.commitment_savings.net` when a candidate resolved; 0 when `actual_term_reason='no_alternative'` (no commitment, you stay on-demand)." }, "monthly_commitment_cost": { "type": "number", "description": "Monthly commitment cost under this target's resolved candidate. 0 when no alternative resolved." }, "upfront_cost": { "type": "number", "description": "One-time upfront dollars under this target's resolved candidate. 0 when no alternative resolved. NOT a rate." } }, "required": [ "monthly_commitment_cost", "monthly_net_savings", "upfront_cost" ], "additionalProperties": false }, "CatalogSKUTarget": { "type": "object", "properties": { "contract_term": { "description": "Requested contract term for this hypothetical.", "type": "string", "enum": [ "one_year_gris", "thirty_day_gris", "two_month_gris", "three_month_gris", "four_month_gris", "five_month_gris", "six_month_gris", "seven_month_gris", "eight_month_gris", "nine_month_gris", "ten_month_gris", "eleven_month_gris", "twelve_month_gris", "thirteen_month_gris", "fourteen_month_gris", "fifteen_month_gris", "sixteen_month_gris", "seventeen_month_gris", "eighteen_month_gris", "nineteen_month_gris", "twenty_month_gris", "twenty_one_month_gris", "twenty_two_month_gris", "twenty_three_month_gris", "twenty_four_month_gris", "twenty_five_month_gris", "twenty_six_month_gris", "twenty_seven_month_gris", "twenty_eight_month_gris", "twenty_nine_month_gris", "thirty_month_gris", "thirty_one_month_gris", "thirty_two_month_gris", "thirty_three_month_gris", "thirty_four_month_gris", "thirty_five_month_gris", "one_year", "two_year", "three_year", "five_year", "zero_day", "thirty_day", "two_month", "three_month", "four_month", "five_month", "six_month", "seven_month", "eight_month", "nine_month", "ten_month", "eleven_month", "thirteen_month", "fourteen_month", "fifteen_month", "sixteen_month", "seventeen_month", "eighteen_month", "nineteen_month", "twenty_month", "twenty_one_month", "twenty_two_month", "twenty_three_month", "twenty_five_month", "twenty_six_month", "twenty_seven_month", "twenty_eight_month", "twenty_nine_month", "thirty_month", "thirty_one_month", "thirty_two_month", "thirty_three_month", "thirty_four_month", "thirty_five_month", null ], "nullable": true }, "payment_option": { "description": "Requested payment option for this hypothetical.", "type": "string", "enum": [ "no_upfront", "partial_upfront", "all_upfront" ] }, "actual_term": { "description": "The contract term that actually resolved. Equals `contract_term` when an exact match exists; otherwise the longest term shorter than the target with the same payment option. Null when no alternative exists for the requested (term, payment) pair.", "type": "string", "enum": [ "one_year_gris", "thirty_day_gris", "two_month_gris", "three_month_gris", "four_month_gris", "five_month_gris", "six_month_gris", "seven_month_gris", "eight_month_gris", "nine_month_gris", "ten_month_gris", "eleven_month_gris", "twelve_month_gris", "thirteen_month_gris", "fourteen_month_gris", "fifteen_month_gris", "sixteen_month_gris", "seventeen_month_gris", "eighteen_month_gris", "nineteen_month_gris", "twenty_month_gris", "twenty_one_month_gris", "twenty_two_month_gris", "twenty_three_month_gris", "twenty_four_month_gris", "twenty_five_month_gris", "twenty_six_month_gris", "twenty_seven_month_gris", "twenty_eight_month_gris", "twenty_nine_month_gris", "thirty_month_gris", "thirty_one_month_gris", "thirty_two_month_gris", "thirty_three_month_gris", "thirty_four_month_gris", "thirty_five_month_gris", "one_year", "two_year", "three_year", "five_year", "zero_day", "thirty_day", "two_month", "three_month", "four_month", "five_month", "six_month", "seven_month", "eight_month", "nine_month", "ten_month", "eleven_month", "thirteen_month", "fourteen_month", "fifteen_month", "sixteen_month", "seventeen_month", "eighteen_month", "nineteen_month", "twenty_month", "twenty_one_month", "twenty_two_month", "twenty_three_month", "twenty_five_month", "twenty_six_month", "twenty_seven_month", "twenty_eight_month", "twenty_nine_month", "thirty_month", "thirty_one_month", "thirty_two_month", "thirty_three_month", "thirty_four_month", "thirty_five_month", null ], "nullable": true }, "actual_payment_option": { "description": "Payment option of the resolved candidate. Equals `payment_option` whenever a candidate resolved (resolution preserves payment option); null when no alternative.", "type": "string", "enum": [ "no_upfront", "partial_upfront", "all_upfront", null ], "nullable": true }, "actual_term_reason": { "type": "string", "enum": [ "exact_match", "fallback_closest_shorter", "no_alternative" ], "description": "Why this target landed at `actual_term`. `exact_match` = the SKU offers exactly this (term, payment). `fallback_closest_shorter` = no exact match; resolved to the longest term shorter than target with the same payment option (GRI variant preferred when same duration). `no_alternative` = nothing qualifies; surfaced explicitly so the agent can flag to the user that this (term, payment) combination doesn't exist for the SKU." }, "candidate": { "description": "The resolved (offer, lease) candidate, or null when `actual_term_reason='no_alternative'`. Same shape as entries in `candidates[]` \u2014 the agent can quote `discount_rate`, `breakeven_days`, etc. directly off this nested entry.", "anyOf": [ { "$ref": "#/components/schemas/CatalogSKUOfferComparisonEntry" }, { "type": "object", "nullable": true } ] }, "commitment_financials_monthly_rate": { "description": "Resolved candidate's 730-hour monthly-rate financials, lifted to the top level so the agent can read the same paths as on the line-item endpoint's `hypothetical_totals[i]`. All-zero when `actual_term_reason='no_alternative'`.", "allOf": [ { "$ref": "#/components/schemas/CommitmentFinancialsNoRebate" } ] }, "commitment_upfront_cost": { "type": "number", "description": "Resolved candidate's one-time upfront cost. 0 when no alternative resolved. NOT a rate." }, "delta_vs_ondemand": { "description": "Axis-by-axis difference vs the on-demand baseline. Analogous to `delta_vs_current` on the line-item endpoint, but the baseline is on-demand (zero commitment) so each field equals the resolved candidate's value directly.", "allOf": [ { "$ref": "#/components/schemas/CatalogSKUTargetDelta" } ] } }, "required": [ "actual_payment_option", "actual_term", "actual_term_reason", "candidate", "commitment_financials_monthly_rate", "commitment_upfront_cost", "contract_term", "delta_vs_ondemand", "payment_option" ], "additionalProperties": false }, "CatalogSKUOfferComparisonResponse": { "type": "object", "properties": { "sku_id": { "type": "string", "format": "uuid", "description": "The CatalogSKU id compared." }, "quantity": { "type": "integer", "description": "Quantity hypothetically committed." }, "ondemand_baseline": { "description": "On-demand reference point. Compare against each candidate's `commitment_financials_monthly_rate.commitment_cost.total` to see the absolute savings, or read `discount_rate` for the relative figure.", "allOf": [ { "$ref": "#/components/schemas/CatalogSKUOndemandBaseline" } ] }, "candidates": { "type": "array", "description": "All (offer, lease) pairs available for this SKU at the requested quantity, filtered to the requested contract_terms and payment_options. Ordered by descending discount_rate.", "items": { "$ref": "#/components/schemas/CatalogSKUOfferComparisonEntry" } }, "targets": { "type": "array", "description": "One entry per requested (contract_term, payment_option) target \u2014 what the SKU resolves to under that hypothetical, with `actual_term_reason` explaining whether it was an exact match, a fallback to the closest shorter term, or no alternative. Mirrors the line-item endpoint's `hypothetical_totals` shape, collapsed to single-row since catalog comparison is single-SKU. The headline 'should I do this' answer per target is `delta_vs_ondemand.monthly_net_savings`.", "items": { "$ref": "#/components/schemas/CatalogSKUTarget" } } }, "required": [ "candidates", "ondemand_baseline", "quantity", "sku_id", "targets" ], "additionalProperties": false }, "OrganizationMembership": { "type": "object", "properties": { "id": { "type": "string", "description": "Organization ID. Pass as `org_id` to other tools." }, "name": { "type": "string", "description": "Human-readable organization name." }, "domain": { "type": "string", "description": "Email domain associated with the org (e.g. 'acme.com'), or null if unset. For other org-management fields (postal address, deactivation flag, created_at), use `get_organization` on a specific `org_id`.", "nullable": true }, "role": { "type": "string", "enum": [ "user", "admin", "support", "cloud_rep", "restricted_user" ], "description": "Caller's role in this org: 'user', 'admin', 'support', 'cloud_rep', or 'restricted_user'. Staff users are reported as 'admin' for every active org." }, "kind": { "description": "How the caller has access: 'direct' (regular member), 'staff' (staff-level access to every active org), or 'partnership' (inherited via a channel partnership).", "enum": [ "direct", "staff", "partnership" ] }, "is_primary": { "type": "boolean", "description": "True for the org the caller's tokens default to when no `org_id` is passed. Matches the earliest-joined direct membership returned by `User.active_memberships`." }, "denied_permissions": { "type": "array", "description": "List of `Resource:action` strings the caller's role is denied (e.g. 'PurchasePlanV2:execute'). Anything not listed is permitted. Use to gate write/destructive recommendations.", "items": { "type": "string" } } }, "required": [ "denied_permissions", "id", "is_primary", "kind", "name", "role" ], "additionalProperties": false }, "Address": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid", "readOnly": true, "description": "Address identifier." }, "line1": { "type": "string", "description": "Street address, line 1." }, "line2": { "type": "string", "default": null, "description": "Street address, line 2 (optional).", "nullable": true }, "city": { "type": "string", "description": "City." }, "state": { "type": "string", "description": "State / region / province." }, "zip": { "type": "string", "description": "Postal / ZIP code." }, "country": { "type": "string", "description": "ISO 3166-1 alpha-2 country code (e.g. 'US', 'GB')." } }, "required": [ "city", "country", "line1", "state", "zip" ], "additionalProperties": false }, "OrganizationDetail": { "type": "object", "properties": { "id": { "type": "string", "readOnly": true, "description": "Organization ID." }, "name": { "type": "string", "description": "Organization name. Unique across the platform." }, "domain": { "type": "string", "description": "Email domain associated with the org (e.g. 'acme.com'). Used for domain-based onboarding flows.", "nullable": true }, "created_at": { "type": "string", "format": "date-time", "readOnly": true, "description": "When the org was created." }, "primary_address": { "description": "The org's primary postal address (optional).", "anyOf": [ { "$ref": "#/components/schemas/Address" }, { "type": "object", "nullable": true } ] } }, "required": [ "name" ], "additionalProperties": false }, "UpdateOrganization": { "type": "object", "properties": { "name": { "type": "string", "minLength": 1, "description": "New organization name." }, "domain": { "type": "string", "minLength": 1, "description": "New email domain, or null to clear.", "nullable": true }, "primary_address": { "description": "Replacement primary address. Send the full address object. Pass null to clear the existing address.", "anyOf": [ { "$ref": "#/components/schemas/Address" }, { "type": "object", "nullable": true } ] } }, "additionalProperties": false } }, "responses": { "UNPROCESSABLE_CONTENT": { "description": "Unprocessable Content", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "DEFAULT_ERROR": { "description": "Default error response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "headers": { "PAGINATION": { "description": "Pagination metadata", "schema": { "$ref": "#/components/schemas/PaginationMetadata" } } } } }