# Native inventory reads

Source: https://holofolder.com/app/docs/native-reads

Authenticated physical-copy, collection and stable-slot projections for REST and MCP.

Native developer reads use the current authenticated key or OAuth boundary. Both require `collection:read`, `binders:read`, current owner or partner membership, and Premium or lifetime access. Read-only credentials can use them. They never impersonate a browser cookie session.

| MCP tool                   | REST GET path relative to `/app/api/v1`          |
| -------------------------- | ------------------------------------------------ |
| `list_inventory_items`     | `/inventory/items`                               |
| `get_inventory_item`       | `/inventory/items/{id}`                          |
| `list_storage_collections` | `/storage/collections`                           |
| `list_storage_slots`       | `/storage/collections/{collectionId}/slots`      |
| `get_storage_slot`         | `/storage/collections/{collectionId}/slots/{id}` |

Copies retain stable IDs, recorded card or Pokémon identity, public grading, acquisition time, item revision and current primary placement. Unassigned means no placement. Repeated cards are separate physical copies, including Trainers and Energy. Empty targets and wanted entries are goals, not ownership.

Collection reads include private owner location, counts, grid and independent collection/layout revisions. Slot reads include ordered positions, exact targets, public wanted entries, and item/placement/collection/layout preconditions. Removing a slot retains its owned copy as Unassigned.

Certificates, private label assets, immutable source evidence and private planning/audit state are omitted. Strict output schemas reject accidental private additions. Use [private-preserving commands](https://holofolder.com/app/docs/markdown/native-storage) to edit a redacted projection without erasing hidden fields.

## Pages and current authority

Use `limit` from 1 to 100. Keep filters, limit and credential unchanged when following `nextCursor`. Cursors bind actor, owner, membership, credential/OAuth session, permissions, transport, operation, filters and current revision evidence. Changed state returns `409 stale_native_cursor`; malformed or mismatched cursors return `400 invalid_pagination`. Restart from the first page instead of combining revisions.

Every result declares `projection:"developer-native-v1"`, `completeSnapshot:false`, `inventoryRevision` and `readRevision`. Pages are not complete owner snapshots or fresh-read browser queue acknowledgements. Private complete browser reads use cookie/RLS authority through their separate first-party transport, never a service-role snapshot sent to the browser.

Current credential revocation, owner/membership change and entitlement loss fail closed. Uninitialized inventories and malformed rows return explicit errors rather than empty results. Missing records return `404`.

## Other supported and unsupported scopes

[Copied preset discovery and previews](https://holofolder.com/app/docs/markdown/preset-previews) have a separate read-only contract. [Native commands and recovery](https://holofolder.com/app/docs/markdown/native-storage) retain explicit permissions, CAS preconditions and exact replay requirements.

Saved collection metadata now includes `presetManifest`, the independent copied initial list. Its optional `setScope` preserves reviewed language, verified finish families, promo/exclusion selections and captured coverage evidence. It is historical disclosure, not enforced membership; current targets are in slot reads. No private source/certificate/asset evidence is added. See [Set checklists](https://holofolder.com/app/docs/markdown/set-checklist-drafts).

Collection metadata pages include the saved initial manifest. Their response budget matches the 2 MiB creation limit plus 16 KiB of framing; use a smaller page if several large manifests exceed it. Other native reads retain the 1 MiB response limit.