git.stella-ops.org/docs/modules/release-orchestrator/api/overview.md

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:

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

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
• Releases API
• Promotions API
• Workflows API
• Agents API
• WebSocket API