# Exayard API

> Developer and agent reference for the Exayard platform: REST API, MCP server, webhooks, SDKs.

Exayard is an AI-powered construction takeoff and estimation platform. This document is the entry point for AI agents and developers integrating with it. Agents should prefer MCP; humans writing code should prefer the REST API + TypeScript SDK.

## Primary surfaces

- [Agent setup prompt](https://exayard.com/prompt.md): paste `Fetch https://exayard.com/prompt.md` into any AI coding agent to connect Exayard in one step
- [OpenAPI 3.1 spec](https://api.exayard.com/v1/openapi.json): machine-readable contract for the REST API
- [Interactive API docs](https://developers.exayard.com/api-reference): Scalar UI over the OpenAPI spec
- [MCP server](https://api.exayard.com/mcp): Streamable HTTP, OAuth-protected; 125 tools covering projects, files, assessments, symbols, measurements, products, vendors, prices, estimates, bids, conversations, widgets
- [ARD catalog](https://api.exayard.com/.well-known/ai-catalog.json): Agentic Resource Discovery manifest (signed) listing the MCP server, REST API, and A2A agent; identity via did:web:exayard.com
- [A2A agent card](https://api.exayard.com/.well-known/agent-card.json): "Exayard" Agent2Agent card (JSON-RPC at /a2a, X-Widget-Key auth)
- [JWKS](https://api.exayard.com/.well-known/jwks.json)
- [OAuth protected-resource metadata](https://api.exayard.com/.well-known/oauth-protected-resource)

## Authentication

- `Authorization: Bearer sk_live_...` (API key) or `Authorization: Bearer <clerk-oauth-token>`
- API keys are issued per-user in the Exayard app under Settings → Developer at `/settings/developer`
- OAuth for agents uses Clerk. MCP clients should follow RFC 9728 discovery — hit `/.well-known/oauth-protected-resource` for authorization-server metadata

## Conventions

- Base URL: `https://api.exayard.com/v1`
- Content type: `application/json` on request and success responses
- Errors: `application/problem+json` per RFC 9457 with `code`, `param`, `doc_url`, `request_id`
- Request IDs: every response includes `X-Request-Id`
- Idempotency: unsafe mutations accept `Idempotency-Key` header (24h replay window)
- Rate limits: `RateLimit` and `RateLimit-Policy` headers (IETF draft) on every response
- Pagination: cursor-based — `limit` + `cursor` query parameters, `next_cursor` in response envelope

## MCP tool categories

- `get_*`, `list_*`, `search_*` — read-only; safe to auto-approve
- `create_*`, `update_*`, `batch_*`, `approve_*` — write; confirm before executing
- `archive_*`, `remove_*`, `cancel_*` — destructive; always confirm

Every MCP tool ships with `readOnlyHint`, `destructiveHint`, and `idempotentHint` annotations so agents can decide auto-approval policy without re-parsing descriptions.

## Key specs

- OpenAPI 3.1 / JSON Schema 2020-12 — https://spec.openapis.org/oas/v3.1.0
- MCP 2025-06-18 — https://modelcontextprotocol.io/specification
- RFC 9457 Problem Details — https://www.rfc-editor.org/rfc/rfc9457
- RFC 9728 OAuth Protected Resource Metadata
- RFC 8414 OAuth Authorization Server Metadata
- RFC 7591 OAuth Dynamic Client Registration (MCP registration, where available)
- draft-ietf-httpapi-ratelimit-headers