# Agent-friendly commitment plan template endpoints  
  
## List commitment plan templates
### get/beta/v1/org/{org_id}/commitment-plan-templates

Returns commitment plan templates scoped to one segment for the given provider. `segment_id` defaults to the provider-resources segment — same fallback as POST/PUT — so the typical caller sees exactly the templates tied to their default segment without cross-segment duplicates.

### Path parameters  
- `org_id` string · uuid **Required**

### Query parameters  
- `provider` string · enum **Required**  
   - Cloud provider (aws, azure, gcp)  
   - Example: `aws`  
   - Possible values: `aws`, `azure`, `gcp`  
- `segment_id` string · uuid · nullable **Optional**  
   - Optional segment ID to scope results. Defaults to the provider resources segment if not specified.  
   - Default: `null`

### Responses  
- 200 **OK**  
  - application/json  
    - `id` string · uuid **Required**  
    - Unique template identifier  
    - `name` string **Required**  
    - Human-readable template name  
    - `segment_id` string · uuid **Required**  
    - Segment this template generates plans for  
    - `created_at` string · date-time **Required**  
    - When the template was created  
    - `is_system_generated` boolean **Required**  
      - True if this template was created automatically by the system — the three built-ins that back Recommended / Balanced / High Savings. Describes origin, not role — system-generated templates are immutable.  
    - `configuration` object · `CommitmentPlanConfiguration` **Required**  
      - Show properties  
  
### Example:  
```
GET /beta/v1/org/{org_id}/commitment-plan-templates?provider=aws HTTP/1.1
Accept: */*
```
  
### Create a commitment plan template
### post/beta/v1/org/{org_id}/commitment-plan-templates

Creates a reusable commitment plan template. If `auto_purchase` is provided, the system will regenerate and optionally purchase plans from this template on the given schedule.

### Path parameters  
- **org_id** string · uuid **Required**

### Body  
- application/json  
    - `provider` string · enum **Required**  
      - Cloud provider (aws, azure, gcp)  
    - Example: `aws`  
    - Possible values: `aws`, `azure`, `gcp`  
    - `segment_id` string · uuid · nullable **Optional**  
      - Optional segment ID to scope results. Defaults to the provider resources segment if not specified.  
      - Default: `null`  
    - `name` string **Required**  
      - Template name  
    - `configuration` object · `CommitmentPlanConfiguration` **Required**  
      - Show properties  
    - `auto_purchase` any of **Optional**  
      - Optional auto-purchase schedule to attach  
      - Default: `null`

### Responses  
- 200 **OK**  
  - application/json  
    - `id` string · uuid **Required**  
    - Unique template identifier  
    - `name` string **Required**  
    - Human-readable template name  
    - `segment_id` string · uuid **Required**  
    - Segment this template generates plans for  
    - `created_at` string · date-time **Required**  
    - When the template was created  
    - `is_system_generated` boolean **Required**  
      - True if this template was created automatically by the system.  
    - `configuration` object · `CommitmentPlanConfiguration` **Required**  
      - Show properties  
    - `auto_purchase` any of **Required**  
      - Scheduled auto-purchase settings, or null if the template is not on a schedule.

### Get a commitment plan template
### get/beta/v1/org/{org_id}/commitment-plan-templates/{template_id}

Returns a single template by ID.

### Path parameters  
- `org_id` string · uuid **Required**  
- `template_id` string · uuid **Required**  
  
### Responses  
- 200 **OK**  
  - application/json  
    - `id` string · uuid **Required**  
    - Unique template identifier  
    - `name` string **Required**  
    - Human-readable template name  
    - `segment_id` string · uuid **Required**  
    - Segment this template generates plans for  
    - `created_at` string · date-time **Required**  
    - When the template was created  
    - `is_system_generated` boolean **Required**  
      - True if this template was created automatically by the system.  
    - `configuration` object · `CommitmentPlanConfiguration` **Required**  
      - Show properties  
    - `auto_purchase` any of **Required**  
      - Scheduled auto-purchase settings, or null if the template is not on a schedule.

### Update a commitment plan template
### put/beta/v1/org/{org_id}/commitment-plan-templates/{template_id}

Merge-semantic update: only keys present in the body are applied.

### Delete a commitment plan template
### delete/beta/v1/org/{org_id}/commitment-plan-templates/{template_id}

Delete a template. System-generated templates cannot be deleted.

### Responses  
- 204 **No Content**

- 400 **Bad request**  
- 401 **Unauthorized**  
- 403 **Forbidden**  
- 404 **Not Found**  
- 500 **Internal server error**  
- default
   - Default error response