docs: Added demo curl commands for testing

README.md

@@ -106,3 +106,87 @@ Launch the stack:
 ```bash
 docker compose up -d
 ```
+
+## Testing the API with curl
+
+All API endpoints are prefixed with `/api/v1`. Below are copy-pasteable `curl` commands using the sample [transactions.csv](file:///home/sortedcord/Projects/alemno_payments/transactions.csv) dataset.
+
+### 1. Upload CSV Transaction Data
+
+Submit a CSV file for asynchronous processing.
+
+```bash
+curl -X POST -F "file=@transactions.csv" http://localhost:3000/api/v1/jobs/upload
+```
+
+_Response Example:_
+
+```json
+{
+  "filename": "transactions.csv",
+  "id": "c0249af1-c52d-4d49-9305-3d1a10f29e03",
+  "status": "pending",
+  "row_count_raw": null,
+  "row_count_clean": null,
+  "created_at": "2026-07-03T06:29:13.123456Z",
+  "completed_at": null,
+  "error_message": null
+}
+```
+
+### 2. Check Job Status
+
+Check the status of a job using the job ID returned by the upload endpoint.
+
+```bash
+curl http://localhost:3000/api/v1/jobs/c0249af1-c52d-4d49-9305-3d1a10f29e03/status
+```
+
+_Response Example (while processing):_
+
+```json
+{
+  "id": "c0249af1-c52d-4d49-9305-3d1a10f29e03",
+  "status": "processing",
+  "summary": null
+}
+```
+
+### 3. Get Full Job Results
+
+Retrieve the high-level summary along with all categorized and parsed transactions once the job is completed.
+
+```bash
+curl http://localhost:3000/api/v1/jobs/c0249af1-c52d-4d49-9305-3d1a10f29e03/results
+```
+
+### 4. List All Jobs
+
+List all historical processing jobs. You can optionally filter by status (e.g. `pending`, `processing`, `completed`, `failed`).
+
+```bash
+# List all jobs
+curl http://localhost:3000/api/v1/jobs
+
+# List completed jobs only
+curl "http://localhost:3000/api/v1/jobs?status=completed"
+```
+
+### 5. List Categories
+
+List all available transaction categories sorted alphabetically.
+
+```bash
+curl http://localhost:3000/api/v1/categories
+```
+
+### 6. Create Custom Category
+
+Add a new custom category. Newly uploaded transactions will dynamically map to this category during classification if identified by the LLM.
+
+```bash
+curl -X POST \
+  -H "Content-Type: application/json" \
+  -d '{"name": "Subscription"}' \
+  http://localhost:3000/api/v1/categories
+```