Install dependencies: 
pip install requests
Process a document: 
import requests

url = "https://api.trycardinal.ai/markdown"

headers = {
    "x-api-key": "YOUR_API_KEY_HERE"
}

files = {
    "file": open("sample.pdf", "rb")  # Or use 'fileUrl' instead
}

data = {
    "startPage": "1"
}

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

print(response.json())
You’ve just processed your first document! The Markdown text will be available in the "pages" → "content" fields of the response.

​
Method 2: Pre-signed File URL

Instead of uploading a file directly, you can pass a publicly accessible or pre-signed file URL: 
import requests

url = "https://api.trycardinal.ai/markdown"

headers = {
    "x-api-key": "YOUR_API_KEY_HERE"
}

data = {
    "fileUrl": "https://your-bucket.s3.amazonaws.com/sample.pdf?X-Amz-Signature=...",
    "startPage": "1"
}

response = requests.post(url, headers=headers, data=data)

print(response.json())
This avoids sending the file bytes directly and is ideal for large files or when working with cloud storage.

​
Method 3: cURL

If you prefer the command line: 
curl --location 'https://api.trycardinal.ai/markdown' \
--header 'x-api-key: YOUR_API_KEY_HERE' \
--form 'file=@"/path/to/your/document.pdf"' \
--form 'startPage=1'

​
Request Parameters

  • file (required if no fileUrl): PDF or image file to process
  • fileUrl (required if no file): Publicly accessible URL to file
  • startPage (optional, default: 1): Start processing from this page
  • ephemeral (optional, default: false): If true, results are not stored

​
Sample Response

{
  "success": true,
  "total_pages": 2,
  "successful_pages": 2,
  "failed_pages": 0,
  "pages": [
    {
      "content": "ACME CORPORATION\nInvoice #INV-2024-001\n\nBill To:\nJohn Doe Industries...",
      "height": 792.0,
      "width": 612.0,
      "barcodes": [
        {
          "type": "CODE_128",
          "value": "ABC123456789",
          "bounding_box": { "x": 450, "y": 50, "width": 120, "height": 25 }
        }
      ],
      "signatures": [
        {
          "type": "handwritten",
          "confidence": 0.89,
          "bounding_box": { "x": 400, "y": 650, "width": 180, "height": 40 }
        }
      ],
      "image_metadata": [
        {
          "image_id": "img_001",
          "format": "PNG",
          "size": { "width": 200, "height": 150 },
          "position": { "x": 100, "y": 200 },
          "caption": "Fig. 3: Prompt Template.",
          "cropped_image_url": "https://example-s3/img_001.png"
        }
      ]
    },
    {
      "content": "TERMS AND CONDITIONS\n\n1. Payment is due within 30 days...",
      "height": 792.0,
      "width": 612.0,
      "image_metadata": []
    }
  ]
}

​
Next Steps

  • Try our other endpoints! Build end-to-end pipelines using all of our endpoints.