canonical: https://jentic.com/apis/api.1up.health/1up-health

# 1upHealth API Collection - All endpoints

Aggregate patient health data from multiple EHRs, health systems, and payers through a unified FHIR-based interface with 21 endpoints. The API supports user management, OAuth 2.0 token exchange, FHIR R4 and DSTU2 resource access, bulk data export, provider search, health system connectivity, and granular permission management. Connect to hundreds of health systems and retrieve Patient, Observation, MedicationRequest, DocumentReference, and other FHIR resources through a single integration point.

## For AI agents

Aggregate patient health data from multiple EHRs and health systems via FHIR, manage user connections, perform bulk exports, and search healthcare providers through a unified API.

## Scope

Does not handle clinical note authoring, appointment scheduling, or claims processing - use for read-only health data aggregation, FHIR resource retrieval, and patient-system connectivity only.

## Capabilities

- Connect patients to hundreds of health systems and retrieve their consolidated health records via FHIR
- Exchange OAuth 2.0 authorization codes for access tokens to access patient-consented health data
- Query FHIR R4 resources including Patient, Observation, and MedicationRequest across connected systems
- Export all patient data in bulk via the $everything operation for comprehensive record retrieval
- Search and discover healthcare providers and connected health systems by name or specialty
- Grant and revoke granular data permissions between users and connected systems
- Retrieve clinical documents including lab reports and discharge summaries via DocumentReference

## Use cases

### AI Agent Health Data Aggregation

AI agents aggregate patient health data from multiple EHRs through Jentic by connecting to 1upHealth's unified FHIR interface. An agent creates a user, generates an auth code, exchanges it for an access token, and then retrieves FHIR resources spanning all connected health systems. Jentic manages the OAuth flow and token lifecycle, enabling agents to focus on clinical data processing rather than multi-system authentication.

Example prompt: Create a new user, generate an authorization code, exchange it for an access token, then retrieve all Patient resources from connected health systems and list their active conditions

### Multi-System Patient Record Retrieval

Pull a patient's complete health record aggregated from all connected health systems through a single API call. The $everything operation on Patient returns all clinical data including conditions, medications, allergies, procedures, and lab results from every connected source. This eliminates the need to query each health system individually and produces a longitudinal patient view.

Example prompt: Execute GET /{FHIRVersion}/Patient/{patientID}/$everything to retrieve all health data for patient ID 12345, then extract medication lists and flag any potential drug interactions

### Provider and Health System Discovery

Search for healthcare providers by name, specialty, or location and discover which health systems are available for patient connections. The provider search endpoint returns matching practitioners with their affiliated systems, enabling applications to guide patients through the connection process. Connected system metadata includes supported FHIR versions and data categories available.

Example prompt: Search for primary care providers in the connected health systems, then list all clinical systems available for patient connection with their supported FHIR versions

### Bulk Data Export for Analytics

Export patient health data in bulk for population health analytics, research, or compliance reporting. The GET /$export endpoint initiates a FHIR Bulk Data Export that produces NDJSON files containing all resources for the authorized patient population. Supports filtering by resource type and date range for targeted exports.

Example prompt: Initiate a bulk data export via GET /$export for all Patient and Observation resources, then poll the export status until complete and retrieve the NDJSON output files

## Key endpoints

| Method | Path | Description |
| --- | --- | --- |
| POST | `/user-management/v1/user` | Create a new user |
| POST | `/user-management/v1/user/auth-code` | Generate authorization code for user |
| POST | `/oauth2/token` | Exchange auth code for access token |
| GET | `/r4/Patient` | Get FHIR R4 Patient resources |
| GET | `/{FHIRVersion}/Patient/{patientID}/$everything` | Get all patient data |
| GET | `/$export` | Bulk data export |
| POST | `/search` | Provider search |
| GET | `/connect/system/clinical` | Get connected health systems |

## Key resources

