Skip to main content

​
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:

Platform API Key

Used for: Document upload operationsHeaders Required:
  • org_id - Your organization ID
  • platform_api_key - Your platform API key

Assistant API Key

Used for: Entity extraction operationsHeaders Required:
  • assistant-api-key - Your assistant API key

​
Authentication Example

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"
See the Authentication Guide for detailed security best practices and credential management.

​
API Endpoints Overview

​
File Endpoints

Upload Document

POST /api/v1/pub/records/document-uploadUpload medical referrals and clinical documents for processing. Supports PDF and image formats.

Get Job Status

GET /v1/jobs/{job_id}Check the status of asynchronous extraction jobs. Poll until completion to retrieve extracted data.

Health Check

GET /api/v1/pub/healthVerify API availability and connectivity. No authentication required.

​
Integration Workflow

Alto Health integrates into your existing clinical workflows:
1

Upload Referral

Use POST /api/v1/pub/records/document-upload to ingest referrals from any source (email, fax, PDF). Receive a record_id.
2

Request Triage

Use POST /v1/extract to initiate automated triage with your clinic-specific rules. Receive a job_id for async processing.
3

Monitor Processing

Poll GET /v1/jobs/ to track Assistant and Judge evaluation. Typical completion: 10-30 seconds.
4

Retrieve Structured Output

When status is completed, response includes triaged referral data with confidence scores and audit trail—ready for EHR or scheduling integration.

​
Rate Limits

To ensure fair usage and system stability, Alto Health implements the following rate limits:
EndpointRate Limit
Document Upload100 requests/minute
Entity Extraction50 requests/minute
Job Status300 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

{
  "data": { /* Response data */ },
  "status_code": 200,
  "message": "success"
}

​
Error Response

{
  "error": "Error Type",
  "message": "Detailed error message",
  "status_code": 400
}

​
HTTP Status Codes

CodeMeaningDescription
200OKRequest succeeded
400Bad RequestInvalid request parameters
401UnauthorizedInvalid or missing API key
403ForbiddenAPI key lacks required permissions
404Not FoundResource doesn’t exist
429Too Many RequestsRate limit exceeded
500Internal Server ErrorServer error occurred
503Service UnavailableService temporarily unavailable

​
SDKs and Libraries

While Alto Health doesn’t provide official SDKs yet, our REST API works with any HTTP client: 
// 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)
});

​
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

Get Help

Email: xiao@altohealth.ioResponse time: Within 24 hours

Report Issues

Found a bug or have API feedback?Contact: xiao@altohealth.io

API Status

Check real-time API health status

Request Features

Have ideas for new API features?Email: xiao@altohealth.io

​
Next Steps

Quickstart

Make your first API call

Authentication

Secure your integration