Automation service API reference
The Automation API reference documents every Heat endpoint with curl examples.
See https://docs.openstack.org/api-ref/orchestration/index.html.
These endpoints cover stack management, resource management, event tracking, and template validation on the OpenStack Heat backend. The placeholders {stack_name}, {stack_id}, {resource_name}, {event_id}, and {resource_type} in the paths below stand for the actual names and IDs of your stacks, resources, events, and resource types.
Base URL#
Every Heat API call is rooted at the project-scoped orchestration endpoint:
https://orchestration.<region>.rumble.cloud/v1/{project_id}The orchestration public endpoint in your service catalog already includes the /v1/{project_id} segment, so read the base URL from the catalog rather than assembling it by hand. Every path in this reference is relative to this base: a path shown as /stacks is {base}/stacks. A request that omits /v1/{project_id} returns 404 Not Found.
Required headers#
| Header | When | Value |
|---|---|---|
X-Auth-Token | Every call | A Keystone identity token. Calls without it return 401 Unauthorized. |
Content-Type | POST, PUT, PATCH | application/json |
Accept | Recommended | application/json |
Endpoints#
All paths are relative to the base URL. The success column lists the HTTP status returned on a normal request.
| Method | Path | Success | Description |
|---|---|---|---|
GET | /stacks | 200 | List stacks |
POST | /stacks | 201 | Create a stack |
GET | /stacks/{stack_name}/{stack_id} | 200 | Show stack details |
PUT | /stacks/{stack_name}/{stack_id} | 202 | Replace a stack with a full template |
PATCH | /stacks/{stack_name}/{stack_id} | 202 | Partial stack update |
DELETE | /stacks/{stack_name}/{stack_id} | 204 | Delete a stack |
GET | /stacks/{stack_name}/{stack_id}/resources | 200 | List stack resources |
GET | /stacks/{stack_name}/{stack_id}/resources/{resource_name} | 200 | Show stack resource details |
GET | /stacks/{stack_name}/{stack_id}/events | 200 | List stack events |
GET | /stacks/{stack_name}/{stack_id}/resources/{resource_name}/events/{event_id} | 200 | Show stack event details |
GET | /stacks/{stack_name}/{stack_id}/template | 200 | Show stack template |
POST | /validate | 200 | Validate a template |
GET | /resource_types | 200 | List resource types |
GET | /resource_types/{resource_type} | 200 | Show resource type details (the schema) |
GET | /resource_types/{resource_type}/template | 200 | Get a resource type template |
PUT and PATCH return 202 Accepted: Heat applies the change asynchronously, so poll the stack status to confirm completion. PUT requires the full template; PATCH applies only the keys supplied in the request body and leaves unspecified parameters at their current values.
Stack event details#
Heat does not serve a single event at the stack-level /events/{event_id} path; that path returns 404 for every event ID. To fetch one event, first call GET /stacks/{stack_name}/{stack_id}/events. Each entry in the response carries a resource_name. Use it to build the resource-scoped detail path:
GET /stacks/{stack_name}/{stack_id}/resources/{resource_name}/events/{event_id}Resource type schema#
GET /resource_types/{resource_type} returns the schema directly in its response body. Heat does not expose a separate /resource_types/{resource_type}/schema endpoint. The body contains properties, attributes, and support_status:
{
"resource_type": "OS::Heat::RandomString",
"properties": {
"length": {
"type": "integer",
"description": "Length of the string to generate.",
"default": 32,
"required": false,
"constraints": [{ "range": { "min": 1, "max": 512 } }],
"update_allowed": false,
"immutable": false
}
},
"attributes": {
"value": {
"description": "The random string generated by this resource.",
"type": "string"
}
},
"support_status": {
"status": "SUPPORTED",
"message": null,
"version": "2014.1",
"previous_status": null
}
}Response envelopes#
Successful responses wrap their payload in a top-level key. Parse the envelope that matches the request:
| Response | Envelope |
|---|---|
GET /stacks | { "stacks": [ ... ] } |
POST /stacks, GET/PUT/PATCH /stacks/{stack_name}/{stack_id} | { "stack": { ... } } |
GET /stacks/{stack_name}/{stack_id}/resources | { "resources": [ ... ] } |
GET /stacks/{stack_name}/{stack_id}/events | { "events": [ ... ] } |
GET /stacks/{stack_name}/{stack_id}/template | the raw template document |
GET /resource_types | { "resource_types": [ ... ] } |
GET /resource_types/{resource_type} | { "resource_type": "...", "properties": { ... }, "attributes": { ... }, "support_status": { ... } } |
Errors#
Heat returns two error envelope shapes. Keystone produces the authentication error; Heat produces the rest.
Keystone authentication error (401):
{
"error": {
"code": 401,
"title": "Unauthorized",
"message": "The request you have made requires authentication."
}
}Heat request error (400, 404, and other 4xx):
{
"code": 404,
"title": "Not Found",
"explanation": "The resource could not be found.",
"error": {
"type": "EntityNotFound",
"traceback": null,
"message": "The Stack (STACK_NAME) could not be found."
}
}A client should read the top-level error.code for Keystone errors and error.type for Heat errors. Observed error.type values and the status that accompanies them:
error.type | Status | Cause |
|---|---|---|
EntityNotFound | 404 | The named stack or resource does not exist |
HTTPNotFound | 404 | The requested sub-resource (for example an event ID) does not exist |
InvalidTemplateVersion | 400 | heat_template_version is not one of the supported values |