Estimatic API docs

1. Get a key

Email developers@estimatic.ai or grab one from Settings → Developers inside the app. Keys are scoped to a single organization and prefixed sk_live_ or sk_test_.

2. Curl — first estimate

curl -X POST https://api.estimatic.ai/v1/estimates \
  -H "Authorization: Bearer sk_live_..." \
  -H "Content-Type: application/json" \
  -d '{
    "prompt": "Replace 24 LF of cedar privacy fence, 6ft tall, with 2 gates.",
    "trade": "fencing",
    "project_zip": "30303"
  }'

3. Node SDK (preview — request access)

// npm i @estimatic/node
import { Estimatic } from "@estimatic/node";

const estimatic = new Estimatic({ apiKey: process.env.ESTIMATIC_KEY! });

const estimate = await estimatic.estimates.create({
  prompt: "Master bath gut remodel, double vanity, heated floors",
  trade: "remodel",
  project_zip: "30303",
  options: { good_better_best: true },
});

console.log(estimate.options.map(o => `${o.tier}: $${o.total_price}`));

4. Python SDK (preview — request access)

# pip install estimatic
from estimatic import Estimatic

client = Estimatic(api_key=os.environ["ESTIMATIC_KEY"])

estimate = client.estimates.create(
    prompt="Replace 30sq architectural shingle roof, tear-off, ice & water on eaves",
    trade="roofing",
    project_zip="30303",
)

print(estimate.totals.grand_total)

5. MCP — hello world

{
  "mcpServers": {
    "estimatic": {
      "url": "https://api.estimatic.ai/mcp",
      "headers": { "Authorization": "Bearer sk_live_..." }
    }
  }
}

Two surfaces, one engine

Use the REST API for traditional integrations. Use the MCP server when you want an AI agent (Claude, Cursor, ChatGPT, your own) to generate, refine, and push estimates as a tool. Both call the same backend, share the same auth, and emit the same webhooks.

Design principles

Predictable resource URLs. Verbs map to HTTP methods. Errors are structured JSON. Every mutating call accepts an Idempotency-Key. List endpoints use cursor pagination. We will never break a /v1/ contract — breaking changes ship behind /v2/.

Status

Currently in private beta. Request a key from your account manager or email developers@estimatic.ai. We onboard new partners weekly.

Key scopes

Keys can be scoped at creation. estimates:read — list/get only. estimates:write — create, refine, archive. integrations:push — push to connected CRMs. webhooks:manage — create/delete webhooks. clients:write — create/update clients. Combine as needed; default new keys get estimates:read + estimates:write.

Multi-org partners

If you hold a partner key that can act on behalf of multiple orgs, pass X-Estimatic-Org: org_01HX... on every request. Without the header the request is rejected with permission_denied.

Key rotation

Rotate from Settings → Developers. The old key keeps working for 24 hours after rotation, giving you a window to deploy. We email every key holder 7 days before any forced rotation.

Error envelope

{
  "error": {
    "type": "validation_failed",
    "message": "project_zip must be a 5-digit US ZIP code.",
    "param": "project_zip",
    "request_id": "req_01JXYZ..."
  }
}

Error types

invalid_request (400) — malformed JSON or missing required field. authentication_failed (401) — bad or missing key. permission_denied (403) — key lacks the scope or org. not_found (404) — id doesn't exist or isn't visible to the caller. conflict (409) — resource already exists in a state that blocks the operation. validation_failed (422) — input parsed but failed business rules; check param. rate_limited (429) — slow down, see Retry-After. idempotency_replayed (200, header) — not an error, but the response was served from cache; check Idempotency-Replayed: true. upstream_unavailable (502) — a connected integration timed out; safe to retry. internal_error (500) — ours; we get paged, you can retry with backoff.

Retry policy

Retry 429, 502, 503, and 504 with exponential backoff (start at 1s, double, cap at 30s, max 5 attempts). Always retry with the same Idempotency-Key — never generate a new one for retries.

Base URL & versioning

https://api.estimatic.ai/v1 — versioned in the URL. Breaking changes ship behind /v2/. Additive changes never break existing /v1/ clients.

Idempotency

Every POST accepts an Idempotency-Key header (any unique string up to 255 chars — UUID v4 recommended). Re-sending the same key within 24 hours returns the original response with header Idempotency-Replayed: true. Different request body + same key = 409 conflict.

