Tag

• Allowed query parameters
• Available Colors
• Tag Groups
• Create a tag
• Update a tag
• Retrieve a tag
• Delete a tag
• List tags

Tags are organizational labels that can be applied to expenses and companies for categorization and filtering. Tags support grouping through underscore notation (e.g., "Priority_High", "Priority_Low") and have customizable colors from a predefined palette.

Allowed query parameters

Filters

Filter	Type	Description
search	String	Full-text search on tag names
type	String	Filter by tag type (e.g., expense for expense-related tags)

Sorting

name, order, created_at

Includes

None

Available Colors

Tags can use the following predefined colors. When creating a tag without specifying a color, the system automatically assigns an unused color from this palette:

blue, indigo, purple, pink, red, orange, yellow, green, teal, lime, cyan, muted

Tag Groups

Tags containing underscores are treated as grouped tags, where the text before the underscore represents the group name and the text after represents the value:

• Priority_High becomes group: {"name": "Priority", "value": "High"}
• Status_Pending becomes group: {"name": "Status", "value": "Pending"}
• Category_Travel becomes group: {"name": "Category", "value": "Travel"}

Create a tag

post

/tag

Attribute (* required)	Type	Description
name *	String	Tag name (max 50 characters)
color	String?	Tag color from available palette (auto-assigned if not provided)

Example request

{
    "name": "Priority_High",
    "color": "red"
}

Example response

// HTTP 201 Created
{
    "id": "a7B9mK3xQ2",
    "name": "Priority_High",
    "type": null,
    "color": "red",
    "group": {
        "name": "Priority",
        "value": "High"
    }
}

Update a tag

put

/tag/{id}

Attribute	Type	Description
name	String?	Tag name (max 50 characters)
color	String?	Tag color from available palette
order	Integer?	Tag order for sorting (minimum: 0)

Example request

{
    "name": "Priority_Critical",
    "color": "red",
    "order": 1
}

Example response

// HTTP 200 OK
{
    "id": "a7B9mK3xQ2",
    "name": "Priority_Critical",
    "type": null,
    "color": "red",
    "group": {
        "name": "Priority",
        "value": "Critical"
    }
}

Retrieve a tag

get

/tag/{id}

Example response

// HTTP 200 OK
{
    "id": "a7B9mK3xQ2",
    "name": "Priority_High",
    "type": null,
    "color": "red",
    "group": {
        "name": "Priority",
        "value": "High"
    }
}

Delete a tag

delete

/tag/{id}

When a tag is deleted, it is automatically detached from all associated expenses and companies.

Example response

// HTTP 204 No Content

List tags

get

/tag

Returns tags sorted by their order field by default. Read more about Pagination, Filtering, Sorting and Includes on the Introduction page.

Example response

// HTTP 200 OK
{
    "data": [
        {
            "id": "a7B9mK3xQ2",
            "name": "Priority_High",
            "type": null,
            "color": "red",
            "group": {
                "name": "Priority",
                "value": "High"
            }
        },
        {
            "id": "m9X2pL8wN5",
            "name": "Priority_Low",
            "type": null,
            "color": "yellow",
            "group": {
                "name": "Priority",
                "value": "Low"
            }
        },
        {
            "id": "k4V7rD1zE8",
            "name": "Travel",
            "type": "expense",
            "color": "blue",
            "group": null
        }
    ],
    "links": {
        "first": "http://localhost:8000/api/tag?page=1",
        "last": "http://localhost:8000/api/tag?page=1",
        "prev": null,
        "next": null
    },
    "meta": {
        "current_page": 1,
        "from": 1,
        "last_page": 1,
        "path": "http://localhost:8000/api/tag",
        "per_page": 25,
        "to": 3,
        "total": 3,
        "allowed_sorts": ["name", "order", "created_at"],
        "allowed_filters": ["search", "type"],
        "summary": null
    }
}