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
- 200 - Empty
- 401 - Invalid Token
- JSON
- Metadata
{
"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": ""
}
}
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
- JSON
- Metadata
{
"data": [],
"links": {
"first": "/api/v1/environment?page=1",
"last": "/api/v1/environment?page=1",
"next": "",
"prev": ""
}
}
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
- JSON
- Metadata
{
"errors": [
{
"status": 401,
"title": "Invalid token"
}
]
}
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