68 lines
3.5 KiB
Markdown
Executable File
68 lines
3.5 KiB
Markdown
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.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.
|