# Bytes management HTTP binding

The primary binding is HTTP on a separate management listener. Paths below
are native to that listener. ULab deployment mounts this API at
`/api/management`, stripping that prefix before forwarding. Operations use
the separate `/api/operations` prefix, following the
[family contract](../../../ulab-standard/MANAGEMENT.md). This
does not add management routes to the content listener.

| Method and path | Operation | Success |
|---|---|---|
| `GET /v1/inventory` | `inventory` | `200`, `Inventory` JSON |
| `GET /livez` | `livez` | `200`, `Health` JSON |
| `GET /healthz` | `healthz` | `200` when management can read its store; `503` otherwise |
| `GET /describe` | `describe` | `200`, management `Description` JSON |
| `GET /describe/{file...}` | `describe_file` | `200`, one listed contract file verbatim |

Every response, including router errors, carries `Ulab-Service: bytes`,
`Ulab-Surface: management` and `Ulab-Contract: 2026-09-11`. The description has
`service`, `surface` and `contract` with the same values. Its `operations` and
`files` describe this listener alone. The original content listener retains its
BN description and contract date.

These routes accept no query parameters or body. Unknown, repeated or empty
query parameters, a bare trailing `?`, and any request body, return `400` JSON
`{"error":"bad_request"}`. There is no request-size-dependent inventory limit:
the two result lists each contain at most ten records. Unsupported methods
return `405`; `HEAD` follows `GET` without a response body. The route returns
`503` JSON `{"error":"inventory_unavailable"}` when a complete observation
cannot be obtained. An unlisted description file returns `404` JSON
`{"error":"not_found"}`. These failures are not content-protocol refusals.

A scan has a thirty-second deadline. Successful observations are cached for
at most five seconds; concurrent callers share the in-progress observation.
The readiness check opens the objects directory and reads at most one entry;
it does not scan the inventory.

Successful inventory responses follow
[Inventory.schema.json](schema/Inventory.schema.json). File timestamps and
the nontransactional observation are specified in [SURFACE.md](SURFACE.md).
The service does no content reads or hash verification for inventory.

The operational health envelope follows the family standard with the
management contract date. `/livez` has empty checks; `/healthz` describes the
management store check. Build values come from the binary's Go build metadata,
or the existing link-time variables
`github.com/Bitspark/bn-bytes/impl/cloud/go/api.Revision` and `.Dirty`.

Contract files are embedded at build and served verbatim as `text/markdown`
or `application/json`. Run `go generate ./api/management` from the service root
to regenerate the table, schemas and OpenAPI from the Go types and operation
table. Drift tests enforce generation and operation coverage.