Skip to main content

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):

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

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