Skip to main content

🏷️ Tags API

The Tags API provides a flexible labeling system for organizing and categorizing transactions beyond the primary category system. Tags allow you to add multiple labels to transactions for better organization, filtering, and reporting.

📡 Base URL​

All tags endpoints are prefixed with:

/wp-json/pika/v1/tags

🚀 Endpoints​

Get All Tags​

Retrieve all tags for the authenticated user.

Endpoint: GET /wp-json/pika/v1/tags

Headers:

  • Cookie: Authentication cookie

Response:

[
  {
      "id": "6",
      "name": "Business",
      "color": "#FFFFFF",
      "bgColor": "#2D3748",
      "icon": "briefcase-business",
      "description": "Business transactions",
      "isSystem": true
  },
  {
      "id": "11",
      "name": "IRCTC",
      "color": "#ffffff",
      "bgColor": "#9A3412",
      "icon": "train-front",
      "description": "",
      "isSystem": false
  },
  ...
]

Example Request:

curl -X GET "http://localhost:8000/wp-json/pika/v1/tags" \
  -H "Cookie: pika_token=token"

Get Tag by ID​

Retrieve a specific tag by its ID.

Endpoint: GET /wp-json/pika/v1/tags/{id}

Headers:

  • Cookie: Authentication cookie

Response:

{
    "id": "19",
    "name": "Amazon",
    "color": "#000000",
    "bgColor": "#Cea968",
    "icon": "redo",
    "description": "",
    "isSystem": false
}

Example Request:

curl -X GET http://localhost:8000/wp-json/pika/v1/tags/19 \
  -H "Cookie: pika_token=token"

Create Tag​

Create a new tag.

Endpoint: POST /wp-json/pika/v1/tags

Headers:

  • Cookie: Authentication cookie
  • Content-Type: application/json

Request Body:

{
    "name":"Friends",
    "description":"",
    "icon":"users",
    "bgColor":"#10B981",
    "color":"#ffffff"
}

Required Fields:

  • name (string): Tag name

Optional Fields:

  • color (string): Text color (hex format)
  • bgColor (string): Background color (hex format)
  • icon (string): Icon identifier
  • description (string): Tag description - Used for AI context

Response:

{
    "id": "20",
    "name": "Friends",
    "color": "#ffffff",
    "bgColor": "#10B981",
    "icon": "users",
    "description": "",
    "isSystem": false
}

Example Request:

curl -X POST http://localhost:8000/wp-json/pika/v1/tags \
  -H "Cookie: pika_token=token" \
  -H "Content-Type: application/json" \
  -d '{
    "name":"Friends",
    "description":"",
    "icon":"users",
    "bgColor":"#10B981",
    "color":"#ffffff"
  }'

Update Tag​

Update an existing tag.

Endpoint: PUT /wp-json/pika/v1/tags/{id}

Headers:

  • Cookie: Authentication cookie
  • Content-Type: application/json

Request Body:

{
  "name":"Friends",
  "description":"Sharing and splitting all expenses among my friends.",
  "icon":"users",
  "bgColor":"#3B82F6",
  "color":"#ffffff"
}

Response:

{
    "id": "20",
    "user_id": "2",
    "name": "Friends",
    "icon": "users",
    "color": "#ffffff",
    "bg_color": "#3B82F6",
    "description": "Sharing and splitting all expenses among my friends.",
    "is_active": "1",
    "created_at": "2025-09-02 04:06:12",
    "updated_at": "2025-09-02 04:09:12"
}

Example Request:

curl -X PUT http://localhost:8000/wp-json/pika/v1/tags/20 \
  -H "Cookie: pika_token=token" \
  -H "Content-Type: application/json" \
  -d '{
    "name":"Friends",
    "description":"Sharing and splitting all expenses among my friends.",
    "icon":"users",
    "bgColor":"#3B82F6",
    "color":"#ffffff"
  }'

Delete Tag​

Delete a tag. System tags cannot be deleted.

Endpoint: DELETE /wp-json/pika/v1/tags/{id}

Headers:

  • Cookie: Authentication cookie

Response:

{"message":"Tag deleted successfully"}

Example Request:

curl -X DELETE http://localhost:8000/wp-json/pika/v1/tags/20 \
  -H "Cookie: pika_token=token"

🏷️ Tag Properties​

Icon Options​

Available Icons:

  • All lucide icons

Color Format​

  • Text Color: Hex color code (e.g., #10b981)
  • Background Color: Hex color code (e.g., #ecfdf5)
  • Recommended: Use contrasting colors for readability
  • Accessibility: Consider color blindness when choosing colors

🚨 Error Responses​

Tag Name Not Unique​

This error occurs when you try to create a tag with a name that's already in use, ensuring that all tag names remain distinct.

{
  "code": "tag_name_not_unique",
  "message": "Tag name is not unique.",
  "data": {
    "status": 400
  }
}

Tag Not Found​

This error is returned when an operation is requested for a tag that doesn't exist in the database. 🏷️

{
  "code": "tag_not_found",
  "message": "Tag not found.",
  "data": {
    "status": 404
  }
}

Invalid Tag Name​

This response is used when the provided tag name doesn't meet validation criteria, such as being empty, too long, or containing invalid characters.

{
  "code": "invalid_name",
  "message": "Invalid tag name.",
  "data": {
    "status": 400
  }
}

📚 Related Documentation​