git.stella-ops.org/docs/specs/symbols/api.md

Symbol Server API

Imposed rule: All API responses must include tenant scoping and content digests; cross-tenant symbol access is forbidden.

Base path: /api/v1/symbols (service: Symbol Server / Export Center plugin).

Endpoints

• GET /manifest – returns SYMBOL_MANIFEST/v1 for the tenant.
  • Headers: X-Stella-Tenant (required)
  • Query: image_digest (optional filter), build_id (exact match)
• GET /files/{path} – stream a symbol file by relative path in manifest.
  • Headers: X-Stella-Tenant
  • Responds with Content-SHA256 header and ETag; 404 if tenant mismatch.
• POST /ingest – upload a symbol bundle (tar or OCI artifact) and manifest.
  • Headers: X-Stella-Tenant, X-Stella-Attestation (optional DSSE digest)
  • Validates manifest checksum, entry digests, and tenant.
• GET /health – readiness/liveness.

Error model

• Problem+JSON; include tenant, correlation_id, and policy fields when access is denied.
• Rate limits: 429 with Retry-After; deterministic budget per tenant.

Security

• Auth via Authority-issued JWT; enforce symbols:read/symbols:write scopes.
• Tenant check on every request; manifest tenant must equal header.
• Optional DSSE attestation digest header is recorded and surfaced in /manifest under source.attestation.

Caching & offline

• Console/CLI cache manifest + files in CAS; revalidate via If-None-Match on GET /manifest.
• Offline kits mount symbol bundle read-only; API client can be pointed at file:// CAS handler for air-gapped use.

Observability

• Emit counters per tenant: symbol_manifest_requests, symbol_file_bytes_served, symbol_ingest_failures.
• Logs include build_id, image_digest, tenant, attested flag.