Connect your estimating workflow
Scoped API keys let integrations prepare real projects, upload plans, run takeoffs, and retrieve reviewed estimates. You keep control of line review and bid finalization.
Available today on every Portravo account: sign in, open Settings > Integrations and create a key. The API covers projects, plan upload, the paid takeoff (existing credits only), the takeoff read and the reviewed-estimate export. Line review, pricing and finalizing a bid happen in Portravo. For assistants, use the MCP connection instead of a key.
Authentication
Send your key in the Authorization header on every request. Never place it in a URL, prompt, screenshot, or source repository.
Authorization: Bearer YOUR_PORTRAVO_API_KEY
Content-Type: application/json
Idempotency-Key: project-2026-0011. Create a key
Sign in, finish account setup, then open Settings > Integrations. Name the key, select only the permissions your integration needs, and save the key in its secure credential store. Keys expire after 90 days; revoke them from Settings.
2. Create the project
Call POST /api/v1/projects with a name and optional address or supported metroCode. Send an Idempotency-Key so retries do not create extra projects. The API uses your account as the owner.
3. Upload the plan
Request POST /api/v1/projects/{id}/uploads with a PDF filename. PUT the PDF to the returned uploadUrl with the short-lived clientToken, then POST the url it returns to the completionUrl. Plans can be up to 10 MiB. The API only adds the first plan to a new project.
4. Extract and review
POST /api/v1/projects/{id}/extract with confirmCreditUse:true and an Idempotency-Key after the user requests the paid takeoff. Existing credits and refund rules apply. Allow up to 300 seconds. Read the project’s takeoff, then open its reviewUrl to verify every line, map assemblies, and price the estimate.
5. Export the reviewed estimate
GET /api/v1/projects/{id}/export downloads the workbook after the existing pricing-readiness checks pass. Source, location and as-of dates stay attached to prices. Finalizing a bid remains a human action in Portravo.
Direct PDF upload
Use the signed upload grant to send the PDF bytes once. The grant is limited to one private object path, PDF type, 10 MiB, and 15 minutes.
const res = await fetch(grant.uploadUrl, {
method: "PUT",
headers: {
Authorization: `Bearer ${grant.clientToken}`,
"Content-Type": "application/pdf",
},
body: pdfBytes,
});
const { url } = await res.json();
// POST { url } to grant.completionUrl
// with your Portravo Authorization header.Limits and retries
All keys share the account’s 120-request-per-minute allowance. Upload grants are limited to 10 per hour; initial extractions to 3 per 10 minutes. Respect Retry-After and allow the longer operation window to reset. JSON bodies are limited to 16 KiB. Use the same Idempotency-Key and identical body when retrying project creation or extraction. A 409 request_in_progress means the request is still running. A 409 outcome_unknown means it was interrupted before its outcome was recorded: Portravo never runs it again under that key and returns the outcome when the project confirms it. Review the project in Portravo before starting the operation again; a missing result is not proof that nothing was charged. A completed response, including a failure, replays for the same key.
An extraction can consume existing paid balance; creating a key or project does not buy credits. Insufficient balance returns 402. API keys cannot change billing, read other users’ projects, replace reviewed lines, or finalize bids. An integration receives the data you authorize it to read; review its privacy policy before connecting. Only upload plans you are permitted to process.