Patient Upload API

The Patient Upload API allows institutions to push patient records directly into their Arkangel workspace programmatically, without manual intervention. Once uploaded, files are processed automatically and results appear in your team's Pandora workspace.

Prerequisites

Contact Arkangel to receive:

• API key — used to authenticate every request
• Team ID — identifies your organization within Arkangel

Supported Formats

Format	Description	Notes
PDF	Clinical histories, discharge summaries, lab reports	1 file = 1 patient
TXT	Plain text clinical notes	1 file = 1 patient
CSV	Structured patient or event data	See CSV format below

Maximum file size: 3MB per file.

CSV Format

CSV files must have patient_id as the first column header. The second column header determines the file type:

Patient file (1 row = 1 patient)

The second column can be anything or absent.

patient_id,name,birth_date,diagnosis
p-001,Jane Doe,1980-03-12,EPOC
p-002,John Smith,1975-07-22,Asthma

Event file (many rows = 1 patient)

The second column must be event_id. All rows sharing the same patient_id are grouped into a single patient record.

patient_id,event_id,event_date,event_type,value,unit
p-001,e-001,2026-01-10,SpO2,94,%
p-001,e-002,2026-01-10,heart_rate,88,bpm
p-002,e-001,2026-01-11,SpO2,97,%

Uploading a File

Endpoint

POST /api/pandora/upload-v2/upload

Headers

Authorization: Bearer your_api_key

Form fields

Field	Required	Description
file	Yes	The file to upload (PDF, TXT, or CSV)
teamId	Yes	Your team ID
groupId	Yes	ID of the Pandora group to add patients to
anonymize	No	Set to true to anonymize records after extraction (default: false)

Request

curl -X POST https://arkangel.ai/api/pandora/upload-v2/upload \
  -H "Authorization: Bearer your_api_key" \
  -F "file=@patients.csv" \
  -F "teamId=your_team_id" \
  -F "groupId=your_group_id" \
  -F "anonymize=false"

JavaScript Example

const formData = new FormData();
formData.append('file', file);
formData.append('teamId', 'your_team_id');
formData.append('groupId', 'your_group_id');
formData.append('anonymize', 'false');

const response = await fetch('https://arkangel.ai/api/pandora/upload-v2/upload', {
  method: 'POST',
  headers: {
    'Authorization': 'Bearer your_api_key'
  },
  body: formData
});

const result = await response.json();

Response

{
  "success": true,
  "patientCount": 3
}

patientCount reflects the number of patients successfully ingested. For PDF and TXT this is always 1. For CSV it matches the number of rows (patient file) or unique patient_id values (event file).

If any patients could not be ingested due to a storage error, expectedCount is also returned so you can detect the discrepancy and re-submit the missing rows:

{
  "success": true,
  "patientCount": 2,
  "expectedCount": 3
}

Error Handling

Code	Error	Description
400	invalid_file_type	File format not supported
400	file_too_large	File exceeds 3MB limit
400	invalid_csv_format	First column is not patient_id
400	missing_patient_id	One or more rows have an empty patient_id
401	unauthorized	Missing or invalid API key
403	forbidden	API key does not have access to this team
413	payload_too_large	Request body exceeds server limit
500	internal_error	Unexpected server error — contact support

Result

No additional calls are needed. Once uploaded, patient data is processed and available in your team's Pandora workspace automatically.

Next Steps

• Authentication — Learn how to manage your API key
• HTTP Reference — View all status codes