# Stacks

> Source: https://developers.cloud66.com/v3/endpoints/stacks/

## Get Stack

URL: https://developers.cloud66.com/v3/endpoints/stacks/#get
Endpoint: GET /stacks/:id
OAuth scope: public

Retrieve the details of the stack specified in the request.

**Related models:** Stack

### Stack status values

| Status | Code | Description |
| ----------- | :---: | ----------------------------------------- |
| STK_QUEUED | 0 | Pending analysis |
| STK_SUCCESS | 1 | Deployed successfully |
| STK_FAILED | 2 | Deployment failed |
| STK_ANALYSING | 3 | Analyzing |
| STK_ANALYSED | 4 | Analyzed |
| STK_QUEUED_FOR_DEPLOYING | 5 | Queued for deployment |
| STK_DEPLOYING | 6 | Deploying |
| STK_TERMINAL_FAILURE | 7 | Unable to analyze |

### Stack health status values

| Status | Code | Description |
| ----------- | :---: | ------------------------------------------ |
| HLT_UNKNOWN | 0 | Unknown |
| HLT_BUILDING | 1 | Building |
| HLT_PARTIAL | 2 | Impaired |
| HLT_OK | 3 | Healthy |
| HLT_BROKEN | 4 | Failed |

### Parameters

- `id` (string, required) — Unique identifier of the stack

### Response

```json
{
  "response":
    {
      "uid": "5999b763474b0eafa5fafb64bff0ba80",
      "name": "Awesome App",
      "git": "http://github.com/cloud66-samples/awesome-app.git",
      "git_branch": "fig",
      "environment": "production",
      "cloud": "DigitalOcean",
      "fqdn": "awesome-app.dev.c66.me",
      "language": "ruby",
      "framework": "rails",
      "status": 1,
      "health": 3,
      "last_activity": "2014-08-14T01:46:53+00:00",
      "last_activity_iso": "2014-08-14T01:46:53+00:00",
      "maintenance_mode": false,
      "has_loadbalancer": false,
      "created_at": "2014-08-14 00:38:14 UTC",
      "updated_at": "2014-08-14 01:46:52 UTC",
      "deploy_directory": "/var/deploy/awesome_app",
      "cloud_status": "partial",
      "created_at_iso": "2014-08-14T00:38:14Z",
      "updated_at_iso": "2014-08-14T01:46:52Z",
      "redeploy_hook": "http://hooks.cloud66.com/stacks/redeploy/b806f1c3344eb3aa2a024b23254b75b3/6d677352a6b2eefec6e345ee2b491521"
    }
}
```

---

## Get Stack Action

URL: https://developers.cloud66.com/v3/endpoints/stacks/#action-get
Endpoint: GET /stacks/:stack_id/actions/:id
OAuth scope: public

Retrieve the details of an asynchronous action performed for the the stack specified in the request based on the supplied action ID.

**Related models:** Stack

### Parameters

- `stack_id` (string, required) — Unique identifier of the stack
- `id` (integer, required) — Identifier of the asynchronous action

### Response

```json
{
  "response": {
    "id": 6566418,
    "user": "person@company.com",
    "resource_type": "stack",
    "action": "application_deployment",
    "resource_id": "84195",
    "started_via": "api",
    "started_at": "2023-10-11T11:43:57Z",
    "finished_at": "2023-10-11T11:47:42Z",
    "finished_success": true,
    "finished_message": "Completed successfully",
    "finished_result": {},
    "metadata": {
      "user_reference": "my-useful-id"
    }
  }
}
```

---

## List Stacks

URL: https://developers.cloud66.com/v3/endpoints/stacks/#list
Endpoint: GET /stacks
OAuth scope: public

Retrieves a paged list of all the stack objects the user can access.

**Related models:** Stack, Pagination

### Response

