### Example Response for Listing Environments (JSON)

Source: https://docs.shipyard.build/api

This is an example JSON response when successfully listing active environments. It includes details about the environments, such as their attributes and links for pagination.

```json
{
  "data": [
    {
      "attributes": {
        "bypass_token": "WBwQX4e_sxUgyJhkJFJzcs-oLmYPinVeogPtsJL_SV-7H7QMBN6n3TCbjcYNzRtH",
        "name": "muti-repo-app",
        "processing": false,
        "projects": [
          {
            "branch": "my-feature-branch",
            "commit_hash": "abcabc123123",
            "org_name": "shipyard",
            "pull_request_number": 1112,
            "repo_name": "flask-backend"
          },
          {
            "branch": "master",
            "commit_hash": "bcabca321321",
            "org_name": "shipyard",
            "pull_request_number": null,
            "repo_name": "flask-frontend"
          }
        ],
        "ready": true,
        "retired": false,
        "deleted": false,
        "stopped": false,
        "url": "https://shipyard-multi-repo-app-pr1112.dev.shipyardbuild.shipyard.host"
      },
      "id": "aaaaaaaa-bbbb-cccc-dddd-eeeeeeeeeeee",
      "links": {
        "self": "/api/v1/application/aaaaaaaa-bbbb-cccc-dddd-eeeeeeeeeeee"
      },
      "type": "application"
    }
  ],
  "links": {
    "first": "/api/v1/environment?page=1",
    "last": "/api/v1/environment?page=10",
    "next": "/api/v1/environment?page=2",
    "prev": ""
  }
}
```

--------------------------------

### Shipyard Initialization Command for Docker Compose

Source: https://docs.shipyard.build/docker-compose

Defines a command to be executed before the service starts. This is useful for tasks like database migrations or setup scripts. It expects a string representing the command to run.

```yaml
shipyard.init: 'python manage.py db migrate'
```

--------------------------------

### Configure Shipyard GitHub Action with inputs

Source: https://docs.shipyard.build/github-actions

This example shows how to configure the Shipyard GitHub Action using inputs instead of environment variables. The api-token input is required for authentication with Shipyard's APIs, and timeout-minutes controls how long to wait for the environment to be ready. Inputs take precedence over environment variables.

```yaml
  - name: Integrate Shipyard  
    uses: shipyard/shipyard-action@1.0.0  
    with:  
        api-token: ${{ secrets.SHIPYARD_API_TOKEN }}  
        timeout-minutes: 30  

```

--------------------------------

### GET /api/v1/environment

Source: https://docs.shipyard.build/api

Lists all active environments with optional filtering by various criteria. Requires API token authentication.

```APIDOC
## GET /api/v1/environment

### Description
Lists all active environments with optional filtering capabilities. Supports pagination.

### Method
GET

### Endpoint
https://shipyard.build/api/v1/environment

### Parameters
#### Query Parameters
- **name** (string) - Optional - Filter by environment name
- **org_name** (string) - Optional - Filter by organization name
- **repo_name** (string) - Optional - Filter by repository name
- **branch** (string) - Optional - Filter by branch name
- **pull_request_number** (string) - Optional - Filter by PR number
- **deleted** (boolean) - Optional - Filter by deleted status (default: false)
- **page** (integer) - Optional - Page number being requested (default: 1)
- **page_size** (integer) - Optional - Number of environments per page (default: 20)

### Request Headers
- **x-api-token** - Required - Your Shipyard API token

### Response
#### Success Response (200)
- **data** (array) - List of environment objects
- **links** (object) - Pagination links

#### Response Example
```json
{
  "data": [
    {
      "attributes": {
        "bypass_token": "WBwQX4e_sxUgyJhkJFJzcs-oLmYPinVeogPtsJL_SV-7H7QMBN6n3TCbjcYNzRtH",
        "name": "muti-repo-app",
        "processing": false,
        "projects": [
          {
            "branch": "my-feature-branch",
            "commit_hash": "abcabc123123",
            "org_name": "shipyard",
            "pull_request_number": 1112,
            "repo_name": "flask-backend"
          }
        ],
        "ready": true,
        "retired": false,
        "deleted": false,
        "stopped": false,
        "url": "https://shipyard-multi-repo-app-pr1112.dev.shipyardbuild.shipyard.host"
      },
      "id": "aaaaaaaa-bbbb-cccc-dddd-eeeeeeeeeeee",
      "links": {
        "self": "/api/v1/application/aaaaaaaa-bbbb-cccc-dddd-eeeeeeeeeeee"
      },
      "type": "application"
    }
  ],
  "links": {
    "first": "/api/v1/environment?page=1",
    "last": "/api/v1/environment?page=10",
    "next": "/api/v1/environment?page=2",
    "prev": ""
  }
}
```

#### Error Responses
- **401** - Invalid token
- **200** - Empty result set
```

