Spaces:
Sleeping
Sleeping
File size: 20,781 Bytes
205f25f | 1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26 27 28 29 30 31 32 33 34 35 36 37 38 39 40 41 42 43 44 45 46 47 48 49 50 51 52 53 54 55 56 57 58 59 60 61 62 63 64 65 66 67 68 69 70 71 72 73 74 75 76 77 78 79 80 81 82 83 84 85 86 87 88 89 90 91 92 93 94 95 96 97 98 99 100 101 102 103 104 105 106 107 108 109 110 111 112 113 114 115 116 117 118 119 120 121 122 123 124 125 126 127 128 129 130 131 132 133 134 135 136 137 138 139 140 141 142 143 144 145 146 147 148 149 150 151 152 153 154 155 156 157 158 159 160 161 162 163 164 165 166 167 168 169 170 171 172 173 174 175 176 177 178 179 180 181 182 183 184 185 186 187 188 189 190 191 192 193 194 195 196 197 198 199 200 201 202 203 204 205 206 207 208 209 210 211 212 213 214 215 216 217 218 219 220 221 222 223 224 225 226 227 228 229 230 231 232 233 234 235 236 237 238 239 240 241 242 243 244 245 246 247 248 249 250 251 252 253 254 255 256 257 258 259 260 261 262 263 264 265 266 267 268 269 270 271 272 273 274 275 276 277 278 279 280 281 282 283 284 285 286 287 288 289 290 291 292 293 294 295 296 297 298 299 300 301 302 303 304 305 306 307 308 309 310 311 312 313 314 315 316 317 318 319 320 321 322 323 324 325 326 327 328 329 330 331 332 333 334 335 336 337 338 339 340 341 342 343 344 345 346 347 348 349 350 351 352 353 354 355 356 357 358 359 360 361 362 363 364 365 366 367 368 369 370 371 372 373 374 375 376 377 378 379 380 381 382 383 384 385 386 387 388 389 390 391 392 393 394 395 396 397 398 399 400 401 402 403 404 405 406 407 408 409 410 411 412 413 414 415 416 417 418 419 420 421 422 423 424 425 426 427 | # BeFree API Reference
This document provides a complete inventory of the REST API endpoints exposed by the BeFree backend server, including authentication requirements, request payloads, and response structures.
---
## Global Authentication Rules
- **Bearer Tokens**: Endpoints requiring authentication look for a JWT token in the `Authorization: Bearer <token>` header.
- **Roles**:
- `tester` (default): View dashboards, upload and review statements.
- `manager`: Access dashboard metrics, review history, and trigger exports.
- `admin`: Full access, including rule manipulation, audit logs, categories, database resets, and administrative commands.
---
## 1. Authentication Endpoints
### `POST /api/v1/auth/login`
- **Auth Required**: No
- **Request Body**: Form parameters (`username`, `password`)
- **Response Schema**: `TokenResponse` (`access_token`, `token_type`, `role`, `username`)
- **Description**: Verifies credentials and returns a signed JWT access token.
### `POST /api/v1/auth/logout`
- **Auth Required**: Yes (`tester` | `manager` | `admin`)
- **Request Body**: None (retrieves token from authorization header)
- **Response Schema**: `{"status": "success", "message": "Logged out"}`
- **Description**: Revokes the active session token in the database.
### `GET /api/v1/auth/me`
- **Auth Required**: Yes (`tester` | `manager` | `admin`)
- **Response Schema**: `UserProfile` (`id`, `username`, `email`, `fullName`, `role`)
- **Description**: Returns the profile details of the currently authenticated user.
### `POST /api/v1/auth/seed-users`
- **Auth Required**: Yes (requires `X-Seed-Secret` header matching `SEED_SECRET` env var)
- **Response Schema**: `{"status": "success", "seeded_count": int}`
- **Description**: Seeds initial system users (`admin`, `manager`, `tester`) into the PostgreSQL database.
---
## 2. Dashboard Endpoints
### `GET /api/v1/dashboard/metrics`
- **Auth Required**: Yes (`tester` | `manager` | `admin`)
- **Response Schema**: `DashboardMetrics` (`totalStatements`, `processedSuccessfully`, `failedStatements`, `averageAccuracy`, `totalFlaggedTransactions`)
- **Description**: Aggregates high-level processing statistics for the main dashboard display.
### `GET /api/v1/dashboard/recent-activity`
- **Auth Required**: Yes (`tester` | `manager` | `admin`)
- **Response Schema**: `List[ActivityItem]` (`id`, `timestamp`, `username`, `action`, `description`)
- **Description**: Lists recent database audit log activities.
### `GET /api/v1/dashboard/recent-statements`
- **Auth Required**: Yes (`tester` | `manager` | `admin`)
- **Response Schema**: `List[StatementSummary]` (`id`, `fileName`, `status`, `uploadedAt`, `accuracy`)
- **Description**: Lists recently processed statement metadata.
---
## 3. Statement Processing Endpoints
### `POST /api/v1/statements/upload`
- **Auth Required**: Yes (`tester` | `manager` | `admin`)
- **Request Body**: Multipart form data with key `files` (array of PDF files)
- **Response Schema**: `UploadInitResponse` (`statementId`, `fileName`, `status`, `ocrFallbackTriggered`)
- **Description**: Ingests PDF files, initializes the transaction database, and caches the raw PDFs on disk.
### `POST /api/v1/statements/{statement_id}/detect-layout`
- **Auth Required**: Yes (`tester` | `manager` | `admin`)
- **Response Schema**: `HeaderDetectionResultModel`
- **Description**: Analyzes pages in the statement to automatically detect header coordinates and column mappings.
### `GET /api/v1/statements/{statement_id}/layout`
- **Auth Required**: Yes (`tester` | `manager` | `admin`)
- **Response Schema**: `HeaderDetectionResultModel`
- **Description**: Retrieves the cached or detected column layout map.
### `GET /api/v1/statements/{statement_id}/page-image/{page_num}`
- **Auth Required**: Yes (`tester` | `manager` | `admin`)
- **Response Schema**: PNG binary stream
- **Description**: Generates and serves a rasterized PNG image of a statement page (used for visual verification in the coordinate inspector).
### `POST /api/v1/statements/{statement_id}/verify-layout`
- **Auth Required**: Yes (`tester` | `manager` | `admin`)
- **Request Body**: `HeaderDetectionResultModel`
- **Response Schema**: `{"success": true}`
- **Description**: Saves layout coordinates adjusted manually by the user in the UI coordinate builder.
### `PATCH /api/v1/statements/{statement_id}/layout/column/{col_name}`
- **Auth Required**: Yes (`tester` | `manager` | `admin`)
- **Request Body**: JSON mapping for x-coordinates (`x_min`, `x_max`)
- **Response Schema**: `{"success": true}`
- **Description**: Modifies coordinate ranges for a single column.
### `POST /api/v1/statements/{statement_id}/process`
- **Auth Required**: Yes (`tester` | `manager` | `admin`)
- **Response Schema**: `{"success": true, "message": "Extraction started"}`
- **Description**: Initiates transaction cell extraction and audits in a background thread.
### `POST /api/v1/statements/{statement_id}/finalise`
- **Auth Required**: Yes (`tester` | `manager` | `admin`)
- **Response Schema**: `{"success": true}`
- **Description**: Finalizes the statement review and generates the default spreadsheet.
### `GET /api/v1/statements/{statement_id}/processing`
- **Auth Required**: Yes (`tester` | `manager` | `admin`)
- **Response Schema**: `ProcessingState`
- **Description**: Polls the background thread extraction progress, stages completed, and remaining duration.
### `POST /api/v1/statements/{statement_id}/processing/cancel`
- **Auth Required**: Yes (`tester` | `manager` | `admin`)
- **Response Schema**: `None`
- **Description**: Cancels background processing for a statement and sets its status to `cancelled`.
### `POST /api/v1/statements/{statement_id}/save-progress`
- **Auth Required**: Yes (`tester` | `manager` | `admin`)
- **Response Schema**: `{"status": "success", "message": "Progress saved"}`
- **Description**: Forces writing the active transaction and correction log states to the excel cached workbook.
### `GET /api/v1/statements/{statement_id}/pdf`
- **Auth Required**: Yes (`tester` | `manager` | `admin`)
- **Response Schema**: PDF binary stream
- **Description**: Downloads the raw uploaded PDF file.
---
## 4. Transaction Endpoints
### `GET /api/v1/statements/{statement_id}/transactions`
- **Auth Required**: Yes (`tester` | `manager` | `admin`)
- **Query Params**: `page` (int), `pageSize` (int), `search` (str), `status` (str), `pageNum` (int), `confidence` (str: `high`|`low`)
- **Response Schema**: `TransactionsPage` (`items`: `List[TransactionRowModel]`, `total`: int, `page`: int, `pageSize`: int)
- **Description**: Retrieves a paginated list of transactions, supporting search queries, status filters, page limits, and date windowing configurations.
### `POST /api/v1/statements/{statement_id}/transactions`
- **Auth Required**: Yes (`tester` | `manager` | `admin`)
- **Request Body**: `TransactionCreatePayload` (`pageNumber`, `date`, `description`, `debit`, `credit`, `balance`)
- **Response Schema**: `TransactionRowModel`
- **Description**: Inserts a manual transaction row, triggers a statement re-audit, and persists the cache.
### `GET /api/v1/statements/{statement_id}/transactions/{tx_id}`
- **Auth Required**: Yes (`tester` | `manager` | `admin`)
- **Response Schema**: `TransactionRowModel`
- **Description**: Returns a single transaction details.
### `PATCH /api/v1/statements/{statement_id}/transactions/{tx_id}`
- **Auth Required**: Yes (`tester` | `manager` | `admin`)
- **Request Body**: `TransactionUpdatePayload` (`date`, `description`, `debit`, `credit`, `balance`, `category`)
- **Response Schema**: `TransactionRowModel`
- **Description**: Updates field values, clears historical audit warnings, and recalculates running balances.
### `DELETE /api/v1/statements/{statement_id}/transactions/{tx_id}`
- **Auth Required**: Yes (`tester` | `manager` | `admin`)
- **Response Schema**: `None`
- **Description**: Deletes a transaction row and updates subsequent running balances.
---
## 5. Review & HITL Endpoints
### `GET /api/v1/statements/{statement_id}/review-session`
- **Auth Required**: Yes (`tester` | `manager` | `admin`)
- **Response Schema**: `ReviewSession` (`statementId`, `fileName`, `bankName`, `pdfUrl`, `uploadedAt`, `uploadedBy`)
- **Description**: Prepares review parameters, returning document URLs and upload history.
### `GET /api/v1/statements/{statement_id}/review/metrics`
- **Auth Required**: Yes (`tester` | `manager` | `admin`)
- **Response Schema**: `ReviewMetrics` (`totalTransactions`, `needsAttention`, `lowConfidence`, `balanceIssues`, `gapsDetected`, `overallAccuracy`)
- **Description**: Aggregates discrepancy indicators and arithmetic error metrics for the review interface.
### `POST /api/v1/statements/{statement_id}/auto-swap-all`
- **Auth Required**: Yes (`tester` | `manager` | `admin`)
- **Response Schema**: `{"success": True, "swappedCount": int}`
- **Description**: Triggers a mathematical audit pass that automatically swaps debit and credit fields on matching rows to correct ledger balance progression.
### `POST /api/v1/statements/{statement_id}/transactions/{tx_id}/swap-debit-credit`
- **Auth Required**: Yes (`tester` | `manager` | `admin`)
- **Response Schema**: `TransactionRowModel`
- **Description**: Forcefully swaps the debit and credit columns of a single transaction and updates balances.
### `POST /api/v1/statements/{statement_id}/pages/{page_num}/review`
- **Auth Required**: Yes (`tester` | `manager` | `admin`)
- **Response Schema**: `{"success": true, "updatedCount": int}`
- **Description**: Bulk marks all transactions on a page as manually verified, clearing audit warnings.
### `POST /api/v1/statements/{statement_id}/re-audit`
- **Auth Required**: Yes (`tester` | `manager` | `admin`)
- **Request Body**: `ReAuditPayload` (`pageNum`)
- **Response Schema**: `{"success": true, "auditResult": {"pageNum": int, "checked": int, "issues": int}}`
- **Description**: Triggers a full-statement auto-swap audit and reports remaining issues for the specified page.
### `GET /api/v1/statements/{statement_id}/flagged`
- **Auth Required**: Yes (`tester` | `manager` | `admin`)
- **Query Params**: `severity` (str), `bank` (str), `search` (str)
- **Response Schema**: `List[FlaggedTransaction]` (`id`, `severity`, `issueType`, `pageNum`, `confidence`, `amount`, `description`, `statementId`)
- **Description**: Returns all extraction and mathematical balance issues that require credit officer verification.
---
## 6. Export Endpoints
### `GET /api/v1/statements/{statement_id}/export/summary`
- **Auth Required**: Yes (`tester` | `manager` | `admin`)
- **Response Schema**: `ExportSummary`
- **Description**: Evaluates classification statistics, distinct calendar months, and counts unverified AI classifications before export.
### `POST /api/v1/statements/{statement_id}/export`
- **Auth Required**: Yes (`tester` | `manager` | `admin`)
- **Request Body**: `ExportRequest` (`format`: `xlsx`|`csv`|`xlsx_audit`)
- **Response Schema**: `ExportResponse` (`downloadUrl`, `fileName`)
- **Description**: Triggers export packaging and returns a download link incorporating temporary JWT tokens.
### `GET /api/v1/statements/{statement_id}/download`
- **Auth Required**: Yes (`tester` | `manager` | `admin`)
- **Query Params**: `format` (str), `token` (str)
- **Response Schema**: Binary file stream
- **Description**: Downloads the statement in Excel (`xlsx` / `xlsx_audit`) or `csv` format. Authenticates via standard headers or query parameter token.
---
## 7. Classification Endpoints
### `POST /api/v1/statements/{statement_id}/classify`
- **Auth Required**: Yes (`tester` | `manager` | `admin`)
- **Response Schema**: `{"statementId": statement_id}`
- **Description**: Starts transaction classification pipeline in a background worker.
### `GET /api/v1/statements/{statement_id}/classify/status`
- **Auth Required**: Yes (`tester` | `manager` | `admin`)
- **Response Schema**: `{"status": str, "progress": int, "successCount": int, "failedCount": int}`
- **Description**: Retrieves the status of the classification pipeline run.
### `PATCH /api/v1/statements/{statement_id}/classify/{tx_id}`
- **Auth Required**: Yes (`tester` | `manager` | `admin`)
- **Request Body**: JSON payload containing `category` (str) and `third_party` (str)
- **Response Schema**: `{"success": true}`
- **Description**: Overrides a transaction's category classification.
### `POST /api/v1/statements/{statement_id}/classify/{tx_id}/confirm`
- **Auth Required**: Yes (`tester` | `manager` | `admin`)
- **Response Schema**: `{"success": true}`
- **Description**: Marks a classification as verified by a broker.
### `POST /api/v1/statements/{statement_id}/classify/confirm-bulk`
- **Auth Required**: Yes (`tester` | `manager` | `admin`)
- **Request Body**: JSON list containing `tx_ids` (List[str])
- **Response Schema**: `{"success": true, "count": int}`
- **Description**: Marks multiple classifications as verified.
### `DELETE /api/v1/statements/{statement_id}/classify/{tx_id}/override`
- **Auth Required**: Yes (`tester` | `manager` | `admin`)
- **Response Schema**: `{"success": true}`
- **Description**: Resets a transaction classification back to its original pipeline-assigned value.
### `POST /api/v1/classify/upload-excel`
- **Auth Required**: Yes (`tester` | `manager` | `admin`)
- **Request Body**: Multipart form data with key `file` (Excel workbook)
- **Response Schema**: `{"statementId": statement_id}`
- **Description**: Ingests a pre-extracted transaction list from an Excel workbook and starts background classification.
---
## 8. Overwatch Observability Endpoints
These read-only endpoints are exposed from the `overwatch_router` component.
### `GET /api/v1/overwatch/events`
- **Auth Required**: Yes (`tester` | `manager` | `admin`)
- **Query Params**: `document_id` (str), `document_name` (str), `log_level` (str), `stage` (str), `from_time` (str), `to_time` (str), `page` (int), `page_size` (int)
- **Response Schema**: `{"items": List[dict], "total": int, "page": int, "page_size": int}`
- **Description**: Queries system observability events from the SQLite WAL store.
### `GET /api/v1/overwatch/documents`
- **Auth Required**: Yes (`tester` | `manager` | `admin`)
- **Query Params**: `from_time` (str), `to_time` (str), `has_errors` (bool), `has_warnings` (bool), `username` (str), `page` (int), `page_size` (int)
- **Response Schema**: `{"items": List[dict], "total": int, "page": int, "page_size": int}`
- **Description**: Lists document-level processing health summaries.
### `GET /api/v1/overwatch/documents/{document_id}/summary`
- **Auth Required**: Yes (`tester` | `manager` | `admin`)
- **Response Schema**: Detailed document health metrics, runtime latency, and stage checks.
- **Description**: Returns the observability details for a single document. Returns `404` if the document is not found.
---
## 9. History Endpoints
### `GET /api/v1/history/statements`
- **Auth Required**: Yes (`tester` | `manager` | `admin`)
- **Response Schema**: `List[HistoryRow]` (`statementId`, `fileName`, `status`, `uploadedAt`, `accuracy`, `txCount`, `flaggedCount`)
- **Description**: Lists all statements ever uploaded to the system.
### `POST /api/v1/history/statements/{statement_id}/reopen`
- **Auth Required**: Yes (`tester` | `manager` | `admin`)
- **Response Schema**: `{"status": "success"}`
- **Description**: Reopens a finalized statement so that users can make additional edits.
### `POST /api/v1/history/statements/{statement_id}/duplicate`
- **Auth Required**: Yes (`tester` | `manager` | `admin`)
- **Response Schema**: `UploadInitResponse`
- **Description**: Clones an existing statement into a new statement ID to allow testing alternative layout rules.
### `DELETE /api/v1/history/statements/{statement_id}`
- **Auth Required**: Yes (`tester` | `manager` | `admin`)
- **Response Schema**: `None`
- **Description**: Deletes a statement, removes its data folder from disk, and removes associated database audit records.
---
## 10. Administration & Settings Endpoints
### `GET /api/v1/settings`
- **Auth Required**: Yes (`tester` | `manager` | `admin`)
- **Response Schema**: `AppSettings`
- **Description**: Returns the active settings (`ocrEnabled`, `confidenceThreshold`, `autoExportEnabled`, `extractLast3Months`).
### `PATCH /api/v1/settings`
- **Auth Required**: Yes (`tester` | `manager` | `admin`)
- **Request Body**: `AppSettings` fields (optional)
- **Response Schema**: `AppSettings`
- **Description**: Modifies settings fields and flushes them to `data/settings.json`.
### `GET /api/v1/admin/audit-logs`
- **Auth Required**: Yes (`admin` only)
- **Response Schema**: JSON list of database audit logs
- **Description**: Lists system audit log table records for security monitoring.
### `GET /api/v1/admin/overwatch/insights`
- **Auth Required**: Yes (`admin` only)
- **Response Schema**: Overwatch analytics metrics (overall throughput, error rates, average latency per stage)
- **Description**: Returns analytics data on backend pipeline performance.
### `GET /api/v1/admin/uploads/pdfs`
- **Auth Required**: Yes (`admin` only)
- **Response Schema**: `List[str]`
- **Description**: Lists file names stored in the filesystem uploads folder.
### `GET /api/v1/admin/uploads/pdfs-runtime`
- **Auth Required**: Yes (`admin` only)
- **Response Schema**: `List[str]`
- **Description**: Scans the database and reports PDF files active in memory cache.
### `GET /api/v1/admin/overwatch/logs`
- **Auth Required**: Yes (`admin` only)
- **Response Schema**: Text stream of raw stdout log entries
- **Description**: Returns the log output stream.
### `GET /api/v1/admin/overwatch/export`
- **Auth Required**: Yes (`admin` only)
- **Response Schema**: CSV stream
- **Description**: Exports all database audit logs and overwatch logs in a single CSV file.
### `POST /api/v1/admin/overwatch/email-report`
- **Auth Required**: Yes (`admin` only)
- **Request Body**: `OverwatchEmailRequest` (`email`: comma-separated recipients)
- **Response Schema**: Status message (`sent` | `simulated`)
- **Description**: Emails system log reports. Generates simulated emails inside `data/simulated_emails/` if no SMTP credentials are configured.
### `GET /api/v1/admin/categories`
- **Auth Required**: Yes (`admin` only)
- **Response Schema**: `List[CategoryDict]`
- **Description**: Lists classification categories in the DB.
### `POST /api/v1/admin/categories`
- **Auth Required**: Yes (`admin` only)
- **Request Body**: Category creation fields
- **Response Schema**: Category dictionary
- **Description**: Inserts a classification category into the database.
### `PATCH /api/v1/admin/categories/{category_id}`
- **Auth Required**: Yes (`admin` only)
- **Request Body**: Category fields
- **Response Schema**: Category dictionary
- **Description**: Updates category details.
### `DELETE /api/v1/admin/categories/{category_id}`
- **Auth Required**: Yes (`admin` only)
- **Response Schema**: Status message
- **Description**: Deletes a classification category and cascades updates.
### `GET /api/v1/admin/rules`
- **Auth Required**: Yes (`admin` only)
- **Response Schema**: `List[RuleDict]`
- **Description**: Lists all active database classification rules.
### `POST /api/v1/admin/rules`
- **Auth Required**: Yes (`admin` only)
- **Request Body**: Rule creation fields
- **Response Schema**: Rule dictionary
- **Description**: Creates a new classification rule.
### `PATCH /api/v1/admin/rules/{rule_id}`
- **Auth Required**: Yes (`admin` only)
- **Request Body**: Rule fields
- **Response Schema**: Rule dictionary
- **Description**: Modifies classification rule fields.
### `DELETE /api/v1/admin/rules/{rule_id}`
- **Auth Required**: Yes (`admin` only)
- **Response Schema**: Status message
- **Description**: Deletes a classification rule in the database.
### `GET /api/v1/admin/llm-status`
- **Auth Required**: Yes (`admin` only)
- **Response Schema**: `{"api_configured": bool, "latency_ms": float}`
- **Description**: Tests connectivity to the Google Gemini API.
### `POST /api/v1/admin/reset-pipeline`
- **Auth Required**: Yes (`admin` only)
- **Response Schema**: `{"status": "reset"}`
- **Description**: Clear in-memory caches, database tables, rules, and resets the server state.
---
## 11. Health Endpoints
### `GET /health`
- **Auth Required**: No
- **Response Schema**: `{"status": "ok", "version": "1.0.0", "database": "connected"}`
- **Description**: Endpoint used for cloud container health checks.
### `GET /`
- **Auth Required**: No
- **Response Schema**: Redirect
- **Description**: Redirects root visitors to `/docs` (FastAPI Swagger interface) or returns simple welcome messages depending on deployment environment settings.
|