---
title: FinSight API
emoji: 📈
colorFrom: blue
colorTo: green
sdk: docker
app_port: 8000
pinned: false
short_description: Grounded AI financial research API
---

# FinSight API

Production backend for **FinSight** - an AI financial research tool that can't
invent a number. It answers questions about public companies by grounding every
figure in a verifiable source (an SEC XBRL fact, an NSE results filing, or an
indexed filing passage) and checking it against that source before returning it.

A FastAPI service running an OpenAI agent loop with a local sentence-transformers
embedding model for retrieval over Postgres + pgvector. It runs as a Docker
container (the model needs real memory), which is why it's deployed here rather
than on a serverless function.

## Endpoints

| Route | Purpose |
|-------|---------|
| `POST /chat`, `/chat/sync` | Grounded research answers (streaming / sync) |
| `GET /companies` | Company list |
| `GET /companies/{ticker}/financials` | XBRL financial facts |
| `GET /companies/{ticker}/filings` | Filing list |
| `GET /companies/{ticker}/prices`, `/quote/{ticker}` | Prices and quotes |
| `GET /screener`, `/results/latest`, `/compare` | Screener, latest results, comparisons |
| `GET /market/overview` | Market snapshot |
| `GET /diff/companies` | Companies with ≥2 comparable filings for a form |
| `GET /diff/{ticker}`, `POST /diff/{ticker}/narrate` | Filing-to-filing change analysis |
| `GET /health` | Liveness + table counts |

## Configuration

Set these under **Settings → Variables and secrets** (as secrets):

| Name | Required | Notes |
|------|----------|-------|
| `OPENAI_API_KEY` | yes | OpenAI API key from platform.openai.com |
| `OPENAI_MODEL` | no | Defaults to `gpt-4o-mini` |
| `DATABASE_URL` | yes | Supabase Postgres **session** pooler URI (port 5432) |
| `SUPABASE_URL` | yes | Supabase project URL |
| `SUPABASE_SERVICE_ROLE_KEY` | yes | Server-side only |
| `SEC_EDGAR_USER_AGENT` | yes | e.g. `Your Name you@example.com` |
| `CORS_ORIGINS` | yes | Frontend origin(s), comma-separated |
| `RESEND_API_KEY` | no | Family-invite emails; falls back to copy-link |

## Deploy

The Space repo root is the `backend/` directory of the FinSight repo (HF needs
the `Dockerfile` at the root). Push that subtree:

```bash
git remote add space https://huggingface.co/spaces/ManasDubey/finsight-api
git subtree push --prefix backend space main
```

HF builds the [`Dockerfile`](./Dockerfile) and routes traffic to `app_port: 8000`.
Once live, `GET https://ManasDubey-finsight-api.hf.space/health` returns
`{"status":"healthy", ...}` with non-zero table counts.

Research & education, not investment advice.