Rate limits

60 req/min per key by default. Burst headroom of 20. Higher limits available on request — email developers@estimatic.ai with your expected volume.

Response headers

X-RateLimit-Limit — your ceiling. X-RateLimit-Remaining — what's left in the current window. X-RateLimit-Reset — Unix seconds until the bucket refills. Retry-After — only on 429, seconds to wait. Idempotency-Replayed — present and true when a cached response is returned. X-Request-Id — include this in any support email.

Event catalog

estimate.created — fires after a successful POST /v1/estimates. estimate.updated — any field change (incl. PATCH). estimate.refined — natural-language refinement applied. estimate.pushed — sent to a connected CRM/accounting tool. estimate.sent — delivered to the customer (email/SMS). estimate.viewed — customer opened the share link. estimate.accepted — customer signed/accepted. estimate.declined — customer declined.

Example payload — estimate.viewed

{
  "id": "evt_01JXYZ...",
  "type": "estimate.viewed",
  "created_at": "2026-05-06T14:22:08Z",
  "data": {
    "estimate_id": "est_01JXYZ...",
    "viewer_ip": "73.12.x.x",
    "user_agent": "Mozilla/5.0 ...",
    "first_view": true
  }
}

Example payload — estimate.accepted

{
  "id": "evt_01JXYZ...",
  "type": "estimate.accepted",
  "created_at": "2026-05-06T15:01:22Z",
  "data": {
    "estimate_id": "est_01JXYZ...",
    "selected_option": "better",
    "signer_name": "Sarah Greene",
    "signed_at": "2026-05-06T15:01:21Z"
  }
}

Verifying signatures (Node / Express)

import crypto from "node:crypto";
import express from "express";

const app = express();

app.post(
  "/hooks/estimatic",
  express.raw({ type: "application/json" }),
  (req, res) => {
    const sig = req.header("x-estimatic-signature") ?? "";
    const ts  = req.header("x-estimatic-timestamp") ?? "";
    const expected = crypto
      .createHmac("sha256", process.env.ESTIMATIC_WEBHOOK_SECRET!)
      .update(`${ts}.${req.body}`)
      .digest("hex");

    const ok =
      sig.length === expected.length &&
      crypto.timingSafeEqual(Buffer.from(sig), Buffer.from(expected));

    if (!ok) return res.status(401).end();
    if (Math.abs(Date.now() / 1000 - Number(ts)) > 300) return res.status(401).end();

    const event = JSON.parse(req.body.toString("utf8"));
    // ... handle event ...
    res.status(200).end();
  }
);

Verifying signatures (Python / Flask)

import hmac, hashlib, os, time
from flask import Flask, request, abort

app = Flask(__name__)
SECRET = os.environ["ESTIMATIC_WEBHOOK_SECRET"].encode()

@app.post("/hooks/estimatic")
def hook():
    sig = request.headers.get("x-estimatic-signature", "")
    ts  = request.headers.get("x-estimatic-timestamp", "")
    body = request.get_data()  # raw bytes — do not parse first

    expected = hmac.new(SECRET, f"{ts}.".encode() + body, hashlib.sha256).hexdigest()
    if not hmac.compare_digest(sig, expected):
        abort(401)
    if abs(time.time() - int(ts)) > 300:
        abort(401)

    event = request.get_json()
    # ... handle event ...
    return "", 200

Endpoint & transport

https://api.estimatic.ai/mcp — Streamable HTTP transport per the MCP spec. Every request must send Authorization: Bearer sk_live_... and Accept: application/json, text/event-stream. The server responds with either JSON or an SSE stream depending on the tool call.

Authentication

Same Bearer key as the REST API, scoped to one org. For multi-org partners, set X-Estimatic-Org on the MCP transport headers — your AI client must support custom headers (Claude Desktop, Cursor, and the OpenAI Agents SDK all do).

Tools — overview

create_estimate, list_estimates, get_estimate, refine_estimate, patch_estimate, archive_estimate, push_estimate, create_client, list_clients, list_integrations, list_pricing_profiles, upload_file. Arguments and return shapes mirror the REST endpoints above.

Tool — create_estimate

