Portal Ops
API Guide

Tool arguments go in input, never in args. Top-level orgId must match the org baked into the key.

{
  "action": "exec",
  "orgId": "YOUR_ORG_ID",
  "toolName": "list_jobs",
  "input": {}
}

Before working on an estimate, call read_estimate_handoff to check staff and prior-agent context, then call estimate_snapshot. If you do not have a job id yet, call list_jobs (or action: "brief") first, then estimate_snapshot or read_proposal with input.jobId from that list. estimate_context, update_estimate, and link_recording are live. estimate_context needs a full-access key (*). Do not invent ids. If the API returns job-not-found, the message includes the identifier that was tried — call list_jobs and retry.

For trials, ask your organization administrator for an approved sandbox with synthetic data and the minimum required access. Keep sandbox login details and keys in your authorized secret store, never in public documentation or chat.

restore_proposal_revision is PR #1239 (not on main yet). Batch and view: "summary" are PR #1240 (not on main yet). Send one exec per request until batch ships.

ChatGPT — one-click Connect

1. Add a custom connector. MCP server URL https://pezleyportal.com/ops-connect. OAuth client ID is pezley-chatgpt. Leave the client secret blank.
2. Redirect URI, exact: https://chatgpt.com/connector_platform_oauth_redirect. Portal returns iss so ChatGPT can use this stable callback. https://chatgpt.com/connector/oauth/… is a different URI and is rejected.
3. Sign in as an org admin and approve the scopes. Owner finances and app import are never granted here. The key page shows “ChatGPT, connected by <name>”. Revoke it to disconnect immediately.
4. Paste this into a new chat: tool arguments always go in the JSON field "input", never "args". Start by calling estimate_snapshot. For a safe trial, use the administrator-approved sandbox.

Claude — one-click Connect

Hosted Claude (claude.ai, desktop, mobile) uses the same server URL https://pezleyportal.com/ops-connect and client ID pezley-claude (no client secret). Redirect URI, exact, from Anthropic’s connector docs: https://claude.ai/api/mcp/auth_callback. Claude Code’s loopback redirect (http://localhost/callback on a changing port) is not a fixed URI, so it is not accepted. Approve scopes as an admin. Revoke “Claude, connected by <name>” on the key page to kill tokens immediately. Same starter prompt. For a safe trial, use the administrator-approved sandbox.

Generic MCP

One exec per request until PR #1240. Example tool: estimate_snapshot with "input": {} and the administrator-approved sandbox orgId for a safe trial. Same starter prompt as ChatGPT.

Agents and integrators should use the generated OpenAPI 3.0 document for every exec tool name, JSON input shape, read vs write kind, and x-ops-scopes group. It is rebuilt from the Portal tool registry on each deploy.

Download YAML  ·  Download JSON  ·  https://pezleyportal.com/portal-ops-openapi.yaml

Browse below or paste the YAML URL into your agent framework. No login required.

1. Read the OpenAPI spec (or Redoc below) — every exec tool has a PortalOpsInput_* schema, scope tags, and write tools include x-examples.
2. As an org admin, issue a ppops_… key under Settings → Portal Ops keys. New keys are opt-in: no scopes are checked until you pick groups (or Full access for every API group). Choose the smallest set that fits — e.g. briefing-read only for a morning snapshot.
3. Store the secret in your assistant env (e.g. PEZLEY_OPS_BRIEF_KEY). Never commit it to git or paste it into customer-visible channels.
4. Call POST https://pezleyportal.com/.netlify/functions/portal-ops-mrz-tool with Authorization: Bearer … and a JSON body. Top-level orgId must match the org baked into the key — not inside input.
5. Use action: "brief" for a one-shot morning snapshot, or action: "exec" with toolName + input for a single registry tool per request. Put tool arguments in input, not args.
6. On 403 / 400, read the code field and adjust scopes or tool choice — see error codes, scope groups, and blocked tools.

Portal Ops is Pezley Portal's HTTP API for external AI assistants, automations, and integrations. Each request is authenticated with a long-lived ppops_… secret your org admin issues in Settings.

Typical uses: a morning operations brief, adding a lead from a phone call, booking an estimate visit, updating a proposal draft, posting a weather delay, or attaching a work-order PDF.

Signing in to the web app as an org admin still unlocks the full in-browser admin assistant catalog. Portal Ops keys are separate credentials with scopes you control.

In Settings → Portal Ops keys, the ChatGPT / MCP connection card controls how long hosted ChatGPT OAuth sessions last for new connects. Default: until the Ops key is revoked or rotated (grantTtlMode: until_revoked) — not a 30-day calendar timer.

