OpenAPI Specification
openapi: 3.1.0
info:
description: '### Welcome to the Archera.ai API documentation.
Archera.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.
Whether 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.
If you have questions or need support, please contact our team at support@archera.ai.
## API Key Access
To use this API, you need an API key.
### How to Create an API Key
1. Log in to the Archera.ai web application.
2. Navigate to **User Settings > API Access**.
<a href="https://app.archera.ai/settings?tab=api§ion=user" target="_blank" rel="noopener noreferrer">Open Settings</a>
3. Click **Create New API Key**.
4. Copy and securely store your new API key.
### How to Use Your API Key
Use the `x-api-key` header:
```bash
curl -H ''x-api-key: YOUR_API_KEY'' https://api.archera.ai/v1/org/{org_id}/metrics?provider=aws
```
Keep your API key secure. If you believe your key has been compromised, deactivate it in the web application and generate a new one.
### How to find your Organization ID
1. Log in to the Archera.ai web application.
2. Navigate to **User Settings > Organization**.
3. 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=<org_id>`
'
title: Archera.ai Commitment Plans API
version: v1.0.0
tags:
- name: Commitment Plans
description: API for managing commitment plans
paths:
/v1/org/{org_id}/commitment-plans/{plan_id}:
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
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.
/v1/org/{org_id}/commitment-plans/{plan_id}/apply:
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
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.
/v1/org/{org_id}/commitment-plans/default:
parameters:
- in: path
name: org_id
required: true
schema:
type: string
format: uuid
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.
/v1/org/{org_id}/commitment-plans/recommended:
parameters:
- in: path
name: org_id
required: true
schema:
type: string
format: uuid
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.
/v1/org/{org_id}/commitment-plans/{plan_id}/line-items:
parameters:
- in: path
name: org_id
required: true
schema:
type: string
format: uuid
- in: path
name: plan_id
required: true
schema:
type: string
format: uuid
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.
/v1/org/{org_id}/commitment-plans/{plan_id}/resource-matches:
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
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.
/v1/org/{org_id}/commitment-plans/{plan_id}/comparison:
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
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 — 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].'
components:
schemas:
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
CommitmentCostBreakdown:
type: object
properties:
cloud_provider_cost:
$ref: '#/components/schemas/CloudProviderCost'
archera_premium:
type: number
description: Archera premium — 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
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 — 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 — 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 — 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
# --- truncated at 32 KB (74 KB total) ---
# Full source: https://raw.githubusercontent.com/api-evangelist/archera/refs/heads/main/openapi/archera-commitment-plans-api-openapi.yml