{ "info": { "description": "### Welcome to the Archera.ai API documentation.\nArchera.ai empowers organizations to optimize cloud costs and automate cloud financial operations. Our API enables seamless integration with your internal tools, workflows, and reporting systems. With this API, you can programmatically access commitment plans, metrics, and more, unlocking the full potential of your cloud data.\n\nWhether you're building custom dashboards, automating cost management, or integrating with third-party platforms, the Archera.ai API provides secure and reliable endpoints to help you achieve your goals.\n\nIf you have questions or need support, please contact our team at support@archera.ai.\n\n## API Key Access\n\nTo use this API, you need an API key.\n\n### How to Create an API Key\n1. Log in to the Archera.ai web application.\n2. Navigate to **User Settings > API Access**.\nOpen Settings\n3. Click **Create New API Key**.\n4. Copy and securely store your new API key.\n\n### How to Use Your API Key\nUse the `x-api-key` header:\n\n```bash\ncurl -H 'x-api-key: YOUR_API_KEY' https://api.archera.ai/v1/org/{org_id}/metrics?provider=aws\n```\n\nKeep your API key secure. If you believe your key has been compromised, deactivate it in the web application and generate a new one.\n### How to find your Organization ID\n1. Log in to the Archera.ai web application.\n2. Navigate to **User Settings > Organization**.\n3. Your Organization ID is displayed at the top of the page. You can also find it in the URL when visiting the Archera app `&orgId=`\n\n", "title": "Archera.ai API", "version": "v1.0.0" }, "paths": { "/v1/org/{org_id}/commitment-plans/{plan_id}": { "get": { "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CommitmentPlan" } } } }, "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" ], "summary": "/commitment-plans/{plan_id}", "description": "Retrieves detailed information about a specific commitment plan, including costs, savings projections, and commitment coverage." }, "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" } } ] }, "/v1/org/{org_id}/commitment-plans/{plan_id}/apply": { "post": { "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CommitmentPlan" } } } }, "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" ], "summary": "/commitment-plans/{plan_id}/apply", "description": "Executes a commitment purchase plan, initiating the commitment purchase process. This action will mark the plan as edited and record the user who initiated the purchase. The plan will then be processed for actual commitment purchases according to the plan specifications." }, "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" } } ] }, "/v1/org/{org_id}/commitment-plans/default": { "get": { "parameters": [ { "in": "query", "name": "provider", "description": "Cloud provider to get default plans for", "schema": { "type": "string", "enum": [ "aws", "azure", "gcp" ], "example": "aws" }, "required": true } ], "responses": { "422": { "$ref": "#/components/responses/UNPROCESSABLE_CONTENT" }, "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "array", "items": { "$ref": "#/components/schemas/CommitmentPlan" } }, "example": [ { "id": "11111111-1111-1111-1111-111111111111", "name": "Recommended", "description": "string", "org_id": "a40f5d1f-d889-42e9-94ea-b9b33585fc6b", "created_at": "2025-06-01T08:00:00Z", "is_calculating": false, "status": "active", "max_term": "string", "covered_ondemand_cost_hourly": 3.21, "before_ondemand_cost_hourly": 4.56, "before_reserved_cost_hourly": 0.0, "amortized_cost_hourly": 2.98, "recurring_cost_hourly": 0.23, "upfront_cost_hourly": 0.0, "before_cost_hourly": 4.56, "after_cost_hourly": 3.21, "total_cost_hourly": 3.44, "savings_hourly": 1.12, "fee_hourly": 0.1, "commitment_coverage": 0.7, "minimum_commitment_cost": 1200, "breakeven_hours": 300, "total_savings": 980, "monthly_savings": 82, "total_monthly_before_cost": 330 }, { "id": "22222222-2222-2222-2222-222222222222", "name": "Balanced", "description": "string", "org_id": "a40f5d1f-d889-42e9-94ea-b9b33585fc6b", "created_at": "2025-06-01T08:00:00Z", "is_calculating": false, "status": "active", "max_term": "string", "covered_ondemand_cost_hourly": 4.85, "before_ondemand_cost_hourly": 6.5, "before_reserved_cost_hourly": 0.0, "amortized_cost_hourly": 3.75, "recurring_cost_hourly": 0.54, "upfront_cost_hourly": 0.0, "before_cost_hourly": 6.5, "after_cost_hourly": 4.29, "total_cost_hourly": 4.83, "savings_hourly": 1.67, "fee_hourly": 0.15, "commitment_coverage": 0.85, "minimum_commitment_cost": 2000, "breakeven_hours": 450, "total_savings": 1460, "monthly_savings": 122, "total_monthly_before_cost": 440 }, { "id": "33333333-3333-3333-3333-333333333333", "name": "High Savings", "description": "string", "org_id": "a40f5d1f-d889-42e9-94ea-b9b33585fc6b", "created_at": "2025-06-01T08:00:00Z", "is_calculating": false, "status": "active", "max_term": "string", "covered_ondemand_cost_hourly": 7.25, "before_ondemand_cost_hourly": 8.9, "before_reserved_cost_hourly": 0.0, "amortized_cost_hourly": 5.1, "recurring_cost_hourly": 0.85, "upfront_cost_hourly": 0.0, "before_cost_hourly": 8.9, "after_cost_hourly": 5.95, "total_cost_hourly": 6.8, "savings_hourly": 2.1, "fee_hourly": 0.25, "commitment_coverage": 0.95, "minimum_commitment_cost": 3500, "breakeven_hours": 620, "total_savings": 2540, "monthly_savings": 220, "total_monthly_before_cost": 650 } ] } } }, "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" ], "summary": "/commitment-plans/default", "description": "Retrieves the three default Archera commitment plans (High Savings, Balanced, Recommended) for the specified cloud provider. These plans are automatically generated based on the organization's usage patterns. Each plan offers different trade-offs between cost savings and flexibility." }, "parameters": [ { "in": "path", "name": "org_id", "required": true, "schema": { "type": "string", "format": "uuid" } } ] }, "/v1/org/{org_id}/commitment-plans/recommended": { "get": { "parameters": [ { "in": "query", "name": "provider", "description": "Cloud provider to get the recommended plan for", "schema": { "type": "string", "enum": [ "aws", "azure", "gcp" ], "example": "aws" }, "required": true } ], "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" ], "summary": "/commitment-plans/recommended", "description": "Retrieves only the recommended Archera commitment plan for the specified cloud provider. This is the optimal plan automatically selected based on the organization's usage patterns, balancing cost savings with flexibility. Returns a 204 No Content response if no recommended plan is available for the specified provider." }, "parameters": [ { "in": "path", "name": "org_id", "required": true, "schema": { "type": "string", "format": "uuid" } } ] }, "/v1/org/{org_id}/commitment-plans/{plan_id}/line-items": { "get": { "parameters": [ { "in": "query", "name": "order_by", "description": "Field to order results by", "schema": { "type": [ "string", "null" ], "default": "id", "enum": [ "id", "plan_id", "offer_id", "account_id", "amortized_cost", "upfront_cost", "recurring_cost", "total_cost", "savings", "fee", "covered_ondemand_cost", "before_ondemand_cost", "before_reserved_cost", "covered_units", "before_cost", "monthly_savings", "breakeven_hours", "discount_rate", "monthly_cost", "selected_quantity", null, "offer.type", "offer.duration_seconds" ], "example": "created_at" }, "required": false }, { "in": "query", "name": "desc", "description": "Sort in descending order if true", "schema": { "type": [ "boolean", "null" ], "default": null, "example": "true" }, "required": false }, { "in": "query", "name": "segment_id", "description": "Filter line items by segment ID", "schema": { "type": "string", "example": "550e8400-e29b-41d4-a716-446655440000" }, "required": false }, { "in": "query", "name": "resource_match_ids", "description": "Filter line items by specific resource match IDs", "schema": { "type": "array", "example": [ "550e8400-e29b-41d4-a716-446655440000", "6ba7b810-9dad-11d1-80b4-00c04fd430c8" ], "items": { "type": "string", "format": "uuid" } }, "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": 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/CommitmentPlanLineItem_Exclude_CoveredServices" } } } }, "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" ], "summary": "/commitment-plans/{plan_id}/line-items", "description": "Retrieves line items for a specific commitment plan, including offer details, costs, and savings information. Line items represent individual commitment purchases within the plan." }, "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" } } ] }, "/v1/org/{org_id}/commitment-plans/{plan_id}/resource-matches": { "get": { "parameters": [ { "in": "query", "name": "order_by", "description": "Field to order results by", "schema": { "type": [ "string", "null" ], "default": "covered_ondemand_cost", "enum": [ "id", "unmatched_units", "total_units", "ondemand_price", "reserved_cost", "explanation_unmatched", "coverage", "ondemand_cost", "covered_ondemand_cost", "before_cost", "after_cost", "covered_units", "average_savings", "average_monthly_savings", "monthly_after_cost", null ] }, "required": false }, { "in": "query", "name": "desc", "description": "Sort in descending order if true", "schema": { "type": "boolean", "default": true }, "required": false }, { "in": "query", "name": "start_date", "description": "Start date for resource usage data", "schema": { "type": "string", "format": "date", "example": "2024-01-01" }, "required": true }, { "in": "query", "name": "end_date", "description": "End date for resource usage data", "schema": { "type": "string", "format": "date", "example": "2024-01-31" }, "required": true }, { "in": "query", "name": "line_item_ids", "description": "Filter by specific line item IDs", "schema": { "type": "array", "example": [ "550e8400-e29b-41d4-a716-446655440000" ], "items": { "type": "string", "format": "uuid" } }, "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": 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/CommitmentPlanResourceMatch" } } } }, "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" ], "summary": "/commitment-plans/{plan_id}/resource-matches", "description": "Retrieves resource matches for a specific commitment plan, showing how resources map to commitment purchases with cost and usage details." }, "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" } } ] }, "/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", "null" ], "default": null, "items": { "type": "string", "format": "uuid" } }, "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", "null" ], "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" ] } }, "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" ], "summary": "/commitment-plans/{plan_id}/comparison", "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" } } ] }, "/v1/org/{org_id}/commitments": { "get": { "parameters": [ { "in": "query", "name": "search", "description": "Text to search across multiple columns (case-insensitive partial match)", "schema": { "type": "string", "example": "us-east-1" }, "required": false }, { "in": "query", "name": "filter", "description": "JSON object specifying field-specific filter criteria", "schema": { "type": [ "object", "null" ], "example": "{\"field\": \"type\", \"op\": \"=\", \"value\": \"Standard\"}", "additionalProperties": {} }, "required": false }, { "in": "query", "name": "desc", "description": "Sort in descending order if true", "schema": { "type": "boolean", "default": true, "example": "true" }, "required": false }, { "in": "query", "name": "order_by", "description": "Field to order results by", "schema": { "type": [ "string", "null" ], "default": "end_date", "enum": [ "duration_seconds", "start_date", "end_date", "upfront_cost", "amortized_cost", "recurring_cost", "created_at", "updated_at", "is_leased", "account_id", "type", "status", "scope", "reservation_end", "utilization", "monthly_savings", null ], "example": "created_at" }, "required": false }, { "in": "query", "name": "provider", "description": "Cloud provider to filter commitments by", "schema": { "type": "string", "enum": [ "aws", "azure", "gcp" ], "example": "aws" }, "required": true }, { "in": "query", "name": "start_date", "description": "Start date for the commitment period (YYYY-MM-DD)", "schema": { "type": "string", "format": "date", "example": "2023-01-01" }, "required": true }, { "in": "query", "name": "end_date", "description": "End date for the commitment period (YYYY-MM-DD)", "schema": { "type": "string", "format": "date", "example": "2023-12-31" }, "required": true }, { "in": "query", "name": "page", "schema": { "type": "integer", "default": 1, "minimum": 1 }, "required": false }, { "in": "query", "name": "page_size", "schema": { "type": "integer", "default": 10, "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/PublicCommitment" } } } }, "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" ], "summary": "/commitments", "description": "Retrieves a paginated list of commitments for the specified organization and time period. Returns detailed information about each commitment including utilization, savings, and status. Results can be filtered by provider, search term, and custom criteria, and sorted by various attributes." }, "parameters": [ { "in": "path", "name": "org_id", "required": true, "schema": { "type": "string", "minLength": 1 } } ] }, "/v1/org/{org_id}/commitments/ids": { "get": { "parameters": [ { "in": "query", "name": "search", "description": "Text to search across multiple columns (case-insensitive partial match)", "schema": { "type": "string", "example": "us-east-1" }, "required": false }, { "in": "query", "name": "filter", "description": "JSON object specifying field-specific filter criteria", "schema": { "type": [ "object", "null" ], "example": "{\"field\": \"type\", \"op\": \"=\", \"value\": \"Standard\"}", "additionalProperties": {} }, "required": false }, { "in": "query", "name": "desc", "description": "Sort in descending order if true", "schema": { "type": "boolean", "default": true, "example": "true" }, "required": false }, { "in": "query", "name": "order_by", "description": "Field to order results by", "schema": { "type": [ "string", "null" ], "default": "end_date", "enum": [ "duration_seconds", "start_date", "end_date", "upfront_cost", "amortized_cost", "recurring_cost", "created_at", "updated_at", "is_leased", "account_id", "type", "status", "scope", "reservation_end", "utilization", "monthly_savings", null ], "example": "created_at" }, "required": false }, { "in": "query", "name": "provider", "description": "Cloud provider to filter commitments by", "schema": { "type": "string", "enum": [ "aws", "azure", "gcp" ], "example": "aws" }, "required": true }, { "in": "query", "name": "start_date", "description": "Start date for the commitment period (YYYY-MM-DD)", "schema": { "type": "string", "format": "date", "example": "2023-01-01" }, "required": true }, { "in": "query", "name": "end_date", "description": "End date for the commitment period (YYYY-MM-DD)", "schema": { "type": "string", "format": "date", "example": "2023-12-31" }, "required": true } ], "responses": { "422": { "$ref": "#/components/responses/UNPROCESSABLE_CONTENT" }, "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/IdsResponse" } } } }, "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" ] }, "parameters": [ { "in": "path", "name": "org_id", "required": true, "schema": { "type": "string", "minLength": 1 } } ] }, "/v1/org/{org_id}/commitments/chart": { "get": { "parameters": [ { "in": "query", "name": "filter", "description": "Optional JSON filter criteria for commitment data", "schema": { "type": [ "object", "null" ], "example": "{\"field\": \"type\", \"op\": \"=\", \"value\": \"Compute Instance\"}", "additionalProperties": {} }, "required": false }, { "in": "query", "name": "provider", "description": "Cloud provider to filter commitments by", "schema": { "type": "string", "enum": [ "aws", "azure", "gcp" ], "example": "aws" }, "required": true }, { "in": "query", "name": "start_date", "description": "Start date for the chart data (YYYY-MM-DD)", "schema": { "type": "string", "format": "date", "example": "2023-01-01" }, "required": true }, { "in": "query", "name": "end_date", "description": "End date for the chart data (YYYY-MM-DD)", "schema": { "type": "string", "format": "date", "example": "2023-12-31" }, "required": true } ], "responses": { "422": { "$ref": "#/components/responses/UNPROCESSABLE_CONTENT" }, "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PubChartResponse" } } } }, "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" ], "summary": "/commitments/chart", "description": "Generates time-series chart data for commitment metrics over the specified time period. The data includes daily or monthly values for commitment spend, utilization, locked vs unlocked commitments, and realized savings. Results are aggregated by day or month depending on the date range selected. \n\n**Future Projections:** When the end_date extends into the future, the API returns projected values based on current commitment utilization patterns. Each data point includes an `is_projection` field that indicates whether the values are historical (false) or projected (true). Projected values assume that active commitments will continue with their current utilization rates through their expiration dates. This is useful for forecasting future commitment costs and savings based on existing commitments." }, "parameters": [ { "in": "path", "name": "org_id", "required": true, "schema": { "type": "string", "minLength": 1 } } ] }, "/v1/org/{org_id}/exchanges/recommendations": { "get": { "parameters": [ { "in": "query", "name": "provider", "description": "Cloud provider (aws, azure, gcp)", "schema": { "example": "aws", "type": "string", "enum": [ "aws", "azure", "gcp" ] }, "required": true }, { "in": "query", "name": "plan_id", "description": "Optional commitment plan ID to use for plan-derived exchange purchases. When omitted, the endpoint prefers the latest calculated 'Recommended RIs Only' default plan for the provider-resources segment \u2014 a twin of the Recommended plan without savings plans, which cannot be exchanged \u2014 falling back to the same Recommended default plan selected by GET /commitment-plans/recommended when that plan does not exist yet. Responses may also include non-plan-derived native-to-GRI exchanges.", "schema": { "type": [ "string", "null" ], "format": "uuid", "default": null }, "required": false }, { "in": "query", "name": "commitment_ids", "description": "Optional explicit Azure commitment IDs to consider returning. When omitted, the exchanger detects underutilized exchange candidates from the default 3-day DailyUtilization lookback. Explicit commitments without utilization rows in that lookback are excluded. Mutually exclusive with plan_id.", "schema": { "type": [ "array", "null" ], "default": null, "items": { "type": "string", "format": "uuid" } }, "required": false, "explode": true, "style": "form" } ], "responses": { "422": { "$ref": "#/components/responses/UNPROCESSABLE_CONTENT" }, "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ExchangeRecommendationsResponse" } } } }, "400": { "description": "Bad Request" }, "204": { "description": "No Content" }, "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" } } } }, "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": [ "Exchanges" ], "summary": "Get Azure exchange recommendations", "description": "Returns Azure reservation exchange recommendations using the same recommendation logic as the beta exchange endpoint, including plan-derived exchanges and eligible same-SKU 1-year native to 1-year GRI exchanges. When plan_id is omitted, the endpoint prefers the latest calculated 'Recommended RIs Only' default plan for the provider-resources segment (a twin of the Recommended plan without savings plans, which cannot be exchanged), falling back to the Recommended default plan when that plan does not exist yet. Currently only provider=azure is supported." }, "parameters": [ { "in": "path", "name": "org_id", "required": true, "schema": { "type": "string", "format": "uuid" } } ] }, "/v1/org/{org_id}/exchanges/recommendations/apply": { "post": { "responses": { "422": { "$ref": "#/components/responses/UNPROCESSABLE_CONTENT" }, "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApplyExchangeRecommendationsResponse" } } } }, "400": { "description": "Bad Request" }, "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" } } } }, "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/ApplyExchangeRecommendationsArgs" } } } }, "tags": [ "Exchanges" ], "summary": "Apply Azure exchange recommendations", "description": "Requests application of one Azure reservation exchange recommendation using the same explicit purchase and return item body as the beta exchange endpoint. Currently only provider=azure is supported." }, "parameters": [ { "in": "path", "name": "org_id", "required": true, "schema": { "type": "string", "format": "uuid" } } ] }, "/v1/org/{org_id}/metrics": { "get": { "parameters": [ { "in": "query", "name": "provider", "description": "Cloud provider to get metrics for", "schema": { "example": "aws", "type": "string", "enum": [ "aws", "azure", "gcp" ] }, "required": true } ], "responses": { "422": { "$ref": "#/components/responses/UNPROCESSABLE_CONTENT" }, "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PublicMetrics" } } } }, "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" ], "summary": "/metrics", "description": "Retrieves key performance metrics for cloud commitments (RIs/SPs) for the specified provider. Returns financial data including lifetime and month-to-date savings, automation status, potential missed savings opportunities, commitment coverage, and utilization rates. This endpoint provides a comprehensive overview of commitment performance and automation status." }, "parameters": [ { "in": "path", "name": "org_id", "required": true, "schema": { "type": "string", "format": "uuid" } } ] }, "/v1/orgs": { "get": { "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "array", "items": { "$ref": "#/components/schemas/Org" } } } } }, "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 accessible organizations", "description": "Returns the list of organizations that the authenticated user has access to. This includes:\n\n- Organizations where the user is a direct member (kind: 'direct')\n- Child organizations if the user belongs to a partner organization (kind: 'partnership')\n- All active organizations if the user is an Archera staff member (kind: 'staff')\n\nEach organization includes the user's role and membership kind.", "tags": [ "Orgs" ] } }, "/v1/org/{org_id}/resources": { "get": { "parameters": [ { "in": "query", "name": "provider", "description": "Filter by provider", "schema": { "type": "string", "enum": [ "aws", "azure", "gcp" ], "example": "aws" }, "required": false }, { "in": "query", "name": "segment_id", "description": "Filter by segment ID", "schema": { "type": "string", "format": "uuid", "example": "550e8400-e29b-41d4-a716-446655440000" }, "required": false }, { "in": "query", "name": "search", "description": "Text to search across multiple columns (case-insensitive partial match)", "schema": { "type": "string", "example": "us-east-1" }, "required": false }, { "in": "query", "name": "desc", "description": "Sort in descending order if true", "schema": { "type": [ "boolean", "null" ], "default": null, "example": "true" }, "required": false }, { "in": "query", "name": "order_by", "description": "Field to order results by", "schema": { "type": [ "string", "null" ], "default": "id", "enum": [ "id", "usage_start", null ], "example": "id" }, "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/ResourceSKU" } } } }, "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" ], "summary": "/resources", "description": "Retrieves a list of infrastructure resources for the organization, including compute instances, databases, and other services with their current status and costs." }, "parameters": [ { "in": "path", "name": "org_id", "required": true, "schema": { "type": "string", "format": "uuid" } } ] }, "/v1/org/{org_id}/resources/{resource_id}/daily-usage": { "get": { "parameters": [ { "in": "query", "name": "start_date", "description": "Start date for the date range filter (inclusive)", "schema": { "type": "string", "format": "date", "example": "2024-01-01" }, "required": true }, { "in": "query", "name": "end_date", "description": "End date for the date range filter (inclusive)", "schema": { "type": "string", "format": "date", "example": "2024-01-31" }, "required": true }, { "in": "query", "name": "catalog_sku_id", "description": "Optional catalog SKU ID to filter daily usage records for a specific SKU", "schema": { "type": [ "string", "null" ], "format": "uuid", "example": "550e8400-e29b-41d4-a716-446655440000" }, "required": false }, { "in": "query", "name": "page", "schema": { "type": "integer", "default": 1, "minimum": 1 }, "required": false }, { "in": "query", "name": "page_size", "schema": { "type": "integer", "default": 100, "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/SKUUsageDaily" } } } }, "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" ], "summary": "/resources/{resource_id}/daily-usage", "description": "Retrieves daily usage data for a specific resource within the specified date range. Optionally filter by catalog_sku_id to get usage for a specific SKU. Including usage metrics, costs, and coverage information." }, "parameters": [ { "in": "path", "name": "org_id", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "in": "path", "name": "resource_id", "required": true, "schema": { "type": "string", "format": "uuid" } } ] }, "/v1/org/{org_id}/uploads": { "post": { "responses": { "422": { "$ref": "#/components/responses/UNPROCESSABLE_CONTENT" }, "201": { "description": "Created", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PublicUpload" } } } }, "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": { "multipart/form-data": { "schema": { "$ref": "#/components/schemas/CreatePublicUpload" } } } }, "tags": [ "Uploads" ], "summary": "Upload a billing file for savings analysis", "description": "Accepts a multipart PDF or CSV billing file, stores it in Archera's invoice upload bucket, and returns an upload ID. Use this upload ID when invoking the Savings Analysis MCP tool. The upload status workflow is: PENDING before storage begins, PROCESSING while the file is being transferred, COMPLETE once it is available for analysis, and ERROR if storage fails." }, "parameters": [ { "in": "path", "name": "org_id", "required": true, "schema": { "type": "string", "format": "uuid" } } ] }, "/v1/org/{org_id}/uploads/{upload_id}": { "get": { "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PublicUpload" } } } }, "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": [ "Uploads" ], "summary": "Get uploaded billing file status", "description": "Returns metadata and upload status for a partner API upload. Clients can poll this endpoint until upload_status is COMPLETE, then pass the upload ID to the Savings Analysis MCP tool." }, "parameters": [ { "in": "path", "name": "org_id", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "in": "path", "name": "upload_id", "required": true, "schema": { "type": "string", "format": "uuid" } } ] }, "/.well-known/jwks.json": { "get": { "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/JWKS" } } } }, "500": { "description": "Failed to load keys" }, "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" } } } } }, "tags": [ "Well-Known" ], "summary": "/.well-known/jwks.json", "description": "Returns the JSON Web Key Set (JWKS) containing public keys used to verify JWT tokens issued by Archera. This endpoint follows the RFC 7517 standard for JWK and is used by clients to validate JWT signatures. No authentication is required as this endpoint provides public cryptographic keys." } }, "/.well-known/oauth-authorization-server": { "get": { "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/OAuthMetadata" } } } }, "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": [ "Well-Known" ], "summary": "/.well-known/oauth-authorization-server", "description": "Returns OAuth 2.0 Authorization Server Metadata as specified in RFC 8414. This endpoint provides automatic discovery of the authorization server's configuration, including supported endpoints, grant types, response types, PKCE methods, and available scopes. OAuth client libraries can use this endpoint to automatically configure themselves without manual endpoint configuration. No authentication is required as this is a public discovery endpoint." } }, "/oauth/authorize": { "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" } } } } }, "summary": "Redirect to React consent page.", "description": "Query Parameters (handled by Authlib):\n client_id: OAuth client identifier\n redirect_uri: Where to redirect after authorization\n response_type: Must be 'code'\n scope: Space-separated list of requested scopes\n state: CSRF protection token (optional but recommended)\n code_challenge: PKCE code challenge\n code_challenge_method: PKCE method (usually 'S256')\n\nReturns:\n Redirect to React consent page with OAuth params and client info", "tags": [ "OAuth" ] }, "post": { "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" } } } } }, "summary": "Handle user authorization decision from React consent page.", "description": "Query Parameters:\n All OAuth params from GET (client_id, redirect_uri, state, etc.)\n\nForm Parameters:\n confirm: 'yes' to authorize, 'no' to deny\n\nReturns:\n Redirect to client with authorization code or error", "tags": [ "OAuth" ] } }, "/oauth/token": { "post": { "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" } } } } }, "summary": "Issue access tokens.", "description": "Form Parameters (authorization_code grant):\n grant_type: Must be 'authorization_code'\n code: Authorization code from /authorize\n redirect_uri: Must match original request\n client_id: OAuth client identifier\n code_verifier: PKCE code verifier\n\nForm Parameters (refresh_token grant):\n grant_type: Must be 'refresh_token'\n refresh_token: Valid refresh token\n client_id: OAuth client identifier\n\nReturns:\n JSON response with access_token (JWT), refresh_token, expires_in, etc.", "tags": [ "OAuth" ] } }, "/oauth/sessions": { "get": { "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "array", "items": { "$ref": "#/components/schemas/OAuthSessionResponse" } } } } }, "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 all active OAuth sessions for the current user.", "description": "Returns:\nList of active sessions including client info, creation time, and scope", "tags": [ "OAuth" ] } }, "/oauth/sessions/{token_id}": { "delete": { "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" } } } } }, "summary": "Revoke a specific OAuth session by token ID.", "description": "Args:\n token_id: UUID of the OAuth token to revoke\n\nReturns:\n 204 No Content on success\n 404 Not Found if session doesn't exist or doesn't belong to user", "tags": [ "OAuth" ] }, "parameters": [ { "in": "path", "name": "token_id", "required": true, "schema": { "type": "string", "format": "uuid" } } ] }, "/oauth/revoke-all": { "post": { "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RevokeAllSessionsResponse" } } } }, "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": "Revoke all OAuth sessions (refresh tokens) for the current user across all clients.", "description": "Returns:\nJSON with message and count of revoked sessions", "tags": [ "OAuth" ] } }, "/oauth/revoke": { "post": { "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" } } } } }, "summary": "Revoke an access token or refresh token.", "description": "Form Parameters:\n token: The token to revoke (access_token or refresh_token)\n token_type_hint: Optional hint about token type ('access_token' or 'refresh_token')\n\nReturns:\n 200 response (always returns 200 per RFC 7009, even for invalid tokens)", "tags": [ "OAuth" ] } }, "/oauth/register": { "post": { "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": [ "OAuth" ] } } }, "tags": [ { "name": "Commitment Plans", "description": "API for managing commitment plans" }, { "name": "Commitments", "description": "API for retrieving and analyzing cloud commitment inventory, including Reserved Instances, Savings Plans, and Azure Reserved VM Instances. Provides access to detailed commitment data, utilization metrics, and cost savings information." }, { "name": "Exchanges", "description": "API for commitment exchange recommendations" }, { "name": "Metrics", "description": "High level metrics to track commitment performance." }, { "name": "Orgs", "description": "Endpoints for organizations accessible to the authenticated user" }, { "name": "Resources", "description": "API for retrieving and analyzing infrastructure resources" }, { "name": "Uploads", "description": "API for uploading billing files for savings analysis" }, { "name": "Well-Known", "description": "OAuth 2.0 discovery endpoints (JWKS and Authorization Server Metadata)" }, { "name": "OAuth", "description": "OAuth 2.0 authorization endpoints for third-party integrations" } ], "openapi": "3.1.0", "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": {}, "code": { "type": [ "string", "null" ] }, "url": { "type": [ "string", "null" ] }, "timestamp": { "type": "string" }, "type": { "type": "string" } }, "required": [ "message", "timestamp", "type" ] }, "CommitmentPlan": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "name": { "type": "string" }, "description": { "type": [ "string", "null" ] }, "org_id": { "type": "string", "format": "uuid" }, "created_at": { "type": "string", "format": "date-time" }, "is_calculating": { "type": "boolean" }, "status": { "enum": [ "new", "reviewed", "scheduled", "completed", "draft", "needs_review", "in_progress" ] }, "max_term": { "type": [ "string", "null" ] }, "covered_ondemand_cost_hourly": { "type": "number" }, "before_ondemand_cost_hourly": { "type": "number" }, "before_reserved_cost_hourly": { "type": "number" }, "amortized_cost_hourly": { "type": "number" }, "recurring_cost_hourly": { "type": "number" }, "upfront_cost_hourly": { "type": "number" }, "before_cost_hourly": { "type": "number" }, "after_cost_hourly": { "type": "number" }, "total_cost_hourly": { "type": "number" }, "savings_hourly": { "type": "number" }, "fee_hourly": { "type": "number" }, "commitment_coverage": { "type": "number" }, "minimum_commitment_cost": { "type": "number" }, "breakeven_hours": { "type": "number" }, "total_savings": { "type": "number" }, "monthly_savings": { "type": "number" }, "total_monthly_before_cost": { "type": "number" } }, "required": [ "after_cost_hourly", "amortized_cost_hourly", "before_cost_hourly", "before_ondemand_cost_hourly", "before_reserved_cost_hourly", "breakeven_hours", "commitment_coverage", "covered_ondemand_cost_hourly", "created_at", "fee_hourly", "id", "is_calculating", "max_term", "minimum_commitment_cost", "monthly_savings", "name", "org_id", "recurring_cost_hourly", "savings_hourly", "status", "total_cost_hourly", "total_monthly_before_cost", "total_savings", "upfront_cost_hourly" ], "additionalProperties": false }, "PurchasePlanContractSpec": { "type": "object", "properties": { "commitment_type": { "type": "string" }, "properties": { "type": "object", "default": {}, "additionalProperties": {} }, "term": { "default": null, "type": [ "string", "null" ], "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 ] }, "payment_option": { "default": null, "type": [ "string", "null" ], "enum": [ "no_upfront", "partial_upfront", "all_upfront", null ] } }, "required": [ "commitment_type" ], "additionalProperties": false }, "PublicCommitmentOffer": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "provider": { "type": "string", "enum": [ "aws", "azure", "gcp" ] }, "provider_offering_id": { "type": "string" }, "type": { "type": "string" }, "display_name": { "type": [ "string", "null" ] }, "leased_display_name": { "type": [ "string", "null" ] }, "region": { "type": [ "string", "null" ] }, "duration_seconds": { "type": "number" }, "upfront_cost": { "type": "number" }, "recurring_cost": { "type": "number" }, "offering_class": { "enum": [ "standard", "convertible", null ] }, "payment_option": { "enum": [ "No Upfront", "Partial Upfront", "All Upfront", null ] }, "offering_id": { "type": [ "string", "null" ] }, "product_description": { "type": [ "string", "null" ] }, "instance_family": { "type": [ "string", "null" ] }, "instance_type": { "type": [ "string", "null" ] }, "tenancy": { "type": [ "string", "null" ] }, "az": { "type": [ "string", "null" ] }, "is_multi_az": { "type": [ "boolean", "null" ] }, "is_flexible": { "type": [ "boolean", "null" ] }, "plan_type": { "type": [ "string", "null" ] } }, "required": [ "az", "display_name", "duration_seconds", "id", "instance_family", "instance_type", "is_flexible", "is_multi_az", "leased_display_name", "offering_id", "plan_type", "product_description", "provider", "provider_offering_id", "recurring_cost", "region", "tenancy", "type", "upfront_cost" ], "additionalProperties": false }, "CommitmentPlanLineItem_Exclude_CoveredServices": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "plan_id": { "type": "string", "format": "uuid" }, "offer_id": { "type": "string", "format": "uuid" }, "lease_menu_item_id": { "type": [ "string", "null" ], "format": "uuid" }, "account_id": { "type": [ "string", "null" ] }, "recommended_quantity": { "type": "integer", "description": "Recommended number of units to purchase" }, "selected_quantity": { "type": "integer", "description": "Selected number of units to purchase" }, "recommended_commitment": { "type": "number", "description": "Recommended hourly commitment amount ($/hour for Savings Plans, 0 for instance RIs)" }, "selected_commitment": { "type": "number", "description": "Selected hourly commitment amount ($/hour for Savings Plans, 0 for instance RIs)" }, "is_selected": { "type": "boolean", "description": "Whether this line item is selected for purchase" }, "after_amortized_cost": { "type": "number", "description": "Hourly amortized cost of the commitment (upfront + recurring)" }, "upfront_cost": { "type": "number", "description": "Total upfront payment required (not hourly rate)" }, "recurring_cost": { "type": "number", "description": "Hourly recurring cost" }, "before_cost": { "type": "number", "description": "Total hourly cost before this commitment (ondemand + existing reservations)" }, "before_ondemand_cost": { "type": "number", "description": "Hourly ondemand cost before this commitment" }, "before_reserved_cost": { "type": "number", "description": "Hourly reserved cost from existing commitments" }, "covered_ondemand_cost": { "type": "number", "description": "Hourly ondemand cost that will be covered by this commitment" }, "after_covered_units": { "type": "number", "description": "Units that will be covered after the plan is applied" }, "total_cost": { "type": "number", "description": "Total cost of this commitment over its full term" }, "monthly_cost": { "type": "number", "description": "Monthly cost of this commitment" }, "savings": { "type": "number", "description": "Hourly savings compared to ondemand pricing" }, "monthly_savings": { "type": "number", "description": "Average monthly savings compared to ondemand pricing" }, "total_savings": { "type": "number", "description": "Total savings over the commitment term" }, "fee": { "type": "number", "description": "Estimated Archera premium (hourly) based on quoted maximum savings. See https://www.archera.ai/pricing for details." }, "discount_rate": { "type": "number", "description": "Discount percentage vs ondemand" }, "breakeven_hours": { "type": "number", "description": "Hours of usage needed until the achieved savings is greater than the remaining commitment for this line item" }, "contract_term": { "description": "Commitment term (e.g., 'one_year_gris', 'thirty_day_gris')", "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 structure (No Upfront, Partial Upfront, All Upfront)", "enum": [ "No Upfront", "Partial Upfront", "All Upfront" ] }, "contract_spec": { "description": "Detailed contract specifications including commitment type and properties", "$ref": "#/components/schemas/PurchasePlanContractSpec" }, "offer": { "description": "Detailed information about the commitment offer", "$ref": "#/components/schemas/PublicCommitmentOffer" } }, "required": [ "account_id", "after_amortized_cost", "after_covered_units", "before_cost", "before_ondemand_cost", "before_reserved_cost", "breakeven_hours", "contract_spec", "contract_term", "covered_ondemand_cost", "discount_rate", "fee", "id", "is_selected", "lease_menu_item_id", "monthly_cost", "monthly_savings", "offer", "offer_id", "payment_option", "plan_id", "recommended_commitment", "recommended_quantity", "recurring_cost", "savings", "selected_commitment", "selected_quantity", "total_cost", "total_savings", "upfront_cost" ], "additionalProperties": false }, "ResourceSKU": { "type": "object", "properties": { "id": { "type": "string" }, "resource_id": { "type": "string", "format": "uuid", "description": "Unique identifier for the underlying resource" }, "provider": { "type": "string", "enum": [ "aws", "azure", "gcp" ] }, "provider_resource_id": { "type": "string", "description": "Provider's unique identifier (e.g., ARN for AWS)", "example": "arn:aws:ec2:us-west-2:123456789012:instance/i-1234567890abcdef0" }, "is_spot": { "type": "boolean", "description": "Whether this is a spot instance (a way to utilize unused instances)" }, "name": { "type": [ "string", "null" ] }, "resource_group": { "type": [ "string", "null" ], "description": "Azure resource group" }, "usage_end": { "type": "string", "format": "date", "description": "Last date this resource had usage" }, "usage_start": { "type": "string", "format": "date", "description": "First date this resource had usage" }, "tags": { "type": "object", "additionalProperties": { "type": "string" } }, "created_at": { "type": "string", "format": "date" }, "updated_at": { "type": "string", "format": "date" }, "instance_id": { "readOnly": true, "type": "string" }, "billing_account_id": { "type": "string", "description": "Management account ID (AWS) or billing account ID (Azure/GCP)" }, "sub_account_id": { "type": "string", "description": "Account ID where the resource is running" }, "management_account_id": { "readOnly": true, "description": "Management account ID (AWS) or billing account ID (Azure/GCP)", "deprecated": true, "type": "string" }, "owner_account_id": { "readOnly": true, "description": "Account ID where the resource is running", "deprecated": true, "type": "string" }, "sku_title": { "readOnly": true, "type": "string" }, "sku_name": { "type": [ "string", "null" ] }, "availability_zone": { "type": [ "string", "null" ] }, "cache_engine": { "type": [ "string", "null" ], "description": "Cache engine type (e.g., Redis, Memcached)" }, "database_engine": { "type": [ "string", "null" ], "description": "Database engine type (e.g., MySQL, PostgreSQL)" }, "description": { "type": [ "string", "null" ] }, "family": { "type": [ "string", "null" ], "description": "Service or product family (e.g., 'Compute', 'Storage')" }, "full_region_name": { "type": [ "string", "null" ] }, "has_ondemand_terms": { "type": [ "boolean", "null" ], "description": "Whether on-demand pricing is available for this SKU" }, "instance_type": { "type": [ "string", "null" ], "description": "Instance type (e.g., 'm5.large', 'Standard_D4s_v3')" }, "instance_type_family": { "type": [ "string", "null" ], "description": "Instance family (e.g., 'm5', 'Standard_D')" }, "is_reservable": { "type": [ "boolean", "null" ], "description": "Whether this resource type supports reservations/commitments" }, "license_model": { "type": [ "string", "null" ] }, "location_type": { "type": [ "string", "null" ] }, "normalization_size_factor": { "type": [ "string", "null" ] }, "operating_system": { "type": [ "string", "null" ] }, "pre_installed_sw": { "type": [ "string", "null" ] }, "price_currency": { "type": [ "string", "null" ] }, "provider_service": { "type": [ "string", "null" ] }, "provider_sku_id": { "type": [ "string", "null" ] }, "publication_date": { "type": [ "string", "null" ] }, "region": { "type": [ "string", "null" ] }, "service": { "type": [ "string", "null" ], "description": "Service name (e.g., 'Amazon Elastic Compute Cloud')" }, "tenancy": { "type": [ "string", "null" ] }, "usage_type": { "type": [ "string", "null" ] }, "version": { "type": [ "string", "null" ] }, "vpc_networking_support": { "type": [ "boolean", "null" ] }, "ondemand_usage_unit": { "type": [ "string", "null" ] } }, "required": [ "billing_account_id", "created_at", "id", "is_spot", "management_account_id", "owner_account_id", "provider", "provider_resource_id", "resource_id", "sub_account_id", "tags", "updated_at", "usage_end", "usage_start" ], "additionalProperties": false }, "CommitmentPlanResourceMatch": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid", "description": "Unique identifier for the resource match" }, "total_units": { "type": "number", "description": "Total resource usage units" }, "before_uncovered_units": { "type": "number", "description": "Units not covered at the moment (before this plan)" }, "after_covered_units": { "type": "number", "description": "Units that will be covered after the plan is applied" }, "after_uncovered_units": { "type": "number", "description": "Units that will remain uncovered after the plan to avoid overcommit" }, "ondemand_price": { "type": "number", "description": "Ondemand cost per unit-hour" }, "if_all_ondemand_cost": { "type": "number", "description": "Hourly cost if paying all the units with ondemand price" }, "before_ondemand_cost": { "type": "number", "description": "Current hourly ondemand cost for units not covered by existing commitments" }, "after_ondemand_cost": { "type": "number", "description": "Hourly ondemand cost remaining after applying this plan" }, "covered_ondemand_cost": { "type": "number", "description": "Hourly ondemand cost for units that will be covered by this plan" }, "before_reserved_cost": { "type": "number", "description": "Hourly cost from current/existing reservations for this resource" }, "after_reserved_cost": { "type": "number", "description": "Hourly commitment/reserved cost after applying this plan" }, "before_cost": { "type": "number", "description": "Total hourly cost before applying this plan (ondemand + reserved costs)" }, "after_cost": { "type": "number", "description": "Total hourly cost after applying this plan" }, "monthly_before_cost": { "type": "number", "description": "Total monthly cost before applying this plan" }, "monthly_after_cost": { "type": "number", "description": "Total monthly cost after applying this plan" }, "monthly_after_reserved_cost": { "type": "number", "description": "Monthly reserved/commitment cost portion after applying this plan" }, "monthly_after_ondemand_cost": { "type": "number", "description": "Monthly ondemand cost portion after applying this plan" }, "average_savings": { "type": "number", "description": "Average hourly savings from this plan" }, "average_monthly_savings": { "type": "number", "description": "Average monthly savings from this plan" }, "usage_type": { "description": "Type of resource usage", "type": "string", "enum": [ "running", "resource", "requests", "gb_seconds", "gb_hours", "cpu_hours", "cpu_utilization", "os_hours", "units_per_month", "gb_per_month", "provisioned_concurrency_gb_seconds", "provisioned_duration_gb_seconds", "unknown" ] }, "coverage": { "type": "number", "description": "Percentage of total units that will be covered by commitments (0-1)" }, "resource": { "description": "Detailed resource information including provider, service, and instance details etc", "anyOf": [ { "$ref": "#/components/schemas/ResourceSKU" }, { "type": "null" } ] } }, "required": [ "after_cost", "after_covered_units", "after_ondemand_cost", "after_reserved_cost", "after_uncovered_units", "average_monthly_savings", "average_savings", "before_cost", "before_ondemand_cost", "before_reserved_cost", "before_uncovered_units", "coverage", "covered_ondemand_cost", "id", "if_all_ondemand_cost", "monthly_after_cost", "monthly_after_ondemand_cost", "monthly_after_reserved_cost", "monthly_before_cost", "ondemand_price", "resource", "total_units", "usage_type" ], "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).", "$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 }, "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.", "$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 }, "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", "null" ], "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 ] }, "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", "null" ], "enum": [ "no_upfront", "partial_upfront", "all_upfront", null ] }, "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 }, "HypotheticalTotal": { "type": "object", "properties": { "contract_term": { "description": "Target contract term for this hypothetical.", "type": [ "string", "null" ], "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 ] }, "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.", "$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.", "$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 }, "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" ] }, "type": { "type": "string", "description": "Commitment type (e.g. 'ri', 'savings_plan', 'cud')" }, "region": { "type": [ "string", "null" ], "description": "Cloud region (e.g. 'us-east-1')" }, "duration_seconds": { "type": "integer", "description": "Total commitment duration in seconds" }, "instance_type": { "type": [ "string", "null" ], "description": "Instance type (e.g. 'm5.xlarge'), null for Savings Plans" }, "instance_family": { "type": [ "string", "null" ], "description": "Instance family (e.g. 'm5'), null for some commitment types" }, "offering_class": { "description": "Offering class (e.g. 'standard', 'convertible')", "type": [ "string", "null" ], "enum": [ "standard", "convertible", null ] }, "payment_option": { "description": "Payment option (e.g. 'no_upfront', 'partial_upfront', 'all_upfront')", "type": [ "string", "null" ], "enum": [ "no_upfront", "partial_upfront", "all_upfront", null ] }, "plan_type": { "type": [ "string", "null" ], "description": "Plan type (e.g. 'Compute', 'EC2Instance')" }, "product_description": { "type": [ "string", "null" ], "description": "Product description (e.g. 'Linux/UNIX')" }, "display_name": { "type": [ "string", "null" ], "description": "Human-readable offer name" }, "guaranteed_display_name": { "type": [ "string", "null" ], "description": "Offer name when purchased as an Archera Guaranteed Commitment" }, "is_flexible": { "type": [ "boolean", "null" ], "description": "Whether the commitment has instance size flexibility" } }, "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", "null" ], "description": "Candidate's breakeven_days minus the current line item's. Null if either side has no finite breakeven." } }, "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).", "$ref": "#/components/schemas/CommitmentOffer" }, "lease_menu_item_id": { "type": [ "string", "null" ], "format": "uuid", "description": "Lease attached to this candidate, or null for none. Pass to PUT as `lease_menu_item_id`." }, "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", "null" ], "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 ] }, "discount_rate": { "type": "number", "description": "Discount rate vs on-demand (0-1) for this candidate." }, "breakeven_days": { "type": [ "number", "null" ], "description": "Days until this candidate pays for itself. Null if breakeven is undefined (no net savings + no amortized cost)." }, "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.", "$ref": "#/components/schemas/CommitmentFinancialsNoRebate" }, "delta_vs_current": { "description": "Axis-by-axis difference vs the current offer. All zeros on the `is_current=true` entry.", "$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.", "$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.", "$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 }, "LeaseMenuItem": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "fee_type": { "type": "string" }, "fee_rate": { "type": "number" }, "is_rebate": { "type": "boolean" }, "lockin_months": { "type": "integer" }, "term_months": { "type": "integer" } }, "required": [ "fee_rate", "fee_type", "is_rebate", "lockin_months", "term_months" ], "additionalProperties": false }, "DailyUtilization": { "type": "object", "properties": { "date": { "type": "string", "format": "date" }, "reservation_utilization": { "type": "number" }, "covered_cost": { "type": "number" }, "cost": { "type": "number" }, "potential_savings": { "type": [ "number", "null" ] }, "running_hours": { "type": [ "number", "null" ] }, "savings": { "type": "number" }, "unutilized_commit": { "type": "number" }, "gri_fees": { "type": "number" }, "net_savings": { "type": "number" } }, "required": [ "cost", "covered_cost", "date", "gri_fees", "net_savings", "potential_savings", "reservation_utilization", "running_hours", "savings", "unutilized_commit" ], "additionalProperties": false }, "PublicCommitment": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "provider": { "type": "string", "enum": [ "aws", "azure", "gcp" ] }, "display_name": { "type": "string" }, "leased_display_name": { "type": "string" }, "provider_reservation_id": { "type": "string" }, "account_id": { "type": [ "string", "null" ] }, "master_account_id": { "readOnly": true, "deprecated": true, "type": [ "string", "null" ] }, "billing_account_id": { "type": [ "string", "null" ] }, "type": { "type": "string" }, "region": { "type": [ "string", "null" ] }, "duration_seconds": { "type": [ "integer", "null" ] }, "reservation_end": { "type": [ "string", "null" ] }, "reservation_start": { "type": [ "string", "null" ] }, "transfer_reservation_start": { "type": [ "string", "null" ], "format": "date-time" }, "transfer_reservation_end": { "type": [ "string", "null" ], "format": "date-time" }, "start_date": { "type": [ "string", "null" ], "format": "date-time" }, "end_date": { "type": [ "string", "null" ], "format": "date-time" }, "status": { "enum": [ "active", "locked", "new", "reselling", "unlocked", "unknown", "cancelled", "expired", "recently_expired", "resold", "removed" ] }, "is_leased": { "type": "boolean" }, "is_active": { "type": "boolean" }, "lease": { "anyOf": [ { "$ref": "#/components/schemas/LeaseMenuItem" }, { "type": "null" } ] }, "lease_start": { "type": [ "string", "null" ], "format": "date-time" }, "lease_lockin_date": { "type": [ "string", "null" ], "format": "date-time" }, "upfront_cost": { "type": "number" }, "recurring_cost": { "type": "number" }, "is_flexible": { "type": [ "boolean", "null" ] }, "payment_option": { "enum": [ "No Upfront", "Partial Upfront", "All Upfront", null ] }, "offering_class": { "enum": [ "standard", "convertible", null ] }, "offering_id": { "type": [ "string", "null" ] }, "instance_count": { "type": [ "integer", "null" ] }, "effective_instance_count": { "type": [ "integer", "null" ] }, "product_description": { "type": [ "string", "null" ] }, "instance_family": { "type": [ "string", "null" ] }, "instance_type": { "type": [ "string", "null" ] }, "tenancy": { "type": [ "string", "null" ] }, "az": { "type": [ "string", "null" ] }, "is_multi_az": { "type": [ "boolean", "null" ] }, "plan_type": { "type": [ "string", "null" ] }, "scope": { "enum": [ "shared", "subscription", "resource_group", "management_group", null ] }, "name": { "type": [ "string", "null" ] }, "order_id": { "type": [ "string", "null" ] }, "resource_group": { "type": [ "string", "null" ] }, "instance_flexibility": { "type": [ "boolean", "null" ] }, "savings": { "type": [ "number", "null" ] }, "monthly_savings": { "type": [ "number", "null" ] }, "net_savings": { "type": [ "number", "null" ] }, "utilization": { "type": [ "number", "null" ] }, "potential_savings": { "type": [ "number", "null" ] }, "running_hours": { "type": [ "number", "null" ] }, "amortized_cost": { "type": [ "number", "null" ] }, "daily_utilizations": { "type": "array", "items": { "$ref": "#/components/schemas/DailyUtilization" } } }, "required": [ "account_id", "amortized_cost", "az", "billing_account_id", "daily_utilizations", "display_name", "duration_seconds", "effective_instance_count", "end_date", "id", "instance_count", "instance_family", "instance_flexibility", "instance_type", "is_active", "is_flexible", "is_leased", "is_multi_az", "lease", "lease_lockin_date", "lease_start", "leased_display_name", "master_account_id", "monthly_savings", "name", "net_savings", "offering_class", "offering_id", "order_id", "payment_option", "plan_type", "potential_savings", "product_description", "provider", "provider_reservation_id", "recurring_cost", "region", "reservation_end", "reservation_start", "resource_group", "running_hours", "savings", "scope", "start_date", "status", "tenancy", "transfer_reservation_end", "transfer_reservation_start", "type", "upfront_cost", "utilization" ], "additionalProperties": false }, "IdsResponse": { "type": "object", "properties": { "ids": { "type": "array", "items": { "type": "string" } } }, "required": [ "ids" ], "additionalProperties": false }, "DataPoint": { "type": "object", "properties": { "date": { "type": "string" }, "remaining_commit": { "type": "number" }, "locked_commit": { "type": "number" }, "unlocked_commit": { "type": "number" }, "savings": { "type": "number" }, "net_savings": { "type": "number" }, "utilization": { "type": "number" }, "unutilized_commit": { "type": "number" }, "is_projection": { "type": "boolean", "description": "Indicates whether this data point is a projection based on current commitment utilization patterns. Historical data (is_projection=false) reflects actual recorded metrics, while projected data (is_projection=true) represents estimated future values assuming commitments continue with their current utilization rates." } }, "required": [ "date", "is_projection", "locked_commit", "net_savings", "remaining_commit", "savings", "unlocked_commit", "unutilized_commit", "utilization" ], "additionalProperties": false }, "PubChartResponse": { "type": "object", "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/DataPoint" } } }, "additionalProperties": false }, "ExchangePurchase": { "type": "object", "properties": { "account_id": { "type": [ "string", "null" ], "description": "Target cloud account/subscription for the purchase." }, "contract_term": { "description": "User-facing purchase commitment term. For leased/guaranteed purchases this is the lease lock-in term; for native purchases it is the offer duration.", "type": [ "string", "null" ], "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 ] }, "lease_menu_item_id": { "type": [ "string", "null" ], "format": "uuid", "description": "Lease menu item attached to the purchase side, or null for native purchases." }, "quantity": { "type": "integer", "description": "Quantity of the Azure reservation to purchase." }, "offer": { "description": "Azure reservation offer being purchased.", "$ref": "#/components/schemas/CommitmentOffer" }, "commitment_upfront_cost": { "type": "number", "description": "One-time upfront dollars required at signing for the purchase side. NOT a monthly rate." }, "commitment_financials_monthly_rate": { "description": "Purchase-side plan line item economics as 730-hour monthly rates.", "$ref": "#/components/schemas/CommitmentFinancialsNoRebate" } }, "required": [ "commitment_financials_monthly_rate", "commitment_upfront_cost", "offer", "quantity" ], "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" ] }, "display_name": { "type": "string", "description": "Human-readable commitment name" }, "guaranteed_display_name": { "type": "string", "description": "Commitment name when held as an Archera Guaranteed Commitment" }, "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", "null" ], "description": "Cloud account ID this commitment is in" }, "billing_account_id": { "type": [ "string", "null" ], "description": "Billing/management account ID" }, "start_date": { "type": [ "string", "null" ], "format": "date-time", "description": "When the commitment started" }, "end_date": { "type": [ "string", "null" ], "format": "date-time", "description": "When the commitment expires" }, "duration_seconds": { "type": [ "integer", "null" ], "description": "Total commitment duration in seconds" }, "guarantee_start": { "type": [ "string", "null" ], "format": "date-time", "description": "When the Archera guarantee period started" }, "guarantee_lockin_date": { "type": [ "string", "null" ], "format": "date-time", "description": "When the Archera guarantee lock-in period ends" }, "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", "null" ], "description": "Cloud region (e.g. 'us-east-1')" }, "instance_type": { "type": [ "string", "null" ], "description": "Instance type (e.g. 'm5.xlarge')" }, "instance_family": { "type": [ "string", "null" ], "description": "Instance family (e.g. 'm5')" }, "plan_type": { "type": [ "string", "null" ], "description": "Plan type (e.g. 'Compute', 'EC2Instance')" }, "payment_option": { "description": "Payment option (e.g. 'no_upfront', 'partial_upfront', 'all_upfront')", "type": [ "string", "null" ], "enum": [ "no_upfront", "partial_upfront", "all_upfront", null ] }, "offering_class": { "description": "Offering class (e.g. 'standard', 'convertible')", "type": [ "string", "null" ], "enum": [ "standard", "convertible", null ] }, "is_flexible": { "type": [ "boolean", "null" ], "description": "Whether the commitment has instance size flexibility" }, "instance_count": { "type": [ "integer", "null" ], "description": "Number of instances covered" }, "contract_term": { "description": "Contract term (e.g. 'thirty_day_gris', 'one_year')", "type": [ "string", "null" ], "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 ] } }, "required": [ "id", "provider" ], "additionalProperties": false }, "ExchangeReturn": { "type": "object", "properties": { "commitment": { "description": "Azure commitment proposed to return in the exchange.", "$ref": "#/components/schemas/Commitment" }, "quantity": { "type": "integer", "description": "Quantity of this commitment proposed for return." }, "remaining_lifetime_commitment": { "type": "number", "description": "Remaining Azure commitment value returned for this commitment quantity. This is lifetime exchange value, not a monthly rate." }, "utilization": { "type": "number", "description": "Whole-commitment utilization of the returned commitment over the DailyUtilization period (0-1)." }, "underutilized_commitment_cost": { "type": "number", "description": "Estimated underutilized commitment cost over the DailyUtilization period. This is a period total, not a monthly rate." }, "utilization_days": { "type": "integer", "description": "Number of DailyUtilization days behind the utilization fields." }, "reservation_resource_id": { "type": "string", "description": "Azure reservation resource ID required by Azure exchange APIs." }, "commitment_financials_monthly_rate": { "description": "Returned commitment economics as a 730-hour monthly rate for the selected integer return quantity. Cost comes from DailyUtilization commitment cost for the response period, scaled to the returned quantity. Savings are computed after assigning as much utilization as possible to the quantity that remains committed, so returned fully-utilized quantities can have positive savings and underutilized quantities have negative savings. Archera premium and rebate are excluded from exchange recommendations and are not included in net savings.", "$ref": "#/components/schemas/CommitmentFinancialsNoRebate" } }, "required": [ "commitment", "commitment_financials_monthly_rate", "quantity", "remaining_lifetime_commitment", "reservation_resource_id", "underutilized_commitment_cost", "utilization", "utilization_days" ], "additionalProperties": false }, "ExchangeReturnedCommitmentDailyUtilization": { "type": "object", "properties": { "date": { "type": "string", "format": "date", "description": "DailyUtilization date." }, "utilization": { "type": "number", "description": "Whole-commitment utilization of the returned commitments for this date (0-1), dollar weighted by each return's commitment cost." } }, "required": [ "date", "utilization" ], "additionalProperties": false }, "ExchangeRecommendationDelta": { "type": "object", "properties": { "monthly_net_savings": { "type": "number", "description": "Purchase monthly net savings minus returned commitments' monthly net savings. Positive means the exchange purchase saves more per 730-hour month." }, "monthly_commitment_cost": { "type": "number", "description": "Purchase monthly commitment cost minus returned commitments' monthly commitment cost. Positive means more monthly commitment spend." }, "purchase_upfront_cost": { "type": "number", "description": "Purchase-side one-time upfront cost only. Not netted against returned commitments because returned financials are monthly-rate utilization actuals and have no upfront component. NOT a rate." } }, "required": [ "monthly_commitment_cost", "monthly_net_savings", "purchase_upfront_cost" ], "additionalProperties": false }, "ExchangeRecommendation": { "type": "object", "properties": { "purchase_lifetime_commitment": { "type": "number", "description": "Lifetime Azure commitment value of the purchase side." }, "returned_lifetime_commitment": { "type": "number", "description": "Lifetime Azure commitment value returned by the exchange." }, "additional_lifetime_commitment": { "type": "number", "description": "Purchase lifetime commitment minus returned lifetime commitment. Azure exchange policy requires this to be non-negative." }, "purchase": { "$ref": "#/components/schemas/ExchangePurchase" }, "returns": { "type": "array", "items": { "$ref": "#/components/schemas/ExchangeReturn" } }, "purchase_commitment_financials_monthly_rate": { "description": "Purchase-side monthly-rate financials.", "$ref": "#/components/schemas/CommitmentFinancialsNoRebate" }, "returned_commitment_financials_monthly_rate": { "description": "Returned commitments' rolled-up monthly-rate financials for the selected integer return quantities. Cost comes from DailyUtilization commitment cost, and savings are computed after assigning as much utilization as possible to the quantity that remains committed. Rebate and Archera premium are excluded from exchange recommendations and are not included in net savings.", "$ref": "#/components/schemas/CommitmentFinancialsNoRebate" }, "returned_commitment_daily_utilizations": { "type": "array", "description": "Daily whole-commitment utilization for the returned commitments, dollar weighted by each return's commitment cost. Use this for exchange-level utilization charts.", "items": { "$ref": "#/components/schemas/ExchangeReturnedCommitmentDailyUtilization" } }, "reason": { "type": [ "string", "null" ], "description": "Short human-readable reason this exchange was recommended, based on how the exchanger generated it." }, "delta_vs_returned": { "description": "Purchase-side economics compared with returned-commitment economics. Monthly fields are purchase-side minus returned-side; purchase_upfront_cost is purchase-side one-time upfront only and is not netted. Purchase financials come from plan-amortized line item financials; returned financials come from DailyUtilization cost and covered usage for the selected integer return quantities, normalized to 730-hour monthly rates.", "$ref": "#/components/schemas/ExchangeRecommendationDelta" } }, "required": [ "additional_lifetime_commitment", "delta_vs_returned", "purchase", "purchase_commitment_financials_monthly_rate", "purchase_lifetime_commitment", "returned_commitment_daily_utilizations", "returned_commitment_financials_monthly_rate", "returned_lifetime_commitment", "returns" ], "additionalProperties": false }, "ExchangeRecommendationsResponse": { "type": "object", "properties": { "current_utilization_lookback_days": { "type": "integer", "description": "Number of trailing days of DailyUtilization used for returned-commitment utilization and financials." }, "data": { "type": "array", "description": "Azure exchange recommendations.", "items": { "$ref": "#/components/schemas/ExchangeRecommendation" } } }, "required": [ "current_utilization_lookback_days", "data" ], "additionalProperties": false }, "ApplyExchangePurchase": { "type": "object", "properties": { "offer_id": { "type": "string", "format": "uuid", "description": "Azure reservation offer ID to purchase." }, "quantity": { "type": "integer", "minimum": 1, "description": "Quantity of this offer to purchase." } }, "required": [ "offer_id", "quantity" ], "additionalProperties": false }, "ApplyExchangeReturn": { "type": "object", "properties": { "commitment_id": { "type": "string", "format": "uuid", "description": "Existing Azure commitment ID to return." }, "quantity": { "type": "integer", "minimum": 1, "description": "Quantity of this commitment to return." } }, "required": [ "commitment_id", "quantity" ], "additionalProperties": false }, "ApplyExchangeRecommendationsArgs": { "type": "object", "properties": { "provider": { "description": "Cloud provider (aws, azure, gcp)", "example": "aws", "type": "string", "enum": [ "aws", "azure", "gcp" ] }, "purchases": { "type": "array", "minItems": 1, "description": "Explicit purchase-side line items for one exchange recommendation.", "items": { "$ref": "#/components/schemas/ApplyExchangePurchase" } }, "returns": { "type": "array", "minItems": 1, "description": "Explicit return-side line items for one exchange recommendation.", "items": { "$ref": "#/components/schemas/ApplyExchangeReturn" } } }, "required": [ "provider", "purchases", "returns" ], "additionalProperties": false }, "ApplyExchangeRecommendationsResponse": { "type": "object", "properties": { "status": { "type": "string", "description": "Application status for the exchange recommendations." }, "recommendation_count": { "type": "integer", "description": "Number of exchange recommendations applied." } }, "required": [ "recommendation_count", "status" ], "additionalProperties": false }, "PublicMetrics": { "type": "object", "properties": { "lifetime_savings": { "type": "number" }, "lifetime_gri_savings": { "type": "number" }, "mtd_savings": { "type": "number" }, "mtd_gri_savings": { "type": "number" }, "purchase_automation_enabled": { "type": "boolean" }, "buyback_automation_enabled": { "type": "boolean" }, "has_actioned_plan": { "type": "boolean" }, "has_pending_actions": { "type": "boolean" }, "latest_execution_date": { "type": "string", "format": "date" }, "purchase_missed_savings": { "type": "number" }, "buyback_missed_savings": { "type": "number" }, "total_daily_missed_savings": { "type": "number" }, "hourly_missed_savings": { "type": "number" }, "missed_savings_start_date": { "type": "string", "format": "date" }, "missed_savings_end_date": { "type": "string", "format": "date" }, "expiring_savings": { "type": "number" }, "coverage": { "type": "number" }, "utilization": { "type": "number" } }, "required": [ "buyback_automation_enabled", "buyback_missed_savings", "coverage", "expiring_savings", "has_actioned_plan", "has_pending_actions", "hourly_missed_savings", "latest_execution_date", "lifetime_gri_savings", "lifetime_savings", "missed_savings_end_date", "missed_savings_start_date", "mtd_gri_savings", "mtd_savings", "purchase_automation_enabled", "purchase_missed_savings", "total_daily_missed_savings", "utilization" ], "additionalProperties": false }, "Org": { "type": "object", "properties": { "org_id": { "type": "string", "pattern": "[0-9a-f]{8}-[0-9a-f]{4}-4[0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}\\Z", "description": "Unique organization identifier" }, "name": { "type": "string", "description": "Organization name" }, "role": { "type": "string", "enum": [ "user", "admin", "support", "cloud_rep", "restricted_user" ], "description": "User's role in the organization (e.g., admin, user, support, cloud_rep, restricted_user)" }, "kind": { "description": "Type of membership: 'direct' (direct member), 'partnership' (via partner org), 'staff' (Archera staff)", "enum": [ "direct", "staff", "partnership" ] } }, "required": [ "kind", "name", "org_id", "role" ], "additionalProperties": false }, "SKUUsageDaily": { "type": "object", "properties": { "date": { "type": "string", "format": "date" }, "usage_account_id": { "readOnly": true, "deprecated": true, "type": "string" }, "sub_account_id": { "type": "string" }, "usage": { "type": "number" }, "reservation_usage": { "type": "number" }, "free_tier_usage": { "type": "number" }, "ondemand_cost": { "type": "number" }, "reserved_cost": { "type": "number" }, "if_all_ondemand_cost": { "type": "number" }, "spot_cost": { "type": "number" }, "free_tier_savings": { "type": "number" }, "usage_type": { "type": [ "string", "null" ] }, "common_usage_type": { "type": [ "string", "null" ] }, "covered_usage": { "type": "number" }, "uptime": { "type": "number" } }, "required": [ "common_usage_type", "covered_usage", "date", "free_tier_savings", "free_tier_usage", "if_all_ondemand_cost", "ondemand_cost", "reservation_usage", "reserved_cost", "spot_cost", "sub_account_id", "uptime", "usage", "usage_account_id", "usage_type" ], "additionalProperties": false }, "CreatePublicUpload": { "type": "object", "properties": { "description": { "type": [ "string", "null" ], "maxLength": 255, "description": "Optional partner-supplied context for the uploaded billing file" }, "file": { "writeOnly": true, "description": "Billing PDF or CSV file to upload for savings analysis", "type": "string", "format": "binary" } }, "required": [ "file" ], "additionalProperties": false }, "PublicUpload": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid", "readOnly": true }, "created_at": { "type": "string", "format": "date-time", "readOnly": true }, "org_id": { "type": "string", "readOnly": true, "maxLength": 50 }, "file_name": { "type": "string", "readOnly": true, "maxLength": 255 }, "content_type": { "type": "string", "readOnly": true, "maxLength": 255 }, "size_bytes": { "type": "integer", "readOnly": true }, "description": { "type": [ "string", "null" ], "readOnly": true, "maxLength": 255 }, "upload_status": { "readOnly": true, "type": "string", "enum": [ "PENDING", "PROCESSING", "COMPLETE", "ERROR" ] }, "source": { "readOnly": true, "enum": [ "agent_upload", "attachment", "partner_api" ] }, "detected_type": { "type": [ "string", "null" ], "readOnly": true, "maxLength": 64 }, "available_actions": { "type": "array", "readOnly": true, "items": { "type": "string" } } }, "required": [ "content_type", "created_at", "description", "detected_type", "file_name", "id", "org_id", "size_bytes", "source", "upload_status" ], "additionalProperties": false }, "JWK": { "type": "object", "properties": { "kty": { "type": "string", "description": "Key type (e.g., 'RSA')" }, "use": { "type": "string", "description": "Public key use (e.g., 'sig' for signature)" }, "kid": { "type": "string", "description": "Key ID for identifying the key" }, "alg": { "type": "string", "description": "Algorithm (e.g., 'RS256')" }, "n": { "type": "string", "description": "RSA modulus (base64url encoded)" }, "e": { "type": "string", "description": "RSA public exponent (base64url encoded)" } }, "required": [ "alg", "e", "kid", "kty", "n", "use" ], "additionalProperties": false }, "JWKS": { "type": "object", "properties": { "keys": { "type": "array", "description": "Array of JSON Web Keys", "items": { "$ref": "#/components/schemas/JWK" } } }, "required": [ "keys" ], "additionalProperties": false }, "OAuthMetadata": { "type": "object", "properties": { "issuer": { "type": "string", "description": "The authorization server's issuer identifier URL" }, "authorization_endpoint": { "type": "string", "description": "URL of the OAuth 2.0 authorization endpoint" }, "token_endpoint": { "type": "string", "description": "URL of the OAuth 2.0 token endpoint" }, "revocation_endpoint": { "type": "string", "description": "URL of the OAuth 2.0 token revocation endpoint (RFC 7009)" }, "registration_endpoint": { "type": "string", "description": "URL of the OAuth 2.0 dynamic client registration endpoint (RFC 7591)" }, "jwks_uri": { "type": "string", "description": "URL of the JSON Web Key Set document" }, "response_types_supported": { "type": "array", "description": "OAuth 2.0 response_type values supported", "items": { "type": "string" } }, "grant_types_supported": { "type": "array", "description": "OAuth 2.0 grant type values supported", "items": { "type": "string" } }, "code_challenge_methods_supported": { "type": "array", "description": "PKCE code challenge methods supported", "items": { "type": "string" } }, "token_endpoint_auth_methods_supported": { "type": "array", "description": "Client authentication methods supported at token endpoint", "items": { "type": "string" } }, "scopes_supported": { "type": "array", "description": "OAuth 2.0 scope values supported", "items": { "type": "string" } }, "service_documentation": { "type": "string", "description": "URL of service documentation for developers" } }, "required": [ "authorization_endpoint", "code_challenge_methods_supported", "grant_types_supported", "issuer", "jwks_uri", "registration_endpoint", "response_types_supported", "revocation_endpoint", "scopes_supported", "token_endpoint", "token_endpoint_auth_methods_supported" ], "additionalProperties": false }, "OAuthSessionResponse": { "type": "object", "properties": { "token_id": { "type": "string", "pattern": "[0-9a-f]{8}-[0-9a-f]{4}-4[0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}\\Z" }, "client_name": { "type": "string" }, "client_id": { "type": "string" }, "created_at": { "type": "integer" }, "scope": { "type": "string" } }, "required": [ "client_id", "client_name", "created_at", "scope", "token_id" ], "additionalProperties": false }, "RevokeAllSessionsResponse": { "type": "object", "properties": { "message": { "type": "string" }, "count": { "type": "integer" } }, "required": [ "count", "message" ], "additionalProperties": false } }, "responses": { "DEFAULT_ERROR": { "description": "Default error response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "UNPROCESSABLE_CONTENT": { "description": "Unprocessable Content", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "headers": { "PAGINATION": { "description": "Pagination metadata", "schema": { "$ref": "#/components/schemas/PaginationMetadata" } } } } }