REST API Reference v2.1 -- Deployments
POST /deployments
Records a deployment event and evaluates it against active deployment policies. Requires deployments:write scope. Request body: {"environment": "production", "version": "2.4.1", "commit_sha": "a1b2c3d4", "deployer": "user_xyz", "artifacts": [{"type": "container_image", "reference": "registry.example.com/app:2.4.1", "sbom_id": "sbom_abc", "scan_id": "scan_xyz"}], "metadata": {"ci_pipeline_id": "pipe_123", "approval_ticket": "SEC-456"}}.
Response: {"id": "deploy_abc", "status": "approved|blocked|pending_approval", "environment": "production", "policy_results": [{"policy_id": "pol_abc", "name": "Production Gate", "result": "pass", "rules_evaluated": 3, "rules_passed": 3}], "created_at": "2026-03-15T14:00:00Z"}. A blocked status means one or more policies with strict enforcement failed. A pending_approval status means manual approval is required.
GET /deployments
Returns deployment history with optional filtering. Query parameters: environment (production, staging, development), status (approved, blocked, pending_approval, rolled_back), deployer (user ID), since and until (ISO 8601 timestamps), page, limit.
Response includes deployment timeline and associated security context: {"data": [{"id": "deploy_abc", "environment": "production", "version": "2.4.1", "status": "approved", "deployer": "user_xyz", "created_at": "2026-03-15T14:00:00Z", "scan_summary": {"critical": 0, "high": 1, "medium": 5}, "alerts_since_deploy": 0}]}. The alerts_since_deploy field helps correlate security events with deployment changes.
POST /deployments/:id/rollback
Records a rollback event associated with a previous deployment. Requires deployments:write scope. Request body: {"reason": "Security incident SEC-789", "rollback_to_version": "2.4.0", "rollback_to_deployment": "deploy_prev"}. The rollback event is linked to the original deployment and any associated security alerts for post-incident analysis.
Response: {"id": "deploy_roll_abc", "type": "rollback", "original_deployment": "deploy_abc", "rolled_back_to": "deploy_prev", "reason": "Security incident SEC-789", "created_at": "2026-03-15T16:30:00Z"}. Rollback events appear in the deployment timeline and trigger deployment.rolled_back webhook events. Use rollback correlation with alert timelines to identify whether deployments introduced security regressions.
All external references have been reviewed by our editorial team.