Shipyard API

Authentication

• Get your Shipyard API token from the Organization Settings page
• Include the token as the x-api-token header with all requests

Endpoints

List all active environments

• URL: GET https://shipyard.build/api/v1/environment

• Arguments (query strings):

Name	Type	Description	Default
name	string	Filter by environment name
org_name	string	Filter by organization name
repo_name	string	Filter by repository name
branch	string	Filter by branch name
pull_request_number	string	Filter by PR number
deleted	boolean	Filter by deleted	false
page	integer	Page number being requested	1
page_size	integer	Number of environments per page	20

• Example cURL:

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

• Example response:

200 - Data

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": ""
  }
}

Metadata

HTTP/2 200
date: Wed, 20 Apr 2022 14:51:57 GMT
content-type: application/json
content-length: 6382
strict-transport-security: max-age=15724800; includeSubDomains

200 - Empty

JSON

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

Metadata

HTTP/2 200
date: Wed, 20 Apr 2022 16:21:42 GMT
content-type: application/json
content-length: 17
strict-transport-security: max-age=15724800; includeSubDomains

401 - Invalid Token

JSON

{
  "errors": [
    {
      "status": 401,
      "title": "Invalid token"
    }
  ]
}

Metadata

HTTP/2 401
date: Wed, 20 Apr 2022 16:16:07 GMT
content-type: application/json
content-length: 87
strict-transport-security: max-age=15724800; includeSubDomains

---

Get an environment by uuid

• URL: GET https://shipyard.build/api/v1/environment/${app_uuid}

• Example cURL:

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

• Responses:

  Status Code	Description
  200	Success
  404	Environment not found

Stop an environment

• URL: POST https://shipyard.build/api/v1/environment/${app_uuid}/stop

note

You can only stop a running environment.

• Example cURL:

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

• Responses:

  Status Code	Description
  204	Environment stopped successfully
  400	Environment is not running
  404	Environment not found

Restart an environment

• URL: POST https://shipyard.build/api/v1/environment/${app_uuid}/restart

note

You can only restart retired environments.

• Example cURL:

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

• Responses:

  Status Code	Description
  204	Environment restarted successfully
  400	Environment is not retired
  404	Environment not found

Rebuild an environment

• URL: POST https://shipyard.build/api/v1/environment/${app_uuid}/rebuild

note

You can only rebuild non-deleted environments.

• Example cURL:

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

• Responses:

  Status Code	Description
  204	Environment rebuilt successfully
  400	Environment is not active
  404	Environment not found

Revive an environment

• URL: POST https://shipyard.build/api/v1/environment/${app_uuid}/revive

note

You can only revive a deleted environments.

• Example cURL:

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

• Responses:

  Status Code	Description
  204	Environment revived successfully
  400	Environment is already active
  404	Environment not found

Cancel an environment's latest build

• URL: POST https://shipyard.build/api/v1/environment/${app_uuid}/cancel

note

You can only cancel an environment's latest build while it is being built.

• Example cURL:

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

• Responses:

  Status Code	Description
  204	Build cancelled successfully
  400	Environment is not active or no builds in-flight
  404	Environment not found

Load a snapshot onto an environment

• URL: POST https://shipyard.build/api/v1/environment/${app_uuid}/snapshot-load

note

Currently only loads a snapshot for the given environment. For snapshot loading between PR environments and/or a base environment, use the Data Dashboard.

• Arguments (json):

Name	Type	Description	Default
sequence_number	integer	Sequence number of desired snapshot to use
source_application_id	string (optional)	UUID of source environment, if different from target environment

• Example 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
    },
    "type": "snapshot-load"
  }
}'

• Responses:

  Status Code	Description
  204	Snapshot load queued
  400	Invalid input
  404	Environment not found

Change an environment's branches

• URL: POST https://shipyard.build/api/v1/environment/${app_uuid}

note

You must declare repo/branch combinations for each existing repo in the environment, even if only one is changed.

• Arguments (json):

Name	Type	Description	Default
projects	array	Repo-branch updates

• Example cURL:

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

• Responses:

  Status Code	Description
  200	Success, new build queued
  400	Invalid input
  404	Environment not found