Search inventory items by name/keyword and/or by tag names (AND of both when both given — e.g. everything tagged "power-tool").

Returns items (not locations) with their immediate location, assetId, and the alias custom field (if $HOMEBOX_ALIAS_FIELD is configured). Use get_item for full detail on one result.

Get full detail for one item by assetId (e.g. 000-028), alias custom field, or name (fuzzy fallback: first keyword match). Includes location path, serial, model, purchase, warranty, custom fields, tags, and attachments.

Return the full location tree as an indented outline.

List what is in a location (e.g. a tote or shelf), by location name.

Returns the items directly in that location plus any sub-locations (their names only — not their contents). Set recursive=True to instead walk the whole subtree and return every item nested under it, each tagged with its full location path; use this when a location (e.g. Garage, Basement) has sub-locations you also want the contents of, to avoid querying each one by hand. location is a name or /-separated path (for duplicate names).

List all tag (label) names. Set detail=True to instead return full tag objects (name, description, color, icon, parent tag name) for auditing tag setup — pair with set_tag to edit any of these.

List items whose warranty expires in a date window, or items with a lifetime warranty.

before/after are ISO dates (YYYY-MM-DD): returns items with after <= warrantyExpires <= before. after defaults to TODAY, so already-expired warranties are excluded unless you pass an earlier after. Set lifetime=True to instead list items flagged as lifetime warranty (before/after ignored). Useful for "which warranties expire this year".

Create an inventory item and enrich it in one call.

location is a location name or /-separated path (must exist; use list_locations). tags are tag names (must already exist; use list_tags). fields maps custom-field name -> value; each value's JSON type picks the field type (string -> text, number -> number [integer-coerced], true/false -> boolean). Returns the new assetId and id.

Attach a document to an item OR a location. source is a local file path or an http(s) URL (downloaded then uploaded). doc_type is e.g. manual, attachment, warranty, receipt, photo. identifier is assetId/alias/name for an item, or a location name/path (tried as a fallback if no item matches). Set primary=True to make a photo the entity's primary image — e.g. a "this is the spot" wayfinding photo on a shelf/tote location (doc_type="photo").

List an item's (or location's) attachments with their ids — the handle needed by get_attachment / rename_attachment / delete_attachment. identifier is assetId / alias field / name, or a location name/path.

Download one attachment (see list_attachments for ids) to a local path, so its content — e.g. an attached manual or receipt — can be read. save_to is a directory (keeps a name based on the title) or a full file path.

Update an attachment's title, type (manual/attachment/warranty/receipt/ photo), or primary flag (see list_attachments for ids). Only the args you pass change; the rest is re-sent as-is.

Bulk-create items and locations from a Homebox CSV (multipart import).

This is the bulk creator for the photo-intake pipeline — one request imports everything, avoiding ~4 API calls per item. Recognized columns: HB.name, HB.location (path e.g. "Garage/Loft" — AUTO-CREATES the hierarchy), HB.tags (must already exist; see list_tags), HB.quantity, HB.serial_number, HB.model_number, HB.manufacturer, HB.notes, HB.purchase_price, HB.purchase_from, HB.purchase_time, HB.warranty_expires, HB.field. (custom fields). A location-only row (HB.location set, contents described elsewhere) creates just the location. After import, call finalize_photos if you attached photos. Returns the count of data rows submitted.

Create a LOCATION entity (e.g. a new tote/bin/shelf) to bootstrap a new storage spot. parent is an existing location name or /-separated path (optional); description is optional free text, e.g. a contents summary (≤1000 chars). Returns the new location id. For deep paths, prefer import_csv's HB.location auto-create.

Edit a LOCATION's metadata (find it by current name or /-path): rename, description (e.g. a contents manifest), notes, tags, custom fields (values typed by JSON type). Only the args you pass change; other fields are preserved. parent moves it under another location; clear_parent=True moves it to the root. entity_type (e.g. "Item") converts a mis-created entity — rare. asset_id overrides the auto-assigned assetId.

Set warranty info on an existing item (assetId / alias field / exact name).

expires is a YYYY-MM-DD date (warranty end), lifetime flags a lifetime warranty, details is a short terms summary (e.g. "limited lifetime, test/measurement instruments excluded"). Only the args you pass change; other fields are preserved.

Create or update custom fields on an existing item (assetId / alias field / exact name).

fields maps custom-field name -> value; each value's JSON type picks the field type (string -> text, number -> number [integer-coerced — the API 500s on float number values], true/false -> boolean). Upsert semantics: named fields are created or overwritten; other fields are preserved.

Set manufacturer/model/serial on an existing item (assetId / alias field / exact name).

Only the args you pass change; other fields are preserved. Use when a nameplate/label photo reveals a serial number or a model-number correction after the item was created.

Move an item to another location (assetId / alias field / exact name).

location is a location name or /-separated path (see list_locations). Uses a partial PATCH, so nothing else on the item changes.

General item editor (assetId / alias field / exact name): rename, edit description/notes/quantity, purchase info, insured/archived flags, and custom fields in one call.