- **User Management** — Create users, update profiles, and generate authorization codes for data access
- **OAuth2** — Token exchange and authentication for accessing patient health data
- **FHIR Resources** — Patient, Observation, MedicationRequest, DocumentReference via R4 and DSTU2
- **Bulk Export** — Full patient data export and $everything queries for comprehensive retrieval
- **Provider Search** — Discover providers, practitioners, and connected health systems
- **Permissions** — Grant and revoke user-level access to specific health data

## Why Jentic

- **Setup:** Wiring the 1upHealth API by hand means implementing its OAuth 2.0 flow, sequencing user creation, auth-code, and token exchange, and mapping the FHIR retrieval and connect routes yourself. Through Jentic you install once, import 1upHealth from the API Directory, store the client credentials once, and your agent calls it.
- **Permission scoping:** 1upHealth puts the patient id in the URL path (/{FHIRVersion}/Patient/{patientID}/$everything), so a rule can pin your agent to one patient: it can retrieve that patient's FHIR data and nothing else. You choose the operations it may call, so user provisioning and export are only included if you add them.
- **Credential handling:** Your 1upHealth OAuth 2.0 credentials and access tokens are stored once, encrypted, by your own Jentic One instance and injected at execution time. They never enter the agent's prompt, logs, or context.
- **Discovery method:** Agents search Jentic by intent such as 'aggregate patient health records from multiple systems', and Jentic returns the matching 1upHealth operation with its input schema so the agent calls the right endpoint without browsing the reference docs.

## Related APIs

- **Epic on FHIR API** — Direct FHIR access to Epic health systems for single-system patient data retrieval
- **Athena Health** — Direct EHR API for athenahealth practices with appointment and chart management
- **ClinicalTrials.gov API** — Clinical trial registry for matching patient data against trial eligibility criteria

## FAQ

### What authentication does the 1upHealth API use?

The 1upHealth API uses OAuth 2.0. You first create a user via POST `/user-management/v1/user`, generate an authorization code via POST `/user-management/v1/user/auth-code`, then exchange it for an access token via POST `/oauth2/token.` Through Jentic, this token lifecycle is managed in your Jentic One instance and agents receive ready-to-use bearer tokens.

### Can I retrieve data from multiple health systems in a single call?

Yes. The GET /{FHIRVersion}/Patient/{patientID}/$everything endpoint returns all health data aggregated from every health system the patient has connected. This includes conditions, medications, lab results, procedures, and documents from all sources in a single FHIR Bundle response.

### What are the rate limits for the 1upHealth API?

1upHealth applies per-application rate limits that vary by plan tier. Standard developer accounts typically support up to 60 requests per minute. Bulk export operations run asynchronously and do not count against per-request limits. Contact 1upHealth for production rate limit details.

### How do I aggregate patient records through Jentic?

Search Jentic for 'aggregate patient health data from multiple EHRs' to discover the 1upHealth endpoints. The agent first calls POST `/user-management/v1/user/auth-code` to get an auth code, exchanges it via POST `/oauth2/token`, then retrieves data via GET `/r4/Patient` or the $everything operation. Install via pip install jentic and use the search-load-execute flow.

### Which health systems can patients connect to?

The GET `/connect/system/clinical` endpoint returns all available health systems for patient connections. 1upHealth supports connections to hundreds of health systems including major hospital networks, health plans, and EHR vendors. Each system entry includes its name, supported FHIR version, and available data categories.

### Does the 1upHealth API support FHIR R4?

Yes. The API supports both FHIR R4 and DSTU2 resource access. R4 endpoints are available under the /r4/ path prefix, while DSTU2 resources use `/dstu2/.` Patient, Observation, MedicationRequest, DocumentReference, and other standard FHIR resources are accessible in both versions.

### Can I limit what my agent is allowed to do with the 1upHealth API?

Yes. Because you run Jentic One yourself, your own rules decide which 1upHealth operations and credentials the agent may use. Since 1upHealth puts the patient ID in the URL path (GET /{FHIRVersion}/Patient/{patientID}/$everything), a rule can pin the agent to one patient so it retrieves that patient's FHIR data and nothing else. You also choose which operations are exposed, so user provisioning (POST `/user-management/v1/user`) and bulk export (GET /$export) are only callable if you add them.