```json
{
  "response": [
    {
      "uid": "5999b763474b0eafa5fafb64bff0ba80",
      "name": "Awesome App",
      "git": "http://github.com/cloud66-samples/awesome-app.git",
      "git_branch": "fig",
      "environment": "production",
      "cloud": "DigitalOcean",
      "fqdn": "awesome-app.dev.c66.me",
      "language": "ruby",
      "framework": "rails",
      "status": 1,
      "health": 3,
      "last_activity": "2014-08-14T01:46:53+00:00",
      "last_activity_iso": "2014-08-14T01:46:53+00:00",
      "maintenance_mode": false,
      "has_loadbalancer": false,
      "created_at": "2014-08-14 00:38:14 UTC",
      "updated_at": "2014-08-14 01:46:52 UTC",
      "deploy_directory": "/var/deploy/awesome_app",
      "cloud_status": "partial",
      "created_at_iso": "2014-08-14T00:38:14Z",
      "updated_at_iso": "2014-08-14T01:46:52Z",
      "redeploy_hook": "http://hooks.cloud66.com/stacks/redeploy/b806f1c3344eb3aa2a024b23254b75b3/6d677352a6b2eefec6e345ee2b491521"
    }
  ],
  "count": 1,
  "pagination": {
    "previous": null,
    "next": null,
    "current": 1,
    "per_page": 30,
    "count": 1,
    "pages": 1
  }
}
```

---

## SSL Certificates

URL: https://developers.cloud66.com/v3/endpoints/stacks/#ssl-certificates
Endpoint: GET /stacks/:stack_id/ssl_certificates
OAuth scope: admin

You can use this method to query, add, delete or update SSL certificates on a stack.

**Related models:** Stack, SSL Certificate, Pagination

### HTTP Methods

- `GET /stacks/:stack_id/ssl_certificates` - List SSL certificates
- `POST /stacks/:stack_id/ssl_certificates` - Create SSL certificate
- `GET /stacks/:stack_id/ssl_certificates/:id` - Get SSL certificate
- `PATCH /stacks/:stack_id/ssl_certificates/:id` - Update SSL certificate
- `PUT /stacks/:stack_id/ssl_certificates/:id` - Update SSL certificate
- `DELETE /stacks/:stack_id/ssl_certificates/:id` - Delete SSL certificate

POST, PATCH and PUT should use the following object format:

```json
{
  "ssl_certificate": {
    "server_names": "mywebsite.com",
    "ssl_termination": true,
    "type": "lets_encrypt",
    "wildcard": true,
    "dns_provider_uuid": "dp-fbe3dd78cdc600b187b38c4d4b6b016b"
  }
}
```

### Parameters

- `stack_id` (string, required) — Unique identifier of the stack
- `type` (string, required) — Type of certificate (manual or lets_encrypt)
- `ssl_termination` (bool, required) — Whether SSL certificate is terminated on the load balancer or not
- `server_names` (string, required) — comma separated list of domains
- `wildcard` (bool, optional) — Whether the certificate must support wildcarded domain names - only applies to type lets_encrypt
- `dns_provider_uuid` (string, optional) — DNS provider to use for the Let's Encrypt DNS challenge
- `certificate` (string, optional) — The certificate address
- `key` (string, optional) — The certificate key
- `intermediate_certificate` (string, optional) — The intermediate certificate chain

### Response

```json
{
  "response": [
    {
      "uuid": "ssl-9ad095613rrr4e0b8f718302bab8709e",
      "name": "pp-ticker-prod-cllaz",
      "server_group_id": null,
      "server_names": "www.fyp111.co",
      "sha256_fingerprint": "481f22f00e117e209dbde4c2ae3831401109fc824784943e39a194a3adb64082",
      "ca_name": "Let's Encrypt",
      "type": "lets_encrypt",
      "wildcard": false,
      "dns_provider_uuid": null,
      "ssl_termination": true,
      "has_intermediate_cert": true,
      "status": 3,
      "created_at": "2023-01-26T10:23:34Z",
      "updated_at": "2023-01-26T10:26:29Z",
      "expires_at": "2023-04-26T09:24:32Z",
      "certificate": null,
      "key": null,
      "intermediate_certificate": null
    }
  ],
  "count": 1,
  "pagination": {
    "previous": null,
    "next": null,
    "current": 1,
    "per_page": 30,
    "count": 1,
    "pages": 1
  }
}
```

