API Reference

API Reference

All endpoints under /api/v1. Every endpoint except POST /auth/login and GET /health requires Authorization: Bearer <jwt>.

Response envelope

Single resource: { data, error }. List: { data, meta, error }. On success error is null; on failure data is null.

{
  "data": [ /* items */ ],
  "meta": { "total_count": 1250, "page": 1, "page_size": 50, "total_pages": 25 },
  "error": null
}

Endpoints (all implemented)

Method	Route	Description
GET	/api/v1/health	DB connectivity health check (unauthenticated)
POST	/api/v1/auth/login	Verify password, issue JWT, return user + sites
GET	/api/v1/auth/me	Current user profile + sites (session rehydration)
GET	/api/v1/sites	Sites the authenticated user can access
GET	/api/v1/batches	Paginated/filterable/sortable batch list
GET	/api/v1/batches/{id}	Batch detail summary
GET	/api/v1/batches/{id}/files	Files in a batch (paginated)
GET	/api/v1/dashboard/summary	Status counters
GET	/api/v1/dashboard/throughput?range=7d	Throughput chart series
GET	/api/v1/dashboard/status-distribution	Status breakdown
GET	/api/v1/dashboard/recent-failures	Paginated recent failures
GET	/api/v1/files/{id}/details	File step history + error + remediation
GET	/api/v1/files/{id}/line-items	Invoice line items + categories + totals
GET	/api/v1/errors/top-frequencies	Top 10 errors + remediation
GET	/api/v1/errors/trend?range=30d	Error trend series
GET	/api/v1/errors	Filtered/paginated error list
GET	/api/v1/errors/export	CSV export of filtered errors
GET	/api/v1/activity-log	Paginated, filtered audit trail

HTTP status codes

Code	When
200	Success
400	Validation failure (bad date, pageSize > 100, bad enum)
401	Missing / invalid / expired JWT
403	Authenticated but not authorized for the requested site (SITE_FORBIDDEN)
404	Resource ID does not exist
500	Unhandled exception (logged, generic message returned)

Seed credentials

Password for all seed users: Password123!

Email	Role	Tenant	Sites the user can access
user.a@acme.com	Viewer	Acme	Mumbai, Delhi
admin@acme.com	Admin	Acme	all 3 (Mumbai, Delhi, Chennai)
user.b@acme.com	Viewer	Acme	Chennai only
user.c@globex.com	Viewer	Globex	Berlin only
admin@globex.com	Admin	Globex	both (Berlin, Munich)

Access is uneven on purpose so you can demonstrate 403 SITE_FORBIDDEN (see Tenant and Site Isolation).

End-to-end smoke test (Swagger, no frontend)

1. GET /api/v1/health → { "status": "healthy", "db": "connected" }
2. POST /api/v1/auth/login (Acme user) → JWT + sites
3. Click Authorize, paste the token (no Bearer prefix)
4. GET /api/v1/auth/me → your profile + sites
5. GET /api/v1/sites → your authorized sites
6. Wrong password → clean 401 with INVALID_CREDENTIALS envelope
7. GET /api/v1/batches → your tenant's batches
8. Log in as user.c@globex.com → confirm you cannot see Acme's data (cross-tenant isolation)
9. Log in as user.b@acme.com (Chennai only), set X-Site-Id to Mumbai → 403 SITE_FORBIDDEN (site-level isolation, FR-5.3)