Scopes vs OAuth: current key scopes are checked on each request, alongside OAuth scope and applicable consent caps. Refresh tools updates metadata; reconnect ChatGPT through normal consent to restore or approve access. See setup, discovery and consent and Estimate Library reads.

Optional: expires_after_days caps lifetime from each new Connect (1–3650 days). Existing ChatGPT sessions keep the deadline from when they connected.

Programmatic parity (Firebase org-admin ID token, not ppops_):

POST https://pezleyportal.com/.netlify/functions/ops-brief-key
{ "action": "key-status", "orgId": "your-org-id" }
→ keys[], availableScopes[], mcpConnection { grantTtlMode, expiresAfterDays }

{ "action": "save-mcp-connection", "orgId": "your-org-id", "grantTtlMode": "until_revoked" }
→ { ok, orgId, mcpConnection }

Tool calls still use POST https://pezleyportal.com/.netlify/functions/portal-ops-mrz-tool with your ppops_ key. See PortalMcpConnectionSettings in the OpenAPI spec.

Authentication & tenant rules

ChatGPT / MCP — setup, refresh & consent

1. Create or open the Pezley Portal developer connection in ChatGPT. For the existing Ops-key flow, use https://pezleyportal.com/mcp with OAuth. Complete the normal Portal consent screen using an administrator-issued key. Never paste a key into chat or a server URL.
2. For an existing plugin, use Refresh tools (or Refresh in its developer connection settings), then start a new conversation with that connection enabled. Check the actual available tool names and input schemas; the catalog changes, so there is no permanent tool count.
3. Refresh updates tool metadata. New OAuth consent is a separate step: invoke the requested action, then let the user complete the normal authentication challenge if additional access is required. Reconnect can retain the previous scope; refresh alone grants no permissions.
4. Verify with the smallest relevant read. For Estimate Library questions, use the structured calls below; a successful morning brief does not verify library access.

Anonymous initialize / tools/list expose discovery metadata, not organization data or authorization. Both routes share the current MCP handler; its tool authentication challenges point at the root resource metadata. Do not assume the alias has separate tools or rewrite authorization URLs to force a scope.

Two permission layers: every call intersects the current Ops key tools with the original OAuth allowed-tool list, for scoped and full-access keys alike. OAuth scope and the original tool list stay unchanged through refresh. For portal:ops:v1, a missing allowed-tool list fails closed. Narrowing a key takes effect immediately. Widening a key or adding tools such as Home File does not expand an existing grant; complete fresh consent to add access. Rotation or revocation invalidates grants derived from that key. The connection lifetime setting applies to new root-flow connections; existing deadlines remain unchanged.

Estimates & proposals — recommended tool sequence

Scope proposals-estimates or *. Canonical loop: read_proposal → save_proposal_draft → read_proposal. Patch only fields you intend to change; confirm estimate.totals, room substrates, and line items on the second read.

SENT estimate: reopen_proposal_draft → edit → read_proposal → send_proposal. See Proposals.

SENT estimate, second person: resend_proposal_email with estimateId + one email — emails the same link; nothing on the proposal changes.

SENT estimate: reopen_proposal_draft → edit → read_proposal → staff re-send in Portal. Ops keys never send proposals (customer-send-blocked, v1956). See Proposals.

Scope-loss failures can come from wiping scope with empty arrays or round-tripping compact read_proposal JSON — use targeted patches and verification reads instead.

Voice estimating (hosted MCP)

For live phone takeoff with ChatGPT + Portal Ops MCP + Plaud/Granola connectors. Goal: one tool call per spoken instruction — no long silent chains.

1. Check context first: call read_estimate_handoff with estimateId, jobId, or jobRef. Review prior decisions, unfinished work, linked recordings, and attached note summaries. This works with the proposals-estimates scope.
2. Call estimate_context once at the start of every conversation (jobRef, today, or YYYY-MM-DD) and keep the result. Scope: full-access key (*); narrower estimate keys use read_estimate_handoff and estimate_snapshot.
3. Find the matching recording from recordingSearch (window = visit start minus 15 minutes through visit end plus 60 minutes, in America/Chicago and ISO) and keywords (customer last name, street, PO). Use list_recordings to browse the org’s connected Plaud/Granola account and read_recording_transcript to read the speech (follow nextOffset until null). A summary is separate from a transcript; transcriptAvailable:false means speech is unavailable. Then link_recording with estimateId or jobId/jobRef (proposals-estimates or jobs-files). Personal recording accounts are not browsed by these tools.
4. Make one update_estimate call per spoken instruction (preferred over read_proposal → save_proposal_draft → read_proposal). Example: “add a 12 by 14 bedroom, walls and ceiling, two coats.”
5. Do not re-read the full proposal after writes — update_estimate returns compact rooms/lines/colors and recomputed totals.
6. Give a short spoken acknowledgement before slow calls.
7. Read back only totals and changed rows.
8. Ask the owner only when truly ambiguous: two visits in the same window, or no recording found.
9. Leave context after work: call add_estimate_note with what changed, key decisions/assumptions, open questions, and next steps. Keep each note under 1,000 characters. Reuse the same idempotencyKey only when retrying that note. The shared Office handoff allows 4,000 characters total and preserves existing notes; if full, ask staff to condense it.