--------------------------------

### Configure Shipyard GitHub Action with environment variables

Source: https://docs.shipyard.build/github-actions

This example demonstrates configuring the Shipyard GitHub Action using environment variables instead of inputs. SHIPYARD_API_TOKEN is required for authentication with Shipyard's APIs, and SHIPYARD_TIMEOUT controls the wait time for environment readiness. Environment variables are overridden by inputs if both are provided.

```yaml
  - name: Integrate Shipyard  
    uses: shipyard/shipyard-action@1.0.0  
    env:  
      SHIPYARD_API_TOKEN: ${{ secrets.SHIPYARD_API_TOKEN }}  
      SHIPYARD_TIMEOUT: 30  

```

--------------------------------

### GET /api/v1/environment/{app_uuid}

Source: https://docs.shipyard.build/api

Retrieves a specific environment by its UUID. Requires API token authentication.

```APIDOC
## GET /api/v1/environment/{app_uuid}

### Description
Retrieves details for a specific environment identified by its UUID.

### Method
GET

### Endpoint
https://shipyard.build/api/v1/environment/{app_uuid}

### Parameters
#### Path Parameters
- **app_uuid** (string) - Required - The UUID of the environment to retrieve

### Request Headers
- **x-api-token** - Required - Your Shipyard API token

### Response
#### Success Response (200)
Returns the environment details in the same format as the list endpoint.

#### Error Responses
- **404** - Environment not found
- **401** - Invalid token
```

--------------------------------

### Get environment build history via Shipyard API

Source: https://docs.shipyard.build/api

Retrieves build history for a specific environment using its UUID. Supports filtering by successful builds and pagination. Requires API token authentication. Returns detailed build information including branch names, commit hashes, and repository details.

```bash
curl -H 'x-api-token: ${YOUR_API_TOKEN}' "https://shipyard.build/api/v1/environment/${app_uuid}/build-history"
```

--------------------------------

### GET /api/v1/environment/{app_uuid}/build-history

Source: https://docs.shipyard.build/api

Retrieves the paginated build history for a specific environment, optionally filtered by build success status.