---

## Stack Actions List

URL: https://developers.cloud66.com/v3/endpoints/stacks/#actions-list
Endpoint: GET /stacks/:id/actions
OAuth scope: public

Retrieve a paged list of all asynchronous actions performed for the stack specified in the request. You can filter actions by your own metadata using `user_reference` (note: metadata needs to be added to the action when it is invoked to be available here).

**Related models:** Stack, Pagination

### The stack action object

| Property | Data type | Description | Sample value |
| ------------- | --------- | ----------------------------------- | ---------------- |
| id | int | The numeric identifier of the stack action. Identifiers increment by one for each performed action. | `10` |
| user_reference | string (up to 255 chars) | Returns actions where the metadata matches the query. | `useful-reference-123` |
| user | string | The email address of the user who performed the stack action. | `hello@cloud66.com`|
| resource_type | string | The resource for which the action was performed, which is `stack` in this case. | `stack` |
| action | string | The action that was performed for the stack. | `restart` |
| resource_id | int | The unique ID of the resource | `283` |
| started_via | string | The process that initiated the action, which is the UI, API, or command line. | `api` |
| started_at | datetime | The date and time the action was initiated, in UTC datetime. | `2014-09-01T19:08:05Z` |
| finished_at | datetime | The date and time the action was completed, in UTC datetime. | `2014-09-01T19:08:09Z` |
| finished_success | bool | Whether the action completed successfully. | `true` |
| finished_message | string | If applicable, the system message associated with the completed action. | `null` |

### Parameters

- `id` (string, required) — Unique identifier of the stack
- `user_reference` (string, optional) — Returns actions where the metadata matches the query (up to 255 chars)

### Response

```json
{
  "response": [
    {
      "id": 6566418,
      "user": "person@company.com",
      "resource_type": "stack",
      "action": "application_deployment",
      "resource_id": "84195",
      "started_via": "api",
      "started_at": "2023-10-11T11:43:57Z",
      "finished_at": "2023-10-11T11:47:42Z",
      "finished_success": true,
      "finished_message": "Completed successfully",
      "finished_result": {},
      "metadata": {
        "user_reference": "my-useful-id"
      }
    }
  ],
  "count": 1,
  "pagination": {
    "previous": null,
    "next": null,
    "current": 1,
    "per_page": 30,
    "count": 1,
    "pages": 1
  }
}
```

---

## Create Stack

URL: https://developers.cloud66.com/v3/endpoints/stacks/#create
Endpoint: POST /stacks
OAuth scope: redeploy

Create and build a new docker stack. Either manifest definition, or `cloud`, `region`, `size` and `build_type` must be passed as params.

**Related models:** Stack

### Parameters

- `name` (string, required) — New stack name
- `environment` (string, required) — New stack environment
- `service_yaml` (string, required) — The services definition of the new docker stack
- `manifest_yaml` (string, optional) — The manifest definition of the new docker stack
- `cloud` (string, optional) — Cloud provider to create servers in
- `key_name` (string, optional) — Name of the cloud provider key (Default or first available key for the cloud if not specified)
- `region` (string, optional) — Region within the cloud to create servers in
- `size` (string, optional) — Size of the server
- `build_type` (string, optional) — Deploy all services to single or multi servers

### Response

```json
{
  "response":
    {
      "id": 10,
      "user": "test@cloud66.com",
      "resource_type": "stack",
      "action": "stack_create",
      "resource_id": "283",
      "started_via": "api",
      "started_at": "2015-09-01T19:08:05Z",
      "finished_at": null,
      "finished_success": null,
      "finished_message": null
    }
}
```

