API support for creating and updating custom fields on items

[milesian01]

What is the problem you are trying to solve with this feature?

I’m looking to automate inventory entry in Homebox using the API. Currently, custom fields can only be created or edited per item via the web UI, but not via the API. This limits bulk entry, automation, and integration with AI-driven workflows.

What is the solution you are proposing?

Enable the creation and editing of custom fields for items through the Homebox API, both on item creation (POST) and item update (PATCH/PUT). This would allow automation tools and scripts to store rich, structured metadata with each item, just like the UI allows.

What alternatives have you considered?

• Manually entering or editing custom fields in the UI after using the API to create items (impractical for bulk workflows).
• Overloading the description or notes fields with extra data (not ideal for structured information).
• Using attachments for metadata (not searchable/filterable as fields).

Additional context

Enabling this would greatly help with bulk imports, integrations, and AI-driven workflows, especially where images and transcribed voice descriptions are being processed programmatically.

Contributions

• I have searched through existing ideas in the discussions to check if this is a duplicate

[tonyaellie]

Update item both put and patch should have the ability to update custom fields.

Anything the frontend can do to the backend is done via the public API.

[tankerkiller125]

Notably you need the put or patch request for the update item capability, with the fields key having something like:

"fields": [
	{
		"name": "Field Name",
		"type": "string",
		"textValue": "This is a text value!"
	}
]

https://homebox.software/en/api/#/paths/v1-items-id/patch

[milesian01]

Thanks for the guidance. Here are my test results from Homebox v0.20.2:

---

Test 1: PATCH to update an existing custom field

Payload:

{
  "fields": [
    {
      "name": "just a test",
      "type": "string",
      "textValue": "updated via API"
    }
  ]
}

API Response:

{
  "fields": [
    {
      "id": "9572e432-8c7b-43a2-971d-a81e3e7a619d",
      "type": "text",
      "name": "just a test",
      "textValue": "asdfasdf",
      "numberValue": 0,
      "booleanValue": false
    }
  ]
}

Field value unchanged in both API and UI.

---

Test 2: PATCH using the field id (also tried type: "text")

Payload:

{
  "fields": [
    {
      "id": "9572e432-8c7b-43a2-971d-a81e3e7a619d",
      "name": "just a test",
      "type": "text",
      "textValue": "updated via API",
      "numberValue": 0,
      "booleanValue": false
    }
  ]
}

API Response: (still unchanged value)

---

Test 3: POST new item with fields

Payload:

{
  "name": "Test Item with Custom Field",
  "description": "Testing field creation via API.",
  "fields": [
    {
      "name": "ai_photo_description",
      "type": "string",
      "textValue": "Should be persisted"
    }
  ]
}

API Response:

{"error":"Unknown Error"}

---

In all cases, field values are not created or updated via API, and there’s either no error or just “Unknown Error” on create. UI behavior matches API response (unchanged or missing fields).

For clarity: Creating new items via API works fine as long as the fields array is omitted. As soon as I include fields (as in Test 3), I get "Unknown Error".

Let me know if I can provide additional info or run any specific test.

[milesian01]

I’ve also found that the standard notes field on items cannot be set or updated via the API (POST or PATCH), even though it’s in the schema and UI.
For example, this PATCH does not update the field:

 curl -X PATCH "http://[host]/api/v1/items/[item_id]" \ -H "Authorization: Bearer [TOKEN]" \ -H "Content-Type: application/json" \ -d '{"notes": "This is a test."}' 

API returns success, but the field remains empty.
This is the same as the behavior with custom fields.

Summary:
Some item fields (custom fields, notes) can only be set via UI, not via API.
Would appreciate clarification or an API fix in a future release!

[tankerkiller125]

You may need to include all of the properties, with PUT, that's at least how the front-end is doing it. I don't have time at this particular moment (writing a final paper for my masters) so I can't take a deep dive into the PATCH method at this time.

[milesian01]

Thanks, your advice to use a full-object PUT with only the allowed fields worked perfectly. Once we excluded all the objects/arrays from GET responses and sent just the expected scalar fields (like name, description, notes, etc.), everything—including the notes field—updated with no issues. Appreciate your help and good luck on your final paper!