```APIDOC
## GET /api/v1/environment/{app_uuid}/build-history

### Description
Returns the build history for the specified environment, including project details, success status, and pagination links.

### Method
GET

### Endpoint
/api/v1/environment/{app_uuid}/build-history

### Parameters
#### Path Parameters
- **app_uuid** (string) - Required - The environment/application UUID

#### Query Parameters
- **successfully_built** (boolean) - Optional - Only return builds that deployed successfully (default: false)
- **page** (integer) - Optional - Page number (default: 1)
- **page_size** (integer) - Optional - Number of builds per page (default: 20)

### Request Example
```
curl -H 'x-api-token: ${YOUR_API_TOKEN}' "https://shipyard.build/api/v1/environment/${app_uuid}/build-history?successfully_built=true&page=1&page_size=20"
```

### Response
#### Success Response (200)
- **data** (object) - Contains builds and metadata
  - **builds** (array) - List of build records
    - **id** (string) - Build identifier
    - **projects** (array) - Related projects
      - **branch** (string) - Git branch
      - **commit_hash** (string) - Commit SHA
      - **repo_owner** (string) - Repository owner
      - **pull_request_number** (integer|null) - PR number if applicable
      - **repo_name** (string) - Repository name
    - **successfully_built** (boolean) - Whether the build deployed successfully
    - **queued_at** (string) - ISO 8601 timestamp
  - **name** (string) - Environment name
  - **id** (string) - Environment/application UUID
  - **links** (object) - Pagination links
    - **first** (string) - First page link
    - **last** (string) - Last page link
    - **next** (string) - Next page link
    - **prev** (string) - Previous page link (empty if none)
  - **type** (string) - Resource type

#### Response Example (Data)
{
  "data": {
    "builds": [
      {
        "id": "111222-ccccc-ddddd-5555",
        "projects": [
          {
            "branch": "my-feature-branch",
            "commit_hash": "abcabc123123",
            "repo_owner": "shipyard",
            "pull_request_number": 1112,
            "repo_name": "flask-backend"
          },
          {
            "branch": "master",
            "commit_hash": "bcabca321321",
            "repo_owner": "shipyard",
            "pull_request_number": null,
            "repo_name": "flask-frontend"
          }
        ],
        "successfully_built": true,
        "queued_at": "2022-04-20T20:02:00.039498Z"
      },
      {
        "id": "111222-ccccc-ddddd-214s",
        "projects": [
          {
            "branch": "my-feature-branch",
            "commit_hash": "abcabc123567",
            "repo_owner": "shipyard",
            "pull_request_number": 1112,
            "repo_name": "flask-backend"
          },
          {
            "branch": "master",
            "commit_hash": "bcabca321321",
            "repo_owner": "shipyard",
            "pull_request_number": null,
            "repo_name": "flask-frontend"
          }
        ],
        "successfully_built": false,
        "queued_at": "2022-04-19T20:02:00.039498Z"
      }
    ],
    "name": "flask-starter-app",
    "id": "aaaaaaaa-bbbb-cccc-dddd-eeeeeeeeeeee",
    "links": {
      "first": "/api/v1/environment/aaaaaaaa-bbbb-cccc-dddd-eeeeeeeeeeee/build-history?page=1",
      "last": "/api/v1/environment/aaaaaaaa-bbbb-cccc-dddd-eeeeeeeeeeee/build-history?page=10",
      "next": "/api/v1/environment/aaaaaaaa-bbbb-cccc-dddd-eeeeeeeeeeee/build-history?page=2",
      "prev": ""
    },
    "type": "application"
  }
}

#### Success Response (200) - Empty
{
  "data": [],
  "id": "aaaaaaaa-bbbb-cccc-dddd-eeeeeeeeeeee",
  "links": {
    "first": "/api/v1/environment/aaaaaaaa-bbbb-cccc-dddd-eeeeeeeeeeee/build-history?page=1",
    "last": "/api/v1/environment/aaaaaaaa-bbbb-cccc-dddd-eeeeeeeeeeee/build-history?page=1",
    "next": "",
    "prev": ""
  },
  "type": "application"
}

#### Error Response (401)
- **errors** (array) - List of errors
  - **status** (integer) - HTTP status code
  - **title** (string) - Error title

#### Error Example (401)
{
  "errors": [
    {
      "status": 401,
      "title": "Invalid token"
    }
  ]
}

#### Error Response (404)
- **errors** (array) - List of errors
  - **status** (integer) - HTTP status code
  - **title** (string) - Error title

#### Error Example (404)
{
  "errors": [
    {
      "status": 404,
      "title": "Application not found!"
    }
  ]
}
```

--------------------------------

### Get Environment by UUID (cURL)

Source: https://docs.shipyard.build/api

This cURL command shows how to retrieve a specific environment using its unique UUID. It requires the API token and the environment's UUID as part of the URL.

```bash
curl -H 'x-api-token: ${YOUR_API_TOKEN}' "https://shipyard.build/api/v1/environment/${app_uuid}"
```

--------------------------------

### Shipyard Primary Route Configuration for Docker Compose

Source: https://docs.shipyard.build/docker-compose

Enables a service to be designated as the primary URL for the environment. This is useful in multi-domain setups. It's a boolean flag.

```yaml
shipyard.primary-route: true
```

--------------------------------

### Define Additional Host URLs for Services

Source: https://docs.shipyard.build/docker-compose

Configure additional host URLs for a service beyond the default. This allows specifying a custom prefix, route, and port. The 'prefix' is required and must start and end with an alphanumeric character. 'route' and 'port' are optional. If 'route' is not provided, the service's default route label is used. If 'port' is not provided, the first exposed port in the Compose definition is used. The input is a JSON string.

```json
shipyard.host.api: '{ "prefix": "api" }'
```

```json
shipyard.host.api-with-route: '{ "prefix": "api", "route": "/api/v1" }'
```

```json
shipyard.host.api-with-port: '{ "prefix": "api", "port": 9090 }'
```

```json
shipyard.host.api-with-route-and-port: '{ "prefix": "api", "route": "/api/v1", "port": 9090 }'
```

--------------------------------

### GCP GCR Roles for Service Account

Source: https://docs.shipyard.build/private-docker-registries

Lists the necessary IAM roles for a GCP service account to access Google Container Registry (GCR) when used with Shipyard. These roles grant permissions to get and list objects and buckets in the specified Google Cloud Storage bucket.

```plaintext
resourcemanager.projects.get
resourcemanager.projects.list
storage.objects.get
storage.objects.list
storage.buckets.get
storage.buckets.list
```

