Sachet API Reference — REST API Specification

Base URL & Authentication

The Sachet API runs as a lightweight, asynchronous FastAPI service. By default, it runs locally on:

http://127.0.0.1:8000

If configured with an API key, supply it in the x-api-key request header. All active session state resides strictly in RAM and expires after 30 minutes of inactivity.

1. Analyze Call Turn

POST /v1/analyze

Ingests a single utterance from either the caller or the citizen. Updates the rolling conversational context, runs MuRIL scoring, checks psychological signals, and returns risk metrics.

Request Body (JSON)

Field	Type	Description
`session_id`	string	Unique UUID identifying the call session.
`text`	string	The transcribed dialogue turn in Hindi, Hinglish, or English.
`speaker`	string	`"caller"` (suspect) or `"victim"` (citizen). Default: `"caller"`.

Response (JSON)

Field	Type	Description
`risk_score`	integer	Calculated scam risk score from `0` to `100`.
`level`	string	`"low"` (<40), `"medium"` (40–64), or `"high"` (≥65).
`reason`	string	Conversational explanation in natural Hindi explaining detected tactics.
`signals`	string[]	List of detected psychological signals (e.g. `["Digital arrest threat", "Urgency deadline"]`).
`alert`	boolean	`true` when consecutive turns sustain high risk, triggering urgent citizen warning.
`history`	integer[]	Trajectory of risk scores across all turns in this session.

cURL Example

curl -X POST http://127.0.0.1:8000/v1/analyze \
  -H "Content-Type: application/json" \
  -d '{
    "session_id": "c71a34d9-8134-4bc8-8c54-722123bf0114",
    "speaker": "caller",
    "text": "Main CBI se bol raha hoon, aapke Aadhaar par arrest warrant hai, phone mat kaatiye."
  }'
        

2. End Session & Purge RAM

POST /v1/session/end

Immediately erases and de-allocates the session's conversational turns and risk history from server memory. Guarantees zero residual data retention.

Request Body

{
  "session_id": "c71a34d9-8134-4bc8-8c54-722123bf0114"
}
        

Response

{
  "deleted": true
}
        

3. Audio Chunk Transcription (Whisper)

POST /v1/transcribe?lang=hi

Streams raw audio chunks (WebM/WAV) to the lightweight Whisper STT pipeline. Returns pure text without retaining the uploaded audio file on disk.

Response

{
  "text": "Aapke Aadhaar card par arrest warrant jaari hua hai."
}
        

4. Health & Status Check

GET /health

Returns service status and count of active ephemeral sessions in memory.

{
  "ok": true,
  "sessions": 1
}
        

Python Integration Example

A simple snippet to stream turns into the Sachet API in Python:

import requests

session_id = "test-session-123"
url = "http://127.0.0.1:8000/v1/analyze"

turn_data = {
    "session_id": session_id,
    "speaker": "caller",
    "text": "Sir aapka electricity bill due hai, aaj raat bijli kat jayegi."
}

response = requests.post(url, json=turn_data)
result = response.json()

print(f"Risk Score: {result['risk_score']}/100")
print(f"Severity  : {result['level']}")
print(f"Reason    : {result['reason']}")
        