API Documentation

01

Quick Start

Four steps from signup to your first RAG-ready ZIP.

# Step 2 — upload
curl -X POST https://getdistil.app/api/v1/convert \
  -H "Authorization: Bearer distil_sk_..." \
  -F "file=@report.pdf"

# → {"job_id":"abc123","status":"pending","estimated_seconds":30}

# Step 3 — poll
curl https://getdistil.app/api/v1/jobs/abc123 \
  -H "Authorization: Bearer distil_sk_..."

02

Authentication

All API requests require an API key passed as a Bearer token.

Authorization: Bearer distil_sk_...

API keys have the format distil_sk_ followed by 32 random characters (42 characters total).

Keys are shown once at creation and cannot be retrieved later. Generate and manage keys in the Dashboard → API Keys.

03

POSTPOST /api/v1/presign

Get a signed Supabase Storage URL so your browser can upload a file directly — bypassing your server entirely. Use this instead of sending the file through /convert when building a web UI.

Request (JSON)

{
  "filename":     "report.pdf",
  "content_type": "application/pdf",
  "size":         1048576
}

Response — 200 OK

{
  "upload_url":    "https://xxxx.supabase.co/storage/v1/object/sign/...",
  "storage_path": "inputs/user_id/job_id.pdf",
  "job_id":        "3f7a1c2d-..."
}

Upload the file with a PUT request to upload_url. Then pass job_id and storage_path in the body of /convert to start processing.

04

POSTPOST /api/v1/convert

Submit a document for conversion. Returns a job_id immediately — processing happens asynchronously.

Request

Content-Type: multipart/form-data

Response — 202 Accepted

{
  "job_id":           "3f7a1c2d-...",
  "status":           "pending",
  "estimated_seconds": 30
}

Error responses

curl -X POST https://getdistil.app/api/v1/convert \
  -H "Authorization: Bearer distil_sk_..." \
  -F "file=@report.pdf" \
  -F "webhook_url=https://example.com/hook"

05

POSTPOST /api/v1/batches

Upload up to 5 files in one request. Each file becomes its own job, processed sequentially. Returns a batch_id you can poll.

Request

Content-Type: multipart/form-data

Fields: files[] (up to 5 files) + optional overrides domain, language, pii_level, governance_level, chunk_size, webhook_url — applied to all files.

Response — 202 Accepted

{
  "batch_id": "b1c2d3e4-...",
  "jobs": [
    {
      "job_id":    "3f7a1c2d-...",
      "filename":  "report.pdf",
      "status":    "pending",
      "poll_url":  "/api/v1/jobs/3f7a1c2d-..."
    }
  ]
}

GET /api/v1/batches/:id

Poll the batch as a whole. Returns aggregated counts.

{
  "batch_id": "b1c2d3e4-...",
  "total":    3,
  "done":     2,
  "failed":   0,
  "pending":  1,
  "jobs": [ /* same shape as /convert response per job */ ]
}

06

GETGET /api/v1/jobs/:id

Poll for job status. Poll every 2–5 seconds until status is done or failed.

Response — pending or processing

{
  "job_id":     "3f7a1c2d-...",
  "status":     "pending"  // or "processing"
  "created_at": "2026-04-02T10:00:00Z"
}

Response — done

{
  "job_id":        "3f7a1c2d-...",
  "status":        "done",
  "result_status": "success",  // or "partial"
  "output_url":    "https://...",  // signed URL, fetch directly
  "total_chunks":  42,
  "total_tokens":  18400,
  "total_pages":   14,
  "completed_at":  "2026-04-02T10:00:35Z",
  "expires_at":    "2026-04-03T10:00:35Z",
  "source_filename": "report.pdf"
}

Response — failed

{
  "job_id":        "3f7a1c2d-...",
  "status":        "failed",
  "error_message": "string",
  "created_at":    "2026-04-02T10:00:00Z"
}

Error responses

curl https://getdistil.app/api/v1/jobs/3f7a1c2d \
  -H "Authorization: Bearer distil_sk_..."

07

Schema Reference

Each chunk in the output ZIP is a Markdown file with YAML frontmatter. Every field is purpose-built for RAG retrieval.

Example chunk

---
id:               a1b2c3d4
source_file:      contract-2024.pdf
source_pages:     [11, 12]
title:           Limitation of Liability
os_component:    governance
context_tier:    task
domain:          legal
language:        en
pii_level:       none
summary:         Caps total liability at 12 months of fees paid.
keywords:        [liability, indemnity, consequential damages, cap]
token_count:     187
governance_level: yellow
---

## 9.2 Limitation of Liability

Neither party shall be liable for indirect, incidental,
or consequential damages...

Fields

ZIP contents

output.zip
├── summary.md          # human-readable conversion summary
├── index.yaml          # document index — all chunks listed with metadata
├── chunk_001-2.md
├── chunk_002-4.md
└── ...

PDF files include page-range suffixes (chunk_001-2.md = ends on page 2). DOCX files use plain names (chunk_001.md) — python-docx does not provide page boundaries.

08

Webhook

Pass a webhook_url when uploading to receive a POST notification on completion.

When it fires

On success, partial, and failed completion. The error_message field is only present on failed; download_url is only present on success / partial.

Payload

// POST to your webhook_url
// Content-Type: application/json
// X-Distil-Signature: sha256=<hmac>

{
  "job_id":        "3f7a1c2d-...",
  "status":        "success",     // "success" | "partial" | "failed"
  "completed_at":  "2026-04-04T08:00:00.000Z",
  "download_url":  "https://...",  // success/partial only
  "total_chunks":  42,
  "total_pages":   14,
  "error_message": "..."          // failed only
}

Signature verification

Every request carries an X-Distil-Signature header. The value is sha256=<HMAC-SHA256(raw_body, secret)>. Verify it to reject spoofed payloads.

// Node.js — Express example
const crypto = require('crypto')

app.post('/hook', express.raw({ type: 'application/json' }), (req, res) => {
  const sig  = req.headers['x-distil-signature'] ?? ''
  const mac  = 'sha256=' + crypto
    .createHmac('sha256', process.env.DISTIL_WEBHOOK_SECRET)
    .update(req.body)
    .digest('hex')

  if (!crypto.timingSafeEqual(Buffer.from(sig), Buffer.from(mac))) {
    return res.status(401).send('Invalid signature')
  }
  const payload = JSON.parse(req.body)
  // handle payload ...
  res.sendStatus(200)
})

# Python — Flask example
import hmac, hashlib, os

@app.route('/hook', methods=['POST'])
def webhook():
    sig     = request.headers.get('X-Distil-Signature', '')
    secret  = os.environ['DISTIL_WEBHOOK_SECRET'].encode()
    mac     = 'sha256=' + hmac.new(secret, request.data, hashlib.sha256).hexdigest()
    if not hmac.compare_digest(sig, mac):
        abort(401)
    payload = request.get_json(force=True)
    # handle payload ...
    return '', 200

09

Usage Quotas

Quotas are measured in pages per month and reset at the start of each calendar month. Exceeding your quota returns a 402 response.

Upgrade your plan in the Dashboard → Billing.