API Overview

Version: v1 Base Path: /api/v1

Design Principles

Authentication

All API requests require a valid JWT Bearer token:

Authorization: Bearer <token>

Tokens are issued by the Authority module and contain:

• user_id: User identifier
• tenant_id: Tenant scope
• roles: User roles
• permissions: Specific permissions

Standard Response Envelope

Success Response

interface ApiResponse<T> {
  success: true;
  data: T;
  meta?: {
    pagination?: PaginationMeta;
    requestId: string;
    timestamp: string;
  };
}

Error Response

interface ApiErrorResponse {
  success: false;
  error: {
    code: string;           // e.g., "PROMOTION_BLOCKED"
    message: string;        // Human-readable message
    details?: object;       // Additional context
    validationErrors?: ValidationError[];
  };
  meta: {
    requestId: string;
    timestamp: string;
  };
}

interface ValidationError {
  field: string;
  message: string;
  code: string;
}

Pagination

interface PaginationMeta {
  page: number;
  pageSize: number;
  totalItems: number;
  totalPages: number;
  hasNext: boolean;
  hasPrevious: boolean;
}

HTTP Status Codes

Common Query Parameters

API Modules

Integration Hub (INTHUB)

GET    /api/v1/integration-types
GET    /api/v1/integration-types/{typeId}
POST   /api/v1/integrations
GET    /api/v1/integrations
GET    /api/v1/integrations/{id}
PUT    /api/v1/integrations/{id}
DELETE /api/v1/integrations/{id}
POST   /api/v1/integrations/{id}/test
POST   /api/v1/integrations/{id}/discover
GET    /api/v1/integrations/{id}/health

Environment & Inventory (ENVMGR)

POST   /api/v1/environments
GET    /api/v1/environments
GET    /api/v1/environments/{id}
PUT    /api/v1/environments/{id}
DELETE /api/v1/environments/{id}
POST   /api/v1/environments/{envId}/freeze-windows
GET    /api/v1/environments/{envId}/freeze-windows
DELETE /api/v1/environments/{envId}/freeze-windows/{windowId}
POST   /api/v1/targets
GET    /api/v1/targets
GET    /api/v1/targets/{id}
PUT    /api/v1/targets/{id}
DELETE /api/v1/targets/{id}
POST   /api/v1/targets/{id}/health-check
GET    /api/v1/targets/{id}/sticker
GET    /api/v1/targets/{id}/drift
POST   /api/v1/agents/register
GET    /api/v1/agents
GET    /api/v1/agents/{id}
PUT    /api/v1/agents/{id}
DELETE /api/v1/agents/{id}
POST   /api/v1/agents/{id}/heartbeat

Release Management (RELMAN)

POST   /api/v1/release-orchestrator/releases/seal
POST   /api/v1/components
GET    /api/v1/components
GET    /api/v1/components/{id}
PATCH  /api/v1/components/{id}
DELETE /api/v1/components/{id}
POST   /api/v1/components/{id}/sync-versions
GET    /api/v1/components/{id}/versions
PATCH  /api/v1/components/{componentId}/versions/{versionId}
GET    /api/v1/release-orchestrator/releases
POST   /api/v1/release-orchestrator/releases
GET    /api/v1/release-orchestrator/releases/{id}
PATCH  /api/v1/release-orchestrator/releases/{id}
DELETE /api/v1/release-orchestrator/releases/{id}
POST   /api/v1/release-orchestrator/releases/{id}/ready
POST   /api/v1/release-orchestrator/releases/{id}/promote
POST   /api/v1/release-orchestrator/releases/{id}/deploy
POST   /api/v1/release-orchestrator/releases/{id}/rollback
POST   /api/v1/release-orchestrator/releases/{id}/clone
GET    /api/v1/release-orchestrator/releases/{releaseId}/components
POST   /api/v1/release-orchestrator/releases/{releaseId}/components
PATCH  /api/v1/release-orchestrator/releases/{releaseId}/components/{componentId}
DELETE /api/v1/release-orchestrator/releases/{releaseId}/components/{componentId}
GET    /api/v1/release-orchestrator/releases/{releaseId}/events
GET    /api/v1/release-orchestrator/releases/{releaseId}/promotion-preview
GET    /api/v1/release-orchestrator/releases/{releaseId}/deploy-preflight
GET    /api/v1/release-orchestrator/releases/{releaseId}/deploy-plan
GET    /api/v1/release-orchestrator/releases/latest-by-name
GET    /api/v1/release-orchestrator/releases/suggest-version
GET    /api/v1/release-orchestrator/releases/activity
GET    /api/v1/release-orchestrator/releases/versions

Access & Sharing (ACCESS)

GET    /api/v1/release-orchestrator/releases/{id}/access
POST   /api/v1/release-orchestrator/releases/{id}/access
DELETE /api/v1/release-orchestrator/releases/{id}/access/{grantId}
GET    /api/v1/release-orchestrator/releases/{id}/access/effective
POST   /api/v1/release-orchestrator/releases/{id}/access/transfer
GET    /api/v1/release-orchestrator/environments/{id}/access
POST   /api/v1/release-orchestrator/environments/{id}/access
DELETE /api/v1/release-orchestrator/environments/{id}/access/{grantId}
GET    /api/v1/release-orchestrator/environments/{id}/access/effective
POST   /api/v1/release-orchestrator/environments/{id}/access/transfer
GET    /api/v1/release-orchestrator/access/effective

