API Categories

API – Categories

Organize bills into named, color-coded categories with optional icons.

Base path: /api/v1/categories

---

Endpoints

Method	Endpoint	Description
GET	/categories	List categories
POST	/categories	Create a category
GET	/categories/{category}	Get a single category
PUT	/categories/{category}	Update a category
DELETE	/categories/{category}	Delete a category

---

GET /categories

List all categories for the active team.

Query Parameters:

Parameter	Type	Description
search	string	Search name/description
user_id	integer	Filter by user ID
team_id	integer	Filter by team ID
with_bills_count	boolean	Include bill count per category
sort_by	string	Column to sort by
sort_direction	string	asc or desc
per_page	integer	Results per page (max: 100)

Response 200:

{
  "data": [
    {
      "id": 1,
      "name": "Entertainment",
      "description": "Streaming and entertainment services",
      "icon": "🎬",
      "color": "#FF5733",
      "bills_count": 3
    }
  ],
  "links": { ... },
  "meta": { ... }
}

---

POST /categories

Create a new category.

Request:

{
  "name": "Entertainment",
  "description": "Streaming services",
  "icon": "🎬",
  "color": "#FF5733"
}

Field	Type	Required	Description
name	string	Yes	Category name (unique per team)
description	string	No	Optional description
icon	string	No	Emoji or icon identifier
color	string	No	Hex color code (e.g. #FF5733)

Response 201:

{
  "success": true,
  "message": "Category created successfully",
  "data": {
    "id": 1,
    "name": "Entertainment",
    "icon": "🎬",
    "color": "#FF5733"
  }
}

---

GET /categories/{category}

Get a single category by ID.

Response 200:

{
  "success": true,
  "data": {
    "id": 1,
    "name": "Entertainment",
    "description": "Streaming and entertainment services",
    "icon": "🎬",
    "color": "#FF5733"
  }
}

---

PUT /categories/{category}

Update an existing category. All fields are optional.

Request:

{
  "name": "Media & Entertainment",
  "description": "All media subscriptions",
  "icon": "📺",
  "color": "#3498DB"
}

Response 200:

{
  "success": true,
  "message": "Category updated successfully",
  "data": {
    "id": 1,
    "name": "Media & Entertainment"
  }
}

---

DELETE /categories/{category}

Delete a category. Deletion is blocked if the category has bills associated with it. Move or delete those bills first.

Response 200:

{
  "success": true,
  "message": "Category deleted successfully"
}

Response 422 — has associated bills:

{
  "success": false,
  "message": "Cannot delete category with associated bills."
}

---

cURL Examples

TOKEN="YOUR_TOKEN"
BASE="https://bills.msar.me/api/v1"

# List categories with bill counts
curl "$BASE/categories?with_bills_count=true" \
  -H "Authorization: Bearer $TOKEN" -H "Accept: application/json"

# Create a category
curl -X POST "$BASE/categories" \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"name":"Utilities","icon":"💡","color":"#F39C12"}'

# Update a category
curl -X PUT "$BASE/categories/1" \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"name":"Home Utilities"}'

# Delete a category
curl -X DELETE "$BASE/categories/1" \
  -H "Authorization: Bearer $TOKEN" -H "Accept: application/json"