> ## Documentation Index
> Fetch the complete documentation index at: https://omniloy.mintlify.site/llms.txt
> Use this file to discover all available pages before exploring further.

# Coding API

> Overview

The Omniscribe Codify API **provides AI-powered ICD-10 medical coding** from clinical notes, **with 77% greater accuracy than general-purpose LLMs**.

**In simple terms**: you send a clinical note (text or PDF), and the API returns structured ICD-10 code assessments with confidence scores, justifications, and detailed analysis of the AI's decision-making process.

## Why We Are Different

Unlike general-purpose LLMs (such as ChatGPT, Claude, etc.), we use **specialized models trained specifically for clinical coding**, achieving:

* 77% higher accuracy than general LLMs in ICD-10 coding.
* A 92% reduction in medical hallucinations.
* Customization for your center: Personalized models trained on your nomenclatures and workflows.
* Truly multilingual: Trained on clinical Spanish, Catalan, Basque, Galician, and English.

## What Is It For?

This API solves critical clinical documentation challenges:

### ICD-10 Medical Coding

* **Automatic ICD-10 code extraction** from clinical notes with AI-powered analysis.
* **Confidence scores** for each code (0-100%) to support coding decisions.
* **Detailed justifications** explaining why each code was selected.
* **Discarded codes analysis** showing rejected codes and reasoning.
* **Measurable ROI**: A 70% reduction in coding time.

### Billing and Compliance

* **Accurate code assignments** for reimbursement.
* **Audit trail** with run\_id tracking for each coding session.
* **Doctor and patient tracking** for regulatory compliance.
* **Quality assurance** through transparent AI decision-making.

### Integration Ready

* **PDF support** for processing scanned documents (up to 5MB).
* **Text input** for direct EHR integration (up to 50KB).
* **Custom AI models** selection for specialized needs.
* **RESTful API** with consistent error handling.

## How Does the Process Work?

### Step 1: Prepare Your Clinical Note

Prepare your clinical note as either:

* **Plain text** (up to 50KB) - from EHR, dictation, or manual entry
* **PDF file** (up to 5MB decoded) - scanned documents or reports

Optionally, specify a custom AI model for specialized processing needs.

### Step 2: Send to the Codify API

Send your clinical note to `/v1/codify` with optional tracking headers for audit purposes.

**Our specialized clinical AI engine**:

1. Analyzes the medical context using models trained on millions of real clinical notes.
2. Identifies diagnoses and medical conditions with high accuracy.
3. Assigns appropriate ICD-10 codes with confidence scores.
4. Provides detailed justifications for each code selection.
5. Shows discarded codes and why they were rejected.

### Step 3: Receive ICD-10 Code Assessments

The API returns:

* **Final code assessments**: Selected ICD-10 codes with descriptions, justifications, and confidence scores
* **Discarded assessments**: Rejected codes showing the AI's decision-making process
* **Run ID**: Unique identifier for tracking and debugging

<Steps>
  <Step title="Clinical Input">
    Submit your clinical note as **text or PDF** to the API.
  </Step>

  <Step title="AI Analysis">
    The **Specialized AI Engine** (+77% accuracy improvement) analyzes the clinical content.
  </Step>

  <Step title="Structured Results">
    Receive **ICD-10 codes** with confidence scores, detailed **justifications**, and discarded codes with reasoning — ready for billing and coding workflows.
  </Step>
</Steps>

**Key advantage:** Complete transparency with confidence scores and justifications helps coders make informed decisions and maintain quality standards.

***

## Available Endpoints

<Columns cols={2}>
  <Card title="POST /v1/codify">
    Codes clinical text into a JSON structure that you define.
  </Card>

  <Card title="GET /v1/health">
    Verifies that the service is operational.
  </Card>
</Columns>

***

## Interactive API Playground

The documentation includes an **interactive API playground** powered by the OpenAPI specification. You can test API calls directly from the browser without writing any code.

<Steps>
  <Step title="Navigate to the API Reference">
    Go to the **API Reference** section in the SofIA API tab, or click [here](/api-reference/codify-clinical-text-into-a-json-structure-you-define).
  </Step>

  <Step title="Configure authentication">
    Enter your Bearer token in the **Authorization** field at the top of the playground.
  </Step>

  <Step title="Fill in the request">
    Use the form fields to build your request, or switch to the **Body** tab to paste raw JSON. The playground validates your input against the OpenAPI schema in real time.
  </Step>

  <Step title="Send and inspect">
    Click **Send** to execute the request. The response panel shows the status code, headers, and formatted JSON body.
  </Step>
</Steps>

<Tip>
  The playground uses your real API credentials. Use test data (not real patient information) when experimenting.
</Tip>

***

## API Versioning

### Versioning Scheme

* **Path versioning:** `/v1/`, `/v2/`, etc.
* **Backward-compatible changes:** Are added to the current version without breaking the API.
* **Breaking changes:** Increment the major version (e.g., v1 → v2).

> **Current version**: **v1.0.0** — Initial release of the public endpoint.

***

## Next Steps

<Columns cols={2}>
  <Card title="1. Quickstart" icon="book" href="/sofia/en/api/quickstart">
    Your first API call
  </Card>

  <Card title="2. Authentication" icon="lock" href="/sofia/en/api/auth">
    Configuring tokens and headers
  </Card>

  <Card title="3. Data Structure" icon="paste" href="/sofia/en/api/request-response">
    Requests and responses
  </Card>

  <Card title="4. View Examples" icon="lightbulb" href="/sofia/en/api/examples">
    Practical coding examples
  </Card>

  <Card title="5. Operations and Errors" icon="gear" href="/sofia/en/api/operations">
    Error handling and security
  </Card>

  <Card title="6. Complete Reference" icon="book" href="/api-reference/codify-clinical-text-into-a-json-structure-you-define">
    OpenAPI specification
  </Card>
</Columns>