API Documentation

v1.0.0

Introduction

Welcome to the NovaReceipt API documentation. Our platform provides a robust solution for extracting structured data from invoices, receipts, and financial documents using advanced OCR and AI technologies.

The system is built on a modern stack including Next.js 15+, Supabase, and FastAPI, leveraging Mistral AI for intelligent parsing.

Authentication & Security

All API requests must be authenticated using Bearer tokens. We use Supabase Auth for user management and Row Level Security (RLS) to ensure data isolation.

Authorization: Bearer YOUR_JWT_TOKEN

Note: Never expose your service role keys on the client side. Use public anon keys for client-side operations and strictly validate JWTs on the server.

Endpoints

FastAPI (OCR + AI)

POST/extract

Extracts text and data from an uploaded document.

Request Body

{
  "file_url": "https://storage.googleapis.com/...",
  "document_type": "receipt" | "invoice"
}

POST/validate

Validates extracted data against business rules using AI.

Next.js API Routes

GET/api/documents

Retrieves a list of user documents.

DELETE/api/documents/{id}

Permanently deletes a document and its associated data.

Workflows

Processing Pipeline

graph LR
    A[User Upload] --> B[Next.js API]
    B --> C{File Type?}
    C -- PDF/Image --> D[FastAPI OCR]
    D --> E[Mistral AI Parsing]
    E --> F[Supabase DB]
    F --> G[Dashboard Update]

Authentication & RLS

sequenceDiagram
    participant U as User
    participant S as Supabase Auth
    participant D as Database (RLS)
    
    U->>S: Login (Email/Pass)
    S-->>U: JWT Token
    U->>D: Request Data + JWT
    D->>D: Verify Token Signature
    D->>D: Check RLS Policy (uid == auth.uid())
    D-->>U: Return Protected Data

Data Models

documents

Column	Type	Description
id	uuid	Primary Key
user_id	uuid	References auth.users
status	enum	'processing', 'completed', 'failed'
metadata	jsonb	Extracted fields (amount, date, etc.)

SDK Examples

JavaScript (Fetch)

const response = await fetch('https://api.novareceipt.com/api/documents', {
  method: 'POST',
  headers: {
    'Authorization': 'Bearer ' + token,
    'Content-Type': 'application/json'
  },
  body: JSON.stringify({ file_url: url })
});

const data = await response.json();

Python (Requests)

import requests

headers = {
    "Authorization": f"Bearer {token}",
    "Content-Type": "application/json"
}

response = requests.post(
    "https://api.novareceipt.com/api/documents",
    headers=headers,
    json={"file_url": url}
)

print(response.json())

Versioning

The API is currently in version v1. All endpoints that might change in breaking ways will be versioned in the URL (e.g., /api/v1/documents).

Changelog

2025-12-04Initial release of the API (v1.0.0)

Security

Rate Limiting: 100 requests per minute per IP.
CORS: Restricted to configured domains.
Secrets: Managed via environment variables, never committed to code.
Vulnerability Mitigation: We actively monitor and patch vulnerabilities like CVE-2025-55182 (React Server Components).