# Exayard — full index for AI agents

> AI-powered takeoffs and cost estimation for construction.

## What Exayard does

Exayard is a construction takeoff, estimation, and bidding platform. The core product workflow:

1. **Upload plans.** PDFs, images, or drawings are uploaded to a project. Files are rasterized to pages and indexed.
2. **Run an assessment.** AI (Claude Vision) scans each page and measures its elements: counts (receptacles, lights, doors), linear measurements (pipe runs, framing), and area measurements (floor, roof). With no item list, it measures and counts everything on the selected sheets, including the symbols the sheet's legend defines.
3. **Adjust.** The measurements land as symbols on the canvas and feed downstream calculations. The user moves, resizes, renames, or deletes them like any hand-drawn measurement.
4. **Attach products and prices.** Line items on each symbol bind to a product catalog; products have vendor-specific prices. Best-price lookup is automatic.
5. **Generate estimates and bids.** The estimator produces a cost breakdown; the bid packages estimate + markup + terms into a shareable document.

Around this spine: real-time canvas collaboration, a project-aware AI chat (Exa), help content in 40 locales, customer-facing widgets for lead capture, and integrations with Slack, Telegram, Cal.com, Calendly.

## Key objects (data model)

- `organizations` → `users` (teams, permissions, credits)
- `projects` → `files` → `pages` (construction docs split into pages)
- `assessments` → `detectedElements` (AI outputs pending approval)
- `layers`, `groups`, `symbols` (approved canvas structure)
- `measurements` (per-shape geometry on a page)
- `lists` (product catalogs), `products`, `vendors`, `vendorPrices`
- `lineItems` (symbol↔product bindings with quantity and unit)
- `estimates`, `bids`, `quotes` (costed outputs)
- `conversations` + `chatMessages` (AI chat)
- `widgets` + `integrations` (embedded lead capture + platform wiring)

## For agents and developers

### Authentication
- API keys, OAuth tokens, and session tokens all issued via Clerk.
- All tokens are Bearer tokens on `Authorization: Bearer ...`.
- MCP uses the same auth layer; third-party agents can use OAuth with PKCE.

### Public surfaces
- REST API: `https://api.exayard.com/v1` — 152 routes, OpenAPI 3.1 at `/v1/openapi.json`.
- MCP server: `https://api.exayard.com/mcp` — Streamable HTTP transport, 125 tools spanning every capability above (projects, files, pages, assessments, layers, groups, symbols, measurements, products, vendors, prices, lists, estimates, bids, widgets, integrations, conversations, messages, notifications, credits, custom properties, folders).
- Widget embed: `https://exayard.com/w/{widgetKey}` — public per-widget interface.
- Interactive API docs: `https://developers.exayard.com/api-reference` (Scalar-rendered).
- Marketing developer hub: `https://exayard.com/developers` — overview of all developer surfaces (REST, MCP, webhooks, CLI, integrations).
- Marketing integrations index: `https://exayard.com/integrations` — Claude, Claude Code, Claude Cowork, Cursor, ChatGPT, Codex, Zapier, n8n, Make.com, Slack, webhooks, CLI.
- Per-agent install pages: `https://exayard.com/integrations/{claude,claude-code,claude-cowork,cursor,codex,chatgpt}` — 60-second install for each supported agent runtime.
- Security overview: `https://exayard.com/security` — encryption, OAuth flow, audit logs, sub-processors, vulnerability disclosure.

### Plan availability
API, MCP server, webhooks, and the Zapier / n8n / Make.com integrations are included on every paid plan (Starter, Professional, Enterprise). Quota differs per tier — see `https://exayard.com/pricing`. Enterprise has unlimited API calls and webhook deliveries plus dedicated integration support.

### Tool categories (MCP)
- **Safe (read):** `get_me`, `list_projects`, `list_products`, `search_products`, `search_vendors`, `get_best_price_for_product`, `list_measurements_by_page`, `list_measurements_by_symbol`, `search_project_files`, etc.
- **Moderate (write):** `create_project`, `create_list`, `create_product`, `batch_create_products`, `set_vendor_price`, `create_symbol`, `add_symbol_line_item`, `propose_analysis`, `run_approved_analysis`, `create_estimate`, `create_bid`, etc.
- **Destructive:** `archive_project`, `cancel_assessment`, `remove_vendor_price`, `remove_symbol`, etc.

### Long-running operations
- `create_estimate` and `create_bid` are blocking 30–60s MCP tool calls. Plan for this timeout.
- `create_assessment` kicks off an async AI job; poll `get_assessment` or (soon) subscribe to webhook events.
- File uploads are two-step: presign via API, upload via the Cloudflare Worker at `sync-worker`.

### Rate limits
- Per-IP: 60/min (default bucket).
- Per-IP global: 150/hour across all endpoints.
- Per-endpoint global: 6000/min.
- 429 responses include `Retry-After` (seconds) and `RateLimit`/`RateLimit-Policy` headers (IETF draft structured field).

### Error shape
Errors use RFC 9457 Problem Details (`application/problem+json`): `{ type, title, status, detail, instance, code, param?, doc_url?, request_id }`. Every response includes `X-Request-Id` for support triage.

## Help topics

- Getting started — account setup, inviting teammates, first project
- Files & documents — uploading, organizing in folders, versioning
- Takeoffs — canvas basics, layers, groups, symbols, measurement tools
- Assessments — running AI detection, reviewing proposed elements, approval flow
- Estimates — line items, markups, labor rates, equipment, crews
- Bids — generating bid documents, sharing, follow-up
- Spreadsheets — data views of takeoff output
- AI chat (Exa) — asking questions grounded in the active project
- Collaboration — sharing projects, permissions, messaging
- Account settings — profile, org, security, API keys
- Billing & credits — subscription, AI credit consumption, usage history

## Standards and specs we follow

- OpenAPI 3.1 / JSON Schema 2020-12
- RFC 9457 Problem Details for HTTP APIs
- draft-ietf-httpapi-ratelimit-headers (RateLimit, RateLimit-Policy)
- Model Context Protocol 2025-06-18 (Streamable HTTP, tool annotations, structured content)
- RFC 9728 OAuth Protected Resource Metadata (`/.well-known/oauth-protected-resource`)
- RFC 8414 OAuth Authorization Server Metadata (via Clerk)
- Schema.org JSON-LD on marketing pages (Organization, SoftwareApplication, FAQPage)
- llmstxt.org format (this file and the index)