Deployment endpoints — fetch and rollback

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

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

object

The deployment record, with the associated build nested inside.

number

Unique deployment ID.

string

Current deployment status. One of live or rolled_back.

Value	Meaning
`live`	This deployment is currently serving traffic
`rolled_back`	This deployment was superseded by a rollback operation

number

ID of the build that produced this deployment.

string

ISO 8601 timestamp of when the deployment record was created.

object

The build record linked to this deployment. See GET /api/build/:buildId for a full description of build fields.

Error responses

Status	Condition
`400`	`deploymentId` or user ID is missing
`401`	JWT is missing or invalid
`403`	The deployment’s project does not belong to the authenticated user
`404`	No 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

number

required

ID of the current live deployment to mark as rolled back.

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

object

The newly created build record that will produce the rolled-back deployment.

number

ID of the new build. Use this to monitor rollback progress via buildStatusUpdate Socket.io events.

string

Always queued immediately after the rollback is initiated.

string

The commit hash from the previous deployment’s build — the exact code that will be checked out and built.

Error responses

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

Overview

Endpoints

Deployment endpoints — fetch and rollback

GET /api/deploy/deployments/:deploymentId

Path parameters

Curl example

Response

Response fields

Error responses

PUT /api/deploy/rollback

Query parameters

Curl example

Response

Response fields

Error responses

​GET /api/deploy/deployments/:deploymentId

​Path parameters

​Curl example

​Response

​Response fields

​Error responses

​PUT /api/deploy/rollback

​Query parameters

​Curl example

​Response

​Response fields

​Error responses

GET /api/deploy/deployments/:deploymentId

Path parameters

Curl example

Response

Response fields

Error responses

PUT /api/deploy/rollback

Query parameters

Curl example

Response

Response fields

Error responses