Shipyard REST API reference overview

The Shipyard REST API lets you manage projects, trigger and inspect builds, fetch deployments, and interact with the CI/CD pipeline programmatically. All API endpoints are mounted under the /api prefix, with the exception of the /health route.

Base URL

http://localhost:8080

Replace localhost:8080 with your server’s address when deploying to a VPS or using a tunnel. All REST endpoints follow the pattern http://<your-server>/api/<resource>.

Authentication

Most endpoints require a JSON Web Token (JWT) issued after completing the GitHub OAuth flow. Pass the token as a Bearer credential in the Authorization header:

Authorization: Bearer <token>

The token is validated on every request by the isAuth middleware. If the header is missing, malformed, or the token is expired, the server responds with 401.

Two endpoint groups do not require a JWT: the /api/auth routes (which are part of the OAuth flow itself) and the /health and /api utility routes. The webhook endpoint uses HMAC-SHA256 signature verification instead of JWT — see the Webhook page for details.

Endpoints

All endpoints return JSON. The tables below list every route, whether it requires authentication, and a short description.

Auth

Method	Endpoint	Auth	Description
GET	`/api/auth/github`	No	Redirects the browser to GitHub’s OAuth authorization page
GET	`/api/auth/github/callback`	No	Handles the OAuth callback, exchanges the code for a token, and redirects to the frontend with a JWT

Repos

Method	Endpoint	Auth	Description
GET	`/api/repo/orgs`	JWT	Fetches the authenticated user’s GitHub organizations plus their personal account
GET	`/api/repo/repos`	JWT	Lists repositories for a given organization or personal account

Projects

Method	Endpoint	Auth	Description
POST	`/api/project`	JWT	Creates a project and registers a GitHub webhook on the target repo
GET	`/api/project/projects`	JWT	Returns all projects belonging to the authenticated user, including their builds and deployments
PUT	`/api/project/projects/:projectId`	JWT	Updates project settings (branch, build command, install command, etc.)
DELETE	`/api/project/projects/:projectId`	JWT	Deletes a project and removes the associated GitHub webhook
DELETE	`/api/project/secret/:secretId`	JWT	Deletes a single encrypted secret by ID

Builds

Method	Endpoint	Auth	Description
POST	`/api/build/rebuild/:buildId`	JWT	Re-runs the build from the commit associated with an existing build record
GET	`/api/build/:buildId`	JWT	Fetches a single build record including its logs and status

Deployments

Method	Endpoint	Auth	Description
GET	`/api/deploy/deployments/:deploymentId`	JWT	Fetches a single deployment record
PUT	`/api/deploy/rollback`	JWT	Rolls back to a previous deployment by re-running its build

Webhook

Method	Endpoint	Auth	Description
POST	`/api/webhook`	HMAC-SHA256	Receives GitHub push events and triggers a build

Health

Method	Endpoint	Auth	Description
GET	`/health`	No	Returns `{ "message": "OK" }` — use for uptime monitoring
GET	`/api`	No	Returns a welcome message confirming the API is reachable

Error responses

All error responses follow a consistent JSON shape:

{
  "message": "A human-readable error description",
  "data": [...]
}

The data field is optional and typically contains validation errors from express-validator when a request body fails validation. Common HTTP status codes:

Code	Meaning
400	Bad request — missing or invalid fields
401	Unauthorized — JWT is missing, expired, or invalid
500	Internal server error — unexpected failure

Explore by resource

Auth

GitHub OAuth flow and JWT issuance

Repos

Browse GitHub organizations and repositories

Projects

Create, update, and delete connected projects

Builds

Trigger rebuilds and inspect build records

Deployments

Fetch deployments and roll back to earlier versions

Webhook

GitHub push event signature verification and build triggering

​Base URL

​Authentication

​Endpoints

​Auth

​Repos

​Projects

​Builds

​Deployments

​Webhook

​Health

​Error responses

​Explore by resource

Auth

Repos

Projects

Builds

Deployments

Webhook

Base URL

Authentication

Endpoints

Auth

Repos

Projects

Builds

Deployments

Webhook

Health

Error responses

Explore by resource