API Reference

VETTR Backend API - A comprehensive REST API for stock analysis, VETR Score calculation, Red Flag detection, and portfolio management for iOS and Android mobile clients. ## Authentication Most endpoints require JWT authentication via Bearer token in Authorization header: ``` Authorization: Bearer <access_token> ``` Access tokens are obtained from `/auth/login`, `/auth/signup`, `/auth/google`, or `/auth/apple` endpoints. ## Rate Limiting API requests are rate-limited based on subscription tier: | Tier | Read Requests | Write Requests | |------|---------------|----------------| | Unauthenticated | 5/min | N/A | | FREE | 60/min | 30/min | | PRO | 120/min | 60/min | | PREMIUM | 300/min | 120/min | Auth endpoints: 10 req/min (authenticated), 5 req/min (unauthenticated) **Rate limit headers:** - `X-RateLimit-Limit`: Maximum requests allowed in time window - `X-RateLimit-Remaining`: Requests remaining in current window - `X-RateLimit-Reset`: Unix timestamp when limit resets - `Retry-After`: Seconds to wait before retrying (included when rate limited) ## Tier Limits Feature access is restricted by subscription tier: | Feature | FREE | PRO | PREMIUM | |---------|------|-----|----------| | Watchlist items | 5 | 25 | Unlimited | | Sync interval | 24h | 12h | 4h | | Pulse delay | 12h | 4h | Real-time | ## Error Response Format All errors follow a standardized JSON format: ```json { "success": false, "error": { "code": "ERROR_CODE", "message": "Human-readable error message", "details": {} // Optional additional details }, "meta": { "timestamp": "2024-01-01T00:00:00.000Z", "request_id": "uuid" } } ``` **Error Codes:** - `AUTH_REQUIRED` (401): Authorization header missing or invalid - `AUTH_EXPIRED` (401): Access token has expired, use refresh token - `AUTH_INVALID_CREDENTIALS` (401): Invalid email or password - `FORBIDDEN` (403): Authenticated but not authorized for this resource - `TIER_LIMIT_EXCEEDED` (403): Subscription tier limit reached (e.g., watchlist full) - `NOT_FOUND` (404): Requested resource does not exist - `CONFLICT` (409): Resource conflict (e.g., duplicate email on signup) - `VALIDATION_ERROR` (422): Request validation failed, see `details` for field errors - `RATE_LIMITED` (429): Rate limit exceeded, see `Retry-After` header - `INTERNAL_ERROR` (500): Unexpected server error **Example Error Responses:** ```json // 401 AUTH_REQUIRED { "success": false, "error": { "code": "AUTH_REQUIRED", "message": "Authorization header is required" } } ``` ```json // 422 VALIDATION_ERROR { "success": false, "error": { "code": "VALIDATION_ERROR", "message": "Validation failed", "details": { "email": "Invalid email format", "password": "Password must be at least 8 characters" } } } ``` ```json // 403 TIER_LIMIT_EXCEEDED { "success": false, "error": { "code": "TIER_LIMIT_EXCEEDED", "message": "Watchlist limit exceeded for FREE tier (max 5 items)" } } ```