Skip to main content

Documentation Index

Fetch the complete documentation index at: https://mintlify.com/sagar-grv/ayush-synapse/llms.txt

Use this file to discover all available pages before exploring further.

By the end of this guide you will have Ayush Synapse running on your machine and will have successfully translated a NAMASTE code to its ICD-11 TM2 equivalent via the REST API. No database setup is required — the server uses SQLite by default and seeds itself with sample data on first boot.

​
Prerequisites

Before you begin, make sure the following tools are available on your system:
  • Python 3.8 or later — check with python --version
  • pip — bundled with Python 3.8+; check with pip --version
  • Git — to clone the repository

​
Setup Steps

1

Clone the repository and create a virtual environment

Clone the Ayush Synapse repository and create an isolated Python environment so that dependencies do not conflict with other projects on your machine.
git clone https://github.com/sagar-grv/ayush-synapse.git
cd ayush-synapse

# Create and activate a virtual environment
python -m venv .venv
source .venv/bin/activate        # macOS / Linux
# .venv\Scripts\activate         # Windows
2

Install dependencies

Install all required Python packages from the pinned requirements file.
pip install -r requirements.txt
The key packages installed are: flask, flask-cors, flask-limiter, flask-sqlalchemy, pyjwt, python-dotenv, pandas, requests, and flask-swagger-ui.
3

Configure environment variables

Copy the provided example file to create your local .env configuration. The defaults work out of the box for local development.
cp .env.example .env
The default .env sets DEMO_MODE=True, uses SQLite for storage, and listens on 0.0.0.0:5000. You do not need to edit anything to proceed.
4

Start the Flask server

Launch the application. It will create the SQLite database, seed sample NAMASTE codes and concept maps, then begin serving requests.
python app.py
Expected output:
Loaded 6 NAMASTE codes from CSV
Saved 6 NAMASTE codes to database
Saved 85 concept mappings to database
Ayush Synapse MVP starting in DEMO mode
Access the application at http://0.0.0.0:5000
Demo mode enabled - all features accessible with demo token
Visit /demo/guide for detailed instructions
 * Running on all addresses (0.0.0.0)
 * Running on http://127.0.0.1:5000
The server is ready when you see the Running on http://127.0.0.1:5000 line.
5

Obtain a demo token

All protected endpoints require a Bearer token. In demo mode you can generate one instantly — no registration needed.
curl -s -X POST http://127.0.0.1:5000/auth/login \
  -H "Content-Type: application/json" \
  -d '{"user_id": "demo_user", "role": "clinician"}'
The response contains your token and confirms demo access:
{
  "message": "Authentication successful",
  "token": "eyJ0eXAiOiJKV1QiLCJhbGciOiJIUzI1NiJ9...",
  "user_id": "demo_user",
  "role": "clinician",
  "permissions": {
    "can_access_all_endpoints": true,
    "can_view_all_data": true,
    "can_perform_translations": true,
    "can_access_fhir_resources": true
  },
  "demo_mode": true,
  "demo_note": "This is a demo token with full access to all features. No registration required."
}
Copy the value of "token" — you will use it in the next section.

​
Your First API Call

Now translate NAMASTE code NAM-001 (Common Cold) to its ICD-11 TM2 equivalent. Replace <YOUR_TOKEN> with the token you copied in Step 5. 
curl -s -X POST http://127.0.0.1:5000/translate \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer <YOUR_TOKEN>" \
  -d '{"sourceCode": "NAM-001", "sourceSystem": "NAMASTE"}'
A successful response confirms the mapping and its confidence score: 
{
  "sourceCode": "NAM-001",
  "targetCode": "TM2-001",
  "targetSystem": "ICD-11 TM2",
  "equivalence": "equivalent",
  "confidence": 0.9
}
FieldDescription
sourceCodeThe NAMASTE code you submitted
targetCodeThe mapped ICD-11 TM2 or Biomedicine code
targetSystemThe target coding system (ICD-11 TM2 or ICD-11 Biomedicine)
equivalenceFHIR equivalence type — equivalent, wider, narrower, or inexact
confidenceA 0–1 score indicating mapping confidence (0.9 = 90%)

​
Explore Further

Demo Mode

Learn how demo mode works, how long tokens last, and how to explore every endpoint without any credentials to manage.

Professional Dashboard

Open the browser-based dashboard for advanced dual-coding search, analytics, and FHIR resource browsing.

API Reference

Complete reference for all public and protected endpoints with request and response schemas.

Build docs developers (and LLMs) love

Get started for freeTalk to us