Skip to content

api.md

Latest commit

 

History

History
327 lines (251 loc) · 4.69 KB

api.md

File metadata and controls

327 lines (251 loc) · 4.69 KB
Raw

API Reference

REST APIs for document management, conversational queries, authentication, and subscriptions.

Base URL

Replace with your actual Railway deployment URL:

https://your-railway-url.up.railway.app/v1

Example:

https://finlens-backend-production.up.railway.app/v1

Authentication

All API requests require authentication using JWT tokens in the Authorization header:

Authorization: Bearer <your-jwt-token>

Endpoints

Authentication

Sign Up

POST /auth/signup
Content-Type: application/json

{
  "email": "user@example.com",
  "password": "securepassword",
  "full_name": "John Doe"
}

Sign In

POST /auth/signin
Content-Type: application/json

{
  "email": "user@example.com",
  "password": "securepassword"
}

Response:

{
  "access_token": "eyJ...",
  "refresh_token": "eyJ...",
  "user": {
    "id": "uuid",
    "email": "user@example.com",
    "full_name": "John Doe"
  },
  "expires_in": 3600
}

Get Current User

GET /auth/me
Authorization: Bearer <token>

Documents

Upload Documents

POST /documents/upload
Content-Type: multipart/form-data

files: [file1.pdf, file2.pdf]
descriptions: ["Q1 2024 Financial Report", "Annual Report 2023"]

Note: descriptions must be a JSON array string in form data.

Response:

{
  "total": 2,
  "successful": 2,
  "failed": 0,
  "results": [
    {
      "document_id": "uuid",
      "status": "processing",
      "message": "Document uploaded successfully",
      "metadata": {
        "company": "Apple",
        "year": 2024,
        "document_type": "10-K"
      }
    }
  ]
}

List Documents

GET /documents?limit=12&offset=0

Response:

{
  "documents": [
    {
      "id": "uuid",
      "filename": "annual_report.pdf",
      "status": "indexed",
      "description": "2023 Annual Report",
      "pages": 150,
      "uploaded_at": "2024-01-15T10:30:00Z"
    }
  ],
  "total": 25,
  "limit": 12,
  "offset": 0
}

Get Document

GET /documents/{document_id}

Delete Document

DELETE /documents/{document_id}

Chat & Queries

Send Query

POST /chat/query
Content-Type: application/json

{
  "query": "What are Apple's revenue trends for the last 3 years?",
  "session_id": "optional-session-uuid",
  "messages": [
    {
      "role": "user",
      "content": "Previous question"
    },
    {
      "role": "assistant",
      "content": "Previous answer"
    }
  ]
}

Response:

{
  "text": "Apple's revenue has shown consistent growth over the past 3 years...",
  "charts": [
    {
      "type": "line",
      "data": {
        "labels": ["2022", "2023", "2024"],
        "datasets": [...]
      }
    }
  ],
  "sources": [
    {
      "company": "Apple Inc.",
      "ticker": "AAPL",
      "year": 2024,
      "document_type": "10-K",
      "page": 45
    }
  ],
  "metadata": {
    "processing_time": 1.2,
    "chunks_retrieved": 8
  }
}

Get Chat Sessions

GET /chat/sessions?limit=50&offset=0

Get Session Messages

GET /chat/sessions/{session_id}

Users & Usage

Get User Profile

GET /users/me

Get Usage Statistics

GET /users/me/usage

Response:

{
  "queries_used_this_month": 1250,
  "queries_limit": 5000,
  "documents_uploaded": 15,
  "documents_limit": 100,
  "subscription_plan": "pro"
}

Subscriptions

Get Subscription

GET /subscriptions/me

Create Subscription

POST /subscriptions/create
Content-Type: application/json

{
  "price_id": "price_xxx"
}

Health Checks

System Health

GET /health

Response:

{
  "status": "healthy",
  "version": "1.0.0",
  "services": {
    "supabase": "connected",
    "qdrant": "connected",
    "openai": "configured"
  }
}

Readiness Check

GET /health/ready

Error Responses

All endpoints return standard HTTP status codes:

  • 200 - Success
  • 400 - Bad Request
  • 401 - Unauthorized
  • 403 - Forbidden
  • 404 - Not Found
  • 429 - Rate Limited
  • 500 - Internal Server Error

Error Response Format:

{
  "detail": "Error description",
  "error_code": "SPECIFIC_ERROR_CODE"
}

Rate Limits

Rate limiting is subscription-based. Users have monthly query limits based on their subscription tier. When limits are exceeded, requests return 429 Too Many Requests:

{
  "error": "Usage limit exceeded",
  "queries_used": 5000,
  "query_limit": 5000,
  "message": "You have reached your monthly query limit..."
}

Support

For API support, create an issue at: GitHub Issues