12. Complete API Reference

12.1 Base URL

Local Development: http://localhost:8000

Base Path: /api/v1

Content-Type: application/json

12.2 Calculate Endpoint

POST /api/v1/calculate

Calculate denomination breakdown for a given amount

Request Body

{
  "amount": 1850.50,
  "currency": "INR",
  "mode": "greedy"
}

Request Parameters

Field	Type	Required	Validation	Description
`amount`	Decimal	?	> 0, = 1 trillion	Amount to calculate
`currency`	String	?	INR \| USD \| EUR \| GBP	Currency code
`mode`	String	?	greedy \| balanced \| minimize_large \| minimize_small	Optimization mode

cURL Example

curl -X POST http://localhost:8000/api/v1/calculate \
  -H "Content-Type: application/json" \
  -d '{"amount": 1850.50, "currency": "INR", "mode": "greedy"}'

Response (200 OK)

{
  "amount": 1850.5,
  "currency": "INR",
  "mode": "greedy",
  "breakdown": [
    {
      "denomination": 500,
      "type": "note",
      "count": 3,
      "total_value": 1500
    },
    {
      "denomination": 200,
      "type": "note",
      "count": 1,
      "total_value": 200
    },
    {
      "denomination": 100,
      "type": "note",
      "count": 1,
      "total_value": 100
    },
    {
      "denomination": 50,
      "type": "note",
      "count": 1,
      "total_value": 50
    },
    {
      "denomination": 0.5,
      "type": "coin",
      "count": 1,
      "total_value": 0.5
    }
  ],
  "summary": {
    "total_pieces": 7,
    "total_notes": 6,
    "total_coins": 1,
    "total_denominations": 5
  },
  "timestamp": "2025-11-27T10:30:00Z",
  "calculation_id": 123
}

Error Responses

Status	Code	Description
400	VALIDATION_ERROR	Invalid request parameters
422	UNPROCESSABLE_ENTITY	Validation failed (Pydantic)
500	CALCULATION_FAILED	Engine processing error

12.3 Bulk Upload Endpoint

POST /api/v1/bulk/upload

Process bulk upload files (CSV, PDF, Word, Images)

Request (Multipart Form Data)

Field	Type	Required	Description
`file`	File	?	CSV, PDF, DOCX, or Image file
`save_to_history`	Boolean		Save results (default: true)
`default_currency`	String		Smart default (default: INR)
`default_mode`	String		Smart default (default: greedy)

cURL Example

curl -X POST http://localhost:8000/api/v1/bulk/upload \
  -F "file=@test.csv" \
  -F "save_to_history=true"

Response (200 OK)

{
  "filename": "test.csv",
  "total_rows": 100,
  "successful_rows": 98,
  "failed_rows": 2,
  "processing_time_seconds": 0.45,
  "results": [
    {
      "row_number": 1,
      "status": "success",
      "amount": 1000,
      "currency": "INR",
      "mode": "greedy",
      "calculation_id": 124,
      "breakdown": [...]
    },
    {
      "row_number": 2,
      "status": "failed",
      "error": "Invalid amount"
    }
  ]
}

12.4 History Endpoints

GET /api/v1/history

Get paginated calculation history

Query Parameters

Parameter	Type	Default	Description
`page`	Integer	1	Page number (min: 1)
`per_page`	Integer	50	Items per page (max: 200)
`currency`	String		Filter by currency
`start_date`	DateTime		Filter from date (ISO 8601)
`end_date`	DateTime		Filter to date (ISO 8601)
`sort_by`	String	timestamp	timestamp \| amount
`sort_order`	String	desc	asc \| desc

Example Request

curl "http://localhost:8000/api/v1/history?page=1&per_page=10¤cy=INR"

Response (200 OK)

{
  "items": [
    {
      "id": 123,
      "amount": 1850.5,
      "currency": "INR",
      "mode": "greedy",
      "breakdown": [...],
      "summary": {...},
      "timestamp": "2025-11-27T10:30:00Z"
    }
  ],
  "pagination": {
    "page": 1,
    "per_page": 10,
    "total_items": 150,
    "total_pages": 15,
    "has_next": true,
    "has_prev": false
  }
}

DELETE /api/v1/history/{id}

Delete a specific calculation

Example Request

curl -X DELETE http://localhost:8000/api/v1/history/123

Response (200 OK)

{
  "message": "Calculation deleted successfully",
  "id": 123
}

DELETE /api/v1/history/clear

Delete all calculations (requires confirmation)

Request Body

{
  "confirm": true
}

Response (200 OK)

{
  "message": "All history cleared",
  "deleted_count": 150
}

12.5 Settings Endpoints

GET /api/v1/settings

Get current user settings

Response (200 OK)

{
  "theme": "dark",
  "language": "en",
  "default_currency": "INR",
  "default_mode": "greedy",
  "auto_save_history": true,
  "updated_at": "2025-11-27T10:00:00Z"
}

PUT /api/v1/settings

Update user settings

Request Body

{
  "theme": "dark",
  "language": "hi",
  "default_currency": "USD",
  "default_mode": "balanced",
  "auto_save_history": false
}

Response (200 OK)

{
  "message": "Settings updated successfully",
  "settings": {
    "theme": "dark",
    "language": "hi",
    "default_currency": "USD",
    "default_mode": "balanced",
    "auto_save_history": false,
    "updated_at": "2025-11-27T10:35:00Z"
  }
}

POST /api/v1/settings/reset

Reset all settings to defaults

Response (200 OK)

{
  "message": "Settings reset to defaults",
  "settings": {
    "theme": "light",
    "language": "en",
    "default_currency": "INR",
    "default_mode": "greedy",
    "auto_save_history": true
  }
}

12.6 Error Response Format

Standard Error Structure

{
  "error": {
    "code": "VALIDATION_ERROR",
    "message": "Amount must be greater than 0",
    "field": "amount",
    "timestamp": "2025-11-27T10:40:00Z"
  }
}

Error Codes

Code	HTTP Status	Description
`VALIDATION_ERROR`	400	Request validation failed
`INVALID_AMOUNT`	400	Amount validation failed
`INVALID_CURRENCY`	400	Unsupported currency
`INVALID_MODE`	400	Unsupported mode
`INVALID_FILE`	400	File validation failed
`CALCULATION_NOT_FOUND`	404	Calculation ID not found
`CALCULATION_FAILED`	500	Engine processing error
`DATABASE_ERROR`	500	Database operation failed
`OCR_PROCESSING_ERROR`	500	OCR failed

12.7 Health Check Endpoint

GET /health

Check API health status

Response (200 OK)

{
  "status": "healthy",
  "timestamp": "2025-11-27T10:45:00Z",
  "database": "connected",
  "version": "1.0.0",
  "uptime_seconds": 3600
}

? Section Complete

This section covers complete API specifications including Calculate, Bulk Upload, History, and Settings endpoints with request/response schemas, validation rules, error codes, and cURL examples.