# Agent-friendly commitment inventory endpoints

## List filterable commitment attributes

### Endpoint

`get/beta/v1/org/{org_id}/commitments/attributes`

### Description

Returns all fields that can be used in the 'filter' parameter of the commitments and commitments metrics endpoints, along with their types.

### Path parameters

- `org_id`: string (uuid) - Required

### Responses

- `200 OK`: application/json
    - `name`: string - Required
    - `field`: string - Required
    - `type`: string (enum) - Required
      - Possible values: `boolean`, `integer`, `float`, `date`, `datetime`, `time`, `currency`, `percent`, `string`, `enum`, `uuid`, `tags`

- `400 Bad request`: application/json
- `401 Unauthorized`: application/json
- `403 Forbidden`: application/json
- `404 Not found`: application/json
- `405 Method not allowed`: application/json
- `409 Conflict`: application/json
- `500 Internal server error`: application/json
- `default Default error response`: application/json

### Example of successful response

```json
[
  {
    "name": "text",
    "field": "text",
    "type": "boolean"
  }
]
```

## Get valid values for a filterable commitment attribute

### Endpoint

`get/beta/v1/org/{org_id}/commitments/attributes/{field}`

### Description

Returns the valid values for a specific filterable field. Use this to discover what values can be passed in a filter object.

### Path parameters

- `org_id`: string (uuid) - Required
- `field`: string - Required

### Query parameters

- `provider`: string (enum) - Required - Cloud provider (aws, azure, gcp)
  - Example: `aws`
  - Possible values: `aws`, `azure`, `gcp`
- `only_active`: boolean - Optional - Only return the default inventory scope (default true).
- `include_recently_expired`: boolean - Optional
- `search`: string - Optional
- `filter`: object - Optional

### Responses

- `200 OK`: application/json - Various attribute Optional types.
- `400 Bad request`: application/json
- `401 Unauthorized`: application/json
- `403 Forbidden`: application/json
- `404 Not found`: application/json
- `405 Method not allowed`: application/json
- `409 Conflict`: application/json
- `422 Unprocessable Content`: application/json
- `500 Internal server error`: application/json
- `default Default error response`: application/json

### Example of successful response

```json
{
  "name": "text",
  "field": "text",
  "type": "boolean",
  "filters": [
    {
      "field": "text",
      "value": "text",
      "op": "="
    }
  ]
}
```

## Get commitment inventory

### Endpoint

`get/beta/v1/org/{org_id}/commitments`

### Description

Returns the organization's commitment inventory for the specified provider.

### Responses

- `200 OK`: application/json
- `400 Bad request`: application/json
- `401 Unauthorized`: application/json
- `403 Forbidden`: application/json
- `404 Not found`: application/json
- `405 Method not allowed`: application/json
- `409 Conflict`: application/json
- `422 Unprocessable Content`: application/json
- `500 Internal server error`: application/json
- `default Default error response`: application/json

### Example of successful response

```json
[
  {
    "id": "123e4567-e89b-12d3-a456-426614174000",
    "provider_reservation_id": "text",
    "provider": "aws",
    "display_name": "text",
    "guaranteed_display_name": "text",
    "type": "text",
    "status": "active",
    "is_active": true,
    "is_archera_guaranteed": true,
    "account_id": "text",
    "billing_account_id": "text",
    "start_date": "2026-07-28T00:50:07.784Z",
    "end_date": "2026-07-28T00:50:07.784Z",
    "duration_seconds": 1,
    "region": "text",
    "instance_type": "text",
    "plan_type": "text",
    "payment_option": "no_upfront",
    "is_flexible": true,
    "instance_count": 1,
    "contract_term": "one_year_gris",
    "utilization": 1,
    "commitment_upfront_cost": 1,
    "commitment_financials_monthly_rate": {
      "commitment_cost": {
        "total": 1,
        "breakdown": {
          "cloud_provider_cost": {
            "total": 1,
            "breakdown": {
              "recurring": 1,
              "amortized_upfront": 1
            }
          },
          "archera_premium": 1
        }
      },
      "commitment_savings": {
        "net": 1,
        "gross": 1,
        "rebate": 1
      },
      "covered_ondemand_cost": 1
    }
  }
]
```

## Get commitment portfolio summary

### Endpoint

`get/beta/v1/org/{org_id}/commitments/summary`

### Responses

### Example of successful response

