Skip to main content

API

Overview​

The API allows for programmatic access to a subset of Shipyard's features. This allows users to write scripts and programs to directly interact with the Shipyard platform instead of through the UI interface.

info

Shipyard's API is currently only available to customers on paid plans.

Please Note

  1. The API is subject to change. The API is tightly coupled with the front end of the application, which is subject to change between releases. While endpoints usually won’t change that much, if you write code to use the API, you might have to update it in the future.
  2. The API isn’t versioned. This means that functionality can change version to version, so don’t expect to stay on a particular version of Shipyard in order to use a β€œstable” API.

Authorization​

In order to interact with the API, an API key is required.

  1. Navigate to your user's Settings page

Settings page API keys

  1. On the right side of the page, enter a name in the API key name text field
  2. Click the Create API Key button

API keys add new key

  1. Copy the generated API key value - this is the only time the value will be available

API keys generated API key value

caution

Treat all API keys like passwords and do not commit them to code or share them with unauthorized parties

Access for an API key can be revoked by clicking the Delete button next to its name in the list.

Endpoints​

These are the currently available endpoints as well as example requests and responses. Note that the ID values would be substituted for the actual UUID values in a real-world request. The API key is the example one generated in the Authorization section above.

The response code snippets have been truncated for brevity.

List Organizations​

Request​

curl https://api.app.shipyardapp.com/orgs --header "X-Shipyard-API-Key: <api-key>"

Response​

{
"data_kind": "organizations",
"data": [
{
"id": "11111111-1111-1111-1111-111111111111",
"name": "example organization",
"created_at": "2019-08-22T21:53:30.095954Z",
...
}
]
}

List Organization Fleets​

Request​

curl https://api.app.shipyardapp.com/orgs/11111111-1111-1111-1111-111111111111/fleets --header "X-Shipyard-API-Key: <api-key>"

Response​

{
"data_kind": "fleets",
"data": [
{
"org_id": "11111111-1111-1111-1111-111111111111",
"id": "33333333-3333-3333-3333-333333333333",
"name": "confident_oyster",
"pallet_ids": [
"44444444-4444-4444-4444-444444444444"
],
"created_at": "2022-07-21T21:37:30.623386Z",
"vessel_dag": {
"vertices": [
"44444444-4444-4444-4444-444444444444"
],
"versions": [
1
],
"edges": []
},
...
}
]
}

Get Fleet​

Request​

curl https://api.app.shipyardapp.com/orgs/11111111-1111-1111-1111-111111111111/projects/22222222-2222-2222-2222-222222222222/fleets/33333333-3333-3333-3333-333333333333 --header "X-Shipyard-API-Key: <api key>"

Response​

The Fleet is returned in FAC YAML format.

name: example fleet
vessels:
first_vessel:
...

Upsert Fleet​

Request​

curl -X PUT https://api.app.shipyardapp.com/orgs/11111111-1111-1111-1111-111111111111/projects/22222222-2222-2222-2222-222222222222/fleets --data-binary @fleet.yaml -header "Content-type: application/yaml" --header "X-Shipyard-API-Key: <api-key>"

The contents of fleet.yaml would be in the required FAC format.

Response​

The Fleet is returned in FAC YAML format.

name: example fleet
vessels:
first_vessel:
...

List Fleet Runs​

Request​

curl https://api.app.shipyardapp.com/orgs/11111111-1111-1111-1111-111111111111/projects/22222222-2222-2222-2222-222222222222/fleets/33333333-3333-3333-3333-333333333333/runs --header "X-Shipyard-API-Key: <api-key>"

Response​

The Fleet Runs are returned in CSV format.

Fleet ID,Fleet Name,Fleet Version,...
fleet_id,example fleet,1,...

Below is a reference table for the Fleet Runs CSV.

ColumnDescription
Fleet IDThe UUID of the associated Fleet
Fleet NameThe name of the associated Fleet
Fleet VersionThe version number of the associated Fleet
Fleet Log IDThe UUID of the Fleet Run log
StatusThe status the Fleet Run completed in
Start TimeThe time the Fleet Run started
End TimeThe time the Fleet Run ended
DurationThe length of time the Fleet Run ran for
Billable RuntimeThe length of time the Fleet Run ran the customer will be billed for
Vessels CountThe number of Vessels in the associated Fleet
TriggerThe method the Fleet Run was started by

List Voyages​

Request​

This request returns all of the Voyages in the requested Organization.

curl https://api.app.shipyardapp.com/orgs/11111111-1111-1111-1111-111111111111/voyages --header "X-Shipyard-API-Key: <api-key>"

Response​

The Voyages are returned in CSV format.

Fleet ID,Fleet Name,Fleet Version,...
fleet_id,example fleet,1,...

Below is a reference table for the Fleet Runs CSV.

ColumnDescription
Fleet IDThe UUID of the Fleet
Fleet NameThe name of the Fleet
Fleet VersionThe version number of the Fleet
Fleet Log IDThe UUID of the Fleet log
Fleet Log TriggerThe method the Fleet was started by
Fleet Log StatusThe status the Fleet completed in
Vessel Log IDThe UUID of the Vessel log
Vessel StatusThe status the Vessel completed in
Vessel NameThe name of the Vessel
Vessel TriggerThe method the Vessel was started by
RetriesThe number of times the Vessel attempted to run
Exit CodeThe final exit code for the Vessel final run
Vessel Start TimeThe time the Vessel started
Vessel End TimeThe time the Vessel ended
DurationThe length of time the Fleet ran for
Billable RuntimeThe length of time the Fleet ran the customer will be billed for