GET
/api/v1/households/{householdId}/inventoryRead the pantry a page at a time: one row per food, as the household's evidence stands
Each row is a fold over the household's observations — quantity, confidence, «last seen», use-by window and the keys merged into it (#466). Names come back in the household's language. ?q= matches the row's display name and its food key, case-insensitively; ?place= is one StorageLocation; ?group= is one of the pantry's four sections — UseSoon, LikelyAvailable, Uncertain or Aged — and leaving it out gives the three the list shows, the archive excluded (#390). ?limit= is 1–100, 50 by default. The order is the pantry's own: the section first, so the reader's headings stay whole across pages, then the use priority, the name and the food key.
total counts every row the filter matches, and nextCursor — opaque — is handed back as ?cursor= for the next page; null on the last. A cursor nobody handed out is a 400. The numbers over the list — the place tabs, the section headings, the triage deck — come from GET …/inventory/summary (#3000, ADR-292).Parameters
| Name | In | Type | Required | Description |
|---|---|---|---|---|
householdId | path | string (uuid) | Required | — |
q | query | string | — | — |
place | query | StorageLocation | — | — |
group | query | InventoryGroup | — | — |
cursor | query | string | — | — |
limit | query | integer (int32) | — | — |
Responses
- 200OK
application/jsonPagedInventoryItemResponse- 400Bad Request
application/problem+jsonProblemDetails- 401No session, or the session is no longer valid.
application/problem+jsonProblemDetails- 404Not Found
application/problem+jsonProblemDetails- 426The build named in X-App-Version is below its platform's version floor (ADR-070). Problem type app-version-unsupported; the only way forward is the store. Callers without the header are never turned away.
application/problem+jsonProblemDetails- 429Too many calls in the window; Retry-After says how long.
application/problem+jsonProblemDetails- Headers
Retry-After- — Seconds to wait when a rate limit answered, or an HTTP date when the household's AI is paused. Absent when the household's AI quota for the period is used up — that resets by itself.
Example
curl -b "bryti_session=…" \
"https://bryti.app/api/v1/households/3fa85f64-5717-4562-b3fc-2c963f66afa6/inventory"Example response
200
application/json{
"items": [
{
"foodKey": "string",
"displayName": "string",
"estimatedQuantity": 0,
"unit": "string",
"confidence": 0,
"storageLocation": {},
"usePriority": {},
"lastEvidenceAt": "2026-09-07T16:30:00Z",
"aisle": {},
"asksForDate": false,
"lastEvidenceKind": {}
}
],
"nextCursor": "string",
"total": 0
}