Skip to content

API Inventory

Base URL

  • Local: http://localhost:8000
  • Production: https://bacmr-backend.onrender.com (Example)

1. General

GET /health

  • Auth: None
  • Purpose: Verify backend is online.
  • Response: {"status": "BacMR Online"}

2. Authentication (/auth)

POST /auth/signup

  • Auth: None
  • Purpose: Register a new user.
  • Request Body: {"email": "...", "password": "...", "full_name": "..."}
  • Response: {"success": true, "data": {"user_id": "...", "email": "..."}}

POST /auth/signin

  • Auth: None
  • Purpose: Sign in and receive JWT tokens.
  • Response: {"success": true, "data": {"access_token": "...", "refresh_token": "...", "user": {...}}}

POST /auth/logout

  • Auth: None (client-side token discard)

POST /auth/reset-password

  • Auth: None
  • Request Body: {"email": "..."}

3. User Profile (/me)

GET /me

  • Auth: Bearer Token (Supabase JWT)
  • Purpose: Get current user's profile.
  • Response: {"id": "...", "email": "...", "full_name": "...", "role": "student"}

PATCH /me

  • Auth: Bearer Token (Supabase JWT)
  • Purpose: Update profile fields.
  • Request Body: {"full_name": "..."}

4. Chat (RAG)

POST /chat

  • Auth: Bearer Token (Supabase JWT)
  • Purpose: Interactive chat with the AI Teacher. Uses reserve/finalize billing.
  • Request Body: 
    {
  "messages": [{"role": "user", "content": "..."}],
  "language": "fr",
  "grade": "12",
  "subject": "math",
  "stream": true
}
  • Response (Streaming): text/event-stream (SSE).
  • Response (JSON): {"answer": "...", "sources": [...]}.

5. Wallet (/wallet)

GET /wallet/balance

  • Auth: Bearer Token (Supabase JWT)
  • Purpose: Retrieve current token balance, tier, and pending reservations.
  • Response: 
    {
  "user_id": "...",
  "token_balance": 50,
  "subscription_tier": "free",
  "pending_reservations": 0
}

GET /wallet/reservations

  • Auth: Bearer Token (Supabase JWT)
  • Purpose: List user's token reservations.
  • Query Params: ?status=reserved

POST /wallet/topup (Admin)

  • Auth: Admin JWT or X-Admin-Key
  • Purpose: Top up a student's wallet with tokens. Records financial transaction.
  • Request Body: 
    {
  "user_id": "uuid",
  "token_amount": 500,
  "amount_cents": 10000,
  "currency": "MRU",
  "payment_method": "cash",
  "payment_ref": "REC-001",
  "description": "Monthly top-up"
}
  • Response: {"transaction_id": "...", "new_balance": 1500, ...}

POST /wallet/transactions/expense (Admin)

  • Auth: Admin JWT or X-Admin-Key
  • Purpose: Log a system expense (API costs, server costs).
  • Request Body: 
    {
  "type": "api_cost",
  "amount_cents": 5000,
  "currency": "USD",
  "description": "OpenAI API usage - February 2026"
}

GET /wallet/transactions (Admin)

  • Auth: Admin JWT or X-Admin-Key
  • Purpose: List financial transactions with filters.
  • Query Params: ?direction=credit&type=topup&user_id=...&limit=50&offset=0

POST /wallet/internal/reserve (Internal)

  • Auth: Admin JWT or X-Admin-Key
  • Purpose: Manually create a token reservation (testing only).

POST /wallet/internal/finalize (Internal)

  • Auth: Admin JWT or X-Admin-Key
  • Purpose: Manually finalize a token reservation (testing only).

6. Admin (/admin)

GET /admin/test-role

  • Auth: Admin JWT or X-Admin-Key
  • Purpose: Verify admin privileges.

GET /admin/users

  • Auth: Admin JWT or X-Admin-Key
  • Purpose: List users from profiles table (paginated).
  • Query Params: ?limit=50&offset=0

PATCH /admin/users/{user_id}/role

  • Auth: Admin JWT or X-Admin-Key
  • Purpose: Update user role (admin, student, teacher).
  • Request Body: {"role": "admin"}

PATCH /admin/users/{user_id}/hint-level

  • Auth: Admin JWT or X-Admin-Key
  • Purpose: Update user's pedagogical hint level (1-5).
  • Query Param: ?hint_level=3

