Add AI plan review to your product

Authorization: Bearer ps_live_xxxxxxxxxxxxxxxxxxxxxxxx

{ "error": { "code": "...", "message": "..." } }

# 1. Create a job
curl -X POST https://YOUR_PLANSIGHT_HOST/api/v1/jobs \
  -H "Authorization: Bearer $KEY" -H "Content-Type: application/json" \
  -d '{"name":"123 Main St — bid #14"}'
# -> { "jobId": "...", "versionId": "..." }

# 2. Register the PDF -> get a presigned upload URL
curl -X POST https://YOUR_PLANSIGHT_HOST/api/v1/jobs/$JOB/files \
  -H "Authorization: Bearer $KEY" -H "Content-Type: application/json" \
  -d '{"fileName":"plans.pdf","fileSize":8421000,"contentType":"application/pdf"}'
# -> { "fileId": "...", "uploadUrl": "https://s3..." }

# 3. PUT the raw bytes to the presigned URL
curl -X PUT "$UPLOAD_URL" -H "Content-Type: application/pdf" --data-binary @plans.pdf

# 4. Start the scan
curl -X POST https://YOUR_PLANSIGHT_HOST/api/v1/jobs/$JOB/scan -H "Authorization: Bearer $KEY"

# 5. Poll status until complete (~minutes)
curl https://YOUR_PLANSIGHT_HOST/api/v1/jobs/$JOB -H "Authorization: Bearer $KEY"
# -> { "jobId": "...", "status": "...", "pipeline": { "currentStage": "...", ... } }

# 6. Read findings
curl https://YOUR_PLANSIGHT_HOST/api/v1/jobs/$JOB/findings -H "Authorization: Bearer $KEY"
# -> { "findings": [ { "severity": "...", "rationale": "...", "evidenceAnchors": [...] } ] }

curl -X POST https://YOUR_PLANSIGHT_HOST/api/v1/embed \
  -H "Authorization: Bearer $KEY" -H "Content-Type: application/json" \
  -d '{"screen":"job","jobId":"'$JOB'"}'
# -> { "url": "https://.../embed/job/JOB?t=SIGNED", "expiresAt": 1733... }

curl -X POST https://YOUR_PLANSIGHT_HOST/api/v1/jobs/$JOB/chat \
  -H "Authorization: Bearer $KEY" -H "Content-Type: application/json" \
  -d '{"message":"What setbacks does the site plan call out?"}'
# -> { "answer": "...", "citations": [ { "page": 4, "sheetType": "...", "excerpt": "..." } ] }

[PlanSight Partner API v1.0.0 · build 7acb0c07c2f1a3ee0ae1476b4d7bf3f05dc96bba · https://plansight.xyz]

You are adding a "PlanSight" integration to our construction job-management app
(we bid, estimate, and pay for work). PlanSight is an AI building-plan code-review
service. Your job: let our users upload plans, see PlanSight's scan results, and
ask questions about a plan — all inside our app.

AUTHORITATIVE DOCS (read these first, in full):
- Guide:   https://plansight.xyz/developers
- OpenAPI: https://plansight.xyz/api/v1/openapi.json   (every endpoint + exact request/response schemas)

CREDENTIALS
- We have a PlanSight API key in the server env var PLANSIGHT_API_KEY (format ps_live_...).
- It is a SERVER-SIDE SECRET. NEVER send it to the browser, log it, or commit it.
- Every server-to-server call: header  Authorization: Bearer $PLANSIGHT_API_KEY
- Our PlanSight account owns everything we send; one "job" in PlanSight === one of our jobs.

BUILD THE FOLLOWING

1) A small server-side PlanSight client (e.g. lib/plansight.ts) that wraps:
   POST https://plansight.xyz/api/v1/jobs                         -> { jobId, versionId }   (create)
   POST https://plansight.xyz/api/v1/jobs/{jobId}/files           -> { fileId, uploadUrl }  (then PUT the PDF bytes to uploadUrl with Content-Type: application/pdf)
   POST https://plansight.xyz/api/v1/jobs/{jobId}/scan            -> starts the scan (async)
   GET  https://plansight.xyz/api/v1/jobs/{jobId}                 -> { status, pipeline }    (poll until complete/failed)
   GET  https://plansight.xyz/api/v1/jobs/{jobId}/findings        -> { findings: [...] }
   POST https://plansight.xyz/api/v1/jobs/{jobId}/chat            -> { answer, citations }
   POST https://plansight.xyz/api/v1/embed { screen, jobId? }     -> { url, expiresAt }      (signed hosted-screen link)

2) On each of our jobs, store the PlanSight jobId. Add an "Upload plans for review"
   action: create a PlanSight job, get a presigned URL, PUT the PDF, then call scan.
   Track status by polling GET /api/v1/jobs/{jobId} (or show our own progress).

3) Add a "PlanSight" screen/tab to each job offering THREE things (use the hosted
   screens — do NOT rebuild PlanSight's UI). For each, call POST /api/v1/embed from
   OUR SERVER (with the API key), then render the returned url in an <iframe>:
   - results:  POST /api/v1/embed { screen: "job",  jobId }  -> iframe the url (marked-up plan + findings, with upload)
   - jobChat:  POST /api/v1/embed { screen: "chat", jobId }  -> iframe the url (ask questions, AI answers)
   - a "Log in to PlanSight" button: POST /api/v1/embed { screen: "login" } -> open the url (their full PlanSight dashboard)
   Embed links expire in ~30 minutes and are scoped to one screen + one job — mint them
   fresh, server-side, when the user opens the screen. NEVER mint them in the browser.

4) (Optional, great for a bid/estimate app) Also pull GET /api/v1/jobs/{jobId}/findings
   server-side and show a NATIVE summary on the job card — counts by severity and any
   cost impact — with an "Open full report" button that opens the embedded results screen.

RULES
- Match the exact shapes in the OpenAPI spec. Handle 401 (bad key), 404 (job not found
  / not ours), and 429 (rate limited — respect the Retry-After header).
- Keep the API key server-side always; the browser only ever sees short-lived embed URLs.
- Scans are asynchronous (minutes); design the UI around "submitted -> processing -> ready".

Confirm your integration plan, then implement it incrementally with tests.