# API Overview **Version**: v1 **Base Path**: `/api/v1` ## Design Principles | Principle | Implementation | |-----------|----------------| | **RESTful** | Resource-oriented URLs, standard HTTP methods | | **Versioned** | `/api/v1/...` prefix; breaking changes require version bump | | **Consistent** | Standard response envelope, error format, pagination | | **Authenticated** | OAuth 2.0 Bearer tokens via Authority module | | **Tenant-scoped** | Tenant ID from token; all operations scoped to tenant | | **Audited** | All mutating operations logged with user/timestamp | ## Authentication All API requests require a valid JWT Bearer token: ```http Authorization: Bearer ``` 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 ```typescript interface ApiResponse { success: true; data: T; meta?: { pagination?: PaginationMeta; requestId: string; timestamp: string; }; } ``` ### Error Response ```typescript 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 ```typescript interface PaginationMeta { page: number; pageSize: number; totalItems: number; totalPages: number; hasNext: boolean; hasPrevious: boolean; } ``` ## HTTP Status Codes | Code | Description | |------|-------------| | `200` | Success | | `201` | Created | | `204` | No Content | | `400` | Bad Request - validation error | | `401` | Unauthorized - invalid/missing token | | `403` | Forbidden - insufficient permissions | | `404` | Not Found | | `409` | Conflict - resource state conflict | | `422` | Unprocessable Entity - business rule violation | | `429` | Too Many Requests - rate limited | | `500` | Internal Server Error | ## Common Query Parameters | Parameter | Type | Description | |-----------|------|-------------| | `page` | integer | Page number (1-indexed) | | `pageSize` | integer | Items per page (max 100) | | `sort` | string | Sort field (prefix `-` for descending) | | `filter` | string | JSON filter expression | ## 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/components GET /api/v1/components GET /api/v1/components/{id} PUT /api/v1/components/{id} DELETE /api/v1/components/{id} POST /api/v1/components/{id}/sync-versions GET /api/v1/components/{id}/versions POST /api/v1/releases GET /api/v1/releases GET /api/v1/releases/{id} PUT /api/v1/releases/{id} DELETE /api/v1/releases/{id} GET /api/v1/releases/{id}/state POST /api/v1/releases/{id}/deprecate GET /api/v1/releases/{id}/compare/{otherId} POST /api/v1/releases/from-latest ``` ### 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/approval-policies GET /api/v1/approval-policies 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 | Tier | Requests/minute | Burst | |------|-----------------|-------| | Standard | 1000 | 100 | | Premium | 5000 | 500 | Rate limit headers: - `X-RateLimit-Limit`: Request limit - `X-RateLimit-Remaining`: Remaining requests - `X-RateLimit-Reset`: Reset timestamp ## References - [Environments API](environments.md) - [Releases API](releases.md) - [Promotions API](promotions.md) - [Workflows API](workflows.md) - [Agents API](agents.md) - [WebSocket API](websockets.md)