Groups

A group is an optional way to organise transactions beyond categories, for example by project, household, or trip. All routes require a bearer token and live under /api/v1.

Endpoints

Method	Path	Action
GET	/api/v1/groups	List groups
POST	/api/v1/groups	Create a group
GET	/api/v1/groups/{id}	Show one group
PUT	/api/v1/groups/{id}	Update a group
DELETE	/api/v1/groups/{id}	Delete a group

Fields

Field	Type	Required	Notes
name	string	yes	Up to 255 characters.
description	string	no	Up to 255 characters.
icon	string	no	Icon value.
icon_type	string	no	Required with icon: icon, image, or emoji.
client_id	string	no	Client-generated ID, {device_uuid}:{entity_uuid}.
created_at	string	no	ISO 8601.

Create

curl -X POST https://api.your-domain.example/api/v1/groups \
  -H "Authorization: Bearer your-token-here" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Summer trip"
  }'

Response shape

{
  "success": true,
  "message": "Group created",
  "data": {
    "id": 3,
    "name": "Summer trip",
    "description": null,
    "icon": null,
    "client_generated_id": "device-uuid:entity-uuid",
    "last_synced_at": "2026-06-14T09:12:00.000000Z"
  }
}