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