```json
{
  "total_commitments": 1,
  "total_active_commitments": 1,
  "recently_expired_commitments": 1,
  "total_guaranteed_commitments": 1,
  "total_native_commitments": 1,
  "average_utilization": 1,
  "expiring_30_days": 1,
  "expiring_90_days": 1,
  "commitment_financials_monthly_rate": {
    "commitment_cost": {
      "total": 1,
      "breakdown": {
        "cloud_provider_cost": {
          "total": 1,
          "breakdown": {
            "recurring": 1,
            "amortized_upfront": 1
          }
        },
        "archera_premium": 1
      }
    },
    "commitment_savings": {
      "net": 1,
      "gross": 1,
      "rebate": 1
    },
    "covered_ondemand_cost": 1
  },
  "by_term": [
    {
      "label": "text",
      "count": 1,
      "average_utilization": 1,
      "commitment_financials_monthly_rate": {
        "commitment_cost": {
          "total": 1,
          "breakdown": {
            "cloud_provider_cost": {
              "total": 1,
              "breakdown": {
                "recurring": 1,
                "amortized_upfront": 1
              }
            },
            "archera_premium": 1
          }
        },
        "commitment_savings": {
          "net": 1,
          "gross": 1,
          "rebate": 1
        },
        "covered_ondemand_cost": 1
      }
    }
  ],
  "by_type": [
    {
      "label": "text",
      "count": 1,
      "average_utilization": 1,
      "commitment_financials_monthly_rate": {
        "commitment_cost": {
          "total": 1,
          "breakdown": {
            "cloud_provider_cost": {
              "total": 1,
              "breakdown": {
                "recurring": 1,
                "amortized_upfront": 1
              }
            },
            "archera_premium": 1
          }
        },
        "commitment_savings": {
          "net": 1,
          "gross": 1,
          "rebate": 1
        },
        "covered_ondemand_cost": 1
      }
    }
  ]
}
```

## Get commitment details

### Endpoint

`get/beta/v1/org/{org_id}/commitments/{commitment_id}`

### Responses

### Example of successful response

```json
{
  "id": "123e4567-e89b-12d3-a456-426614174000",
  "provider_reservation_id": "text",
  "provider": "aws",
  "display_name": "text",
  "guaranteed_display_name": "text",
  "type": "text",
  "status": "active",
  "is_active": true,
  "is_archera_guaranteed": true,
  "account_id": "text",
  "billing_account_id": "text",
  "start_date": "2026-07-28T00:50:07.784Z",
  "end_date": "2026-07-28T00:50:07.784Z",
  "duration_seconds": 1,
  "guarantee_start": "2026-07-28T00:50:07.784Z",
  "guarantee_lockin_date": "2026-07-28T00:50:07.784Z",
  "region": "text",
  "instance_type": "text",
  "instance_family": "text",
  "plan_type": "text",
  "payment_option": "no_upfront",
  "offering_class": "standard",
  "is_flexible": true,
  "instance_count": 1,
  "contract_term": "one_year_gris",
  "utilization": 1,
  "commitment_upfront_cost": 1,
  "commitment_financials_monthly_rate": {
    "commitment_cost": {
      "total": 1,
      "breakdown": {
        "cloud_provider_cost": {
          "total": 1,
          "breakdown": {
            "recurring": 1,
            "amortized_upfront": 1
          }
        },
        "archera_premium": 1
      }
    },
    "commitment_savings": {
      "net": 1,
      "gross": 1,
      "rebate": 1
    },
    "covered_ondemand_cost": 1
  }
}
```

## Compare offer alternatives across commitments in a portfolio

### Endpoint

`get/beta/v1/org/{org_id}/commitments/comparison`

### Responses

### Example of successful response

