git.stella-ops.org/docs/api/overview.md

StellaOps API Overview

Last updated: 2025-11-25 (Md.V docs stream)

Scope

Shared conventions for all StellaOps HTTP APIs. Service-specific schemas live under src/Api/StellaOps.Api.OpenApi and composed out/api/stella.yaml.

Authentication & tenancy

• Auth: Bearer tokens (Authorization: Bearer <token>); service accounts must include aud for the target service.
• Tenancy: Multi-tenant endpoints require X-Stella-Tenant (or embedded tenant in token claims). Requests without tenant fail with 403 + error.code = TENANT_REQUIRED.
• Scopes: Each endpoint documents required scopes; clients must send least-privilege tokens.

Pagination

• Cursor-based: page_token (opaque), page_size (default 50, max 500 unless noted).
• Responses include next_page_token when more results are available.
• Ordering is deterministic per endpoint (documented under each path).

Idempotency

• Write endpoints accept optional Idempotency-Key header (UUID). Servers must de-duplicate on key + tenant + path.
• Idempotent methods: GET/HEAD/OPTIONS always; POST/PUT/PATCH/DELETE idempotent only when key is provided and documented.

Rate limits

• Standard headers: X-RateLimit-Limit, X-RateLimit-Remaining, X-RateLimit-Reset (UTC epoch seconds).
• 429 responses use the standard error envelope; clients should back off using Retry-After when present.

Error envelope

All error responses use:

{
  "error": {
    "code": "STRING_ENUM",
    "message": "human readable",
    "trace_id": "<trace or correlation id>"
  }
}

• trace_id maps to server traces/logs; CLI/Console surface it in verbose output.

Headers

• Required observability headers: traceparent (W3C), optional baggage for routing; services echo correlation IDs in responses.
• 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 (pnpm api:lint).
• Compat report reviewed (pnpm api:compat vs stella-baseline.yaml).
• Changelog artefacts generated (out/api/changelog/* with checksums/signature).
• Error envelope and headers documented.
• Pagination, idempotency, tenancy, scopes documented.