Compare & Synthesize

Compare and Synthesize are public API surfaces. Use Compare for grounded document matching. Use Synthesize One or Synthesize Set for generated test documents that can be fed back into Parse, Extract, Tables, Classify, Ask, or Compare.

Compare contract

POST /api/v1/compare accepts exactly two or three uploaded file IDs. Set schema to "auto" or pass a full Schema V2 object.

{
  "file_ids": ["file_invoice", "file_purchase_order"],
  "execution_mode": "sync",
  "schema": "auto"
}

Do not use split comparison endpoints or Compare-specific instructions fields.

Synthesize contracts

POST /api/v1/synthesize/one creates or edits one generated document:

{
  "execution_mode": "sync",
  "prompt": "Generate a purchase order matching this invoice layout and values.",
  "inputs": [{"file_id": "file_invoice"}]
}

POST /api/v1/synthesize/set plans and generates a document set:

{
  "execution_mode": "sync",
  "prompt": "Generate a matching invoice, purchase order, and delivery note set for one AP reconciliation test."
}

cURL

curl -sS -X POST "https://api.docspeed.ai/api/v1/compare" \
  -H "Authorization: Bearer ${DOCSPEED_API_KEY}" \
  -H "Content-Type: application/json" \
  -d '{
    "file_ids": ["file_invoice", "file_purchase_order"],
    "execution_mode": "sync",
    "schema": "auto"
  }'

Python

import requests

response = requests.post(
    "https://api.docspeed.ai/api/v1/synthesize/one",
    headers={
        "Authorization": "Bearer YOUR_API_KEY",
        "Content-Type": "application/json",
    },
    json={
        "execution_mode": "sync",
        "prompt": "Generate a purchase order matching this invoice layout and values.",
        "inputs": [{"file_id": "file_invoice"}],
    },
    timeout=600,
)
response.raise_for_status()
print(response.json())

TypeScript

const response = await fetch("https://api.docspeed.ai/api/v1/synthesize/set", {
  method: "POST",
  headers: {
    Authorization: "Bearer YOUR_API_KEY",
    "Content-Type": "application/json",
  },
  body: JSON.stringify({
    execution_mode: "sync",
    prompt: "Generate a matching invoice, purchase order, and delivery note set for one AP reconciliation test.",
  }),
});

console.log(await response.json());

Example Compare response fragment

{
  "schema": {"doc_class": "ap_reconciliation", "fields": [], "tables": []},
  "documents": [
    {
      "file_id": "file_invoice",
      "side": "left",
      "extraction": {"schema": {"doc_class": "invoice"}, "result": {}, "grounding_mode": "regions", "page_count": 1}
    },
    {
      "file_id": "file_purchase_order",
      "side": "right",
      "extraction": {"schema": {"doc_class": "purchase_order"}, "result": {}, "grounding_mode": "regions", "page_count": 1}
    }
  ],
  "verdict": {"status": "match_with_errors", "summary": "One critical value differs."},
  "items": [
    {
      "id": "item_total",
      "key": "invoice.total_due",
      "label": "Total due",
      "status": "mismatch",
      "left_value": "1240.00",
      "right_value": "1200.00",
      "region_ids": {
        "file_invoice": ["p1_total"],
        "file_purchase_order": ["p1_total"]
      }
    }
  ]
}

Example Synthesize Set response fragment

{
  "prompt": "Generate a matching invoice, purchase order, and delivery note set for one AP reconciliation test.",
  "source_file_ids": [],
  "documents": [
    {
      "document_key": "invoice",
      "document_type": "invoice",
      "file": {"file_id": "file_generated_invoice", "filename": "fake_invoice.pdf", "size_bytes": 182400, "created_at": 1776054000.0},
      "task": "generate_related_document",
      "prompt": "Generate the invoice member of the AP reconciliation set.",
      "metadata": {"document_type": "invoice"}
    }
  ]
}

Production notes

• Compare is sync-only in this release.
• Synthesize One and Synthesize Set are sync-oriented generation workflows in this release.
• Generated files returned by Synthesize are reusable file_id values for downstream Docspeed APIs.
• Synthesize is the public feature name; do not rename it to Synthetic in API contracts.