Deployments API

Deploy, rollback, terminate, restart, and scale application deployments.

Deployment Statuses: pending, building, deploying, deployed, failed, rolled_back, terminated, expired


GET /api/deployments/:projectId

Lists all deployments for a project, ordered by creation date descending.

Auth: Bearer token (any authenticated user)

Response 200:

[
  {
    "id": "uuid",
    "projectId": "uuid",
    "environmentId": "uuid",
    "version": "1.0.0",
    "branch": "main",
    "commitSha": "abc123",
    "imageTag": "my-app:latest",
    "status": "deployed",
    "deployedById": "uuid",
    "previewUrl": null,
    "deployedAt": "2026-07-01T12:00:00.000Z",
    "createdAt": "2026-07-01T12:00:00.000Z"
  }
]

POST /api/deploy

Triggers a new deployment. Creates a deployment record and runs the deploy process asynchronously:

  • Preview environments are created on-the-fly and deployed via K8s manifests.
  • Staging/Production environments are deployed via ArgoCD with status polling (up to 3 minutes).
  • On success, an SMTP notification is sent to all DEVOPS users (if SMTP is configured).
  • If the branch contains a ClickUp task ID, a preview comment is posted and the task is linked.

Auth: Bearer token (DEVOPS, TECH_LEAD, DEVELOPER)

Request Body:

{
  "projectId": "uuid",
  "environmentId": "uuid",
  "environmentName": "staging",
  "version": "2.0.0",
  "branch": "feature/new-feature",
  "commitSha": "def456",
  "imageTag": "my-app:2.0.0",
  "metadata": {}
}
Field Type Required Description
projectId uuid yes Project to deploy
environmentId uuid no Target environment (omit for preview)
environmentName string no Use preview to create a preview env
version string no Semantic version (default: 1.0.0)
branch string no Git branch (default: main)
commitSha string no Git commit SHA (default: unknown)
imageTag string no Docker image tag (default: latest)
metadata object no Arbitrary metadata

Response 201:

{
  "id": "uuid",
  "projectId": "uuid",
  "environmentId": "uuid",
  "version": "2.0.0",
  "branch": "feature/new-feature",
  "status": "pending",
  "previewUrl": null,
  "createdAt": "2026-07-01T12:00:00.000Z"
}

POST /api/deployments/:id/terminate

Terminates a deployment by setting its status to terminated. Requires DEVOPS, TECH_LEAD, or DEVELOPER role. Audit-logged.

Auth: Bearer token (DEVOPS, TECH_LEAD, DEVELOPER)

Response 200:

{
  "id": "uuid",
  "status": "terminated",
  "terminatedAt": "2026-07-01T12:00:00.000Z"
}

POST /api/deployments/:id/restart

Restarts a deployment by resetting its status to pending. Simulates a fresh deploy after 2 seconds. Requires DEVOPS role.

Auth: Bearer token (DEVOPS)

Response 200:

{
  "message": "Restart triggered",
  "deployment": {
    "id": "uuid",
    "status": "pending"
  }
}

PATCH /api/deployments/:id/scale

Scales a deployment by updating its replica count in metadata. Requires DEVOPS role. Audit-logged.

Auth: Bearer token (DEVOPS)

Request Body:

{
  "replicas": 5
}

Response 200:

{
  "id": "uuid",
  "metadata": {
    "replicas": 5
  }
}

POST /api/rollback

Rolls back a deployment to a previous version. Marks the current deployment as rolled_back and creates a new deployment record with the previous version. Triggers a GitLab pipeline. Requires DEVOPS or TECH_LEAD role. Audit-logged.

Auth: Bearer token (DEVOPS, TECH_LEAD)

Request Body:

{
  "deploymentId": "uuid-of-deployment-to-rollback",
  "previousVersion": "1.0.0"
}

Response 201:

{
  "rolledBack": {
    "id": "uuid",
    "status": "rolled_back",
    "terminatedAt": "2026-07-01T12:00:00.000Z"
  },
  "newDeployment": {
    "id": "uuid",
    "version": "1.0.0",
    "status": "deployed",
    "deployedAt": "2026-07-01T12:00:00.000Z"
  }
}

Error Codes

Status Error Description
404 Project not found Invalid projectId
404 Environment not found Invalid environmentId
404 Deployment not found Invalid deployment ID