---

## Reboot Stack Servers

URL: https://developers.cloud66.com/v3/endpoints/stacks/#reboot-servers
Endpoint: POST /stacks/:stack_id/reboot_servers
OAuth scope: reboot

You can use this method to reboot the stack or specific server group of a stack.

**Related models:** Stack, Server

### Parameters

- `stack_id` (string, required) — Unique identifier of the stack
- `strategy` (string, required) — parallel or serial
- `group` (string, optional) — all or web/db/redis etc (default is web)

### Response

```json
{
  "response": {
    "id": 10,
    "user": "test@cloud66.com",
    "resource_type": "stack",
    "action": "stack_reboot",
    "resource_id": "283",
    "started_via": "api",
    "started_at": "2016-01-01T19:08:05Z",
    "finished_at": null,
    "finished_success": null,
    "finished_message": null
  }
}
```

---

## Run Stack Action

URL: https://developers.cloud66.com/v3/endpoints/stacks/#run-action
Endpoint: POST /stacks/:stack_id/actions
OAuth scope: redeploy

Perform an asynchronous action for the stack specified in the request. You can use this method to restart the stack, clear the stack's cache, enable maintenance mode, manage database replication, and control containers, services, and processes.

**Related models:** Stack

### Available Commands

| Command | Comments | Extra Parameters |
| ---------- | ---------- | ---------------- |
| clear_caches | Clears all application caches for the stack | None |
| container_restart | Restarts a particular container on the given stack | • `container_id`:`container-id-or-name` |
| disable_replication_slave_db | Disable replication to the specified slave database server | • `server_uid`:`server-uid`<br/> • `db_type`:`postgresql`, `redis`, `mysql` (optional) |
| maintenance_mode | Enable or disable maintenance mode for a stack | • `value`:`1` for enable or `0` for disable |
| process_pause | Pauses the specified process | • `process_name`:`process-name` (optional)<br/> • `server_uid`:`server-uid` (optional) |
| process_restart | Restarts the specified process | • `process_name`:`process-name` (optional)<br/> • `server_uid`:`server-uid` (optional) |
| process_resume | Resumes the specified process | • `process_name`:`process-name` (optional)<br/> • `server_uid`:`server-uid` (optional) |
| promote_slave_db | Promote the specified slave database server to a standalone master | • `server_uid`:`server-uid`<br/> • `db_type`:`postgresql`, `redis`, `mysql` (optional) |
| restart | Restarts all stack components | None |
| resync_slave_db | Re-sync the specified slave database server with its master database server | • `server_uid`:`server-uid`<br/> • `db_type`:`postgresql`, `mysql` (optional) |
| service_pause | Pauses all the containers from the given service | • `service_name`:`service-name` (optional)<br/> • `server_uid`:`server-uid` (optional) |
| service_restart | Restarts all the containers from the given service | • `service_name`:`service-name` (optional)<br/> • `server_uid`:`server-uid` (optional) |
| service_resume | Resumes all the containers from the given service | • `service_name`:`service-name` (optional)<br/> • `server_uid`:`server-uid` (optional) |

### Parameters

- `stack_id` (string, required) — Unique identifier of the stack
- `command` (string, required) — The action to perform for the stack. Valid values are clear_caches, maintenance_mode, restart, promote_slave_db, resync_slave_db, disable_replication_slave_db, container_restart, service_restart, service_pause, service_resume, process_restart, process_pause, and process_resume.

### Response

```json
{
  "response": {
    "id": 10,
    "user": "test@cloud66.com",
    "resource_type": "stack",
    "action": "clear_caches",
    "resource_id": "283",
    "started_via": "api",
    "started_at": "2014-09-01T19:08:05Z",
    "finished_at": null,
    "finished_success": null,
    "finished_message": null
  }
}
```