Expense API Reference

Complete reference for all Expense API endpoints.

Base URL

https://api.example.com/expense/v1

Authentication

All requests must include an Authorization header:

Authorization: Bearer YOUR_API_KEY

Endpoints

Expenses

GET /expenses

Retrieve a list of expenses.

Parameters:

• limit (optional): Number of results to return (default: 50, max: 100)
• offset (optional): Number of results to skip (default: 0)
• category (optional): Filter by category
• start_date (optional): Filter expenses from this date (YYYY-MM-DD)
• end_date (optional): Filter expenses to this date (YYYY-MM-DD)

Example Request:

curl -H "Authorization: Bearer YOUR_API_KEY" \
     "https://api.example.com/expense/v1/expenses?limit=10&category=food"

Example Response:

{
  "data": [
    {
      "id": "exp_123456",
      "amount": 25.50,
      "description": "Coffee and pastry",
      "category": "food",
      "date": "2025-01-01",
      "created_at": "2025-01-01T10:30:00Z",
      "updated_at": "2025-01-01T10:30:00Z"
    }
  ],
  "pagination": {
    "limit": 10,
    "offset": 0,
    "total": 1,
    "has_more": false
  }
}

POST /expenses

Create a new expense.

Request Body:

{
  "amount": 25.50,
  "description": "Coffee and pastry",
  "category": "food",
  "date": "2025-01-01"
}

Required Fields:

• amount: Decimal amount of the expense
• description: Text description of the expense
• category: Category slug (see Categories)
• date: Date in YYYY-MM-DD format

GET /expenses/{id}

Retrieve a specific expense by ID.

Example Request:

curl -H "Authorization: Bearer YOUR_API_KEY" \
     "https://api.example.com/expense/v1/expenses/exp_123456"

PUT /expenses/{id}

Update an existing expense.

Request Body: Same as POST /expenses

DELETE /expenses/{id}

Delete an expense.

Example Request:

curl -X DELETE \
     -H "Authorization: Bearer YOUR_API_KEY" \
     "https://api.example.com/expense/v1/expenses/exp_123456"

Categories

GET /categories

Retrieve all available expense categories.

Example Response:

{
  "data": [
    {
      "slug": "food",
      "name": "Food & Dining",
      "description": "Meals, groceries, and dining out"
    },
    {
      "slug": "transport",
      "name": "Transportation",
      "description": "Gas, public transit, rideshare"
    }
  ]
}

Error Responses

All errors follow this format:

{
  "error": {
    "code": "VALIDATION_ERROR",
    "message": "The amount field is required.",
    "details": {
      "field": "amount",
      "reason": "required"
    }
  }
}

Common Error Codes

• VALIDATION_ERROR (400): Invalid request data
• UNAUTHORIZED (401): Invalid or missing API key
• NOT_FOUND (404): Resource not found
• RATE_LIMITED (429): Too many requests
• INTERNAL_ERROR (500): Server error

Rate Limits

• 1000 requests per hour per API key
• Rate limit headers are included in all responses:
  • X-RateLimit-Limit: Request limit per hour
  • X-RateLimit-Remaining: Requests remaining in current window
  • X-RateLimit-Reset: Unix timestamp when the rate limit resets