Skip to content

API_EN.md

Latest commit

 

History

History
104 lines (66 loc) · 4.24 KB

API_EN.md

File metadata and controls

104 lines (66 loc) · 4.24 KB
Raw

API Documentation - InsightPop (v1)

Infrastructure Note: As of version 0.4.1, the backend strictly requires vital environment variables (GEMINI_API_KEYS, SECRET_KEY, MONGO_URI) validated via Pydantic. The server will refuse to start if the .env file is incorrect or incomplete.

Global Error Standard: As of version 0.5.1, all API errors (HTTP 400, 401, 404, 409, 429, 500) return a standardized JSON object in the format {"detail": "Descriptive error message."}.

Developer Mock Mode: The API supports a test mode by sending the X-Mock-Mode: true header. When present, production services (Gemini) are replaced by fixed mock responses, and JWT expiration validation is ignored, allowing local simulations without consuming quotas.

This is the complete technical reference for all endpoints available in the FastAPI backend (/api/v1). All responses and requests (except file uploads) use the application/json format.

Index

🔐 Authentication and Account (/auth)

Security Warning (JWT): Most endpoints in this API (except open routes like /auth/signup and /auth/token) require JWT token authentication. You must include the Authorization: Bearer <your_token> header in protected requests.

POST /auth/signup

Registers a new user and returns a JWT access token. Profile facts and suggested initial rules are also saved. This endpoint has Rate Limiting per IP.

POST /auth/token

Authenticates the user by validating the password and returns a JWT access token.

PUT /auth/profile

Updates an existing user's profile and saves additional rules if provided.

POST /auth/forgot-password

Requests password recovery by sending a secure link via email.

POST /auth/reset-password

Sets a new password using a valid recovery token.

DELETE /auth/account

Permanently deletes the logged-in user's account and all associated data (rules and insights).

💬 Conversational Onboarding (/onboarding)

GET /onboarding/start

Starts the onboarding process, returning the virtual assistant's welcome message. This endpoint has Rate Limiting per IP.

POST /onboarding/message

Sends the chat history for Gemini to continuously analyze the user profile.

🧠 AI Processing and Extraction (/process)

POST /process

Receives an unstructured file, sends it to the AI (Google Gemini), and returns structured JSON data. (Note: Uses a deterministic Smart Scoring algorithm that ensures high availability by switching keys and models in milliseconds). This endpoint has Rate Limiting per IP.

📚 Insight / Memory Management (/insights & /confirm-insights)

POST /confirm-insights

Main (and central) endpoint for saving, editing, or merging memories. Contains internal logic for duplicate checking by identifiers (Tax ID, Email, Phone) to prevent repeated records.

This endpoint serves three distinct app flows depending on the payload parameters:

  1. New Memory Creation
  2. Existing Memory Editing
  3. Memory Consolidation/Merging

GET /insights

Lists all memories. Supports search query param for global textual search.

GET /insights/count

Returns the total count of a user's memories.

GET /insights/{insight_id}

Returns the details of a specific memory by its ID.

POST /insights/{insight_id}/snooze

Reschedules the date of a specific action trigger within a memory.

DELETE /insights/{insight_id}/triggers/{trigger_index}

Permanently removes a specific action trigger within a memory.

DELETE /insights/{insight_id}

Permanently deletes a memory.

⚙️ User Rules (/rules)

GET /rules

Lists all registered guidelines for a user.

POST /rules

Creates a new rule for the AI.

PUT /rules/{rule_id}

Completely replaces a rule's data.

DELETE /rules/{rule_id}

Deletes a rule.