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.

Choosing an organization

If your token is a user API token and the resource you are targeting lives in an organization other than your default org, append the org query parameter to the URL (e.g. ?org=YourOrgName). Organization API tokens are already scoped to a single org, so the org parameter is not needed for them.

Endpoints

Deploy a detached environment

Create a brand-new, independent ("detached") environment by cloning an existing application build. The new environment copies the source environment's configuration (secrets, build args, env vars, OAuth users) and then runs on its own, with no link back to the source.

Feature must be enabled

Detached environments must be enabled for your organization. If the feature is off you will receive a 403, contact Shipyard to enable it.

URL: POST https://shipyard.build/api/v1/application-build/${app_build_uuid}/detached-app-build

${app_build_uuid} is the UUID of the source application build to clone from. With a user API token, remember to add ?org=YourOrgName if the build is not in your default org.
Arguments (json, all optional):

Name	Type	Description	Default
display_name	string	Name for the new detached environment
project_branch_overrides	object	Map of `repo_name` to `branch` to override the branch for specific repos	`{}`
build_on_commit	string or object	Whether the detached env rebuilds on new commits. A string (`"always"`, `"inherit"`, or `"never"`) applies to all repos; an object maps `repo_name` to setting per-repo	`"never"`

Example cURL:

curl -H "x-api-token: ${YOUR_API_TOKEN}" -H "Content-Type: application/json" \
  -X POST "https://shipyard.build/api/v1/application-build/${app_build_uuid}/detached-app-build" \
  --data-raw '{
    "display_name": "my-detached-env",
    "project_branch_overrides": { "flask-backend": "my-feature-branch" },
    "build_on_commit": "never"
  }'

Example response:

{
  "data": {
    "message": "Detached environment 'my-detached-env' deployed successfully",
    "application_uuid": "aaaaaaaa-bbbb-cccc-dddd-eeeeeeeeeeee",
    "application_build_uuid": "ffffffff-gggg-hhhh-iiii-jjjjjjjjjjjj",
    "display_name": "my-detached-env"
  }
}

Responses:

Status Code	Description
201	Detached environment created and deploying
400	Invalid input (e.g. unexpected parameter, or invalid `build_on_commit` value)
401	Invalid token
403	Detached environments are not enabled for this org, or the build belongs to another org
404	Source application build not found

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

Status Code	Description
200	Success
404	Environment 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):

Name	Type	Description	Default
successfully_built	boolean	Only return environments which were deployed successfully	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/${app_uuid}/build-history"

Responses:

Status Code Description
200 Success
404 Environment not found
Example response:

Status Code	Description
200	Success
404	Environment not found

200 - Data
200 - Empty
401 - Invalid Token
404 - Invalid UUID

JSON
Metadata

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

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": [],
  "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=1",
    "next": "",
    "prev": ""
  },
  "type": "application"
}

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

JSON
Metadata

{
  "errors": [
    {
      "status": 404,
      "title": "Application not found!"
    }
  ]
}

HTTP/2 404
date: Wed, 20 Apr 2022 16:16:07 GMT
content-type: application/json
content-length: 87
strict-transport-security: max-age=15724800; includeSubDomains

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

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

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

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

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

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
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,
      "source_application_id": "000-0fsdf-ljsdfk"
    },
    "type": "snapshot-load"
  }
}'

Responses:

Status Code Description
204 Snapshot load queued
400 Invalid input
404 Environment not found

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

Status Code	Description
200	Success, new build queued
400	Invalid input
404	Environment not found

List an environment's env vars

URL: GET https://shipyard.build/api/v1/environment/${app_uuid}/env-vars
Example cURL:

curl -H 'x-api-token: ${YOUR_API_TOKEN}' "https://shipyard.build/api/v1/environment/${app_uuid}/env-vars"

Example response:

200 - Data
401 - Invalid Token

{
  "data": [
    {
      "type": "env-var",
      "id": "aaaaaaaa-bbbb-cccc-dddd-eeeeeeeeeeee",
      "attributes": {
        "name": "DATABASE_URL",
        "value": "p*****************5432/mydb",
        "hidden": true,
        "services": [],
        "created_at": "2026-04-15T12:00:00",
        "updated_at": "2026-04-15T12:00:00"
      }
    },
    {
      "type": "env-var",
      "id": "ffffffff-gggg-hhhh-iiii-jjjjjjjjjjjj",
      "attributes": {
        "name": "DEBUG",
        "value": "true",
        "hidden": false,
        "services": ["web"],
        "created_at": "2026-04-15T12:00:00",
        "updated_at": "2026-04-15T12:00:00"
      }
    }
  ],
  "included": {
    "inherited": []
  }
}