--------------------------------

### Define Kubernetes Post-Start Exec Command

Source: https://docs.shipyard.build/docker-compose

Specify a command to be executed on the Kubernetes post-start event for the service. The command must be provided as a JSON string representing an array of strings.

```json
shipyard.lifecycle.postStart.exec.command: "[\"sh\", \"/srv/poststart.sh\"]"
```

--------------------------------

### List All Active Environments (cURL)

Source: https://docs.shipyard.build/api

This cURL command demonstrates how to list all active environments in Shipyard. It requires an API token for authentication and accepts query string parameters for filtering.

```bash
curl -H 'x-api-token: ${YOUR_API_TOKEN}' "https://shipyard.build/api/v1/environment?pull_request_number=1112&org_name=shipyardbuild"
```

--------------------------------

### Run E2E tests on Shipyard ephemeral environment

Source: https://docs.shipyard.build/github-actions

This GitHub Actions workflow demonstrates how to collect a bypass token and URL for an authenticated Shipyard ephemeral environment attached to a pull request in order to run E2E tests. It checks out the code, integrates with Shipyard using the shipyard-action, and runs Cypress tests using environment variables set by the action.

```yaml
on: [pull_request]  
  
jobs:  
  cypress-e2e-tests:  
    runs-on: ubuntu-latest  
    name: Collect the bypass token and URL for an authenticated ephemeral environment attached to this PR in order to run E2E tests on it.  
    steps:  
      - name: Checkout  
        uses: actions/checkout@v2  
      - name: Integrate Shipyard  
        uses: shipyard/shipyard-action@1.0.0  
        env:  
          SHIPYARD_API_TOKEN: ${{ secrets.SHIPYARD_API_TOKEN }}  
      - name: Run the E2E tests against the ephemeral environment  
        run: npm run test  
        shell: bash  
        env:  
            CYPRESS_BASE_URL: $SHIPYARD_ENVIRONMENT_URL  
            CYPRESS_BYPASS_TOKEN: $SHIPYARD_BYPASS_TOKEN  

```

--------------------------------

### Shipyard Readiness Probe Configuration for Docker Compose

Source: https://docs.shipyard.build/docker-compose

Configures readiness probes for a service to determine if it's ready to receive traffic. Supports defining the command to execute, failure threshold, HTTP headers and path, initial delay, probe period, success threshold, and timeout. Commands should be JSON arrays.

```yaml
shipyard.readiness.exec.command: '["bash", "some-script.sh"]'
```

```yaml
shipyard.readiness.failure_threshold: 1
```

```yaml
shipyard.readiness.http.headers: '{"x-reason": "health"}'
```

```yaml
shipyard.readiness.http.path: /healthz
```

```yaml
shipyard.readiness.initial_delay: 10
```

```yaml
shipyard.readiness.period: 15
```

```yaml
shipyard.readiness.success_threshold: 1
```

```yaml
shipyard.readiness.timeout_seconds: 10
```

--------------------------------

### POST /api/v1/environment/${app_uuid}/snapshot-load

Source: https://docs.shipyard.build/api

Loads a specific snapshot onto an environment, allowing you to restore the environment to a previous state. Supports loading from a different source environment or the target environment itself. The operation queues a background process to handle the snapshot restoration.

```APIDOC
## POST /api/v1/environment/${app_uuid}/snapshot-load

### Description
Loads a specific snapshot onto an environment, allowing you to restore the environment to a previous state. Supports loading from a different source environment or the target environment itself. The operation queues a background process to handle the snapshot restoration.

### Method
POST

### Endpoint
https://shipyard.build/api/v1/environment/${app_uuid}/snapshot-load

### Parameters
#### Path Parameters
- **app_uuid** (string) - Required - UUID of the target environment

#### Request Body
- **data.attributes.sequence_number** (integer) - Required - Sequence number of desired snapshot to use
- **data.attributes.source_application_id** (string) - Optional - UUID of source environment, if different from target environment
- **data.type** (string) - Required - Must be "snapshot-load"

### Request Example
```json
{
  "data": {
    "attributes": {
      "sequence_number": 778,
      "source_application_id": "000-0fsdf-ljsdfk"
    },
    "type": "snapshot-load"
  }
}
```

### Response
#### Success Response (204)
- Snapshot load queued

#### Error Responses
- **400** - Invalid input
- **404** - Environment not found

#### Response Example
```
204 No Content
```
```

--------------------------------

### AWS ECR Read-Only IAM Policy