{
  "name": "create_estimate",
  "description": "Generate a fully-priced estimate from a natural-language scope and (optionally) attached files.",
  "inputSchema": {
    "type": "object",
    "required": ["prompt"],
    "properties": {
      "prompt": { "type": "string" },
      "trade": { "type": "string", "enum": ["remodel","roofing","fencing","electrical","plumbing","hvac","landscaping","general"] },
      "project_zip": { "type": "string", "pattern": "^[0-9]{5}$" },
      "client_id": { "type": "string" },
      "file_ids": { "type": "array", "items": { "type": "string" } },
      "options": {
        "type": "object",
        "properties": {
          "good_better_best": { "type": "boolean", "default": true },
          "upsells": { "type": "boolean", "default": false },
          "local_permits": { "type": "boolean", "default": true }
        }
      }
    }
  }
}

Tool — refine_estimate

{
  "name": "refine_estimate",
  "description": "Apply a natural-language change to an existing estimate and re-price.",
  "inputSchema": {
    "type": "object",
    "required": ["estimate_id", "message"],
    "properties": {
      "estimate_id": { "type": "string" },
      "message":     { "type": "string" }
    }
  }
}

Tool — push_estimate

{
  "name": "push_estimate",
  "description": "Push a finished estimate into a connected CRM or accounting system.",
  "inputSchema": {
    "type": "object",
    "required": ["estimate_id", "integration"],
    "properties": {
      "estimate_id": { "type": "string" },
      "integration": { "type": "string", "enum": ["jobber","servicetitan","housecall_pro","quickbooks"] },
      "target":      { "type": "string", "enum": ["quote","estimate","invoice"], "default": "quote" },
      "client_id":   { "type": "string" }
    }
  }
}

Setup — Claude Desktop

// ~/Library/Application Support/Claude/claude_desktop_config.json
{
  "mcpServers": {
    "estimatic": {
      "url": "https://api.estimatic.ai/mcp",
      "headers": {
        "Authorization": "Bearer sk_live_..."
      }
    }
  }
}

Setup — Cursor / VS Code

// .cursor/mcp.json (or VS Code MCP settings)
{
  "mcpServers": {
    "estimatic": {
      "url": "https://api.estimatic.ai/mcp",
      "headers": { "Authorization": "Bearer sk_live_..." }
    }
  }
}

Setup — ChatGPT (Custom Connector)

In ChatGPT → Settings → Connectors → Add custom connector. Name: Estimatic. URL: https://api.estimatic.ai/mcp. Auth: Bearer token, paste your sk_live_ key. Save, then enable it in any chat. Ask the model: 'Use the estimatic connector to draft a roof replacement estimate for ZIP 30303, 30sq architectural shingles.'

Setup — OpenAI Agents SDK (Python)

# pip install openai-agents
from agents import Agent, Runner
from agents.mcp import MCPServerStreamableHttp

estimatic = MCPServerStreamableHttp(
    name="estimatic",
    params={
        "url": "https://api.estimatic.ai/mcp",
        "headers": {"Authorization": f"Bearer {os.environ['ESTIMATIC_KEY']}"},
    },
)

agent = Agent(
    name="EstimatorBot",
    instructions="You draft contractor estimates. Always call estimatic.create_estimate.",
    mcp_servers=[estimatic],
)

result = Runner.run_sync(agent, "Quote a 24 LF cedar privacy fence in ZIP 30303.")
print(result.final_output)

Prompting tips

1) Be explicit about the tool: 'Use estimatic.create_estimate to scope this bath remodel...' — vague prompts often skip the tool entirely. 2) Always pass project_zip — without it, pricing falls back to org default and accuracy drops 5–15%. 3) Chain refinements: 'Now use estimatic.refine_estimate to add a permit line for the city of Atlanta.' rather than re-creating from scratch.

Stability promise

Additive changes (new fields, new endpoints, new event types) are non-breaking and ship continuously to /v1/. Breaking changes ship behind /v2/ — never as a quiet change to /v1/. Deprecations get a 90-day email notice to every key holder.

v1.0 — public beta (target Q3 2026)

First stable release of /v1/estimates, /v1/clients, /v1/files, /v1/pricing-profiles, /v1/integrations, /v1/webhooks, and the MCP server.

Pre-beta

Private partners get early access via direct integration with our team. Endpoints are stable but breaking changes are still possible — we'll email every key holder before any.