Skip to main content

​
Introduction

The BillBuddy API is a RESTful API that allows you to manage groups, expenses, and settlements for splitting bills among friends. All API endpoints return JSON responses and use standard HTTP response codes.

​
Base URL

The API is served at: 
http://localhost:5000/api
All endpoints are prefixed with /api. For example, to register a user: 
POST http://localhost:5000/api/auth/register

​
Request Format

​
Content Type

All POST and PUT requests must include a Content-Type: application/json header and send data as JSON in the request body. 
curl -X POST http://localhost:5000/api/auth/register \
  -H "Content-Type: application/json" \
  -d '{"name":"John Doe","email":"john@example.com","password":"secret123"}'

​
Request Size Limit

The API accepts request payloads up to 10MB in size.

​
Response Format

All API responses are returned in JSON format. Successful responses typically include the requested data directly or wrapped in a response object.

​
Success Response

Authentication Success: 
{
  "success": true,
  "token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9..."
}
Resource Response: 
{
  "_id": "507f1f77bcf86cd799439011",
  "name": "Weekend Trip",
  "description": "Expenses for our weekend getaway",
  "members": [...],
  "createdAt": "2024-01-15T10:30:00.000Z"
}
List Response: 
[
  {
    "_id": "507f1f77bcf86cd799439011",
    "description": "Dinner at restaurant",
    "amount": 120.50
  },
  {
    "_id": "507f1f77bcf86cd799439012",
    "description": "Groceries",
    "amount": 45.00
  }
]

​
Error Handling

The API uses standard HTTP status codes to indicate the success or failure of requests.

​
HTTP Status Codes

​
200
OK
Request succeeded. The response body contains the requested data.
​
201
Created
Resource successfully created. The response body contains the new resource.
​
400
Bad Request
Invalid request data or validation error.
​
401
Unauthorized
Missing or invalid authentication token.
​
403
Forbidden
Authenticated but not authorized to access the resource.
​
404
Not Found
The requested resource does not exist.
​
500
Server Error
An unexpected error occurred on the server.

​
Error Response Format

Error responses include a message field describing the error: 
{
  "message": "User already exists"
}

​
Common Error Messages

Validation Errors: 
{
  "message": "Invalid JSON payload"
}
Authentication Errors: 
{
  "message": "Not authorized, no token"
}

{
  "message": "Not authorized"
}
Authorization Errors: 
{
  "message": "Not authorized to access this group"
}
Resource Not Found: 
{
  "message": "Group not found"
}
Server Errors: 
{
  "message": "Server error"
}

​
CORS Configuration

The API supports Cross-Origin Resource Sharing (CORS) with the following configuration:
  • Allowed Origins: http://localhost:5173, http://127.0.0.1:5173
  • Allowed Methods: GET, POST, PUT, DELETE, OPTIONS
  • Allowed Headers: Content-Type, Authorization, Accept
  • Credentials: Supported

​
Rate Limiting

Currently, the API does not implement rate limiting. This may be added in future versions.

​
Example Request

Here’s a complete example of creating a new expense: 
curl -X POST http://localhost:5000/api/expenses \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9..." \
  -d '{
    "description": "Dinner at Italian restaurant",
    "amount": 120.50,
    "group": "507f1f77bcf86cd799439011",
    "splitAmong": ["507f191e810c19729de860ea", "507f191e810c19729de860eb"],
    "category": "Food"
  }'
Response (201 Created): 
{
  "_id": "507f1f77bcf86cd799439013",
  "description": "Dinner at Italian restaurant",
  "amount": 120.50,
  "paidBy": "507f191e810c19729de860ea",
  "group": "507f1f77bcf86cd799439011",
  "splitAmong": [
    "507f191e810c19729de860ea",
    "507f191e810c19729de860eb"
  ],
  "category": "Food",
  "date": "2024-01-15T18:30:00.000Z"
}

​
Next Steps

Authentication

Learn how to authenticate and obtain access tokens

Groups

Manage groups and their members

Expenses

Create and track expenses

Build docs developers (and LLMs) love

Get started for freeTalk to us