Deployed Estate / Watch (ESTATE)

GET    /api/v1/release-orchestrator/estate/status
GET    /api/v1/release-orchestrator/estate/drift
GET    /api/v1/release-orchestrator/estate/deviations
GET    /api/v1/release-orchestrator/estate
GET    /api/v1/release-orchestrator/estate/digest/{digest}

Workflow Engine (WORKFL)

POST   /api/v1/workflow-templates
GET    /api/v1/workflow-templates
GET    /api/v1/workflow-templates/{id}
PUT    /api/v1/workflow-templates/{id}
DELETE /api/v1/workflow-templates/{id}
POST   /api/v1/workflow-templates/{id}/validate
GET    /api/v1/step-types
GET    /api/v1/step-types/{type}
POST   /api/v1/workflow-runs
GET    /api/v1/workflow-runs
GET    /api/v1/workflow-runs/{id}
POST   /api/v1/workflow-runs/{id}/pause
POST   /api/v1/workflow-runs/{id}/resume
POST   /api/v1/workflow-runs/{id}/cancel
GET    /api/v1/workflow-runs/{id}/steps
GET    /api/v1/workflow-runs/{id}/steps/{nodeId}
GET    /api/v1/workflow-runs/{id}/steps/{nodeId}/logs
GET    /api/v1/workflow-runs/{id}/steps/{nodeId}/artifacts

Promotion & Approval (PROMOT)

POST   /api/v1/promotions
GET    /api/v1/promotions
GET    /api/v1/promotions/{id}
POST   /api/v1/promotions/{id}/approve
POST   /api/v1/promotions/{id}/reject
POST   /api/v1/promotions/{id}/cancel
GET    /api/v1/promotions/{id}/decision
GET    /api/v1/promotions/{id}/approvals
GET    /api/v1/promotions/{id}/evidence
POST   /api/v1/promotions/preview-gates
POST   /api/v1/release-orchestrator/approval-policies
GET    /api/v1/release-orchestrator/approval-policies
GET    /api/v1/release-orchestrator/approval-policies/{id}
PUT    /api/v1/release-orchestrator/approval-policies/{id}
DELETE /api/v1/release-orchestrator/approval-policies/{id}
GET    /api/v1/my/pending-approvals

Deployment (DEPLOY)

GET    /api/v1/deployment-jobs
GET    /api/v1/deployment-jobs/{id}
GET    /api/v1/deployment-jobs/{id}/tasks
GET    /api/v1/deployment-jobs/{id}/tasks/{taskId}
GET    /api/v1/deployment-jobs/{id}/tasks/{taskId}/logs
GET    /api/v1/deployment-jobs/{id}/artifacts
GET    /api/v1/deployment-jobs/{id}/artifacts/{artifactId}
POST   /api/v1/rollbacks
GET    /api/v1/rollbacks

Progressive Delivery (PROGDL)

POST   /api/v1/ab-releases
GET    /api/v1/ab-releases
GET    /api/v1/ab-releases/{id}
POST   /api/v1/ab-releases/{id}/start
POST   /api/v1/ab-releases/{id}/advance
POST   /api/v1/ab-releases/{id}/promote
POST   /api/v1/ab-releases/{id}/rollback
GET    /api/v1/ab-releases/{id}/traffic
GET    /api/v1/ab-releases/{id}/health
GET    /api/v1/rollout-strategies

Release Evidence (RELEVI)

GET    /api/v1/evidence-packets
GET    /api/v1/evidence-packets/{id}
GET    /api/v1/evidence-packets/{id}/download
POST   /api/v1/audit-reports
GET    /api/v1/audit-reports/{id}
GET    /api/v1/audit-reports/{id}/download
GET    /api/v1/version-stickers
GET    /api/v1/version-stickers/{id}

Plugin Infrastructure (PLUGIN)

GET    /api/v1/plugins
GET    /api/v1/plugins/{id}
POST   /api/v1/plugins/{id}/enable
POST   /api/v1/plugins/{id}/disable
GET    /api/v1/plugins/{id}/health
POST   /api/v1/plugin-instances
GET    /api/v1/plugin-instances
PUT    /api/v1/plugin-instances/{id}
DELETE /api/v1/plugin-instances/{id}

WebSocket Endpoints

WS  /api/v1/workflow-runs/{id}/stream
WS  /api/v1/deployment-jobs/{id}/stream
WS  /api/v1/agents/{id}/task-stream
WS  /api/v1/dashboard/stream

Rate Limits

Rate limit headers:

• X-RateLimit-Limit: Request limit
• X-RateLimit-Remaining: Remaining requests
• X-RateLimit-Reset: Reset timestamp

References

• Release Seal Aggregate API
• Resource Access & Sharing API
• Environments API
• Releases API
• Promotions API
• Workflows API
• Agents API
• WebSocket API