Deployments API

Deployment hooks, deliverable generation, dual-track comparison, and rollback.

Deployment Hooks

Outbound webhooks that fire when workflows complete or gates are approved, allowing integration with external CI/CD pipelines.

List Hooks

GET /api/v1/projects/{project_id}/deployment-hooks
Authorization: Bearer <token>

Response 200 OK

[
  {
    "id": "uuid",
    "project_id": "uuid",
    "name": "Production Deploy",
    "url": "https://ci.example.com/webhooks/deploy",
    "trigger_on": "workflow_done",
    "environment": "production",
    "headers": {},
    "enabled": true,
    "created_at": "2026-01-01T00:00:00Z"
  }
]

Create Hook

Requires admin role.

POST /api/v1/projects/{project_id}/deployment-hooks
Authorization: Bearer <token>
Content-Type: application/json

{
  "name": "Staging Deploy",
  "url": "https://ci.example.com/webhooks/deploy",
  "secret": "my-webhook-secret",
  "trigger_on": "gate_approved",
  "environment": "staging",
  "enabled": true
}

When a secret is provided, each dispatch includes an X-ASF-Signature header with an HMAC-SHA256 signature of the payload.

Update / Delete Hook

PUT /api/v1/deployment-hooks/{hook_id}
DELETE /api/v1/deployment-hooks/{hook_id}
Authorization: Bearer <token>

Test Hook

Sends a test.ping event to verify connectivity.

POST /api/v1/deployment-hooks/{hook_id}/test
Authorization: Bearer <token>

Manual Trigger

Sends a manual.trigger event.

POST /api/v1/deployment-hooks/{hook_id}/trigger
Authorization: Bearer <token>

Dispatch History

GET /api/v1/deployment-hooks/{hook_id}/dispatches
Authorization: Bearer <token>

Rollback

Fires a deployment.rollback event to all enabled hooks for the project. Requires admin role.

POST /api/v1/projects/{project_id}/deployment-rollback
Authorization: Bearer <token>
Content-Type: application/json

{
  "target_version": "v1.2.3",
  "reason": "Critical bug in payment flow",
  "environment": "production"
}

Deliverables

Auto-generated documentation and reports from project data.

List Deliverables

GET /api/v1/projects/{project_id}/deliverables?deliverable_type=changelog
Authorization: Bearer <token>

Generate Deliverable

POST /api/v1/projects/{project_id}/deliverables/generate
Authorization: Bearer <token>
Content-Type: application/json

{
  "deliverable_type": "changelog",
  "requirement_id": "uuid"
}

Supported Types

Type	Description
changelog	Release changelog from requirement changes
project_summary	High-level project overview
deployment_guide	Step-by-step deployment instructions
api_docs	API documentation from project endpoints
user_manual	End-user documentation

Get / Delete

GET /api/v1/deliverables/{deliverable_id}
DELETE /api/v1/deliverables/{deliverable_id}
Authorization: Bearer <token>

Publish / Archive

POST /api/v1/deliverables/{deliverable_id}/publish
POST /api/v1/deliverables/{deliverable_id}/archive
Authorization: Bearer <token>

Dual-Track Comparison

Compare two AI agents side-by-side on the same task.

Create Comparison

POST /api/v1/projects/{project_id}/dual-track
Authorization: Bearer <token>
Content-Type: application/json

{
  "work_item_id": "uuid",
  "track_a_graph_id": "uuid",
  "track_b_graph_id": "uuid",
  "track_a_agent": "claude-code",
  "track_b_agent": "gemini-cli"
}

Run Comparison Analysis

Triggers AI-powered comparison of the two tracks.

POST /api/v1/dual-track/{comparison_id}/compare
Authorization: Bearer <token>

Decide Winner

POST /api/v1/dual-track/{comparison_id}/decide
Authorization: Bearer <token>
Content-Type: application/json

{ "winner": "a" }

winner must be a, b, or tie.

Cancel / Delete

POST /api/v1/dual-track/{comparison_id}/cancel
DELETE /api/v1/dual-track/{comparison_id}
Authorization: Bearer <token>