Skip to main content

Shipyard API

API Token​

Organization Settings

To access your Organization Settings page, click on Settings at the top of your main dashboard:

Access Shipyard org settings page

If you have the Shipyard API enabled for your organization, you can grab its token by going to the Org Settings page 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