/api prefix, with the exception of the /health route.
Base URL
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 theAuthorization header:
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: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