Source: https://docs.shipyard.build/private-docker-registries

This JSON policy grants read-only access to AWS Elastic Container Registry (ECR) for a Shipyard user. It includes permissions for getting authorization tokens, checking layer availability, downloading layer URLs, and describing repositories and images. Ensure the AWS user has these IAM permissions.

```json
{
    "Version": "2012-10-17",
    "Statement": [
        {
            "Effect": "Allow",
            "Action": [
                "ecr:GetAuthorizationToken",
                "ecr:BatchCheckLayerAvailability",
                "ecr:GetDownloadUrlForLayer",
                "ecr:GetRepositoryPolicy",
                "ecr:DescribeRepositories",
                "ecr:ListImages",
                "ecr:DescribeImages",
                "ecr:BatchGetImage",
                "ecr:GetLifecyclePolicy",
                "ecr:GetLifecyclePolicyPreview",
                "ecr:ListTagsForResource",
                "ecr:DescribeImageScanFindings"
            ],
            "Resource": "*"
        }
    ]
}
```

--------------------------------

### Run E2E Tests on Ephemeral Environment

Source: https://docs.shipyard.build/circle-ci

Complete CircleCI workflow demonstrating E2E testing on ephemeral environments. Checks out code, fetches Shipyard environment variables using the orb command which sets SHIPYARD_ENVIRONMENT_URL, SHIPYARD_BYPASS_TOKEN, and SHIPYARD_ENVIRONMENT_ID. Configurable parameters include api-token, timeout-minutes, exit-if-not-pull-request, and app-name.

```YAML
version: '2.1'
orbs:
  shipyard: shipyard/shipyard@1
jobs:
  ephemeral-e2e-tests:
    executor:
      name: cypress/browsers-chrome77
    steps:
      - checkout
      - shipyard/fetch-shipyard-env
      - run:
          command: |
            export CYPRESS_BASE_URL=${SHIPYARD_ENVIRONMENT_URL}
            export CYPRESS_BYPASS_TOKEN=${SHIPYARD_BYPASS_TOKEN}
            npm run test
          name: Run the e2e tests on the ephemeral environment
workflows:
  use-my-orb:
    jobs:
      - ephemeral-e2e-tests
```

--------------------------------

### Load Snapshot onto Environment (cURL)

Source: https://docs.shipyard.build/api

Loads a snapshot onto an environment. Requires the application UUID, API token, and a JSON payload specifying the snapshot sequence number and optionally a source application ID. Successful requests return a 204 status code.

```curl
curl -H "x-api-token: ${YOUR_API_TOKEN}" -H "Content-Type: application/json" -XPOST https://shipyard.build/api/v1/environment/${app_uuid}/snapshot-load --data-raw '{  
  "data": {  
    "attributes": {  
      "sequence_number": 778,  
      "source_application_id": "000-0fsdf-ljsdfk"  
    },  
    "type": "snapshot-load"  
  }  
}'
```

--------------------------------

### Shipyard Liveness Probe Configuration for Docker Compose

Source: https://docs.shipyard.build/docker-compose

Configures liveness probes for a service to determine its health. Supports defining the command to execute, failure threshold, HTTP headers and path for probes, initial delay, probe period, and timeout. Commands should be JSON arrays.

```yaml
shipyard.liveness.exec.command: '["bash", "some-script.sh"]'
```

```yaml
shipyard.liveness.failure_threshold: 1
```

```yaml
shipyard.liveness.http.headers: '{"x-reason": "health"}'
```

```yaml
shipyard.liveness.http.path: /healthz
```

```yaml
shipyard.liveness.initial_delay: 10
```

```yaml
shipyard.liveness.period: 15
```

```yaml
shipyard.liveness.timeout_seconds: 10
```

--------------------------------

### POST /api/v1/environment/${app_uuid}/restart

Source: https://docs.shipyard.build/api

Restarts a retired environment, bringing it back into active service. This operation can only be performed on environments that have been previously retired and are currently inactive.

```APIDOC
## POST /api/v1/environment/${app_uuid}/restart

### Description
Restarts a retired environment, bringing it back into active service. This operation can only be performed on environments that have been previously retired and are currently inactive.

### Method
POST

### Endpoint
https://shipyard.build/api/v1/environment/${app_uuid}/restart

### Parameters
#### Path Parameters
- **app_uuid** (string) - Required - UUID of the environment to restart

### Request Example
```
curl -H 'x-api-token: ${YOUR_API_TOKEN}' -X POST "https://shipyard.build/api/v1/environment/${app_uuid}/restart"
```

### Response
#### Success Response (204)
- Environment restarted successfully

#### Error Responses
- **400** - Environment is not retired
- **404** - Environment not found

#### Response Example
```
204 No Content
```
```

