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

# API Reference

> Integration API for Alto Health referral automation platform

## Welcome to the Alto Health API

The Alto Health API enables integration of our dual-AI referral processing platform into your clinic workflows. Automate referral ingestion, triage, and structured data export—reducing admin workload by 75% while maintaining clinical safety and explainability.

## Base URL

All API requests should be made to:

```
https://app.arahealth.io
```

## Authentication

Alto Health uses API key-based authentication with organization-level scoping for security and data isolation.

### Authentication Types

Different endpoints require different authentication methods:

<CardGroup cols={2}>
  <Card title="Platform API Key" icon="key">
    **Used for:** Document upload operations

    **Headers Required:**

    * `org_id` - Your organization ID
    * `platform_api_key` - Your platform API key
  </Card>

  <Card title="Assistant API Key" icon="wand-magic-sparkles">
    **Used for:** Entity extraction operations

    **Headers Required:**

    * `assistant-api-key` - Your assistant API key
  </Card>
</CardGroup>

### Authentication Example

<CodeGroup>
  ```bash Document Upload theme={null}
  curl -X POST https://app.arahealth.io/api/v1/pub/records/document-upload \
    -H "org_id: your_organization_id" \
    -H "platform_api_key: your_platform_api_key" \
    -F "referral=@document.pdf"
  ```

  ```bash Entity Extraction theme={null}
  curl -X POST https://app.arahealth.io/v1/extract \
    -H "assistant-api-key: your_assistant_api_key" \
    -H "Content-Type: application/json" \
    -d '{...}'
  ```

  ```bash Job Status (No Auth Required) theme={null}
  curl -X GET https://app.arahealth.io/v1/jobs/{job_id}
  ```
</CodeGroup>

<Note>
  See the [Authentication Guide](/guides/authentication) for detailed security best practices and credential management.
</Note>

## API Endpoints Overview

### File Endpoints

<CardGroup cols={1}>
  <Card title="Upload Document" icon="upload" href="/api-reference/endpoint/document-upload">
    **POST** `/api/v1/pub/records/document-upload`

    Upload medical referrals and clinical documents for processing. Supports PDF and image formats.
  </Card>

  <Card title="Get Job Status" icon="clock" href="/api-reference/endpoint/get-job">
    **GET** `/v1/jobs/{job_id}`

    Check the status of asynchronous extraction jobs. Poll until completion to retrieve extracted data.
  </Card>

  <Card title="Health Check" icon="heart-pulse" href="/api-reference/endpoint/health-check">
    **GET** `/api/v1/pub/health`

    Verify API availability and connectivity. No authentication required.
  </Card>
</CardGroup>

## Integration Workflow

Alto Health integrates into your existing clinical workflows:

<Steps>
  <Step title="Upload Referral">
    Use **POST /api/v1/pub/records/document-upload** to ingest referrals from any source (email, fax, PDF). Receive a `record_id`.
  </Step>

  <Step title="Request Triage">
    Use **POST /v1/extract** to initiate automated triage with your clinic-specific rules. Receive a `job_id` for async processing.
  </Step>

  <Step title="Monitor Processing">
    Poll **GET /v1/jobs/{job_id}** to track Assistant and Judge evaluation. Typical completion: 10-30 seconds.
  </Step>

  <Step title="Retrieve Structured Output">
    When status is `completed`, response includes triaged referral data with confidence scores and audit trail—ready for EHR or scheduling integration.
  </Step>
</Steps>

## Rate Limits

To ensure fair usage and system stability, Alto Health implements the following rate limits:

| Endpoint          | Rate Limit          |
| ----------------- | ------------------- |
| Document Upload   | 100 requests/minute |
| Entity Extraction | 50 requests/minute  |
| Job Status        | 300 requests/minute |

When rate limited, you'll receive a `429 Too Many Requests` response with a `retry_after` header.

## Response Format

All API responses follow a consistent JSON structure:

### Success Response

```json theme={null}
{
  "data": { /* Response data */ },
  "status_code": 200,
  "message": "success"
}
```

### Error Response

```json theme={null}
{
  "error": "Error Type",
  "message": "Detailed error message",
  "status_code": 400
}
```

## HTTP Status Codes

| Code  | Meaning               | Description                        |
| ----- | --------------------- | ---------------------------------- |
| `200` | OK                    | Request succeeded                  |
| `400` | Bad Request           | Invalid request parameters         |
| `401` | Unauthorized          | Invalid or missing API key         |
| `403` | Forbidden             | API key lacks required permissions |
| `404` | Not Found             | Resource doesn't exist             |
| `429` | Too Many Requests     | Rate limit exceeded                |
| `500` | Internal Server Error | Server error occurred              |
| `503` | Service Unavailable   | Service temporarily unavailable    |

## SDKs and Libraries

While Alto Health doesn't provide official SDKs yet, our REST API works with any HTTP client:

<CodeGroup>
  ```javascript JavaScript / Node.js theme={null}
  // Using fetch (native in Node.js 18+)
  const response = await fetch('https://app.arahealth.io/v1/extract', {
    method: 'POST',
    headers: {
      'assistant-api-key': process.env.ALTO_ASSISTANT_API_KEY,
      'Content-Type': 'application/json'
    },
    body: JSON.stringify(payload)
  });
  ```

  ```python Python theme={null}
  # Using requests library
  import requests

  response = requests.post(
      'https://app.arahealth.io/v1/extract',
      headers={
          'assistant-api-key': os.environ['ALTO_ASSISTANT_API_KEY'],
          'Content-Type': 'application/json'
      },
      json=payload
  )
  ```

  ```bash cURL theme={null}
  curl -X POST https://app.arahealth.io/v1/extract \
    -H "assistant-api-key: $ALTO_ASSISTANT_API_KEY" \
    -H "Content-Type: application/json" \
    -d @payload.json
  ```

  ```csharp C# theme={null}
  // Using HttpClient
  var client = new HttpClient();
  var request = new HttpRequestMessage(HttpMethod.Post,
      "https://app.arahealth.io/v1/extract");
  request.Headers.Add("assistant-api-key", apiKey);
  request.Content = new StringContent(jsonPayload,
      Encoding.UTF8, "application/json");

  var response = await client.SendAsync(request);
  ```
</CodeGroup>

## API Versioning

Alto Health uses URL-based versioning:

* Current version: **v1**
* Base path: `/v1/` or `/api/v1/pub/`

We maintain backward compatibility and provide advance notice before deprecating any endpoints.

## Support & Feedback

<CardGroup cols={2}>
  <Card title="Get Help" icon="headset">
    Email: [xiao@altohealth.io](mailto:xiao@altohealth.io)

    Response time: Within 24 hours
  </Card>

  <Card title="Report Issues" icon="bug">
    Found a bug or have API feedback?

    Contact: [xiao@altohealth.io](mailto:xiao@altohealth.io)
  </Card>

  <Card title="API Status" icon="heart-pulse" href="https://app.arahealth.io/api/v1/pub/health">
    Check real-time API health status
  </Card>

  <Card title="Request Features" icon="lightbulb">
    Have ideas for new API features?

    Email: [xiao@altohealth.io](mailto:xiao@altohealth.io)
  </Card>
</CardGroup>

## Next Steps

<CardGroup cols={3}>
  <Card title="Quickstart" icon="rocket" href="/quickstart">
    Make your first API call
  </Card>

  <Card title="Authentication" icon="key" href="/guides/authentication">
    Secure your integration
  </Card>
</CardGroup>