# API and CLI Reference

This is the single entry point for operators and integrators who need:
- API contracts (OpenAPI, schemas, samples)
- CLI command guides and automation-friendly outputs
- Cross-cutting conventions (auth, tenancy, errors, determinism, offline posture)

Detailed references live under `docs/api/` and `docs/modules/cli/`.

## Quick links

| Goal | Open this |
| --- | --- |
| API conventions (headers, pagination, errors) | `docs/api/overview.md` |
| API versioning policy | `docs/api/versioning.md` |
| Gateway tenancy header policy | `docs/api/gateway/tenant-auth.md` |
| Gateway header hardening rules | `docs/modules/gateway/identity-header-policy.md` |
| Console workspaces (findings/VEX views) | `docs/api/console/workspaces.md` |
| Console search and downloads | `docs/api/console/search-downloads.md` |
| Exceptions API entry point | `docs/api/exceptions.md` |
| Download aggregated OpenAPI via CLI | `docs/modules/cli/guides/commands/api.md` |
| CLI command reference (by command group) | `docs/modules/cli/guides/commands/` |
| CLI authentication and tokens | `docs/modules/cli/guides/commands/auth.md` |
| CLI Concelier job triggers (`db`) | `docs/modules/cli/guides/commands/db.md`, `docs/10_CONCELIER_CLI_QUICKSTART.md` |
| CLI offline/air-gap workflows | `docs/modules/cli/guides/commands/offline.md`, `docs/24_OFFLINE_KIT.md` |
| CLI reachability workflow | `docs/modules/cli/guides/commands/reachability.md` |
| CLI vulnerability workflow | `docs/modules/cli/guides/commands/vuln.md` |
| Vuln Explorer OpenAPI (v1) | `docs/modules/vuln-explorer/openapi/vuln-explorer.v1.yaml` |
| Graph Gateway API (draft) | `docs/api/graph.md`, `docs/api/graph-gateway-spec-draft.yaml` |

## Where the API contracts live

StellaOps treats the OpenAPI documents and JSON schemas as the source of truth for HTTP shapes.

- Aggregation/discovery: `docs/api/openapi-discovery.md`
- Gateway-proxied reference docs + samples: `docs/api/gateway/`
- Service-specific OpenAPI (selected):
  - `docs/modules/vuln-explorer/openapi/vuln-explorer.v1.yaml`
  - `docs/api/notify-openapi.yaml`
  - `docs/api/taskrunner-openapi.yaml`
  - `docs/api/proofs-openapi.yaml`
  - `docs/api/vexlens-openapi.yaml`
- API samples and fixtures (deterministic): `docs/api/**/samples/`

If you are building an SDK or want a single document for tooling, prefer the CLI OpenAPI download flow:
- `stella api spec list`
- `stella api spec download --output ./openapi.yaml --format openapi-yaml`

See: `docs/modules/cli/guides/commands/api.md`.

## Where the CLI docs live

The `stella` CLI is documented as:
- High-level module docs: `docs/modules/cli/README.md`, `docs/modules/cli/architecture.md`
- Command guides: `docs/modules/cli/guides/commands/` (one file per command group)

CLI docs are written to match repo reality; avoid copying raw endpoint paths into the CLI guides unless they are backed by OpenAPI and tests.

## Cross-cutting conventions (high-level)

For the detailed contract, see `docs/api/overview.md`. The stable rules to keep in mind:

- Auth: bearer tokens are the baseline; sender-constrained modes (DPoP/mTLS) are deployment-profile dependent.
- Tenancy: every tenant-scoped request must carry an explicit tenant context (see `docs/api/gateway/tenant-auth.md`).
- Determinism: stable ordering, stable ids, UTC ISO-8601 timestamps, and canonical hashing where applicable.
- Streaming: some endpoints use NDJSON (`application/x-ndjson`) for deterministic, resumable tile/record streams.
- Offline-first: workflows must remain runnable in air-gapped mode using Offline Kit bundles and locally verifiable signatures.