3.5 KiB
Executable File
3.5 KiB
Executable File
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.yamldocs/api/notify-openapi.yamldocs/api/taskrunner-openapi.yamldocs/api/proofs-openapi.yamldocs/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 liststella 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.