Internal only: handoff notes appear to the estimator in Office handoff. They are stored separately from estimates and never included in client proposals, PDFs, share pages, or customer AI. Never paste internal context into customer-facing estimate notes. These tools require proposals-estimates (or full access). Existing MCP connections must complete fresh consent to gain newly added tools.

{"action":"exec","orgId":"YOUR_ORG_ID","toolName":"read_estimate_handoff","input":{"jobId":"job-123"}}
{"action":"exec","orgId":"YOUR_ORG_ID","toolName":"add_estimate_note","input":{"jobId":"job-123","note":"Updated bedroom walls and ceiling. Confirm trim sheen before sending.","idempotencyKey":"bedroom-handoff-1"}}

update_estimate resolves natural jobRef server-side (PO, customer, address, jobId). Ambiguous refs return a short candidate list — never guess. Merge-only: empty arrays are no-ops; explicit removeAreaIds / removeDescriptorIds / removeColorIds only. estimate_snapshot is the lean read-back tool when needed.

create_estimate vs save_proposal_draft

What to include on save_proposal_draft

Estimate pricing rule

PRICING RULE: price painting and staining through areas[] (substrates with productId, productionRateId, coats) so the crew work order gets hours and materials. Use a flat-priced lineItem only for an add-on such as lift or equipment rental (set flatAddOn:true). Never add a separate paint/stain materials line; materials come from the products on area substrates.

GOOD: areas:[{name:"Living room",length:18,width:15,height:9,substrates:[{name:"Walls",productionRateId,productId,coats:2}]}] plus lineItems:[{name:"Boom lift rental",amount:1200,flatAddOn:true}]. BAD: {name:"Exterior painting",amount:4800} (painting as a flat price, so no crew hours); {name:"Paint and materials",amount:650} or {name:"Duration (5 gal)",amount:450} (separate materials line).

Guidance only: the server does not reject lines for their price.

edit_job with hoursEstimate updates the job stamp only — not Estimate Builder takeoff hours. Use save_proposal_draft for builder scope.

Keys with Scheduling & visits get the same server tools the in-app schedule assistant uses for bars, spots, crew assignment, visits, delays, and shift reads — not a read-only subset. Issue scheduling alone for a schedule bot; add production-rates if the assistant needs rate-book capacity hints.

• Read first: list_jobs (schedule + spots), read_job, list_crew, list_appointments, scan_shifts / analyze_time_trends for capacity.
• Write bars: edit_job_schedule (startDate, endDate, estimatedHours, crewLeadName, notBefore, datesLocked). Shift the end date when you push the start unless you intend to shorten the job.
• Write spots: add_spot_assignment / remove_spot_assignment — day-level overlay; does not move the schedule bar.
• Crew & hours: assign_to_job; edit_job with hoursEstimate when planning length (not for arbitrary status edits — use job-status).
• Visits: read list_schedule (estimator hours, booked visits, open slots), then book_estimate_visit (booking again moves it), offer_estimate_visit, cancel_estimate_visit, book_client_visit, cancel_client_visit. Book only after the customer confirmed: pass customerConfirmed: true. Booking never emails or texts the customer, and automatic visit reminders stay off unless you pass notifyCustomer: true because you were explicitly asked.
• Delays: post_job_delay (+ optional polish_delay_reason) — customer share + crew cascade.
• In-app only: write_schedule_with_ai opens the Write with AI panel in the portal; automations should use edit_job_schedule or visit tools instead.
• MCP: reconnect after scope changes (ops-mcp-consent-stale). Clock in/out and Owner $ tools stay off the hosted catalog — not required for scheduling.

Estimate drafts use create_estimate (blank draft on an existing job) and save_proposal_draft (rooms, descriptors, pricing, exclusions). Scope proposals-estimates or *. Use the job's Portal jobId, not the printed estimate number. Automations: see AI assistants before editing drafts.

Exclusions shape (required pattern)

Exclusions are what is NOT included — never stuff them into descriptor description or room notes. OpenAPI documents exclusions as:

• Array of strings — one customer-facing bullet per entry.
• Array of objects — { "text": "…" } (optional id).
• Single string — newline-separated; each non-empty line becomes one bullet.