{
  "errors": [
    {
      "status": 401,
      "title": "Invalid token"
    }
  ]
}

Responses:

Status Code Description
200 Success
401 Invalid token
404 Environment not found

Status Code	Description
200	Success
401	Invalid token
404	Environment not found

Add or update env vars

URL: PUT https://shipyard.build/api/v1/environment/${app_uuid}/env-vars

note

This endpoint uses upsert semantics: if an env var with the same name already exists, its value is updated. Otherwise, a new env var is created. If duplicate names are included in the same request, the last value wins.

Arguments (json):

Name	Type	Description	Default
env_vars	array	List of env var objects to create or update (required)
env_vars[].name	string	Name of the environment variable (required)
env_vars[].value	string	Value of the environment variable (required)
env_vars[].hidden	boolean	Whether the value should be masked in responses	true
env_vars[].services	array	List of service names to scope this variable to	null (all services)

Example cURL:

curl -H "x-api-token: ${YOUR_API_TOKEN}" -H "Content-Type: application/json" -X PUT "https://shipyard.build/api/v1/environment/${app_uuid}/env-vars" --data-raw '{
  "env_vars": [
    {
      "name": "DATABASE_URL",
      "value": "postgres://user:pass@host:5432/mydb"
    },
    {
      "name": "DEBUG",
      "value": "true",
      "hidden": false,
      "services": ["web"]
    }
  ]
}'

Example response:

200 - Success
207 - Partial Failure

{
  "data": [
    {
      "type": "env-var",
      "id": "aaaaaaaa-bbbb-cccc-dddd-eeeeeeeeeeee",
      "attributes": {
        "name": "DATABASE_URL",
        "value": "p*****************5432/mydb",
        "hidden": true,
        "services": [],
        "created_at": "2026-04-15T12:00:00",
        "updated_at": "2026-04-15T12:00:00"
      }
    },
    {
      "type": "env-var",
      "id": "ffffffff-gggg-hhhh-iiii-jjjjjjjjjjjj",
      "attributes": {
        "name": "DEBUG",
        "value": "true",
        "hidden": false,
        "services": ["web"],
        "created_at": "2026-04-15T12:00:00",
        "updated_at": "2026-04-15T12:00:00"
      }
    }
  ]
}

{
  "data": [
    {
      "type": "env-var",
      "id": "aaaaaaaa-bbbb-cccc-dddd-eeeeeeeeeeee",
      "attributes": {
        "name": "VALID_VAR",
        "value": "some_value",
        "hidden": true,
        "services": [],
        "created_at": "2026-04-15T12:00:00",
        "updated_at": "2026-04-15T12:00:00"
      }
    }
  ],
  "errors": [
    {
      "name": null,
      "error": "name and value are required"
    }
  ]
}

Responses:

Status Code	Description
200	All env vars created/updated successfully
207	Partial success, some env vars failed (see `errors` in response)
400	Missing or invalid `env_vars` field
401	Invalid token
404	Environment not found

Delete an env var

URL: DELETE https://shipyard.build/api/v1/environment/${app_uuid}/env-vars/${var_name}
Example cURL:

curl -H 'x-api-token: ${YOUR_API_TOKEN}' -X DELETE "https://shipyard.build/api/v1/environment/${app_uuid}/env-vars/DATABASE_URL"

Responses:

Status Code Description
204 Env var deleted successfully
401 Invalid token
404 Environment or env var not found

Status Code	Description
204	Env var deleted successfully
401	Invalid token
404	Environment or env var not found

API Token​

Endpoints​

Deploy a detached environment​

List all active environments​

Get an environment by UUID​

Get an environment's build history by UUID​

Stop an environment​

Restart an environment​

Rebuild an environment​

Revive an environment​

Cancel an environment's latest build​

Load a snapshot onto an environment​

Change an environment's branches​

List an environment's env vars​

Add or update env vars​

Delete an env var​

API Token

Endpoints

Deploy a detached environment

List all active environments

Get an environment by UUID

Get an environment's build history by UUID

Stop an environment

Restart an environment

Rebuild an environment

Revive an environment

Cancel an environment's latest build

Load a snapshot onto an environment

Change an environment's branches

List an environment's env vars

Add or update env vars

Delete an env var