Endpoints

Upload Endpoint

Upload documents for processing and conversion to FHIR format.

Overview

The Upload endpoint supports two mutually exclusive modes:

Direct upload — Send files via multipart/form-data. Once uploaded, you receive a unique file_id that can be used with the Convert endpoint.
URL ingest — Provide a presigned S3 URL via application/json. The platform fetches the file from the URL and stores it, returning a file_id.

Endpoint Details

URL: POST /api/v1/upload Content-Type: multipart/form-data (direct upload) or application/json (URL ingest)

Request Parameters

Headers

Header	Type	Required	Description
`X-Client-Id`	string	Yes	Client ID from the API keys
`X-Client-Secret`	string	Yes	Client secret from the API keys
`Content-Type`	string	Yes	`multipart/form-data` for direct upload or `application/json` for URL ingest

Mode 1: Direct Upload (multipart/form-data)

Parameter	Type	Required	Description
`file`	file	Yes	The document to upload
`file_type`	string	Yes	Type of file: `pdf`, `ccda`, or `csv`

Mode 2: URL Ingest (application/json)

Parameter	Type	Required	Description
`presigned_url`	string	Yes	HTTPS presigned S3 URL to fetch the file from
`file_type`	string	Yes	Type of file: `pdf`, `ccda`, or `csv`

Supported File Types

PDF files (.pdf) — Medical documents, reports, forms
CCDA files (.xml) — Consolidated Clinical Document Architecture files
CSV files (.csv) — Comma-separated values data files
Maximum file size (direct upload): 50MB per file

Request Examples

Direct Upload

curl -X POST "https://platform.curiflow.com/api/v1/upload" 
  -H "X-Client-Id: your-client-id" 
  -H "X-Client-Secret: your-client-secret" 
  -F "file=@document.pdf" 
  -F "file_type=pdf"

const formData = new FormData();
formData.append('file', fileInput.files[0]);
formData.append('file_type', 'pdf');

const response = await fetch('https://platform.curiflow.com/api/v1/upload', {
	method: 'POST',
	headers: {
		'X-Client-Id': 'your-client-id',
		'X-Client-Secret': 'your-client-secret'
	},
	body: formData
});

const result = await response.json();

import requests

url = "https://platform.curiflow.com/api/v1/upload"
headers = {
    "X-Client-Id": "your-client-id",
    "X-Client-Secret": "your-client-secret"
}

files = {
    'file': ('document.pdf', open('document.pdf', 'rb'), 'application/pdf')
}
data = {
    'file_type': 'pdf'
}

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

URL Ingest

curl -X POST "https://platform.curiflow.com/api/v1/upload" 
  -H "X-Client-Id: your-client-id" 
  -H "X-Client-Secret: your-client-secret" 
  -H "Content-Type: application/json" 
  -d '{
    "presigned_url": "https://your-bucket.s3.amazonaws.com/path/to/document.pdf?X-Amz-Algorithm=...",
    "file_type": "pdf"
  }'

const response = await fetch('https://platform.curiflow.com/api/v1/upload', {
	method: 'POST',
	headers: {
		'X-Client-Id': 'your-client-id',
		'X-Client-Secret': 'your-client-secret',
		'Content-Type': 'application/json'
	},
	body: JSON.stringify({
		presigned_url:
			'https://your-bucket.s3.amazonaws.com/path/to/document.pdf?X-Amz-Algorithm=...',
		file_type: 'pdf'
	})
});

const result = await response.json();

import requests

url = "https://platform.curiflow.com/api/v1/upload"
headers = {
    "X-Client-Id": "your-client-id",
    "X-Client-Secret": "your-client-secret",
    "Content-Type": "application/json"
}

payload = {
    "presigned_url": "https://your-bucket.s3.amazonaws.com/path/to/document.pdf?X-Amz-Algorithm=...",
    "file_type": "pdf"
}

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

Response Format

Success Response (200 OK)

{
	"message": "File uploaded successfully",
	"file_id": "UUID-file-id.pdf"
}

Response Fields

Field	Type	Description
`message`	string	Success message
`file_id`	string	Unique identifier for the uploaded file in the format `{uuid}.{ext}`

Status and Error Codes

HTTP Code	Message
`200`	File uploaded successfully
`400`	file_type is required and must be one of: pdf, ccda, csv
`400`	file_type must be one of: pdf, ccda, csv
`400`	Uploaded file must include a filename with a permitted extension
`400`	Multipart upload requires form fields: file, file_type
`400`	Multipart upload must include only file and file_type fields
`400`	Invalid JSON body
`400`	JSON body must be an object
`400`	JSON ingest requires presigned_url and file_type
`400`	presigned_url must be HTTPS and use an allowed S3 host
`400`	File content does not match declared file_type
`400`	Password-protected PDFs are not supported.
`400`	Uploaded file is not a valid PDF
`400`	Uploaded file is empty
`400`	CSV must be valid UTF-8
`400`	CSV must contain a header row and at least one data row
`401`	Unauthorized (missing or invalid authentication)
`403`	Insufficient permissions
`413`	File exceeds maximum direct upload size of 50MB
`429`	Too many requests. For more details, visit the page Rate Limits
`500`	Internal server error
`504`	API gateway Timeout

Best Practices

File Validation: Validate file type and size before uploading
Security: Keep your client credentials secure
Choose the right mode: Use direct upload for files under 50MB. Use URL ingest for larger files already stored on S3
Set file_type correctly: Ensure the file_type value matches the actual content of your file to avoid validation errors

Next Steps

After successful upload, use the returned file_id to:

Convert the file via the Convert endpoint