Skip to content

API Migration Guide — Entity Merge

This guide is for third-party developers integrating with the Homebox REST API. It covers all breaking changes introduced by the entity merge, where items and locations were unified into a single “entities” API.

Items and locations are now both entities, differentiated by a user-definable entity type. The separate /v1/items/* and /v1/locations/* endpoints have been replaced by a unified /v1/entities/* API. A new /v1/entity-types API lets you manage the types that determine entity behavior.

All of the following endpoints have been removed:

  • GET/POST /v1/items, GET/PUT/PATCH/DELETE /v1/items/{id}
  • GET/POST /v1/locations, GET/PUT/DELETE /v1/locations/{id}
  • GET /v1/locations/tree
  • GET /v1/items/{id}/path, POST /v1/items/{id}/duplicate
  • POST/PUT/DELETE/GET /v1/items/{id}/attachments/*
  • GET/POST /v1/items/{id}/maintenance
  • GET /v1/items/export, POST /v1/items/import
  • GET /v1/items/fields, GET /v1/items/fields/values
Method Path Description
GET /v1/entities Query entities. Returns items by default; pass ?isLocation=true for locations.
POST /v1/entities Create an entity. Set entityTypeId to control whether it’s an item or location.
GET /v1/entities/{id} Get a single entity by ID.
PUT /v1/entities/{id} Full update of an entity.
PATCH /v1/entities/{id} Partial update (quantity, parent, tags).
DELETE /v1/entities/{id} Delete an entity.
POST /v1/entities/{id}/duplicate Duplicate an entity.
GET /v1/entities/{id}/path Get the full hierarchy path to an entity.
GET /v1/entities/tree Get the location/item tree (replaces /v1/locations/tree).
GET /v1/entities/export Export entities as CSV.
POST /v1/entities/import Import entities from CSV.
GET /v1/entities/fields Get all custom field names.
GET /v1/entities/fields/values Get all values for a given custom field.
Method Path Description
POST /v1/entities/{id}/attachments Upload an attachment.
GET /v1/entities/{id}/attachments/{attachment_id} Download an attachment file.
PUT /v1/entities/{id}/attachments/{attachment_id} Update attachment metadata.
DELETE /v1/entities/{id}/attachments/{attachment_id} Delete an attachment.
Method Path Description
GET /v1/entities/{id}/maintenance Get maintenance log for an entity.
POST /v1/entities/{id}/maintenance Create a maintenance entry.
Method Path Description
GET /v1/entity-types List all entity types for the current group.
POST /v1/entity-types Create an entity type.
PUT /v1/entity-types/{id} Update an entity type.
DELETE /v1/entity-types/{id} Delete an entity type (fails if entities still use it).
Parameter Type Default Description
isLocation bool false true returns locations only (with itemCount on each). Omit or false for items only.
filterChildren bool false When isLocation=true, return only root locations (those with no parent).
parentIds []string — Filter by parent entity ID. Replaces the old locations parameter.
q string — Search query.
tags []string — Filter by tag IDs.
negateTags bool false Exclude entities matching the given tags.
page int — Page number for pagination.
pageSize int — Items per page.
orderBy string — Sort field (name, createdAt, updatedAt).
includeArchived bool false Include archived entities.
fields []string — Filter by custom field values (fieldName=value format).
Parameter Type Default Description
withItems bool false Include items (non-location entities) in the tree.
Parameter Type Description
field string Required. The custom field name to get values for.
{
"name": "My Item",
"description": "A description",
"quantity": 1,
"parentId": "uuid-of-parent-location",
"entityTypeId": "uuid-of-entity-type",
"tagIds": ["uuid-1", "uuid-2"]
}

Changes from the old POST /v1/items:

Old Field New Field Notes
locationId parentId The parent entity (typically a location).
— entityTypeId New. Controls whether this is an item or location. Omit to default to the group’s “Item” type. Pass a location-type entity type ID to create a location.
Old Field New Field
locationId parentId
syncChildItemsLocations syncChildEntityLocations
— entityTypeId (optional — change the entity’s type)
Old Field New Field
locationId parentId
— entityTypeId (optional)

Create Entity Type — POST /v1/entity-types

Section titled “Create Entity Type — POST /v1/entity-types”
{
"name": "Shelf",
"isLocation": true,
"icon": "",
"defaultTemplateId": "uuid-or-omit"
}
  • isLocation — if true, entities of this type act as containers (appear in the location tree, can hold other entities).
  • defaultTemplateId — optional. When set, creating an entity with this type will auto-apply the template’s defaults.

The location field has been replaced by parent. A new entityType field is included.

{
"id": "...",
"name": "My Item",
"parent": {
"id": "...",
"name": "Living Room"
},
"entityType": {
"id": "...",
"name": "Item",
"isLocation": false
},
"itemCount": 0,
"tags": [],
"quantity": 1,
"purchasePrice": 0,
"assetId": "001-234",
"insured": false,
"archived": false,
"createdAt": "...",
"updatedAt": "..."
}
  • parent replaces location. It references the parent entity (which is typically a location-type entity for items).
  • entityType is new. It contains the type’s id, name, and isLocation flag.
  • itemCount is populated only when querying with ?isLocation=true. It contains the count of non-location child entities.

The children field now only includes location-type children (sub-containers). To get items inside a location, query GET /v1/entities?parentIds=[locationId].

{
"id": "...",
"name": "Shelf",
"description": "",
"isLocation": true,
"icon": "",
"defaultTemplateId": "...",
"defaultTemplate": {
"id": "...",
"name": "Default Shelf Template",
"description": ""
},
"createdAt": "...",
"updatedAt": "..."
}

All GET /v1/entities responses (both items and locations) return a consistent paginated shape:

{
"page": 1,
"pageSize": 50,
"total": 120,
"items": [],
"totalPrice": 1234.56
}

totalPrice is the sum of purchasePrice * quantity for non-sold items in the result set.

The item.mutation and location.mutation events have been merged into a single event:

{
"event": "entity.mutation",
"data": {
"gid": "group-uuid"
}
}

Subscribe to entity.mutation to be notified of any entity change (create, update, delete) regardless of whether it’s an item or location.

  1. Update all endpoint URLs — replace /v1/items/* and /v1/locations/* with /v1/entities/*
  2. Update create/update payloads — locationId → parentId, syncChildItemsLocations → syncChildEntityLocations
  3. Update response parsing — item.location → item.parent, and expect entityType on all entity responses
  4. Update query parameters — ?locations= → ?parentIds=, use ?isLocation=true to query locations
  5. Update WebSocket listeners — listen for entity.mutation instead of item.mutation / location.mutation
  6. Use /v1/entity-types to query available types if your integration needs to create entities with specific types