{
  "action": "exec",
  "orgId": "your-org-id",
  "toolName": "save_proposal_draft",
  "input": {
    "estimateId": "ESTIMATE_ID",
    "exclusions": [
      "Soffits and fascia are excluded.",
      { "text": "Moisture repairs behind siding are excluded." }
    ],
    "customerSummary": "Prep and paint main body per scope."
  }
}

Rooms need length, width, and height (or sqft) to persist. Per-room notes: "" clears; omit to keep. Patch rules: AI assistants.

The home-file scope (or Full access) grants read_home_file, set_home_file_access, set_home_file_formulas and set_home_file_leftovers. Jobs & files and morning brief scopes do not grant these tools. Gate codes, lockbox details, access notes and pets remain staff-only; these tools do not send or publish a customer Home File.

For formulas or leftovers, pass jobId and the matching row list. A matching row id replaces that row; a new row appends. removeIds removes selected rows, and replace: true replaces the whole list. Rows and parent metadata commit together. Concurrent edits to separate rows survive, and a failed transaction commits nothing. Each job save keeps the existing cap of 60 formulas or 40 leftovers; the response reports dropped overflow rows.

Use items[] for up to 20 jobs. Each job is a separate transaction: a later failure does not undo a job already saved. Prices are stripped from the timeline and row text. Use the supported consent flow if the requested tool is denied; changing a key or refreshing metadata does not upgrade an OAuth scope.

Margin, burden, CFO packs, bank inbox, Numbers settings, and job costing writes require the owner-finance scope on the ops key (or a legacy full-access key). Without it, finance tools return 403 with finance-scope-required.

Tools include analyze_numbers, advise_cfo, query_cfo_knowledge, list_cfo_packs, draft_cfo_report, save_numbers_settings, save_job_costing, bank reconciliation helpers, and related reads — full list under owner-finance in the scope table above and in OpenAPI x-portal-ops-scope-appendix.

The same importer as Settings → Import from another app, on the Portal Ops key. It reads a PaintScout export (the .tar.gz, or its loose files) or the spreadsheet template CSV, matches it against this org's jobs, contacts, estimates, and invoices, and imports the result as one batch you can undo. DripJobs is coming soon.

Who can call it: keys with the app-import scope (high risk) or Full access, and org-admin ID tokens. One-click Connect (ChatGPT / Claude) cannot grant app-import — issue a manual key. Every write lands in the key's own org; orgId inside input is ignored and a top-level orgId for another org returns org-mismatch.

How to call it: the normal exec (one tool) or batch (ops[]) on portal-ops-mrz-tool. On hosted MCP use mrz_exec with toolName (or portal_ops_batch). There is no separate import endpoint and no ops_ shortcut for these four tools.

{ "action": "batch", "orgId": "your-org-id", "ops": [
  { "toolName": "preview_app_import", "input": { "source": "generic", "csv": "quoteNumber,firstName,…" } }
] }
// review counts + duplicates, then:
{ "action": "exec", "orgId": "your-org-id", "toolName": "commit_app_import", "input": { "previewId": "aip_…" } }

Duplicates: jobs match on the quote number only — never an invoice number, because the two sequences collide. Contacts match on PaintScout contact id, email, or 10-digit phone; estimates and invoices on their PaintScout ids. Each match is listed in duplicates with reason: "already-in-portal" and is updated, not created. Imported ids are stable, so importing the same quote again updates the same records.

Idempotent commit: previewId comes from the org, source, mode, file bytes, and selection. Calling commit_app_import again returns the same importBatchId with alreadyCommitted: true and writes nothing. A commit that stopped partway resumes the same batch: fields edited after the rows it already wrote stay, including a payment's method, check number, and client payment id. The saved undo snapshot is not replaced. Each contact, estimate, job, and invoice is written in its own transaction, so an edit made after the prepare read is not overwritten. A payment or refund that lands after that invoice was read stays, and so do the imported amount, status, and label. The undo snapshot stores what the import meant to write, not that live payment or refund. A job paidAt set in that gap stays on the job and is not stored as the import's paid date. Those payment conflicts are stored on the batch and show up from list_app_import_batches. The commit renews its claim while it reads and writes. It marks the preview committed only while that preview still says committing. If undo wins first, the commit stops and does not set committed. Previewing the same file and selection after a commit returns status: "committed". To import it again, undo that batch first, then preview again.

Limits: upload 4 MB (decoded tar.gz, or UTF-8 bytes of csv / files); a tar.gz may unpack to 32 MB; at most 200 files. A hosted MCP request is capped at 5.5 MB, and base64 adds a third, so send uploads near 4 MB over HTTP exec. preview_app_import, commit_app_import, and undo_app_import each add 5 to the rate-limit weight, on exec or inside batch, so one of them is not weight 1.