Spaces:
Running on Zero
Running on Zero
| # 📜 SaulGPT API Reference Manual | |
| **API Version:** 2.2.0 | |
| **Cloud Base URL:** `https://lvvbaaal-legalgpt-api.hf.space` | |
| **Local Development Base URL:** `http://localhost:8000` | |
| **Transport Security:** HTTPS / TLS 1.3 | |
| **Authentication Scheme:** Bearer Token (JWT, 30-day validity, HS256) + BYOK Header (`X-Groq-Api-Key`) | |
| --- | |
| ## 1. Authentication Endpoints | |
| ### `POST /api/auth/signup` | |
| Registers a new user in the PostgreSQL (or local SQLite) database. | |
| - **Request Body:** | |
| ```json | |
| { | |
| "username": "advocate_sharma", | |
| "email": "sharma@lawchambers.in", | |
| "password": "StrongPassword123!" | |
| } | |
| ``` | |
| - **Response (200 OK):** | |
| ```json | |
| { | |
| "token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...", | |
| "user": { | |
| "id": 1, | |
| "username": "advocate_sharma", | |
| "email": "sharma@lawchambers.in" | |
| } | |
| } | |
| ``` | |
| ### `POST /api/auth/login` | |
| Authenticates existing users and issues a JWT token. | |
| - **Request Body:** | |
| ```json | |
| { | |
| "email": "sharma@lawchambers.in", | |
| "password": "StrongPassword123!" | |
| } | |
| ``` | |
| - **Response (200 OK):** | |
| ```json | |
| { | |
| "token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...", | |
| "user": { | |
| "id": 1, | |
| "username": "advocate_sharma", | |
| "email": "sharma@lawchambers.in" | |
| } | |
| } | |
| ``` | |
| ### `GET /api/auth/me` | |
| Retrieves current authenticated profile. | |
| - **Headers:** `Authorization: Bearer <token>` | |
| - **Response (200 OK):** | |
| ```json | |
| { | |
| "id": 1, | |
| "username": "advocate_sharma", | |
| "email": "sharma@lawchambers.in" | |
| } | |
| ``` | |
| --- | |
| ## 2. BYOK (Bring Your Own Key) Security Endpoints | |
| ### `POST /api/keys/validate` | |
| Validates a personal Groq API key format and live cloud quota. | |
| - **Request Body:** | |
| ```json | |
| { | |
| "key": "gsk_live_sample_token..." | |
| } | |
| ``` | |
| - **Response (200 OK):** | |
| ```json | |
| { | |
| "valid": true, | |
| "message": "Key is active and authenticated with Groq API" | |
| } | |
| ``` | |
| ### `GET /api/keys/status` | |
| Checks if the server environment has a default Groq key or requires BYOK. | |
| - **Response (200 OK):** | |
| ```json | |
| { | |
| "server_key_present": true, | |
| "byok_required": false | |
| } | |
| ``` | |
| --- | |
| ## 3. Core Chat & Document Pipeline Endpoints | |
| ### `POST /api/chat` | |
| Main conversational query endpoint. Dispatches through the 6-layer RAG pipeline, triage state machine, or document drafting interview. | |
| - **Headers:** | |
| - `Content-Type: application/json` | |
| - `Authorization: Bearer <token>` *(Optional; guest session assumed if omitted)* | |
| - `X-Groq-Api-Key: gsk_...` *(Optional; forwards personal Groq quota)* | |
| - **Request Body:** | |
| ```json | |
| { | |
| "message": "Draft a legal notice for cheque bounce of Rs 75,000", | |
| "session_id": "session_uuid_or_custom_id", | |
| "user_id": 1, | |
| "conv_id": 6 | |
| } | |
| ``` | |
| - **Response (200 OK):** | |
| ```json | |
| { | |
| "response": "**Cheque Bounce Notice** has been drafted successfully.\n\n[Download your document](https://lvvbaaal-legalgpt-api.hf.space/api/document/session_uuid_or_custom_id)", | |
| "mode_used": "document", | |
| "confidence_score": 0.85, | |
| "critic_reward_score": 0.95, | |
| "critic_deliberation": null, | |
| "is_hallucinating": false, | |
| "citations": [], | |
| "remapped_laws": { | |
| "IPC": "BNS (Bharatiya Nyaya Sanhita, 2023)", | |
| "CrPC": "BNSS (Bharatiya Nagarik Suraksha Sanhita, 2023)" | |
| }, | |
| "meta": { | |
| "document_ready": true, | |
| "document_url": "https://lvvbaaal-legalgpt-api.hf.space/api/document/session_uuid_or_custom_id" | |
| }, | |
| "conv_id": 6, | |
| "interview_active": false, | |
| "interview_complete": true | |
| } | |
| ``` | |
| ### `GET /api/document/{session_id}` | |
| Streams a generated Microsoft Word (`.docx`) file as a download attachment. | |
| - **Response Headers:** | |
| - `Content-Type: application/vnd.openxmlformats-officedocument.wordprocessingml.document` | |
| - `Content-Disposition: attachment; filename="legal_document_{session_id}.docx"` | |
| - `Access-Control-Allow-Origin: *` | |
| ### `GET /api/draft/state/{session_id}` | |
| Returns active interview state, current progress percentage, and missing fields. | |
| - **Response (200 OK):** | |
| ```json | |
| { | |
| "state": "interviewing", | |
| "doc_type": "cheque_bounce", | |
| "progress_pct": 57, | |
| "missing_fields": ["amount", "date_of_default"], | |
| "is_active": true | |
| } | |
| ``` | |
| ### `DELETE /api/draft/state/{session_id}` | |
| Cancels the active drafting interview and resets the session state. | |
| ### `DELETE /api/history/{session_id}` | |
| Purges the in-memory conversation history for a given session. | |
| --- | |
| ## 4. Pre-Trial Studio & Moot Court Endpoints | |
| ### `POST /api/trial/start` | |
| Initializes an adversarial Moot Court chamber. | |
| - **Request Body:** | |
| ```json | |
| { | |
| "case_title": "State vs. Accused (Section 103 BNS)", | |
| "scenario_description": "Accused allegedly assaulted complainant on 10 July 2024...", | |
| "session_id": "trial_session_001" | |
| } | |
| ``` | |
| - **Response (200 OK):** | |
| ```json | |
| { | |
| "trial_id": "trial_session_001", | |
| "judge_summary": "Issue framed under Section 103 BNS 2023...", | |
| "petitioner_strategy": "Argue premeditation and direct ocular evidence...", | |
| "respondent_strategy": "Assert right of private defense under Section 34 BNS..." | |
| } | |
| ``` | |
| ### `POST /api/trial/turn` | |
| Executes an adversarial interrogation turn with the judicial cross-examiner under Section 146 BSA 2023. | |
| - **Request Body:** | |
| ```json | |
| { | |
| "trial_id": "trial_session_001", | |
| "user_statement": "The witness claims he saw the incident under street lighting from 50 meters away.", | |
| "role": "petitioner" | |
| } | |
| ``` | |
| ### `POST /api/trial/conclude` | |
| Concludes the moot proceedings, tallies evidence scores, and renders a judicial verdict. | |
| ### `GET /api/trial/precedents/{case_id}` | |
| Retrieves verbatim precedent holdings and coram metadata from the 50,000+ landmark judgment index. | |
| --- | |
| ## 5. Multimodal Evidence & Section 63 BSA Certification | |
| ### `POST /api/evidence/upload` | |
| Uploads digital evidence (audio files, WhatsApp chat exports, invoice PDFs, cheque scans) for forensic verification. | |
| - **Form Data:** | |
| - `file`: Binary file upload | |
| - `session_id`: Session string | |
| - `evidence_type`: `audio` | `document` | `cheque` | |
| - **Response (200 OK):** | |
| ```json | |
| { | |
| "evidence_id": "EVID-2024-99182", | |
| "sha256_hash": "e3b0c44298fc1c149afbf4c8996fb92427ae41e4649b934ca495991b7852b855", | |
| "certificate": { | |
| "certificate_id": "BSA-63-2024-99182", | |
| "pdf_url": "/api/certificates/BSA-63-2024-99182.pdf" | |
| }, | |
| "extracted_data": { | |
| "summary": "Audio conversation between tenant and landlord regarding rent default." | |
| } | |
| } | |
| ``` | |
| ### `GET /api/certificates/{cert_filename}` | |
| Serves court-admissible Section 63 BSA PDF certificates. | |
| --- | |
| ## 6. Contract Risk Evaluator (Layer 6) | |
| ### `POST /api/upload` | |
| Evaluates contracts and master agreements up to 25,000 characters in a single pass. | |
| - **Form Data:** | |
| - `file`: Contract document (`.pdf`, `.docx`, `.txt`) | |
| - `session_id`: String | |
| - **Response (200 OK):** | |
| ```json | |
| { | |
| "session_id": "contract_audit_001", | |
| "evaluation": { | |
| "overall_score": 72, | |
| "risk_level": "Medium Risk", | |
| "summary": "Standard SaaS subscription agreement with void post-termination non-compete.", | |
| "void_clauses": [ | |
| { | |
| "clause": "Clause 14.2: Employee non-compete for 2 years across India", | |
| "statute": "Section 27, Indian Contract Act 1872", | |
| "remedy": "Delete non-compete; replace with strict customer non-solicitation." | |
| } | |
| ] | |
| } | |
| } | |
| ``` | |
| --- | |
| ## 7. Cloud Persistence & Conversations | |
| ### `GET /api/conversations` | |
| Lists past conversations for the authenticated user from Supabase. | |
| - **Headers:** `Authorization: Bearer <token>` | |
| - **Response (200 OK):** | |
| ```json | |
| { | |
| "conversations": [ | |
| { | |
| "id": 6, | |
| "title": "Cheque Bounce Notice under Section 138 NIA", | |
| "created_at": "2026-10-26T14:44:43Z", | |
| "updated_at": "2026-10-26T14:51:03Z" | |
| } | |
| ], | |
| "total": 1 | |
| } | |
| ``` | |
| ### `GET /api/conversations/{id}` | |
| Loads full turn history and structured metadata for conversation ID. | |
| - **Headers:** `Authorization: Bearer <token>` | |
| ### `DELETE /api/conversations/{id}` | |
| Permanently deletes a conversation and cascades through messages. | |
| --- | |
| ## 8. System Diagnostics | |
| ### `GET /api/health` | |
| Checks server vitality and returns feature capabilities. | |
| - **Response (200 OK):** | |
| ```json | |
| { | |
| "status": "SaulGPT API is Online ⚖️", | |
| "version": "2.0.0", | |
| "features": [ | |
| "6-layer RAG", | |
| "Contract Evaluation", | |
| "Interactive Drafter" | |
| ] | |
| } | |
| ``` | |