# 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`.

## Related Documentation

- [OpenAPI Discovery](openapi-discovery.md) - Discovery endpoints and aggregation
- [Schema Validation](../modules/router/schema-validation.md) - JSON Schema validation for microservice endpoints
- [OpenAPI Aggregation](../modules/router/openapi-aggregation.md) - Gateway OpenAPI document generation

## 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:
```json
{
  "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.