Item Schema

The item object is returned by GET /items (in the data array) and GET /items/{id} (directly under data). The detail endpoint includes additional valuation and photo fields not present in the list.

Example — `GET /items/{id}`

{
  "data": {
    "id": "uuid",
    "name": "Neumann U87",
    "manufacturer": "Neumann",
    "model": "U87",
    "serial_number": "...",
    "barcode": "...",
    "category": "Microphones",
    "tags": ["vintage", "tube"],
    "purchase_price": 2500.00,
    "acquisition_date": "2014-01-15",
    "depreciation_method": "Manual",
    "current_estimated_value": 4800.00,
    "value_source": "market",
    "market_value_as_of": "2026-04-20T00:00:00Z",
    "agreed_value_from_policy": null,
    "reported_insured_value": 4500.00,
    "coverage_state": "under_covered",
    "gap_amount": 300.00,
    "location_id": null,
    "photo_urls": ["https://…"],
    "created_at": "...",
    "updated_at": "..."
  },
  "_meta": {
    "disclaimers": ["…", "…"]
  }
}

Fields

Fields marked Detail only are returned by GET /items/{id} but not by GET /items.

Field	Type	Where	Notes
`id`	uuid	Both	Unique item ID.
`name`	string	Both	Item name.
`manufacturer`	string	Both	—
`model`	string	Both	—
`serial_number`	string	Both	—
`barcode`	string	Both	—
`category`	string	Both	One of the canonical category values — see Category values.
`tags`	string[]	Both	—
`purchase_price`	number	Both	What you paid.
`acquisition_date`	date	Both	When you acquired it.
`depreciation_method`	string	Both	How value is calculated.
`current_estimated_value`	number \| null	Detail only	Computed current value. Null when not available.
`value_source`	enum \| null	Detail only	How the current value was derived (see value_source). Null when not available.
`market_value_as_of`	timestamp	Both	When the market value was last refreshed.
`agreed_value_from_policy`	number \| null	Detail only	Always `null` in v1 (reserved for a future version).
`reported_insured_value`	number	Both	The value you've reported as insured.
`coverage_state`	enum \| null	Detail only	Valuation state (see coverage_state). Null when not available.
`gap_amount`	number \| null	Detail only	Difference between estimated value and insured value. Null when not available.
`location_id`	uuid \| null	Both	Location, when set.
`photo_urls`	string[]	Detail only	Signed photo URLs, valid for 1 hour. Empty array if photos cannot be resolved.
`created_at`	timestamp	Both	—
`updated_at`	timestamp	Both	—

`category` values

category is one of 16 canonical strings. You can filter GET /items by category using the exact strings below — matching is case-sensitive and exact, with no trimming.

Items that don't fit a specific category, or that were created before the current vocabulary was introduced, carry "Other / Uncategorised".

Signal Chain

Microphones · Preamps & Channel Strips · Outboard — Dynamics & EQ · Effects & Reverb Units · Mixing Consoles & Summing · Recorders & Tape Machines · Interfaces & Converters · Monitoring & Headphones

Instruments & Backline

Guitars & Basses · Keyboards & Synthesizers · Drums & Percussion · Amplifiers & Cabinets

Infrastructure

Computers & Software · Cables, Stands & Accessories · Acoustic Treatment & Furniture

Fallback

Other / Uncategorised

The strings are byte-exact. Note the em dash (—, U+2014) in "Outboard — Dynamics & EQ" and the en-GB spelling "Uncategorised". A plain hyphen or "Uncategorized" won't match — and as of migration 071, the database enforces these strings with a CHECK constraint, so an off-vocabulary value written directly to the API is rejected rather than stored.

Category values in stored data

Items are stored with canonical-cased category values. The CSV importer normalises casing on write, so a row imported as microphones is stored and returned as Microphones. When you filter GET /items by category, use the exact canonical strings shown above — the filter is case-sensitive.

`value_source`

How current_estimated_value was derived. One of:

agreed · market · manual · depreciated · purchase_price · replacement_cost · unknown

The value agreed only appears in a future version once policy-backed agreed values ship.

`coverage_state`

One of: fully_covered · under_covered · uninsured · value_unknown.

These are the raw DB-level enum names. They map to the labels you see in the app — Fully Declared, Under-Declared, Not Declared, and Value Unknown — but the API returns the enum names, not the UI labels, so your integration keys off stable identifiers.

When coverage_state is null, the valuation projection was unavailable for that item. The item record is still complete — only the valuation fields are affected.

coverage_state is a documentation state, not an adequacy claim. It tells you whether an item's value is recorded and declared — not whether your insurance policy will actually pay out. Adequacy modeling (multiple policies, deductibles, perils) is not part of the v1 API. Every API response includes this in _meta.disclaimers.

Forward-compatible fields

Some fields (agreed_value_from_policy) exist now but are reserved for future versions — they're present so your integration won't break when those features ship. In v1, agreed_value_from_policy is always null.

Item Schema

Example — GET /items/{id}

Fields

category values

Category values in stored data

value_source

coverage_state

Forward-compatible fields

On this page

Example — `GET /items/{id}`

`category` values

`value_source`

`coverage_state`