Skip to main content
Trigger an asynchronous comparison between two drawings. The system matches sheets between the drawings, generates overlays for each matched block pair, and detects changes and clashes. Returns a job_id for polling.

​
When to Use

  • Compare two revisions of the same drawing set (e.g., Rev A vs Rev B)
  • Detect cross-discipline clashes between structural and mechanical drawings
  • The user asks “what changed” between drawing versions
Comparison is an async operation that consumes credits. It may take seconds to minutes depending on the number of sheets. Use PollJob to poll for completion.

​
Parameters

ParameterTypeRequiredDescription
project_idstringyesProject scope
drawing_a_idstringyesFirst drawing (typically the older revision)
drawing_b_idstringyesSecond drawing (typically the newer revision)

​
Response

{
  "job_id": "job_cmp_01",
  "status": "queued"
}
FieldTypeDescription
job_idstringUse with PollJob to poll status
statusstringInitial status, always "queued"

​
Workflow

1

Identify the drawings

Use Query with entity: "sheet" to find sheets and their parent drawing IDs. Filter by discipline or search by name.
2

Trigger comparison

Call Compare with both drawing IDs. Note the returned job_id.
3

Poll for completion

Call PollJob with the job_id. The job progresses through queued > started > completed.
4

Inspect results

Once complete, use Query with entity: "block" and include: ["overlays", "changes"] on the compared blocks to get detailed change descriptions.

​
Example

​
Compare architectural revisions

First, find the drawings: 
// Query
{
  "entity": "sheet",
  "project_id": "proj_oak",
  "discipline": "A"
}
// Response includes sheets from both "Arch Set Rev A" (dr_arch_a)
// and "Arch Set Rev B" (dr_arch_b)
Then trigger the comparison: 
// Compare
{
  "project_id": "proj_oak",
  "drawing_a_id": "dr_arch_a",
  "drawing_b_id": "dr_arch_b"
}

// Response
{
  "job_id": "job_cmp_01",
  "status": "queued"
}
  • PollJob - Poll the comparison job for status and results
  • Query - Find drawings and their IDs before comparing, fetch change and clash details after
  • ViewImage - View overlay images showing additions and deletions