REST API Reference

All endpoints are prefixed with /api. Authenticated endpoints require a Bearer token in the Authorization header.

Authorization: Bearer <token>

Tokens are obtained from /api/auth/login or by using an API key. A Swagger UI with full request/response schemas is available at http://localhost:3000/docs when running in development mode.

---

Authentication

POST /api/auth/register

Register a new user account.

Body

{ "email": "alice@example.com", "password": "secret", "name": "Alice" }

Response 201 — { accessToken, refreshToken, user }

---

POST /api/auth/login

Authenticate and receive access/refresh tokens.

Body

{ "email": "alice@example.com", "password": "secret" }

Response 200 — { accessToken, refreshToken, user }

---

POST /api/auth/refresh

Exchange a refresh token for a new access token.

Body { "refreshToken": "..." }Response 200 — { accessToken, refreshToken }

---

POST /api/auth/logout

Invalidate a refresh token.

Body { "refreshToken": "..." }Response 200 — { "message": "Logged out" }

---

GET /api/auth/registration-status

Check if public registration is enabled. No auth required.

Response 200 — { "registrationEnabled": true }

---

Projects

GET /api/projects — List all visible projects

GET /api/projects/public — List public projects (no auth required)

GET /api/projects/mine — List your own projects

GET /api/projects/:id — Get a project by ID

POST /api/projects — Create a project

{ "name": "my-app", "path": "org/my-app", "provider": "github", "visibility": "private" }

Response 201 — created project.

PATCH /api/projects/:id — Update a project (all fields optional)

DELETE /api/projects/:id — Delete a project — 204

---

Pipelines

GET /api/projects/:projectId/pipelines — List pipelines

GET /api/projects/:projectId/pipelines/:id — Get a pipeline

POST /api/projects/:projectId/pipelines — Create a pipeline

{ "name": "ci" }

Response 201 — created pipeline.

PUT /api/projects/:projectId/pipelines/:id — Save full pipeline state

{
  "viewport": { "x": 0, "y": 0, "zoom": 1 },
  "stages": [],
  "stageEdges": []
}

Response 200 — updated pipeline.

GET /api/projects/:projectId/pipelines/:id/execution-plan

Compute the topological execution order (dry-run, no execution).

DELETE /api/projects/:projectId/pipelines/:id — Delete a pipeline — 204

---

Credentials

GET /api/credentials — List credentials (values redacted)

POST /api/credentials — Create a credential

{ "provider": "docker", "label": "Docker Hub Token", "value": "dckr_pat_..." }

PUT /api/credentials/:id — Update label or value

DELETE /api/credentials/:id — Delete — 204

---

API Keys

GET /api/api-keys — List API keys

POST /api/api-keys — Create an API key

{ "name": "ci-bot" }

Response 201 — includes rawKey (shown once only).

POST /api/api-keys/:id/revoke — Revoke a key

DELETE /api/api-keys/:id — Permanently delete — 204

---

Users

GET /api/users/me — Get your profile

GET /api/users — List all users (admin only)

POST /api/users — Create a user (admin only)

{ "email": "bob@example.com", "password": "secret", "name": "Bob", "role": "user" }

PATCH /api/users/:id — Update role (admin only)

DELETE /api/users/:id — Delete user (admin only)

---

Admin

GET /api/admin/settings — Get global settings (admin only)

Response { "registrationEnabled": true }

PATCH /api/admin/settings — Update settings (admin only)

{ "registrationEnabled": false }

---

Status codes

Code	Meaning
200	OK
201	Created
204	No content
400	Validation error
401	Missing or invalid token
403	Insufficient permissions
404	Not found
500	Server error