Developer Documentation
API Reference and Integration Guide
Overview
MedTrack AI provides a REST API for managing medical reports, extracting biomarkers, and tracking health metrics. All API endpoints require authentication via Supabase session cookies (set during Google OAuth sign-in).
Authentication
- Initiate Google OAuth:
GET /api/auth/google→ returns{ url }to redirect the user - Callback:
GET /api/auth/callback?code=...→ exchanges code for session, sets cookies - Check session:
GET /api/auth/session→ returns current user, subscription status, free tier remaining - Sign out:
POST /api/auth/signout→ clears session cookies
API Endpoints Reference
| Method | Endpoint | Description | Auth |
|---|---|---|---|
| GET | /api/auth/google | Start Google OAuth flow | No |
| GET | /api/auth/callback | OAuth callback (exchanges code for session) | No |
| GET | /api/auth/session | Get current user & subscription status | No |
| POST | /api/auth/signout | Sign out and clear cookies | No |
| GET | /api/reports | List all user reports | Yes |
| POST | /api/reports | Upload medical report (multipart/form-data) | Yes |
| GET | /api/reports/:id | Get report detail with metrics | Yes |
| DELETE | /api/reports/:id | Delete a report and its metrics | Yes |
| POST | /api/reports/:id/process-page | Process a single page (base64 data) | Yes |
| POST | /api/reports/:id/finalize | Finalize multi-page report analysis | Yes |
| POST | /api/reports/:id/retry | Retry failed analysis | Yes |
| GET | /api/metrics | Get all biomarker groups with trends | Yes |
| GET | /api/metrics?name=X | Get single metric history | Yes |
| GET | /api/files/:filename | Download uploaded file | Yes |
| POST | /api/checkout/create-order | Create Razorpay payment order | Yes |
| POST | /api/checkout/verify | Verify payment signature | Yes |
Rate Limits
- Upload: 10 requests per 5 minutes per user
- AI Analysis: 20 requests per 24 hours per user
- Auth: 5 signup attempts per hour per IP
All rate-limited responses return HTTP 429 with a Retry-After header and RFC RateLimit-* headers.
Response Format
All API responses return JSON. Successful responses include the requested data. Error responses follow this structure:
{
"error": "Human-readable message",
"code": "MACHINE_READABLE_CODE"
}HTTP status codes used: 200 (success), 400 (bad request), 401 (not authenticated), 402 (subscription required), 404 (not found), 413 (payload too large), 415 (unsupported media type), 429 (rate limited), 500 (server error)
Machine-Readable API Specification
A complete OpenAPI 3.1 specification is available at /openapi.json. This spec includes typed schemas for all request/response bodies and is compatible with LLM function-calling formats.
Agent Instructions
See /llms.txt for guidance on when and how AI agents should interact with MedTrack AI.