Quickstart

This guide walks through the complete request cycle using curl. By the end you’ll have uploaded a document, waited for processing, and fetched a structured JSON result.

All examples use sk_test_… sandbox keys. Swap in a sk_live_… key when you’re ready for production.

Get an API key

API keys are issued per organisation in the Folio dashboard. Each key is prefixed with sk_test_ (sandbox) or sk_live_ (production).Set it as an environment variable so you don’t have to paste it into every command:

export FOLIO_API_KEY="sk_test_..."

See Authentication for key types, rotation, and security guidance.

Submit a document

Send the file as multipart/form-data. The only required field is file; document_type is recommended when you know it.

curl -X POST https://api.glialhealth.com/v1/documents \
  -H "Authorization: Bearer sk_test_..." \
  -F file=@report.pdf \
  -F document_type=lab_report

Folio accepts multipart only — there is no base64 or JSON body option for file uploads.

You’ll receive a 202 Accepted with a document object:

{
  "id": "doc_01j9xkqz3b0000000000000000",
  "object": "document",
  "status": "queued",
  "document_type": "lab_report",
  "created_at": "2025-10-14T18:23:00Z",
  "result_url": "/v1/documents/doc_01j9xkqz3b0000000000000000/result"
}

Save the id — you’ll use it in the next steps.

Wait for processing

Poll with the ?wait=<seconds> long-poll parameter. The server holds the connection open until the document moves out of queued/processing, or the timeout expires.

curl "https://api.glialhealth.com/v1/documents/doc_01j9xkqz3b0000000000000000?wait=30" \
  -H "Authorization: Bearer sk_test_..."

When the response comes back with "status": "completed" you’re ready to fetch the full result. If it returns "status": "processing" before the timeout, wait a moment and poll again.See Async model for a deeper look at the lifecycle and webhook alternatives.

Fetch the result

curl https://api.glialhealth.com/v1/documents/doc_01j9xkqz3b0000000000000000/result \
  -H "Authorization: Bearer sk_test_..."

A 409 means the document isn’t ready yet. A 200 returns the full extraction result:

{
  "id": "doc_01j9xkqz3b0000000000000000",
  "status": "completed",
  "document_type": "lab_report",
  "document_type_confidence": 0.97,
  "language": "en",
  "extract": {
    "patient_name": {
      "value": "Jane Doe",
      "confidence": 0.99,
      "found": true,
      "page": 1,
      "bbox": {"x": 0.05, "y": 0.12, "width": 0.15, "height": 0.02}
    },
    "test_date": {
      "value": "2025-10-10",
      "confidence": 0.95,
      "found": true,
      "page": 1,
      "bbox": {"x": 0.05, "y": 0.15, "width": 0.11, "height": 0.02}
    },
    "hemoglobin": {
      "value": "13.8 g/dL",
      "confidence": 0.91,
      "found": true,
      "page": 2,
      "bbox": {"x": 0.05, "y": 0.38, "width": 0.12, "height": 0.02}
    }
  },
  "tables": [],
  "review_status": "auto",
  "flags": [],
  "deidentified": false,
  "processing_time_ms": 3420
}

Each field in extract carries a confidence score (0–1), a found boolean, the page number, and a bounding-box for UI overlays. review_status: "auto" means the result passed confidence thresholds without needing human review.

Next steps

Async model

Webhooks, long-polling, and the full document lifecycle.

Custom schemas

Define exactly which fields Folio should extract from any document type.

Confidence & HITL

Set thresholds that trigger human review for low-confidence extractions.

De-identification

Strip PHI before results leave the pipeline.

Get started

Guides

API reference

Next steps

Async model

Custom schemas

Confidence & HITL

De-identification

​Next steps

Async model

Custom schemas

Confidence & HITL

De-identification

Next steps