--------------------------------

### POST /api/v1/environment/{app_uuid}/stop

Source: https://docs.shipyard.build/api

Stops a running environment. Use this to halt an active environment deployment.

```APIDOC
## POST /api/v1/environment/{app_uuid}/stop

### Description
Stops the specified environment. You can only stop a running environment.

### Method
POST

### Endpoint
/api/v1/environment/{app_uuid}/stop

### Parameters
#### Path Parameters
- **app_uuid** (string) - Required - The environment/application UUID

### Request Example
```
curl -H 'x-api-token: ${YOUR_API_TOKEN}' -X POST "https://shipyard.build/api/v1/environment/${app_uuid}/stop"
```

### Response
#### Success Response (204)
No content.

#### Error Response (400)
- **errors** (array) - List of errors
  - **status** (integer) - HTTP status code
  - **title** (string) - Error title

#### Error Response (404)
- **errors** (array) - List of errors
  - **status** (integer) - HTTP status code
  - **title** (string) - Error title
```

--------------------------------

### POST /api/v1/environment/${app_uuid}/rebuild

Source: https://docs.shipyard.build/api

Rebuilds an active environment from its current configuration and branch settings. This operation initiates a fresh build process and can only be performed on currently active environments.

```APIDOC
## POST /api/v1/environment/${app_uuid}/rebuild

### Description
Rebuilds an active environment from its current configuration and branch settings. This operation initiates a fresh build process and can only be performed on currently active environments.

### Method
POST

### Endpoint
https://shipyard.build/api/v1/environment/${app_uuid}/rebuild

### Parameters
#### Path Parameters
- **app_uuid** (string) - Required - UUID of the environment to rebuild

### Request Example
```
curl -H 'x-api-token: ${YOUR_API_TOKEN}' -X POST "https://shipyard.build/api/v1/environment/${app_uuid}/rebuild"
```

### Response
#### Success Response (204)
- Environment rebuilt successfully

#### Error Responses
- **400** - Environment is not active
- **404** - Environment not found

#### Response Example
```
204 No Content
```
```

--------------------------------

### POST /api/v1/environment/${app_uuid}

Source: https://docs.shipyard.build/api

Updates an environment's configuration, specifically for changing repository branches. All existing repositories in the environment must be specified in the update, even if only one branch is being changed. This operation triggers a new build with the updated branch configuration.

```APIDOC
## POST /api/v1/environment/${app_uuid}

### Description
Updates an environment's configuration, specifically for changing repository branches. All existing repositories in the environment must be specified in the update, even if only one branch is being changed. This operation triggers a new build with the updated branch configuration.

### Method
POST

### Endpoint
https://shipyard.build/api/v1/environment/${app_uuid}

### Parameters
#### Path Parameters
- **app_uuid** (string) - Required - UUID of the environment to update

#### Request Body
- **data.attributes.projects** (array) - Required - Repo-branch updates containing:
  - **repo_name** (string) - Name of the repository
  - **branch** (string) - Branch to set for the repository
- **data.id** (string) - Required - Environment UUID
- **data.type** (string) - Required - Must be "application"

### Request Example
```json
{
  "data": {
    "attributes": {
      "projects": [
        {
          "branch": "new-volume",
          "repo_name": "react-flask-starter"
        },
        {
          "branch": "master",
          "repo_name": "react-starter"
        }
      ]
    },
    "id": "${app_uuid}",
    "type": "application"
  }
}
```

### Response
#### Success Response (200)
- Success, new build queued

#### Error Responses
- **400** - Invalid input
- **404** - Environment not found

#### Response Example
```
200 OK
```
```

--------------------------------

### Restart Environment (cURL)

Source: https://docs.shipyard.build/api

Restarts a retired environment. Requires the application UUID and an API token. Only retired environments can be restarted. Successful requests return a 204 status code.

```curl
curl -H 'x-api-token: ${YOUR_API_TOKEN}' -X POST "https://shipyard.build/api/v1/environment/${app_uuid}/restart"
```

--------------------------------

### POST /api/v1/environment/${app_uuid}/revive

Source: https://docs.shipyard.build/api

Revives a deleted environment, restoring it to a previous state. This operation can only be performed on environments that have been previously deleted and are available for restoration.

