Auto-Revision Watcher

The auto-revision watcher monitors a structural drawing source and automatically re-runs the full Eurocode pipeline when updated drawings are detected. The result is a revised fabrication bundle — PDF, IFC, Excel BOM, DSTV NC1 — delivered without manual intervention.

Entitlement: Auto-revision is available on Pro and Studio plans. Free tier users see the watcher registration UI with a 402 upgrade prompt.

How it works

Three intake methods feed the same pipeline:

Manual push — POST /api/jobs/:id/revisions with a multipart PDF.
HTTP watcher — FrameAI polls a URL every 15 minutes (configurable). When the ETag or content hash changes, a revision job is enqueued.
Email inbound — send a PDF attachment to your job's unique address (job-<token>@in.frameai-structural.polsia.app) to trigger a revision.

On completion the pipeline computes a structured diff (members changed, load inputs, compliance status flips) and emails a markdown summary to the job owner. Studio org members with the Engineer role are CC'd automatically.

Entitlement

Free — watcher API returns 402 with upgrade_url: "/pricing".
Pro — all three intake methods, unlimited watchers per job.
Studio — same as Pro plus org engineer CC on notification emails.

Method 1 — Manual push

Upload a revised PDF directly to a job. FrameAI creates a child job, runs the full pipeline, and diffs the result against the parent.

Endpoint

POST/api/jobs/:id/revisionsPro / Studio

Content-Type: multipart/form-data

Example

curl -X POST https://frameai-structural.polsia.app/api/jobs/42/revisions \
  -F "email=you@firm.com" \
  -F "pdf=@revised-drawing.pdf"

Response 202

{
  "revision_id": 7,
  "revision_index": 2,
  "job_id": 99,
  "parent_job_id": 42,
  "revision_number": 2,
  "status": "pending",
  "poll_url": "/api/upload/preview/99"
}

Method 2 — HTTP watcher

Register a URL to be polled every N seconds. FrameAI sends a HEAD request; if the ETag (or content MD5 when no ETag is present) changes, the new PDF is downloaded and a revision job is enqueued.

Register a watcher

POST/api/jobs/:id/watch

curl -X POST https://frameai-structural.polsia.app/api/jobs/42/watch \
  -H "Content-Type: application/json" \
  -d '{
    "email": "you@firm.com",
    "source": "http",
    "watch_url": "https://storage.example.com/drawings/frame-v2.pdf",
    "poll_interval_seconds": 900
  }'

Response 201

{
  "watcher_id": 3,
  "job_id": 42,
  "source": "http",
  "watch_url": "https://storage.example.com/drawings/frame-v2.pdf",
  "poll_interval_seconds": 900,
  "message": "We will poll ... every 900s and create a revision if the content changes."
}

List watchers

GET/api/jobs/:id/watch

curl "https://frameai-structural.polsia.app/api/jobs/42/watch?email=you@firm.com"

Method 3 — Email inbound

Each email watcher gets a unique routing address. Emails sent to that address with a PDF attachment trigger a revision automatically.

Register an email watcher

curl -X POST https://frameai-structural.polsia.app/api/jobs/42/watch \
  -H "Content-Type: application/json" \
  -d '{ "email": "you@firm.com", "source": "email" }'

Response 201

{
  "watcher_id": 4,
  "source": "email",
  "email_address": "job-a3f8c1d2e5b4...@in.frameai-structural.polsia.app",
  "message": "Send revised PDF attachments to job-...@in.frameai-structural.polsia.app to trigger a revision."
}

Forward your CAD tool's PDF export directly to this address. Postmark routes it to FrameAI, which extracts the first PDF attachment and enqueues a revision job.

Watch API reference

POST /api/jobs/:id/revisions

Auth: email form field (matches job owner)
Body: multipart/form-data — field pdf (binary, max 20 MB)
Returns: 202 with { revision_id, revision_index, job_id, poll_url }
Errors: 402 (Free tier), 403 (not owner), 404 (job not found)

POST /api/jobs/:id/watch

Auth: email in JSON body
Body JSON: { source, watch_url?, poll_interval_seconds? }
Returns: 201 with { watcher_id, email_address?, poll_interval_seconds }

GET /api/jobs/:id/watch

Auth: email query param
Returns: 200 with { watchers: [...] }

Diff schema

The structured diff is stored in revision_diff_json on the child job and returned by GET /api/jobs/:id/diff/:previousId.

{
  "from_job_id": 42, "to_job_id": 99,
  "from_revision": 1, "to_revision": 2,
  "members":  { "added": [...], "removed": [...], "changed": [...] },
  "connections": { "changed": [...] },
  "welds":    { "changed": [...] },
  "rc_beams": { "changed": [...] },
  "loads":    [{ "field": "wind_q_p_kPa", "from": 0.6, "to": 0.8 }],
  "materials": [{ "mark": "B01", "from": "S275", "to": "S355" }],
  "geometry":  [{ "mark": "R01", "delta": { "length_mm": { "from": 7000, "to": 7200, "delta": 200 } } }],
  "weight":    { "from_kg": 4200, "to_kg": 4650, "delta_kg": 450, "headline": "4200 kg → 4650 kg (+450 kg)" },
  "compliance": { "newly_failed": [], "newly_passed": [...] },
  "utilization_summary": [...]
}

Notification email

When a revision pipeline completes, FrameAI sends a transactional email to the job owner with:

Subject: Revision ready — <project_name> rev N
Body: markdown diff summary (weight delta, member changes, compliance flips)
CTA: Download revised set → linking to /jobs#job-<childJobId>

Studio org members with the Engineer role are CC'd automatically. Owners can unsubscribe via the link in the email footer.