API Reference

Complete reference for the AyushBridge FHIR R4-compliant terminology API. All endpoints follow FHIR specifications and support standard HTTP methods and status codes.

Authentication

All API requests require OAuth 2.0 Bearer token authentication via ABHA (Ayushman Bharat Health Account):

Authorization Header

Authorization: Bearer <ABHA_TOKEN>

curl -X POST "https://abha.abdm.gov.in/auth/oauth2/token" \
  -H "Content-Type: application/x-www-form-urlencoded" \
  -d "grant_type=client_credentials" \
  -d "client_id=YOUR_CLIENT_ID" \
  -d "client_secret=YOUR_CLIENT_SECRET" \
  -d "scope=openid profile abha-enrol"

Base URL & Headers

Production: https://api.ayushbridge.in
Development: http://localhost:3000

Required Headers

Authorization: Bearer <ABHA_TOKEN>
Accept: application/fhir+json
Content-Type: application/fhir+json

Optional Headers

Accept-Language: en, hi
X-Request-ID: unique-request-identifier

Terminology Lookup

Lookup specific terminology codes with detailed information.

NAMASTE Code Lookup

GET

/fhir/CodeSystem/namaste/$lookup

curl -X GET "https://api.ayushbridge.in/fhir/CodeSystem/namaste/\$lookup?code=NAM001" \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -H "Accept: application/fhir+json"

Parameters

code (required): NAMASTE code to look up
system (optional): Code system URI
version (optional): Version of the code system
displayLanguage (optional): Language for display text ('en', 'hi')

Response

{
  "resourceType": "Parameters",
  "parameter": [
    {
      "name": "name",
      "valueString": "NAMASTE Code System"
    },
    {
      "name": "display",
      "valueString": "Amavata (Rheumatoid Arthritis)"
    },
    {
      "name": "designation",
      "part": [
        {
          "name": "language",
          "valueCode": "hi"
        },
        {
          "name": "value",
          "valueString": "आमवात"
        }
      ]
    },
    {
      "name": "property",
      "part": [
        {
          "name": "code",
          "valueCode": "traditional-system"
        },
        {
          "name": "value",
          "valueString": "ayurveda"
        }
      ]
    }
  ]
}

Search & Autocomplete

Search and auto-complete functionality for terminology discovery.

NAMASTE Term Search

GET

/fhir/ValueSet/namaste/$expand

curl -X GET "https://api.ayushbridge.in/fhir/ValueSet/namaste/\$expand?filter=amavata&count=10" \
  -H "Authorization: Bearer YOUR_TOKEN"

Parameters

filter (required): Search term for auto-complete
count (optional): Maximum results (default: 20, max: 100)
system (optional): Filter by traditional medicine system
includeDefinition (optional): Include concept definitions

Response

{
  "resourceType": "ValueSet",
  "expansion": {
    "timestamp": "2025-09-09T10:30:00Z",
    "total": 3,
    "contains": [
      {
        "system": "https://ayush.gov.in/fhir/CodeSystem/namaste",
        "code": "NAM001",
        "display": "Amavata (Rheumatoid Arthritis)",
        "designation": [
          {
            "language": "hi",
            "value": "आमवात"
          }
        ]
      }
    ]
  }
}

Code Translation

Translate codes between different terminology systems.

NAMASTE to ICD-11 Translation

POST

/fhir/ConceptMap/namaste-to-icd11/$translate

curl -X POST "https://api.ayushbridge.in/fhir/ConceptMap/namaste-to-icd11/\$translate" \
  -H "Content-Type: application/fhir+json" \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -d '{
    "resourceType": "Parameters",
    "parameter": [
      {"name": "code", "valueCode": "NAM001"},
      {"name": "system", "valueUri": "https://ayush.gov.in/fhir/CodeSystem/namaste"},
      {"name": "target", "valueUri": "http://id.who.int/icd/release/11/mms"}
    ]
  }'

Parameters

code (required): Source code to translate
system (required): Source code system URI
target (required): Target system URI
reverse (optional): Perform reverse translation

