Request & Response Schemas

This page lists the canonical JSON shapes accepted and returned by the API.

Create extraction request

POST /v1/extractions takes a JSON body. The file is sent as a base64-encoded string — there is no multipart upload.

{
  "file":         "JVBERi0xLjcK...",         // base64 of the file bytes
  "file_name":    "invoice.pdf",             // required, with extension
  "content_type": "application/pdf",         // optional, inferred from file_name
  "template_id":  "tpl_invoice"              // optional
}

Allowed content types: application/pdf, image/jpeg, image/png, image/webp. Max 20 MB after decoding.

Extraction

{
  "id":            "ext_01HZX...",          // ulid
  "status":        "completed",             // "processing" | "completed" | "failed"
  "file_name":     "invoice.pdf",
  "file_type":     "application/pdf",
  "template_id":   "tpl_invoice" | null,
  "source":        "api",
  "confidence":    96,                       // 0-100, null while processing
  "credits_used":  1,
  "fields": [
    {
      "id":          1,
      "field":       "Invoice Number",
      "value":       "INV-2024-081",
      "confidence":  99,                     // 0-100
      "explanation": "Found in top-right header."
    }
  ],
  "data":          { /* flat key/value mirror of fields */ },
  "error_message": null,
  "created_at":    "2024-08-12T10:23:01Z",
  "completed_at":  "2024-08-12T10:23:04Z"
}

API key (me)

{
  "api_key": {
    "id":            "key_01HZX...",
    "name":          "production",
    "prefix":        "dpk_live_a",
    "scopes":        ["extractions:read", "extractions:write"],
    "workspace_id":  "ws_01HZX..."
  },
  "request_id": "req_01HZX..."
}

Error envelope

All non-2xx responses follow this shape:

{
  "error": {
    "code":    "invalid_file",
    "message": "File format not supported. Use PDF, JPEG, PNG, or WebP."
  },
  "request_id": "req_01HZX..."
}