Overview
The Tags API allows you to create, read, update, and delete tags for organizing transactions. Tags help categorize and filter your financial data.
Authentication
- List/Show: Requires
read or read_write scope
- Create/Update/Delete: Requires
read_write scope
Endpoints
Retrieve all tags belonging to the family.
[
{
"id": "1",
"name": "Groceries",
"color": "#3b82f6",
"created_at": "2024-01-10T08:00:00Z",
"updated_at": "2024-01-10T08:00:00Z"
},
{
"id": "2",
"name": "Travel",
"color": "#e99537",
"created_at": "2024-01-15T12:30:00Z",
"updated_at": "2024-01-15T12:30:00Z"
}
]
curl -X GET https://your-domain.com/api/v1/tags \
-H "X-Api-Key: your_api_key_here"
Get a Specific Tag
Retrieve a single tag by ID.
The unique identifier of the tag
{
"id": "1",
"name": "Groceries",
"color": "#3b82f6",
"created_at": "2024-01-10T08:00:00Z",
"updated_at": "2024-01-10T08:00:00Z"
}
curl -X GET https://your-domain.com/api/v1/tags/1 \
-H "X-Api-Key: your_api_key_here"
Create a Tag
Create a new tag for the family.
Tag parameters
Hex color code (e.g., #3b82f6). If not provided, a random color will be assigned.
201 Created.
{
"tag": {
"name": "Vacation",
"color": "#4da568"
}
}
{
"id": "3",
"name": "Vacation",
"color": "#4da568",
"created_at": "2024-03-04T10:00:00Z",
"updated_at": "2024-03-04T10:00:00Z"
}
curl -X POST https://your-domain.com/api/v1/tags \
-H "X-Api-Key: your_api_key_here" \
-H "Content-Type: application/json" \
-d '{
"tag": {
"name": "Vacation",
"color": "#4da568"
}
}'
Update a Tag
The unique identifier of the tag
{
"id": "3",
"name": "Summer Vacation",
"color": "#4da568",
"created_at": "2024-03-04T10:00:00Z",
"updated_at": "2024-03-04T11:30:00Z"
}
curl -X PATCH https://your-domain.com/api/v1/tags/3 \
-H "X-Api-Key: your_api_key_here" \
-H "Content-Type: application/json" \
-d '{
"tag": {
"name": "Summer Vacation"
}
}'
Delete a Tag
The unique identifier of the tag to delete
204 No Content on success.
Example Request
curl -X DELETE https://your-domain.com/api/v1/tags/3 \
-H "X-Api-Key: your_api_key_here"
Response Fields
Unique identifier for the tag
Hex color code for visual display
ISO 8601 timestamp when the tag was created
ISO 8601 timestamp when the tag was last updated
Available Colors
If you don’t specify a color when creating a tag, one of these colors will be randomly assigned:
#e99537 (Orange)#4da568 (Green)#6471eb (Blue)#db5a54 (Red)#df4e92 (Pink)#c44fe9 (Purple)#eb5429 (Orange Red)#61c9ea (Cyan)#805dee (Violet)#6ad28a (Light Green)
Error Responses
{
"error": "Tag not found"
}
{
"error": "Name can't be blank"
}
{
"error": "insufficient_scope",
"message": "This action requires the 'read_write' scope"
}
{
"error": "Failed to create tag"
}
Validation Rules
- Tag names must be unique within a family
- Color must be a valid hex code in the format
#RRGGBB
- Tag names cannot be empty