POST /admin/users

  • Auth: Admin JWT or X-Admin-Key
  • Purpose: Create a new user via Supabase Auth admin API.
  • Request Body: {"email": "...", "password": "...", "full_name": "...", "role": "student"}

DELETE /admin/users/{user_id}

  • Auth: Admin JWT or X-Admin-Key
  • Purpose: Delete a user from Supabase Auth and profiles table.

POST /admin/users/{user_id}/reset-password

  • Auth: Admin JWT or X-Admin-Key
  • Purpose: Reset a user's password.
  • Request Body: {"new_password": "..."}

GET /admin/stats

  • Auth: Admin JWT or X-Admin-Key
  • Purpose: Dashboard statistics (documents, chunks, references, users, jobs).

GET /admin/references

  • Auth: Admin JWT or X-Admin-Key
  • Purpose: List all references across all sources.
  • Query Params: ?status=ready&limit=50&offset=0

GET /admin/scrape-runs

  • Auth: Admin JWT or X-Admin-Key
  • Purpose: List all scrape runs across all sources.

POST /admin/upload-curriculum

  • Auth: Admin JWT or X-Admin-Key
  • Purpose: Manually upload a PDF for ingestion.
  • Content-Type: multipart/form-data
  • Fields: file, grade, subject, language, namespace, pdf_source

POST /admin/ingest/{reference_id}

  • Auth: Admin JWT or X-Admin-Key
  • Purpose: Create a queued ingestion job for a reference. Processing runs in the background after dispatch.
  • Query Param: ?force=false
  • Response: {"status": "queued", "job_id": "...", "reference_id": "..."}

POST /admin/jobs/dispatch

  • Auth: Admin JWT or X-Admin-Key
  • Purpose: Pick the oldest queued ingestion job and start background processing.
  • Response: {"status": "dispatched", "job_id": "...", "reference_id": "..."}

GET /admin/jobs

  • Auth: Admin JWT or X-Admin-Key
  • Purpose: List ingestion jobs with optional status filter.
  • Query Params: ?status=queued&limit=50&offset=0

GET /admin/jobs/{job_id}

  • Auth: Admin JWT or X-Admin-Key
  • Purpose: Get details for a single ingestion job.

POST /admin/jobs/{job_id}/requeue

  • Auth: Admin JWT or X-Admin-Key
  • Purpose: Requeue a failed job for retry.

PATCH /admin/documents/{document_id}

  • Auth: Admin JWT or X-Admin-Key
  • Purpose: Update optional metadata on a document (title, major, weight, category).

DELETE /admin/documents/{document_id}

  • Auth: Admin JWT or X-Admin-Key
  • Purpose: Delete a document, its chunks, and Pinecone vectors. Resets linked reference status.

POST /admin/vector-embedding (Legacy)

  • Auth: Admin JWT or X-Admin-Key
  • Purpose: Legacy endpoint — creates a queued job and returns immediately.
  • Request Body: {"reference_id": "UUID", "force": false}

7. Curriculum (/curriculum) — Student Content Browsing

GET /curriculum/subjects

  • Auth: None (public)
  • Purpose: List distinct subjects from ingested (ready) documents.
  • Response: {"subjects": ["Mathematiques", "Physique", ...], "total": 4}

GET /curriculum/textbooks

  • Auth: None (public)
  • Purpose: List available textbooks grouped by education level.
  • Query Params: ?grade=...&subject=...&language=... (all optional)

GET /curriculum/textbooks/{id}

  • Auth: None (public)
  • Purpose: Get details for a single textbook including page range from chunks.

8. Scraping (/scraping)

GET /scraping/sources

  • Auth: None
  • Purpose: List supported scraper sources.
  • Response: {"sources": ["koutoubi"]}

POST /scraping/{source}/sync

  • Auth: Admin JWT or X-Admin-Key
  • Purpose: Trigger a scrape of a portal.
  • Response: {"run_id": "...", "status": "success", "found_count": 120, "new_count": 5}

GET /scraping/{source}/runs

  • Auth: None
  • Purpose: List recent scrape runs for a source.

GET /scraping/{source}/references

  • Auth: None
  • Purpose: List discovered curriculum files.
  • Query Params: ?status=discovered&limit=50&offset=0

Back to Index