> ## 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.

# API: Quick start

> Get started with the SofIA Codify API in minutes with a simple request example

## Prerequisites

<Columns cols={3}>
  <Card title="API Token" icon="check">
    We provide it when contracting the service
  </Card>

  <Card title="Endpoint" icon="check">
    Production or development URL
  </Card>

  <Card title="Tool for making HTTP requests" icon="check">
    Postman, curl, or your favorite language
  </Card>
</Columns>

***

## Your first API call

### Basic example with curl

```bash theme={null}
curl -X POST "https://{your-endpoint}/v1/codify" \
  -H "Authorization: Bearer YOUR_TOKEN_HERE" \
  -H "Content-Type: application/json" \
  -H "x-doctor: dr_123" \
  -H "x-patient: pt_456" \
  -d '{
    "medical_note": "Patient presents with Type 2 Diabetes Mellitus. Current medications: Metformin 500mg BID, Glipizide 5mg QD. Blood glucose levels stable. No complications noted. HbA1c: 6.8%.",
    "model": "balanced"
  }'
```

### Expected response

```json theme={null}
{
  "final_code_assessments": [
    {
      "code": "E11.9",
      "description": "Type 2 diabetes mellitus without complications",
      "justification": "The note documents Type 2 Diabetes without mention of decompensation or complications; corresponds to E11.9 (DM2 without complications).",
      "confidence_percent": 92.4
    },
    {
      "code": "Z79.84",
      "description": "Long term (current) use of oral hypoglycemic drugs",
      "justification": "The patient uses metformin and glipizide chronically; both are oral antidiabetic drugs, supporting long term use of oral hypoglycemic drugs.",
      "confidence_percent": 96.1
    }
  ],
  "discarded_code_assessments": [],
  "run_id": "1ef8e0d4-7890-6b3c-8f90-abcdef123456"
}
```

Congratulations! You have coded your first clinical note with AI-powered ICD-10 medical coding!

***

## Request breakdown

### Mandatory headers

```http theme={null}
Authorization: Bearer YOUR_TOKEN_HERE
Content-Type: application/json
```

### Optional headers

Visit [Authentication](/sofia/en/api/auth#optional-headers-recommended) for traceability header configuration.

### Request body

You must provide **either** `medical_note` OR `pdf_file` (mutually exclusive):

| Field          | Required | Description                                                                   |
| -------------- | -------- | ----------------------------------------------------------------------------- |
| `medical_note` | Yes\*    | The clinical text to code (max 50KB)                                          |
| `pdf_file`     | Yes\*    | PDF file object with base64 encoded data (max 5MB decoded)                    |
| `model`        | No       | AI model quality level: `"fast"`, `"balanced"` (default), or `"high-quality"` |

\*One of `medical_note` or `pdf_file` is required, but not both.

***

## Examples in different languages

<CodeGroup>
  ```python Python theme={null}
  import requests

  url = "https://{your-endpoint}/v1/codify"
  headers = {
      "Authorization": "Bearer YOUR_TOKEN_HERE",
      "Content-Type": "application/json",
      "x-doctor": "dr_123",
      "x-patient": "pt_456"
  }

  payload = {
      "medical_note": "Patient presents with Type 2 Diabetes Mellitus. Current medications: Metformin 500mg BID, Glipizide 5mg QD. Blood glucose levels stable. No complications noted. HbA1c: 6.8%.",
      "model": "balanced"
  }

  response = requests.post(url, json=payload, headers=headers)
  result = response.json()

  print(f"Final codes: {len(result['final_code_assessments'])}")
  for assessment in result['final_code_assessments']:
      print(f"  {assessment['code']}: {assessment['description']} ({assessment['confidence_percent']}%)")
  print(f"Run ID: {result['run_id']}")
  ```

  ```javascript JavaScript (Node.js) theme={null}
  const axios = require('axios');

  const url = 'https://{your-endpoint}/v1/codify';
  const headers = {
    'Authorization': 'Bearer YOUR_TOKEN_HERE',
    'Content-Type': 'application/json',
    'x-doctor': 'dr_123',
    'x-patient': 'pt_456'
  };

  const payload = {
    medical_note: 'Patient presents with Type 2 Diabetes Mellitus. Current medications: Metformin 500mg BID, Glipizide 5mg QD. Blood glucose levels stable. No complications noted. HbA1c: 6.8%.',
    model: 'balanced'
  };

  axios.post(url, payload, { headers })
    .then(response => {
      console.log('Final codes:', response.data.final_code_assessments.length);
      response.data.final_code_assessments.forEach(assessment => {
        console.log(`  ${assessment.code}: ${assessment.description} (${assessment.confidence_percent}%)`);
      });
      console.log('Run ID:', response.data.run_id);
    })
    .catch(error => {
      console.error('Error:', error.response?.data || error.message);
    });
  ```
</CodeGroup>

***

## Available environments

Visit [Environment configuration](/sofia/en/api/auth#available-environments) for detailed URLs and features.

***

## Next steps

<Columns cols={2}>
  <Card title="1. View complete structure" icon="clipboard" href="/sofia/en/api/request-response">
    All available fields
  </Card>

  <Card title="2. View PDF file format" icon="file" href="/sofia/en/api/request-response">
    How to send PDF files for coding
  </Card>

  <Card title="3. View advanced examples" icon="lightbulb" href="/sofia/en/api/examples">
    Real use cases (billing datasets, structured notes, etc.)
  </Card>

  <Card title="4. Error handling" icon="gear" href="/sofia/en/api/operations">
    What to do when something fails
  </Card>
</Columns>