Skip to main content
A deployment record is created automatically when a build passes and the project has no sensitive environment variables that would prevent static serving. Each deployment is linked to the build that produced it and carries a status of either live or rolled_back. These two endpoints let you inspect a deployment’s current state and roll back to an earlier one when needed.

​
GET /api/deploy/deployments/:deploymentId

Fetches a single deployment record by ID. The server verifies that the deployment’s build belongs to a project owned by the authenticated user before responding. Requires JWT.

​
Path parameters

​
deploymentId
number
required
Numeric ID of the deployment to fetch. Deployment IDs appear in the deployment field nested inside each build in the GET /api/project/projects response.

​
Curl example

curl https://your-server/api/deploy/deployments/9 \
  -H "Authorization: Bearer <your-jwt>"

​
Response

{
  "message": "Deployment fetched",
  "deployment": {
    "id": 9,
    "status": "live",
    "buildId": 14,
    "createdAt": "2026-04-11T12:02:35.000Z",
    "build": {
      "id": 14,
      "status": "passed",
      "commit": "fix: update hero copy",
      "branch": "main",
      "commitAuthor": "Jane Doe",
      "commitHash": "a1b2c3d4e5f6",
      "exitCode": 0,
      "projectId": 7,
      "startedAt": "2026-04-11T12:00:05.000Z",
      "finishedAt": "2026-04-11T12:02:30.000Z"
    }
  }
}

​
Response fields

​
deployment
object
The deployment record, with the associated build nested inside.
​
deployment.id
number
Unique deployment ID.
​
deployment.status
string
Current deployment status. One of live or rolled_back.
ValueMeaning
liveThis deployment is currently serving traffic
rolled_backThis deployment was superseded by a rollback operation
​
deployment.buildId
number
ID of the build that produced this deployment.
​
deployment.createdAt
string
ISO 8601 timestamp of when the deployment record was created.
​
deployment.build
object
The build record linked to this deployment. See GET /api/build/:buildId for a full description of build fields.

​
Error responses

StatusCondition
400deploymentId or user ID is missing
401JWT is missing or invalid
403The deployment’s project does not belong to the authenticated user
404No deployment found with the given ID

​
PUT /api/deploy/rollback

Rolls back to a previous deployment by re-running the full build pipeline from that deployment’s original commit hash. The current live deployment is marked as rolled_back, a new build record is created and queued, and the pipeline runs asynchronously in the background. Requires JWT.
Rollback triggers a full rebuild — Shipyard clones the repository at the previous commit hash, runs the install and build commands inside a Docker container, and deploys the output if the build passes. It is not a file restore or a swap of static assets; the entire CI pipeline executes again.

​
Query parameters

​
latest
number
required
ID of the current live deployment to mark as rolled back.
​
prev
number
required
ID of the previous deployment to roll back to. Shipyard reads the commit hash from this deployment’s associated build and uses it to create the new build.

​
Curl example

curl -X PUT "https://your-server/api/deploy/rollback?latest=42&prev=38" \
  -H "Authorization: Bearer <your-jwt>"

​
Response

The server responds immediately with the new queued build. The rebuild pipeline runs asynchronously after the response is sent. 
{
  "message": "Deployment rollback and re-queued",
  "build": {
    "id": 51,
    "status": "queued",
    "commit": "feat: add dashboard charts",
    "branch": "main",
    "commitAuthor": "Jane Doe",
    "commitHash": "b9f3e1a2c4d5",
    "exitCode": null,
    "projectId": 7,
    "startedAt": "2026-04-11T15:00:00.000Z",
    "finishedAt": null
  }
}

​
Response fields

​
build
object
The newly created build record that will produce the rolled-back deployment.
​
build.id
number
ID of the new build. Use this to monitor rollback progress via buildStatusUpdate Socket.io events.
​
build.status
string
Always queued immediately after the rollback is initiated.
​
build.commitHash
string
The commit hash from the previous deployment’s build — the exact code that will be checked out and built.

​
Error responses

StatusCondition
400latest or prev query parameters are missing
401JWT is missing or invalid
403The previous deployment’s project does not belong to the authenticated user
404No deployment found for the given prev ID
500Failed to insert the new build record

Build docs developers (and LLMs) love

Get started for freeTalk to us