```json
{
  "current_totals": {
    "commitment_financials_monthly_rate": {
      "commitment_cost": {
        "total": 1,
        "breakdown": {
          "cloud_provider_cost": {
            "total": 1,
            "breakdown": {
              "recurring": 1,
              "amortized_upfront": 1
            }
          },
          "archera_premium": 1
        }
      },
      "commitment_savings": {
        "net": 1,
        "gross": 1
      },
      "covered_ondemand_cost": 1
    },
    "commitment_upfront_cost": 1
  },
  "hypothetical_totals": [
    {
      "contract_term": "one_year_gris",
      "payment_option": "no_upfront",
      "commitment_financials_monthly_rate": {
        "commitment_cost": {
          "total": 1,
          "breakdown": {
            "cloud_provider_cost": {
              "total": 1,
              "breakdown": {
                "recurring": 1,
                "amortized_upfront": 1
              }
            },
            "archera_premium": 1
          }
        },
        "commitment_savings": {
          "net": 1,
          "gross": 1
        },
        "covered_ondemand_cost": 1
      },
      "commitment_upfront_cost": 1,
      "delta_vs_current": {
        "monthly_net_savings": 1,
        "monthly_commitment_cost": 1,
        "upfront_cost": 1
      },
      "commitments": [
        {
          "commitment_id": "123e4567-e89b-12d3-a456-426614174000",
          "actual_term": "one_year_gris",
          "actual_payment_option": "no_upfront",
          "actual_term_reason": "exact_match",
          "utilization_warning": true
        }
      ],
      "low_utilization_commitment_count": 1
    }
  ],
  "data": [
    {
      "commitment_id": "123e4567-e89b-12d3-a456-426614174000",
      "current": {
        "commitment": {
          "id": "123e4567-e89b-12d3-a456-426614174000",
          "provider_reservation_id": "text",
          "provider": "aws",
          "display_name": "text",
          "guaranteed_display_name": "text",
          "type": "text",
          "status": "active",
          "is_active": true,
          "is_archera_guaranteed": true,
          "account_id": "text",
          "billing_account_id": "text",
          "start_date": "2026-07-28T00:50:07.784Z",
          "end_date": "2026-07-28T00:50:07.784Z",
          "duration_seconds": 1,
          "guarantee_start": "2026-07-28T00:50:07.784Z",
          "guarantee_lockin_date": "2026-07-28T00:50:07.784Z",
          "region": "text",
          "instance_type": "text",
          "instance_family": "text",
          "plan_type": "text",
          "payment_option": "no_upfront",
          "offering_class": "standard",
          "is_flexible": true,
          "instance_count": 1,
          "contract_term": "one_year_gris"
        },
        "utilization": 1,
        "discount_rate": 1,
        "breakeven_days": 1,
        "commitment_upfront_cost": 1,
        "commitment_financials_monthly_rate": {
          "commitment_cost": {
            "total": 1,
            "breakdown": {
              "cloud_provider_cost": {
                "total": 1,
                "breakdown": {
                  "recurring": 1,
                  "amortized_upfront": 1
                }
              },
              "archera_premium": 1
            }
          },
          "commitment_savings": {
            "net": 1,
            "gross": 1
          },
          "covered_ondemand_cost": 1
        }
      },
      "candidates": [
        {
          "offer_id": "123e4567-e89b-12d3-a456-426614174000",
          "offer": {
            "id": "123e4567-e89b-12d3-a456-426614174000",
            "provider": "aws",
            "type": "text",
            "region": "text",
            "duration_seconds": 1,
            "instance_type": "text",
            "instance_family": "text",
            "offering_class": "standard",
            "payment_option": "no_upfront",
            "plan_type": "text",
            "product_description": "text",
            "display_name": "text",
            "guaranteed_display_name": "text",
            "is_flexible": true
          },
          "lease_menu_item_id": "123e4567-e89b-12d3-a456-426614174000",
          "selected_amount": 1,
          "contract_term": "one_year_gris",
          "discount_rate": 1,
          "breakeven_days": 1,
          "commitment_upfront_cost": 1,
          "commitment_financials_monthly_rate": {
            "commitment_cost": {
              "total": 1,
              "breakdown": {
                "cloud_provider_cost": {
                  "total": 1,
                  "breakdown": {
                    "recurring": 1,
                    "amortized_upfront": 1
                  }
                },
                "archera_premium": 1
              }
            },
            "commitment_savings": {
              "net": 1,
              "gross": 1
            },
            "covered_ondemand_cost": 1
          },
          "delta_vs_current": {
            "monthly_net_savings": 1,
            "upfront_cost": 1,
            "discount_rate": 1,
            "breakeven_days": 1
          }
        }
      ]
    }
  ],
  "skipped_commitments": [
    {
      "commitment_id": "123e4567-e89b-12d3-a456-426614174000",
      "reason": "text"
    }
  ]
}
```

## Get commitment portfolio metrics over time

### Endpoint

`get/beta/v1/org/{org_id}/commitments/metrics`

### Responses

### Example of successful response

```json
{
  "period_start": "text",
  "period_end": "text",
  "utilization": 1,
  "underutilized_commitment_cost": 1,
  "commitment_financials_period_total": {
    "commitment_cost": {
      "total": 1,
      "breakdown": {
        "cloud_provider_cost": {
          "total": 1,
          "breakdown": {
            "recurring": 1,
            "amortized_upfront": 1
          }
        },
        "archera_premium": 1
      }
    },
    "commitment_savings": {
      "net": 1,
      "gross": 1,
      "rebate": 1
    },
    "covered_ondemand_cost": 1
  },
  "data": [
    {
      "date": "text",
      "utilization": 1,
      "underutilized_commitment_cost": 1,
      "commitment_financials_daily_total": {
        "commitment_cost": {
          "total": 1,
          "breakdown": {
            "cloud_provider_cost": {
              "total": 1,
              "breakdown": {
                "recurring": 1,
                "amortized_upfront": 1
              }
            },
            "archera_premium": 1
          }
        },
        "commitment_savings": {
          "net": 1,
          "gross": 1,
          "rebate": 1
        },
        "covered_ondemand_cost": 1
      }
    }
  ]
}
```