Browse the reference

Categories

7 endpoints

List categories in this household

GET/households/{householdId}/categories

read:categories

Example request

bash

curl -H "Authorization: Bearer vokse_sk_…" \     -X GET https://api.vokse.ai/households/current/categories

Response200 · Success

Create a category in a group

POST/households/{householdId}/categories

write:categories

Request body

json

{  "name": "Groceries",  "groupId": "01J8ME9C4TJ6WX2K8V5R3Q7S9Z"}

Example request

bash

curl -H "Authorization: Bearer vokse_sk_…" \     -H "Content-Type: application/json" \     -H "Idempotency-Key: $(uuidgen)" \     -X POST https://api.vokse.ai/households/current/categories \     -d '{"name":"Groceries","groupId":"01J8ME9C4TJ6WX2K8V5R3Q7S9Z"}'

Response201 · Success

Update a category

PATCH/households/{householdId}/categories/{categoryId}

write:categories

Parameters

Name	In	Required
categoryId	path	Required

Request body

json

{  "name": "Groceries & household"}

Example request

bash

curl -H "Authorization: Bearer vokse_sk_…" \     -H "Content-Type: application/json" \     -H "Idempotency-Key: $(uuidgen)" \     -X PATCH https://api.vokse.ai/households/current/categories/{categoryId} \     -d '{"name":"Groceries & household"}'

Response200 · Success

Soft-delete a category

DELETE/households/{householdId}/categories/{categoryId}

write:categories

Parameters

Name	In	Required
categoryId	path	Required

Example request

bash

curl -H "Authorization: Bearer vokse_sk_…" \     -X DELETE https://api.vokse.ai/households/current/categories/{categoryId}

Response204 · No content

Atomically reorder categories across groups

POST/households/{householdId}/categories/reorder

write:categories

Example request

bash

curl -H "Authorization: Bearer vokse_sk_…" \     -H "Idempotency-Key: $(uuidgen)" \     -X POST https://api.vokse.ai/households/current/categories/reorder

Response204 · No content

Suggest catalogue icons for category names. Layered resolver (emoji hint → multilingual dictionary → persistent cache → AI); never fails: unknown names get the default icon with confidence 0.

POST/households/{householdId}/icons/suggest

read:categories

Example request

bash

curl -H "Authorization: Bearer vokse_sk_…" \     -H "Idempotency-Key: $(uuidgen)" \     -X POST https://api.vokse.ai/households/current/icons/suggest

Response200 · Success

Seed a starter category pack into this household. Idempotent by name: existing groups are reused and existing categories skipped, so re-running never duplicates the structure. Names are created in the household data language.

POST/households/{householdId}/starter-pack

write:categories

Request body

json

{  "packId": "essentials"}

Example request

bash

curl -H "Authorization: Bearer vokse_sk_…" \     -H "Content-Type: application/json" \     -H "Idempotency-Key: $(uuidgen)" \     -X POST https://api.vokse.ai/households/current/starter-pack \     -d '{"packId":"essentials"}'

Response201 · Success