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

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

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. Submit ICD-10 Job (Async)

POST /api/v1/pcr/icd10/text

Submit clinical text for ICD-10 generation as an asynchronous job. The API immediately returns a job_id. Poll the job status endpoint to fetch final codes when complete.

Request

Content-Type: application/json

{
  "text": "67-year-old male with long-standing hypertension and type 2 diabetes mellitus.",
  "webhook_url": "https://your-hook.example.com/notify"  // optional
}

Successful Response 202 Accepted

{
  "job_id": "67f4ea3b8c7b2f64b2f1a3cd",
  "status": "queued",
  "message": "ICD-10 request accepted; processing has started",
  "created_at": "2026-04-21T19:14:02.739182",
  "webhook_url": "https://your-hook.example.com/notify"
}

Error Responses

Webhook Events (Optional)

If webhook_url is provided, the API sends POST callbacks for:

4. Get ICD-10 Job Status

GET /api/v1/pcr/icd10/{job_id}

Poll the status of a submitted ICD-10 async job.

Path Parameter

ParameterTypeDescription
job_idstring ID returned by /api/v1/pcr/icd10/text

Successful Response 200 OK (Completed)

{
  "job_id": "67f4ea3b8c7b2f64b2f1a3cd",
  "status": "completed",
  "created_at": "2026-04-21T19:14:02.739182",
  "updated_at": "2026-04-21T19:14:13.989100",
  "icd10_codes": [
    {
      "name": "Primary hypertension",
      "icd10_code": "I10",
      "evidence": "history of high blood pressure"
    }
  ]
}

Successful Response 200 OK (Failed)

{
  "job_id": "67f4ea3b8c7b2f64b2f1a3cd",
  "status": "failed",
  "created_at": "2026-04-21T19:14:02.739182",
  "updated_at": "2026-04-21T19:14:13.989100",
  "error_code": "rag_service_error",
  "error_message": "ICD-10 upstream service error"
}

Error Responses

5. List Community Templates

GET /api/v1/pcr/templates/community

List public community templates available for audio-to-note generation. This endpoint returns only the minimal catalog fields: _id, name, and short_description.

Query Parameters

ParameterTypeDescription
skipintegerPagination offset (default 0)
limitintegerPagination size (default 20, max 100)
namestringOptional case-insensitive filter by template name
searchstringOptional case-insensitive keyword search over name and short description

Successful Response 200 OK

{
  "data": [
    {
      "_id": "66eb0bfe20db7d898c8e5c4e",
      "name": "GENERAL TEMPLATE",
      "short_description": "A minimal and versatile template designed for any clinical interview."
    }
  ],
  "count": 1
}

6. Submit Audio-to-Note Job (Async)

POST /api/v1/pcr/audio/notes

Submit an audio file and a required community template_id. The API returns 202 Accepted immediately and processes transcript + note generation in the background.

Request

Successful Response 202 Accepted

{
  "job_id": "680a8eb5904f2995138cf6b6",
  "status": "queued",
  "message": "Audio note request accepted; processing has started",
  "created_at": "2026-04-25T10:40:15.947012",
  "webhook_url": "https://your-hook.example.com/notify"
}

Error Responses

Webhook Events (Optional)

If webhook_url is provided, this endpoint sends POST callbacks for:

7. Get Audio-to-Note Job Status

GET /api/v1/pcr/audio/notes/{job_id}

Poll the status of a submitted audio-note async job.

Successful Response 200 OK (Completed)

{
  "job_id": "680a8eb5904f2995138cf6b6",
  "status": "completed",
  "created_at": "2026-04-25T10:40:15.947012",
  "updated_at": "2026-04-25T10:41:22.103050",
  "transcript": "Patient reports worsening cough over 3 days...",
  "note": "Clinical note generated using selected community template..."
}

Successful Response 200 OK (Failed)

{
  "job_id": "680a8eb5904f2995138cf6b6",
  "status": "failed",
  "created_at": "2026-04-25T10:40:15.947012",
  "updated_at": "2026-04-25T10:41:22.103050",
  "error_code": "transcription_failed",
  "error_message": "Failed to transcribe audio"
}

Error Responses

8. 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

ParameterTypeDescription
upload_idstring ID returned when files were uploaded

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

Common Response Fields

FieldTypeDescription
messagestringInformational message
upload_idstringIdentifier for async file uploads
job_idstringIdentifier for async ICD-10 jobs
statusstringOne of queued, processing, completed, failed
created_atstring (ISO 8601)Job creation timestamp
updated_atstring (ISO 8601)Most recent job status update timestamp
responsestringGenerated summary text
icd10_codesarrayFinal ICD-10 output for completed ICD-10 jobs
transcriptstringGenerated transcript text for completed audio-note jobs
notestringGenerated clinical note for completed audio-note jobs
error_codestringSanitized machine-friendly error classification for failed ICD-10 jobs
error_messagestringSanitized human-readable error message for failed async jobs
extra_informationstringOriginal context or instructions you provided
webhook_urlstringURL you provided to receive completion callbacks
metadataobjectAll other fields you sent, echoed back and forwarded; if you provided email, first_name, and last_name, those will also appear here and drive patient auto-lookup/creation (and reflect in your Global Scribe app account).
detailstringError or rate-limit detail message

Contact & Support

For API key requests or assistance, please contact contact@sporo.health.