Sporo Patient Chart Review API

Authentication

All endpoints require an API key sent in the request header:

X-API-KEY: <your_api_key>

Rate Limits

• Upload endpoints (files or text): 10 requests per hour
• Status endpoint: 5 requests per minute

If a rate limit is exceeded, the API responds with 429 Too Many Requests and a retry message.

Endpoints

1. Upload Files for Processing

POST /api/v1/pcr/upload/

Upload one or more documents for asynchronous summarization. You can include any number of extra form fields—they will be stored in metadata, and if you provide a webhook_url, they will all be forwarded in that webhook.

Patient auto-lookup/creation: If you supply email, first_name, and last_name in your form fields, the API will:

1. Case-insensitively search for a patient record matching that email and either name order (first_name/last_name or swapped).
2. If found, attach documents to the existing patient; otherwise, create a new patient with those fields.
3. Your provided email, first_name, and last_name will also be reflected on your account in the Global Scribe app.

Request

• Content-Type: multipart/form-data
• files: array of file uploads
• extra_information (optional): additional context or notes
• webhook_url (optional): URL to receive a POST when processing completes
• Any other form field—you choose the keys—will be echoed back under metadata.
• To auto-create/find a patient, include in your form:
  • email
  • first_name
  • last_name

Successful Response 200 OK

{
  "message": "Files uploaded successfully; processing is underway.",
  "upload_id": "684a9f404c658fc1a0743af9",
  "webhook_url": "https://your-hook.example.com/notify",
  "extra_information": "Patient Tony Stark, June 2025 notes",
  "metadata": {
    "unique_identifier": "case-1234",
    "foo": "bar",
    "email": "tony.stark@example.com",
    "first_name": "Tony",
    "last_name": "Stark"
  }
}

Error Response 429 Too Many Requests

{
  "detail": "Rate limit of 10 requests per hour exceeded. Please try again after an hour."
}

2. Upload Text for Summary

POST /api/v1/pcr/upload/text/

Submit plain text for immediate summarization. You can include any extra JSON properties; they will be stored in metadata and forwarded via webhook if you supply one.

Request

Content-Type: application/json

{
  "user_input": "Text to be summarized.",
  "extra_information": "Optional context or instructions.",
  "webhook_url": "https://your-hook.example.com/notify",
  "unique_identifier": "note-5678",
  "foo": "bar"
}

Successful Response 200 OK

{
  "response": "Generated summary of the provided text.",
  "webhook_url": "https://your-hook.example.com/notify",
  "extra_information": "Optional context or instructions.",
  "metadata": {
    "unique_identifier": "note-5678",
    "foo": "bar"
  }
}

Error Response 429 Too Many Requests

{
  "detail": "Rate limit of 10 requests per hour exceeded. Please try again after an hour."
}

3. Get Upload Status

GET /api/v1/pcr/{upload_id}

Check the processing status of a previously uploaded batch. The response includes your original extra_information, stored metadata, and the patient lookup fields if provided.

Path Parameter

Successful Response 200 OK

{
  "status": "completed",           // or "queued", "processing", "failed"
  "response": "Summarized content of the uploaded files...",
  "extra_information": "Patient Tony Stark, June 2025 notes",
  "metadata": {
    "unique_identifier": "case-1234",
    "foo": "bar",
    "email": "tony.stark@example.com",
    "first_name": "Tony",
    "last_name": "Stark"
  }
}

Error Responses

• 400 Bad Request – Invalid upload_id format
• 404 Not Found – No upload found for the given ID
• 429 Too Many Requests – Rate limit of 5 requests per minute exceeded

Common Response Fields

Contact & Support

For API key requests or assistance, please contact contact@sporohealth.com.