Skip to main content

Shipyard API

API Token​

If you have the Shipyard API enabled for your organization, you can grab its token by going to the Org Settings page from your main dashboard and clicking the copy button:

Get Shipyard API key from Org Settings page

Make sure to 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):

NameTypeDescriptionDefault
namestringFilter by environment name
org_namestringFilter by organization name
repo_namestringFilter by repository name
branchstringFilter by branch name
pull_request_numberstringFilter by PR number
deletedbooleanFilter by deletedfalse
pageintegerPage number being requested1
page_sizeintegerNumber of environments per page20
  • 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:
{
  "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": ""
  }
}

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 CodeDescription
    200Success
    404Environment not found

Get an environment's build history by UUID​

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

  • Arguments (query strings):

NameTypeDescriptionDefault
successfully_builtbooleanOnly return environments which were deployed successfullyfalse
pageintegerPage number being requested1
page_sizeintegerNumber of environments per page20
  • Example cURL:
curl -H 'x-api-token: ${YOUR_API_TOKEN}' "https://shipyard.build/api/v1/environment/${app_uuid}/build-history"

  • Responses:

    Status CodeDescription
    200Success
    404Environment not found

  • Example response:

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

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 CodeDescription
    204Environment stopped successfully
    400Environment is not running
    404Environment 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 CodeDescription
    204Environment restarted successfully
    400Environment is not retired
    404Environment 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 CodeDescription
    204Environment rebuilt successfully
    400Environment is not active
    404Environment 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 CodeDescription
    204Environment revived successfully
    400Environment is already active
    404Environment 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 CodeDescription
    204Build cancelled successfully
    400Environment is not active or no builds in-flight
    404Environment not found

Load a snapshot onto an environment​

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

  • Arguments (json):

NameTypeDescriptionDefault
sequence_numberintegerSequence number of desired snapshot to use
source_application_idstring (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,
      "source_application_id": "000-0fsdf-ljsdfk"
    },
    "type": "snapshot-load"
  }
}'

  • Responses:

    Status CodeDescription
    204Snapshot load queued
    400Invalid input
    404Environment 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):
NameTypeDescriptionDefault
projectsarrayRepo-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 CodeDescription
    200Success, new build queued
    400Invalid input
    404Environment not found