Supported Translation Paths

NAMASTE → ICD-11 TM2
NAMASTE → ICD-11 Biomedicine
ICD-11 TM2 ↔ ICD-11 Biomedicine
WHO Ayurveda → NAMASTE

Response

{
  "resourceType": "Parameters",
  "parameter": [
    {
      "name": "result",
      "valueBoolean": true
    },
    {
      "name": "match",
      "part": [
        {
          "name": "equivalence",
          "valueCode": "equivalent"
        },
        {
          "name": "concept",
          "valueCoding": {
            "system": "http://id.who.int/icd/release/11/mms",
            "code": "TM26.0",
            "display": "Disorders of vata dosha"
          }
        },
        {
          "name": "confidence",
          "valueDecimal": 0.95
        }
      ]
    }
  ]
}

FHIR Bundle Upload

Upload FHIR Bundles with dual-coded conditions and observations.

Create Dual-Coded Condition

POST

/fhir/Bundle

curl -X POST "https://api.ayushbridge.in/fhir/Bundle" \
  -H "Content-Type: application/fhir+json" \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -d @dual-coded-condition.json

Example Bundle

{
  "resourceType": "Bundle",
  "type": "transaction",
  "entry": [
    {
      "resource": {
        "resourceType": "Condition",
        "subject": {
          "reference": "Patient/example-patient"
        },
        "code": {
          "coding": [
            {
              "system": "https://ayush.gov.in/fhir/CodeSystem/namaste",
              "code": "NAM001",
              "display": "Amavata"
            },
            {
              "system": "http://id.who.int/icd/release/11/mms",
              "code": "TM26.0",
              "display": "Disorders of vata dosha"
            },
            {
              "system": "http://id.who.int/icd/release/11/mms",
              "code": "FA20.00",
              "display": "Rheumatoid arthritis, unspecified"
            }
          ]
        },
        "clinicalStatus": {
          "coding": [
            {
              "system": "http://terminology.hl7.org/CodeSystem/condition-clinical",
              "code": "active"
            }
          ]
        },
        "category": [
          {
            "coding": [
              {
                "system": "http://terminology.hl7.org/CodeSystem/condition-category",
                "code": "problem-list-item"
              }
            ]
          }
        ]
      },
      "request": {
        "method": "POST",
        "url": "Condition"
      }
    }
  ]
}

Batch Operations

Perform batch operations for multiple codes simultaneously.

Batch Translation

POST

/fhir/ConceptMap/$batch-translate

curl -X POST "https://api.ayushbridge.in/fhir/ConceptMap/\$batch-translate" \
  -H "Content-Type: application/fhir+json" \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -d '{
    "resourceType": "Parameters",
    "parameter": [
      {
        "name": "codes",
        "part": [
          {"name": "code", "valueCode": "NAM001"},
          {"name": "code", "valueCode": "NAM002"}
        ]
      },
      {"name": "source", "valueUri": "https://ayush.gov.in/fhir/CodeSystem/namaste"},
      {"name": "target", "valueUri": "http://id.who.int/icd/release/11/mms"}
    ]
  }'

Error Handling

AyushBridge uses standard HTTP status codes and FHIR OperationOutcome resources for error reporting.

Error Response Format

{
  "resourceType": "OperationOutcome",
  "issue": [
    {
      "severity": "error",
      "code": "not-found",
      "details": {
        "text": "Code NAM999 not found in NAMASTE CodeSystem"
      },
      "diagnostics": "Verify the code exists in the current version"
    }
  ]
}

Common Error Codes

Status	Code	Description
400	`invalid`	Invalid request parameters
401	`login`	Authentication required
403	`forbidden`	Insufficient permissions
404	`not-found`	Resource not found
429	`throttled`	Rate limit exceeded
500	`exception`	Internal server error

Rate Limiting

Default Limit: 1000 requests per hour per client
Headers: X-RateLimit-Limit, X-RateLimit-Remaining, X-RateLimit-Reset
Burst Allowance: 100 requests per minute

Learn more about authentication setup