```APIDOC
## POST /api/v1/environment/${app_uuid}/revive

### Description
Revives a deleted environment, restoring it to a previous state. This operation can only be performed on environments that have been previously deleted and are available for restoration.

### Method
POST

### Endpoint
https://shipyard.build/api/v1/environment/${app_uuid}/revive

### Parameters
#### Path Parameters
- **app_uuid** (string) - Required - UUID of the environment to revive

### Request Example
```
curl -H 'x-api-token: ${YOUR_API_TOKEN}' -X POST "https://shipyard.build/api/v1/environment/${app_uuid}/revive"
```

### Response
#### Success Response (204)
- Environment revived successfully

#### Error Responses
- **400** - Environment is already active
- **404** - Environment not found

#### Response Example
```
204 No Content
```
```

--------------------------------

### Empty Response for Listing Environments (JSON)

Source: https://docs.shipyard.build/api

This JSON represents an empty response when no environments match the query criteria. It indicates that the 'data' array is empty but provides pagination links.

```json
{
  "data": [],
  "links": {
    "first": "/api/v1/environment?page=1",
    "last": "/api/v1/environment?page=1",
    "next": "",
    "prev": ""
  }
}
```

--------------------------------

### Define Kubernetes Pre-Stop Exec Command

Source: https://docs.shipyard.build/docker-compose

Specify a command to be executed on the Kubernetes pre-stop event for the service. The command must be provided as a JSON string representing an array of strings.

```json
shipyard.lifecycle.preStop.exec.command: "[\"sh\", \"/srv/prestop.sh\"]"
```

--------------------------------

### Stop running environment via Shipyard API

Source: https://docs.shipyard.build/api

Stops a currently running environment specified by its UUID. Can only be executed on environments that are currently running. Requires API token authentication. Returns success or error status codes.

```bash
curl -H 'x-api-token: ${YOUR_API_TOKEN}' -X POST "https://shipyard.build/api/v1/environment/${app_uuid}/stop"
```

--------------------------------

### Configure CircleCI Version and Shipyard Orb

Source: https://docs.shipyard.build/circle-ci

Minimal CircleCI configuration to enable Shipyard orb integration. Declares CircleCI version 2.1 and imports the Shipyard orb from the CircleCI registry. This configuration is required before using any Shipyard orb commands in workflows.

```YAML
version: 2.1

orbs:
  shipyard: shipyard/shipyard@3.6.1
```

--------------------------------

### Set Deployment Disk Size

Source: https://docs.shipyard.build/docker-compose

Allocate a persistent disk of a specified size to be used as a volume for the service. The size is specified with a unit (e.g., Gi).

```yaml
shipyard.deploy.disk.size: 10Gi
```

--------------------------------

### Revive Environment (cURL)

Source: https://docs.shipyard.build/api

Revives a deleted environment. Requires the application UUID and an API token. Only deleted environments can be revived. A successful revival returns a 204 status code.

```curl
curl -H 'x-api-token: ${YOUR_API_TOKEN}' -X POST "https://shipyard.build/api/v1/environment/${app_uuid}/revive"
```

--------------------------------

### Configure Kubernetes Security Context

Source: https://docs.shipyard.build/docker-compose

Provide a direct definition for the Kubernetes security context of the pod. This is supplied as a JSON string.

```json
shipyard.securityContext: '{"capabilities": {"add": ["SYS_ADMIN"]}}'
```

--------------------------------

### Rebuild Environment (cURL)

Source: https://docs.shipyard.build/api

Rebuilds a non-deleted environment. Requires the application UUID and an API token. Non-deleted environments can be rebuilt. A successful rebuild returns a 204 status code.

```curl
curl -H 'x-api-token: ${YOUR_API_TOKEN}' -X POST "https://shipyard.build/api/v1/environment/${app_uuid}/rebuild"
```

--------------------------------

### Change Environment Branches (cURL)

Source: https://docs.shipyard.build/api

Updates the branches for repositories within an environment. Requires the application UUID, API token, and a JSON payload listing project (repo-branch) combinations. All existing repos must be declared, even if unchanged. A successful update queues a new build and returns a 200 status code.

```curl
curl -H "x-api-token: ${YOUR_API_TOKEN}" -H "Content-Type: application/json" -XPATCH https://shipyard.build/api/v1/environment/${app_uuid} --data-raw '{  
  "data": {  
    "attributes": {  
      "projects": [  
        {  
          "branch": "new-volume",  
          "repo_name": "react-flask-starter"  
        },  
        {  
          "branch": "master",  
          "repo_name": "react-starter"  
        }  
      ]  
    },  
    "id": "${app_uuid}",  
    "type": "application"  
  }  
}'
```

