Stella Ops API Overview

The shared contract every Stella Ops HTTP API follows: authentication, tenancy, pagination, idempotency, rate limits, error envelopes, and determinism guarantees. Read this once, then rely on each service’s OpenAPI document for endpoint-specific details.

Audience: API client integrators, SDK authors, and service developers.

Last updated: 2026-05-30 (doc ↔ code reconciliation)

Scope

Shared conventions for all Stella Ops HTTP APIs. Per-service schemas live under src/Api/StellaOps.Api.OpenApi/<service>/openapi.yaml; the aggregate spec is composed by compose.mjs to src/Api/StellaOps.Api.OpenApi/stella.yaml. Note: that aggregate currently carries x-stellaops-contract-status: contains-draft-stubs (draft stub services include export-center, graph, jobengine, policy, scheduler), so it is not a fully authoritative shipped contract for those services.

Related Documentation

• OpenAPI Discovery - Discovery endpoints and aggregation
• Schema Validation - JSON Schema validation for microservice endpoints
• OpenAPI Aggregation - Gateway OpenAPI document generation

Authentication & tenancy

• Auth: Bearer tokens (Authorization: Bearer <token>), validated as JWTs issued by Authority (OAuth 2.1). The resource server validates the token aud claim against its configured audiences (StellaOpsResourceServerOptions.Audiences -> jwt.TokenValidationParameters.ValidAudiences), so service accounts must request a token whose aud includes the target service.
• Tenancy: Tenant identity is resolved claim-first, not header-first. StellaOpsTenantResolver reads the tenant exclusively from envelope-bound JWT claims, in priority order stellaops:tenant (canonical) -> tenant_id -> tenant -> tid (legacy). The header fallbacks (X-StellaOps-TenantId, X-StellaOps-Tenant, X-Stella-Tenant, X-Tenant-Id) are stripped at ingress and are no longer honoured as a tenancy source.
  • Endpoints that require a tenant use the RequireTenant() endpoint filter. A request with no resolvable tenant is rejected with HTTP 400and an application/problem+json body ({ "type", "title", "status": 400, "detail", "error_code": "tenant_missing" }) — not 403 and not error.code = TENANT_REQUIRED. Other failure codes are tenant_conflict and tenant_invalid_format.
  • Exception: a small number of legacy Authority tenant-scoped surfaces (Console / Console-Admin tiers, per AUTH-DRIFT-003) still require the X-StellaOps-TenantId header and treat the bearer claim as informational only; on those surfaces a mismatched header vs. claim returns 403 and a missing header returns 400 tenant_header_missing. These are documented per path.
• Scopes: Each endpoint documents required scopes; clients must send least-privilege tokens. The canonical scope catalogue is StellaOpsScopes (src/Authority/StellaOps.Authority/StellaOps.Auth.Abstractions/StellaOpsScopes.cs); it is the JWT authorization surface (what may appear in the scope claim). Token issuance filters requested scopes against authority.clients.allowed_scopes — the authority.permissions table is the Console RBAC catalogue and is not consulted at request time. Scope-string formats are not uniform: most are colon-delimited (scanner:read, policy:write, vuln:view) but several families are dot-delimited (concelier.merge, packs.read, export.viewer, notify.viewer, ops.health, analytics.read).

Pagination

• Cursor-based. The canonical shared parameters are limit (integer, default 50, max 200 unless noted) and cursor (opaque string); see _shared/parameters/paging.yaml. Some service specs use the camelCase aliases pageSize (max 200, default 50) / pageToken (e.g. Notifier) — confirm the exact names in each service’s OpenAPI document.
• List responses carry page metadata (_shared/schemas/common.yaml PageMetadata): hasMore (boolean), and nextCursor / previousCursor when more pages are available.
• All response field names are camelCase (services serialize with JsonNamingPolicy.CamelCase); there are no snake_case API fields.
• Ordering is deterministic per endpoint (documented under each path).

Idempotency

• Some write endpoints accept an Idempotency-Key header (UUID) to de-duplicate retries (e.g. the Notifier API declares it required, format: uuid); servers de-duplicate on key + tenant + path. This is per-endpoint, not a platform-wide guarantee — check each service’s spec.
• Idempotent methods: GET/HEAD/OPTIONS always; POST/PUT/PATCH/DELETE idempotent only when an Idempotency-Key is provided and the endpoint documents support for it.

Rate limits

• The gateway rate limiter (StellaOps.Router.Gateway RateLimitMiddleware) emits X-RateLimit-Limit, X-RateLimit-Remaining, and X-RateLimit-Reset (the reset instant as UTC epoch seconds) on responses where a concrete window+limit applies. Limits are partitioned per tenant + microservice.
• On 429 Too Many Requests the limiter always sets a Retry-After header (seconds, minimum 1) and returns the rate-limit error body shown under “Error envelope”; clients should back off using Retry-After.

Error envelope

The canonical error envelope (_shared/schemas/common.yaml ErrorEnvelope, served as application/json) is flat — the fields are not nested under an error object, and field names are camelCase:

{
  "code": "service_unavailable",
  "message": "human readable",
  "traceId": "<trace or correlation id>"
}

• code and message are required; traceId is the optional correlation identifier and maps to server traces/logs (CLI/Console surface it in verbose output).
• Minimal-API services emit the same flat shape but commonly name the machine-readable code field error instead of code (e.g. Notify: { "error": "tenant_missing", "message": "...", "traceId": "..." }). The error value is the code string, not a nested object.
• Tenant and some validation rejections instead use RFC 7807 application/problem+json ({ "type", "title", "status", "detail", "error_code" }). Treat error_code / error / code as the machine-readable discriminator depending on the surface.
• The 429 body adds rate-limit context: { "error": "rate_limit_exceeded", "message", "retryAfter", "limit", "current", "window", "scope" }.

Headers

• Observability: the platform configures OpenTelemetry tracing (StellaOps.Telemetry.Core), which propagates W3C Trace Context via traceparent (and optionally baggage). Clients should forward traceparent when chaining calls; the correlation identifier is surfaced back as traceId in the error envelope.
• Content negotiation: Accept defaults to application/json; NDJSON endpoints use application/x-ndjson.
• All times are UTC ISO-8601; hashes are lowercase hex.

Determinism & offline

• APIs must return stable ordering for identical inputs; list endpoints document their sort keys.
• Clients should operate offline using cached responses where supported; air-gap endpoints document required bundles/trust roots.

Checklist for new/changed endpoints

• [ ] Added request/response examples (see examples/ folders).
• [ ] Spectral lint passes (npm run api:lint; runs @stoplight/spectral-cli against src/Api/StellaOps.Api.OpenApi/**/*.yaml).
• [ ] Compat report reviewed (npm run api:compat vs src/Api/StellaOps.Api.OpenApi/baselines/stella-baseline.yaml).
• [ ] Aggregate spec recomposed (npm run api:compose -> src/Api/StellaOps.Api.OpenApi/stella.yaml) and changelog regenerated (npm run api:changelog).
• [ ] Error envelope and headers documented.
• [ ] Pagination, idempotency, tenancy, scopes documented.