Only the args you pass are changed. Quantity-only changes go via a partial PATCH; anything else uses a full-body PUT that preserves the rest of the item (the 0.26 PUT-clears gotcha). fields maps custom-field name -> value, typed by JSON type (see set_fields). To move an item use move_item; for warranty/identity/tags see set_warranty/set_identity/set_tags.

Record that an item was sold (assetId / alias field / exact name): price, buyer, YYYY-MM-DD date, notes — only the args you pass are set. clear=True instead erases all four sold fields (un-sells the item). Other fields are preserved. Pair with set_item(archived=True) if the item should also leave active inventory.

Duplicate an existing item (assetId / alias field / exact name), e.g. "I bought a second one". prefix is prepended to the new item's name. Copies custom fields by default; attachments and maintenance log only on request. NOTE: copied custom fields include the alias field verbatim — if you use one, give the copy its own value via set_fields right after. Returns the new item's id and assetId.

Add, remove, or replace tags on an existing item (assetId / alias field / exact name).

mode is "add" (default — merges with the item's existing tags), "remove" (drops just the named tags, keeps the rest), or "replace" (item ends up with exactly these tags, nothing else). Tag names are matched case-insensitively against list_tags and auto-created if they don't exist yet. Everything else on the item is untouched (partial PATCH).

Create or edit a tag's own metadata — NOT what's tagged on an item (see set_tags for that). Matches name case-insensitively against list_tags; creates the tag if it doesn't exist yet. Only the args you pass are changed. parent nests this tag under another (existing) tag name, for grouping related tags in the Homebox UI (e.g. several condition-* tags under a "condition" parent); pass clear_parent=True to un-nest it. Use list_tags(detail=True) to see current tag metadata first.

PERMANENTLY delete an item (assetId / alias field / exact name), including its attachments. confirm must equal the item's exact name. There is no undo.

PERMANENTLY delete a location (name or /-separated path). confirm must equal the location's exact name. A location that still contains items or sub-locations is refused unless confirm_nonempty=True — sub-locations are deleted with it, and its items are ORPHANED to the top level (not deleted). There is no undo.

PERMANENTLY delete a tag itself (it is removed from every tagged item; the items survive). confirm must equal the tag's exact name.

PERMANENTLY delete one attachment from an item or location (see list_attachments for ids). confirm must equal the attachment's exact title.

Save a printable Homebox label PNG (QR + readable name) for a location or item, e.g. to stick on a tote/bin. kind is "location", "item", or "asset". For location/item, identifier is a name or slug (resolved to an id); for asset it's the assetId (e.g. 000-028). Saves to out_dir (default: $HOMEBOX_LABEL_DIR, else the current directory). Returns the saved file path.

Save a raw QR-code JPEG encoding arbitrary data (e.g. a deep link). For tote labels prefer generate_label (adds the readable name). Saves to out_dir (default: $HOMEBOX_LABEL_DIR, else the current directory). Returns the saved file path.

Return {field_value: assetId} for every entity that has the named custom field — a one-pass index for DEDUPE before a bulk import (q does not index custom fields, so this scans every entity). field_name defaults to $HOMEBOX_ALIAS_FIELD. assetId may be empty for un-asset'd rows. Deliberately uncapped: a truncated dedupe index causes duplicates, so expect a large result on a large inventory.

Finalize after a bulk photo attach: ensure every entity with photos has a primary image, then generate any missing thumbnails. (Wraps the set-primary-photos and create-missing-thumbnails actions, which are always run as a pair.)

Look up a UPC/EAN barcode → name/manufacturer/model (optional path for boxed goods). Thin wrapper over GET /products/search-from-barcode.

Add a maintenance-log entry to an item (assetId / alias field / exact name) — e.g. "changed the mower oil today" (completed_date) or "sharpen blades in spring" (scheduled_date). Dates are YYYY-MM-DD; cost is a number. Returns the new entry's id.

List maintenance entries — for one item (assetId / alias field / name) or, with no identifier, across the whole inventory ("what maintenance is due?"). status is "scheduled" (upcoming), "completed", or "both".

Edit a maintenance entry (see list_maintenance for ids) — e.g. mark a scheduled entry completed by setting completed_date. Only the args you pass change; the rest of the entry is re-sent as-is (the update is a full PUT).

PERMANENTLY delete one maintenance entry (see list_maintenance for ids). confirm must equal the entry's exact name.

Inventory statistics — the cheap way to answer "what's my inventory worth?" without scanning items. by is: totals — counts (items/locations/tags/users), total purchase price, items with warranty; locations — total value per location; tags — total value per tag; purchase-price — value over time (optional YYYY-MM-DD start/end).

Export the whole inventory as a Homebox CSV (the complement of import_csv; also a quick backup). Saves to save_to (file path or directory; default: homebox-export.csv in the current directory) and returns the path and row count.

Discover the custom-field schema actually in use: with no arg, all custom-field NAMES across the inventory; with field, the distinct VALUES of that field ({"total", "values"}, capped at limit). Useful before set_fields/field_index on an unfamiliar instance.