API Overview

API Overview

Bill Organizer exposes a versioned REST API built on Laravel Sanctum for token-based authentication. The API is suitable for mobile apps, third-party integrations, and external automation.

---

Base URL

https://bills.msar.me/api/v1

For local development:

http://localhost:8000/api/v1

---

API Version

Current version: v1

The version prefix is part of every endpoint URL (/api/v1/...). When breaking changes are introduced, a new version (/api/v2/...) will be released while v1 remains available for backward compatibility.

---

Authentication

All endpoints except /auth/login and /auth/register require a Bearer token in the Authorization header.

Authorization: Bearer {your_token}
Content-Type: application/json
Accept: application/json

Authentication Levels

Level	Routes	Requirement
Public	/auth/login, /auth/register	None
Authenticated	All other routes	Valid Bearer token
Team-scoped	Bills, Categories, Transactions, Notes	Valid token + active team

Tokens are issued on login or registration and must be stored securely by the client. Tokens do not expire by default but can be configured in config/sanctum.php.

---

Standard Response Envelope

All responses (success and error) use a consistent JSON envelope:

Success

{
  "success": true,
  "message": "Operation successful",
  "data": { }
}

Error

{
  "success": false,
  "message": "Error description",
  "errors": {
    "field_name": ["Validation error message"]
  }
}

---

HTTP Status Codes

Code	Meaning
200	OK — request succeeded
201	Created — resource created successfully
400	Bad Request
401	Unauthorized — missing or invalid token
403	Forbidden — insufficient permissions
404	Not Found
422	Unprocessable Entity — validation error
429	Too Many Requests — rate limit exceeded
500	Server Error

---

Pagination

All list endpoints return paginated responses. The default page size is 15 with a maximum of 100.

{
  "data": [ ... ],
  "links": {
    "first": "https://bills.msar.me/api/v1/bills?page=1",
    "last":  "https://bills.msar.me/api/v1/bills?page=5",
    "prev":  null,
    "next":  "https://bills.msar.me/api/v1/bills?page=2"
  },
  "meta": {
    "current_page": 1,
    "from": 1,
    "last_page": 5,
    "per_page": 15,
    "to": 15,
    "total": 67
  }
}

Pagination Query Parameters

Parameter	Description	Default	Max
page	Page number	1	—
per_page	Results per page	15	100

---

Sorting

All list endpoints support multi-column sorting:

Parameter	Description	Default
sort_by	Column name to sort by	Varies by resource
sort_direction	asc or desc	asc

Example:

GET /api/v1/bills?sort_by=due_date&sort_direction=desc

---

Search

All list endpoints support a search query parameter with two modes:

Mode	Syntax	Example
Default	?search=value	?search=Netflix
Column-specific	?search=column:value	?search=title:Netflix

GET /api/v1/bills?search=Netflix
GET /api/v1/bills?search=title:Netflix
GET /api/v1/bills?search=amount:15.99

---

Rate Limiting

Client type	Limit
Authenticated	60 requests per minute
Guest (unauthenticated)	10 requests per minute

Rate limit headers are included in every response:

X-RateLimit-Limit: 60
X-RateLimit-Remaining: 59
X-RateLimit-Reset: 1609459200

When the limit is exceeded, the API returns 429 Too Many Requests. Implement exponential backoff in your client to handle this gracefully.

---

Endpoints Summary

Resource	Endpoints	Total
Authentication	Login, Register, Logout, Profile (GET/PUT)	5
Bills	CRUD + Mark as Paid + Upcoming	7
Categories	CRUD	5
Transactions	CRUD + Receipt	6
Teams	CRUD + Members + Switch	8
Notes	CRUD	5
Webhooks	CRUD + Deliveries + Retry	8
Users	List + Show	2
Total		46

---

Best Practices

1. Always include Accept: application/json header to receive JSON responses.
2. Store tokens securely — never expose them in client-side source code or version control.
3. Use HTTPS in production.
4. Handle 429 responses with exponential backoff.
5. Use filtering and pagination to keep response sizes small.
6. Use the column:value search syntax for precise queries.
7. Switch the active team (POST /teams/{team}/switch) before making team-scoped requests.

---

Related Pages

• API Setup — environment configuration, Postman collection, cURL examples
• API – Authentication
• API – Bills
• API – Categories
• API – Transactions
• API – Teams
• API – Notes
• API – Webhooks
• API – Users