Skip to main content
Normalize tabular data from spreadsheets into structured rows with column descriptors. Supports CSV, XLSX, Apple Numbers (export), and Google Sheets exports.

​
Request body

  • sourceUrl — HTTPS or signed URL to the spreadsheet file. Required if file is not provided.
  • file — Optional uploaded spreadsheet/CSV file via multipart/form-data.
  • sourceName — Optional label saved with the extracted dataset.
  • options — Optional object. Supported keys:
    • sheet — Name or index of the worksheet to extract (default: all sheets).
    • headerRow — Row number containing column headers (default 1).
    • dateFormat — Output date format (default ISO 8601).
    • numericLocale — Locale for decimal parsing (default en-US).
  • webhookUrl — Optional HTTPS URL Horizon should call when the extraction finishes.

​
Sample request

curl https://api.worklet.cloud/v1/extract/spreadsheet \
  -H "Content-Type: application/json" \
  -d '{
    "sourceUrl": "https://cdn.example.com/reports/sales-q1-2025.xlsx",
    "sourceName": "Sales Q1 2025",
    "options": {
      "sheet": "Summary",
      "headerRow": 2,
      "dateFormat": "yyyy-MM-dd",
      "numericLocale": "en-US"
    }
  }'

# or upload the spreadsheet directly

curl https://api.worklet.cloud/v1/extract/spreadsheet \
  -H "Content-Type: application/json" \
  -d '{
    "file": "data:application/vnd.openxmlformats-officedocument.spreadsheetml.sheet;base64,UEsDBBQABgAIA...",
    "sourceName": "Sales Q1 2025",
    "options": {
      "sheet": "Summary",
      "headerRow": 2,
      "dateFormat": "yyyy-MM-dd",
      "numericLocale": "en-US"
    }
  }'

​
Response

Returns 202 Accepted with jobId, status, statusUrl, and optional etaSeconds. Completed jobs include normalized rows, column schemas, and summary statistics.

​
Notes

  • Large sheets run asynchronously; chunking respects logical rows.
  • Hidden sheets are ignored unless explicitly referenced via sheet.
  • Numbers files must be exported to .xlsx or .csv before ingestion.
  • Poll GET /jobs/{jobId} (the same as statusUrl) to monitor progress or retrieve normalized rows after the job completes.
  • To upload the spreadsheet directly, send multipart/form-data with a file field instead of sourceUrl.

​
x402 flow

Spreadsheet extraction is priced via Coinbase’s x402 protocol. A missing proof triggers: 
HTTP/1.1 402 Payment Required
Content-Type: application/json

{
  "x402Version": 1,
  "accepts": [
    {
      "scheme": "exact",
      "network": "base-sepolia",
      "maxAmountRequired": "180000",
      "resource": "POST /extract/spreadsheet",
      "description": "Horizon spreadsheet extraction",
      "mimeType": "application/json",
      "payTo": "0xYourReceivingWallet",
      "maxTimeoutSeconds": 300,
      "asset": "0xYourUSDCContract",
      "extra": {
        "name": "USDC",
        "version": "1"
      }
    }
  ],
  "error": null
}
Provide the accepts payload to your facilitator, call /verify and /settle, then replay the POST with the Base64 token in X-PAYMENT. Horizon resumes the extraction and includes X-PAYMENT-RESPONSE for your records.