--------------------------------

### Shipyard Job Execution Configuration for Docker Compose

Source: https://docs.shipyard.build/docker-compose

Configures a service to run as a Kubernetes Job. The `shipyard.job: true` label enables this functionality. Additional labels like `shipyard.job.schedule` and other Kubernetes job-specific labels can be used to customize job behavior.

```yaml
shipyard.job: true
```

```yaml
shipyard.job.schedule: '*/2 * * * *'
```

```yaml
cronjob:
    labels:
      shipyard.job: true
      shipyard.job.schedule: '*/2 * * * *'
      shipyard.job.restartPolicy: Never
      shipyard.job.backoffLimit: 2
      shipyard.job.activeDeadlineSeconds: 60
      shipyard.job.successfulJobsHistoryLimit: 5
      shipyard.job.failedJobsHistoryLimit: 3
      shipyard.job.concurrencyPolicy: Forbid
```

--------------------------------

### Shipyard Routing Configuration for Docker Compose

Source: https://docs.shipyard.build/docker-compose

Configures how HTTP requests are routed to services. Supports defining a base route prefix, named routes, OAuth redirect URIs, and request path rewriting. Dynamic path parameters like `{{ path_of_route }}` and `{{ name }}` are supported.

```yaml
shipyard.route: '/'
```

```yaml
shipyard.route.api: '/api'
```

```yaml
shipyard.route.oauth.redirect-uri: /callback/oauth/github
```

```yaml
shipyard.route.oauth.google.redirect-uri: /callback/oauth/google
```

```yaml
shipyard.route.rewrite: true
```

--------------------------------

### Define Named Volume in Docker Compose

Source: https://docs.shipyard.build/volume-management

This YAML configuration sets up a PostgreSQL service using a named volume for data persistence. It depends on Docker Compose and defines a service with environment variables, volume mapping, and ports. The output is a running Postgres container with persistent data storage.

```yaml
version: '3.8'

services:
  postgres:
    image: postgres:latest
    environment:
      POSTGRES_DB: app
      POSTGRES_USER: obscure-user
      POSTGRES_PASSWORD: obscure-password
    volumes:
      # this example is using named volume
      - postgres-data:/var/lib/postgresql/data
    ports:
      - "5432:5432"
    restart: always

volumes:
  # this is how you create a named volume
  postgres-data:
```

--------------------------------

### Enable GCP CloudSQL Sidecar

Source: https://docs.shipyard.build/docker-compose

Enable or disable the inclusion of a GCP CloudSQL sidecar container with the service. This is a boolean flag.

```yaml
shipyard.cloudsql.sidecar: true
```

--------------------------------

### Enable Pod Anti-Affinity

Source: https://docs.shipyard.build/docker-compose

Enable pod anti-affinity to encourage replicas within the same deployment to schedule on different nodes. This is a boolean flag.

```yaml
shipyard.remote.podAntiAffinity: true
```

--------------------------------

### POST /api/v1/environment/${app_uuid}/cancel

Source: https://docs.shipyard.build/api

Cancels the latest build operation for an environment. This operation can only be performed while a build is currently in progress (in-flight) for an active environment.

```APIDOC
## POST /api/v1/environment/${app_uuid}/cancel

### Description
Cancels the latest build operation for an environment. This operation can only be performed while a build is currently in progress (in-flight) for an active environment.

### Method
POST

### Endpoint
https://shipyard.build/api/v1/environment/${app_uuid}/cancel

### Parameters
#### Path Parameters
- **app_uuid** (string) - Required - UUID of the environment whose build to cancel

### Request Example
```
curl -H 'x-api-token: ${YOUR_API_TOKEN}' -X POST "https://shipyard.build/api/v1/environment/${app_uuid}/cancel"
```

### Response
#### Success Response (204)
- Build cancelled successfully

#### Error Responses
- **400** - Environment is not active or no builds in-flight
- **404** - Environment not found

#### Response Example
```
204 No Content
```
```

--------------------------------

### GCP Artifact Registry Roles for Service Account

Source: https://docs.shipyard.build/private-docker-registries

Specifies the required IAM roles for a GCP service account to interact with Artifact Registry for Shipyard integration. These roles include read, write, and create-on-push permissions. Assign these roles to the service account on the relevant Artifact Registry.

```plaintext
roles/artifactregistry.reader
roles/artifactregistry.writer
roles/artifactregistry.createOnPushWriter
```