Compare Versions API
The Compare Versions API runs the same comparison as Compare Versions from your own scripts and systems. You send two PDFs (the old and the new revision), get a job id back, and poll it until the findings are ready.
The API is switched on per organization, and each key is issued by Structured. Ask your Structured contact for a key. Every request carries it in the X-API-Key header.
All paths below are on https://api.getstructured.ai.
The examples hand the key to curl on standard input (-H @-, curl 7.55 or later), so it is never on curl's command line, where other users of the same machine could read it. They run in any POSIX shell (sh, bash, zsh).
Recommended: upload to storage, then start the comparison
Each PDF goes straight to storage first, and the comparison is started with a small JSON request that names the two uploads. This works for files of any size up to the limit, and a large file never rides in an API request.
1. Get an upload URL for each file
printf 'X-API-Key: %s\n' "$STRUCTURED_API_KEY" |
curl -s https://api.getstructured.ai/api/v1/uploads/staged-url \
-H @- \
-H "Content-Type: application/json" \
-d '{"kind": "compare_pdf", "file_name": "A-101 rev B.pdf", "size": 48213377}'
size is the file's size in bytes. The answer:
{
"ref": "0b5c1f0e-6d1e-4a8e-9a43-7f2f0c1d2e3f/A-101_rev_B.pdf",
"upload_url": "https://...blob.core.windows.net/...",
"expires_at": "2026-10-27T18:04:11Z",
"max_bytes": 209715200
}
Keep ref; you send it in step 3. A file over max_bytes (200 MB) or not named .pdf is refused here.
2. Upload the file to upload_url
curl -s -X PUT "$UPLOAD_URL" \
-H "x-ms-blob-type: BlockBlob" \
-H "Content-Type: application/pdf" \
--data-binary @"A-101 rev B.pdf"
The x-ms-blob-type: BlockBlob header is required. The URL can be used once: it creates the file and cannot replace it, so a second upload needs a new URL from step 1.
Repeat steps 1 and 2 for the other PDF.
3. Start the comparison
printf 'X-API-Key: %s\n' "$STRUCTURED_API_KEY" |
curl -s https://api.getstructured.ai/api/v1/compare-versions/from-uploads \
-H @- \
-H "Content-Type: application/json" \
-d '{"old_file_ref": "'"$OLD_REF"'", "new_file_ref": "'"$NEW_REF"'"}'
The answer is 202 Accepted:
{
"job_id": "5f0e6a4c-2b7d-4a19-8c55-0c8e1b9d7a21",
"status": "pending",
"status_url": "/api/v1/compare-versions/5f0e6a4c-2b7d-4a19-8c55-0c8e1b9d7a21"
}
A ref works only for the person whose key asked for it (with any of that person's Compare API keys), and only for one day. Once a comparison starts, its two uploads are used up. When the start is refused because of either file (empty, not a PDF, over 200 MB, not a readable PDF, or too many pages), both uploads are used up, even the one that was fine: upload both files again and send their new refs. If the start is refused because of the hourly limit or your organization's spending limit, or fails on our side, the uploads are kept, so you can send the same refs again later.
Supported: one multipart request
Existing integrations can keep sending both files in one multipart/form-data request, with the fields old_file and new_file:
printf 'X-API-Key: %s\n' "$STRUCTURED_API_KEY" |
curl -s https://api.getstructured.ai/api/v1/compare-versions \
-H @- \
-F "old_file=@A-101 rev A.pdf;type=application/pdf" \
-F "new_file=@A-101 rev B.pdf;type=application/pdf"
It answers exactly as step 3 does, runs the same checks and limits, and keeps working. For new integrations, use the upload form above.
Poll for the result
printf 'X-API-Key: %s\n' "$STRUCTURED_API_KEY" |
curl -s https://api.getstructured.ai/api/v1/compare-versions/$JOB_ID \
-H @-
Poll until done is true. A finished job has status ready, a summary, and findings: each one with what changed, its severity, and the page and box on the old and new sheet it was found on. A job that could not finish has status failed and an error. Pass ?include_findings=false to poll without the findings list.
Limits and errors
| Answer | Why |
|---|---|
401 | The key is missing, revoked, or belongs to someone who no longer has access. |
400 | A file is empty, is not a PDF, or cannot be read as one; or a ref is malformed. |
409 | A ref names nothing: the upload in step 2 did not finish, it is more than a day old, or it was already used up (by a comparison, or by a start refused because of either file). |
413 | A file is over 200 MB, or has more pages than your organization's per-document limit. |
429 | Your organization reached its hourly limit of comparisons. Only accepted comparisons count toward it. |
402 | Your organization's spending limit is reached. |
The uploaded PDFs and the comparison are kept in a Compare API project in your organization, which you can open in Structured like any other project.