Projects API

Manage platform projects, environments, and SDK tokens.


GET /api/projects

Lists all projects with their related environments and deployments.

Auth: Bearer token (any authenticated user)

Response 200:

[
  {
    "id": "uuid",
    "name": "my-app",
    "stack": "nodejs",
    "description": "My application",
    "repositoryUrl": "https://gitlab.com/org/my-app",
    "domain": "my-app.example.com",
    "clickupListId": null,
    "isActive": true,
    "environments": [
      {
        "id": "uuid",
        "name": "development",
        "namespace": "my-app-development",
        "domain": "my-app-development.example.com"
      }
    ],
    "deployments": []
  }
]

POST /api/projects

Creates a new project. Automatically creates development, staging, and production environments. Requires DEVOPS or TECH_LEAD role. Audit-logged.

Auth: Bearer token (DEVOPS, TECH_LEAD)

Request Body:

{
  "name": "my-app",
  "stack": "nodejs",
  "description": "My application",
  "repositoryUrl": "https://gitlab.com/org/my-app",
  "domain": "my-app.example.com",
  "clickupListId": "optional-clickup-list-id"
}

Stack Types: nodejs, angular, python, static

Response 201:

{
  "id": "uuid",
  "name": "my-app",
  "stack": "nodejs",
  "description": "My application",
  "repositoryUrl": "https://gitlab.com/org/my-app",
  "domain": "my-app.example.com",
  "isActive": true
}

GET /api/projects/:id

Retrieves a single project by ID with its environments and deployments.

Auth: Bearer token (any authenticated user)

Response 200:

{
  "id": "uuid",
  "name": "my-app",
  "stack": "nodejs",
  "description": "My application",
  "repositoryUrl": "https://gitlab.com/org/my-app",
  "domain": "my-app.example.com",
  "isActive": true,
  "environments": [],
  "deployments": []
}

Error 404:

{ "error": "Project not found" }

PUT /api/projects/:id

Updates a project's settings. Requires DEVOPS or TECH_LEAD role. Audit-logged.

Auth: Bearer token (DEVOPS, TECH_LEAD)

Request Body: (all fields optional)

{
  "name": "updated-app",
  "stack": "python",
  "description": "Updated description",
  "repositoryUrl": "https://gitlab.com/org/updated-app",
  "domain": "updated-app.example.com",
  "clickupListId": "new-list-id"
}

Response 200:

{
  "id": "uuid",
  "name": "updated-app",
  "stack": "python",
  "description": "Updated description"
}

DELETE /api/projects/:id

Soft-deletes a project by setting deletedAt and isActive = false. Requires DEVOPS role. Audit-logged.

Auth: Bearer token (DEVOPS)

Response 200:

{ "message": "Project soft-deleted" }

SDK Tokens

GET /api/projects/:projectId/tokens

Lists all SDK tokens for a project. Token values are masked for security.

Auth: Bearer token (any authenticated user)

Response 200:

[
  {
    "id": "uuid",
    "name": "production-token",
    "token": "sdk_live_abc123...defg",
    "status": "active",
    "createdAt": "2026-01-01T00:00:00.000Z"
  }
]

POST /api/projects/:projectId/tokens

Creates a new SDK token. The plaintext token is returned only once. Requires DEVOPS or TECH_LEAD role. Audit-logged.

Auth: Bearer token (DEVOPS, TECH_LEAD)

Request Body:

{
  "name": "production-token"
}

Response 201:

{
  "id": "uuid",
  "name": "production-token",
  "token": "sdk_live_abc123def456...",
  "status": "active",
  "createdAt": "2026-01-01T00:00:00.000Z"
}

DELETE /api/projects/:projectId/tokens/:tokenId

Revokes an SDK token by deleting it. Requires DEVOPS or TECH_LEAD role (the same roles that can create tokens) and project devops access. Audit-logged.

Auth: Bearer token (DEVOPS, TECH_LEAD)

Error 404: SDK Token not found (unknown id, or a token of another project).

Response 200:

{ "success": true, "message": "SDK Token revoked" }

ArgoCD Status

GET /api/projects/:projectId/argocd-status

Queries the ArgoCD application status for the project's staging environment.

Auth: Bearer token (any authenticated user)

Response 200 (connected):

{
  "connected": true,
  "appName": "my-app-staging",
  "syncStatus": "Synced",
  "healthStatus": "Healthy",
  "revision": "abc123def456",
  "syncTime": "2026-07-01T12:00:00.000Z"
}

Response 200 (disconnected):

{
  "connected": false,
  "error": "Could not reach ArgoCD: ...",
  "syncStatus": "Offline",
  "healthStatus": "Unknown"
}

Live Resource Topology

GET /api/projects/:projectId/environments/:envId/topology

Read-only resource graph of one environment, shown on the portal's GitOps tab (refreshed every 10 s while the tab is visible). envId is the environment UUID (an environment name such as staging is accepted too).

Combines the ArgoCD Application's status.resources (sync / health per managed resource, including Missing ones) with live objects listed in the environment namespace only: Deployments, ReplicaSets, Pods, Services, Ingresses, cert-manager Certificates, PVCs and Events. Secret and ConfigMap nodes are derived from the objects that reference them (names only); the API never lists or reads Secrets.

Auth: Bearer token, project member (viewer or higher), or agent token with projects:read

Response 200:

{
  "namespace": "shop-staging-0123456789abcdef",
  "appName": "shop-staging-0123456789abcdef",
  "environmentId": "…",
  "environment": "staging",
  "argo": { "found": true, "error": null, "sync": "Synced", "health": "Healthy", "revision": "abc123" },
  "nodes": [
    { "id": "Deployment/web", "kind": "Deployment", "name": "web", "health": "Healthy", "sync": "Synced",
      "info": { "replicas": 3, "readyReplicas": 3 }, "events": [] },
    { "id": "Pod/web-7d9-a", "kind": "Pod", "name": "web-7d9-a", "health": "Degraded", "sync": null,
      "info": { "ready": "0/1", "reason": "CrashLoopBackOff", "restarts": 7 }, "events": [] }
  ],
  "edges": [
    { "from": "Deployment/web", "to": "ReplicaSet/web-7d9", "type": "owns" },
    { "from": "Ingress/web", "to": "Service/web", "type": "routes" },
    { "from": "Service/web", "to": "Pod/web-7d9-a", "type": "selects" }
  ],
  "counts": { "Deployment": 1, "ReplicaSet": 1, "Pod": 1 },
  "warnings": [],
  "generatedAt": "2026-11-10T12:00:00.000Z"
}

Edges: owns (ownerReferences, and Application → managed resource), routes (Ingress backend → Service), selects (Service selector → Pod, Ingress TLS / Certificate secretName, Pod → PVC / ConfigMap / Secret it uses). argo.found is false when the Application does not exist; the live graph is still returned. warnings names reads that failed (for example missing RBAC in an older namespace). 503 when Kubernetes is unreachable.


Error Codes

Status Error Description
404 Project not found Project ID does not exist
404 SDK Token not found Token ID does not exist
400 Token name is required Missing name when creating token