Skip to main content

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.

Available on request

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).

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​

AnswerWhy
401The key is missing, revoked, or belongs to someone who no longer has access.
400A file is empty, is not a PDF, or cannot be read as one; or a ref is malformed.
409A 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).
413A file is over 200 MB, or has more pages than your organization's per-document limit.
429Your organization reached its hourly limit of comparisons. Only accepted comparisons count toward it.
402Your 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.