API Overview

Construction AI is an open platform. Where most contech tools lock customer data inside proprietary schemas, we expose ours through a documented public API that vendors and AI agents alike can consume.

This page is the orientation layer. By the end of it you should know what the platform exposes, which surface fits your use case, and where to go next.

The platform in one paragraph

Construction AI is a unified construction management platform — tender, project management, site management, and financial modules under one roof — with a canonical data model that's exposed through two parallel surfaces: a public REST API for system integrations and an MCP server for AI agents. Both share the same authentication, the same multi-tenant isolation, the same audit log, and the same underlying data. They are not separate products — they are two faces over a single platform.

Two surfaces, one platform

   AI agents                          System integrations
   (Claude desktop,                   (vendor bridges, internal
    customer agents,                   tooling, scripts, partners)
    internal AI fleet)
          │                                          │
          │ JSON-RPC                                 │ HTTPS REST
          ▼                                          ▼
   ┌─────────────────────┐              ┌──────────────────────┐
   │  MCP Server         │              │  Public REST API     │
   │  /api/mcp           │              │  /api/construction-pm│
   │  OAuth 2.1 + PKCE   │              │  Bearer token        │
   │   or bearer token   │              │   (cai_sk_live_*)    │
   └──────────┬──────────┘              └──────────┬───────────┘
              │                                     │
              └────────────────┬────────────────────┘
                               ▼
              ┌────────────────────────────────────┐
              │  Per-tenant canonical store         │
              │  PostgreSQL · S3 · Vector index     │
              └────────────────────────────────────┘

Public REST API

Conventional HTTPS REST. Authenticate with a bearer token (cai_sk_live_*) issued by a tenant admin. Read and write the canonical entities — projects, RFIs, drawings, files, snags, submittals, financial records — using HTTP verbs you already know.

Best for: vendor integrations, server-to-server data sync, custom dashboards, scripts and internal tooling, anywhere a vendor wants to push or pull data programmatically.

MCP Server

Model Context Protocol over JSON-RPC. AI agents discover available tools, authenticate via OAuth 2.1 with PKCE (or a bearer token for direct clients), and invoke domain-specific operations like "list open RFIs", "find drawings affected by this clash", "summarise variations under this cost code".

Best for: AI agents (Claude desktop, ChatGPT custom connectors, internal corporate agents), agentic workflows over construction data.

Same auth, same data

Both surfaces share the same authentication tokens and the same canonical data. A token issued for the REST API also works against the MCP server (and vice versa, where scopes permit). Audit logs are unified — you can see every call against a key regardless of which surface it hit.

This matters because it means your integration choice is about how you consume the data, not whether you can. Build a server-side sync against REST and an in-app agent against MCP, with one key, one tenant, one audit trail.

Multi-tenant by design

Every token is scoped to one tenant. Every request resolves to one organisation. Cross-tenant data leaks are not just policy — they're physically prevented by PostgreSQL row-level security plus a service-layer ownership check. The architecture has no "admin override" that crosses tenants.

What you can do — at a glance

What you cannot do

• Cross-tenant queries. Tokens are tenant-scoped. There is no "read all organisations" mode.
• Direct database access. The platform exposes its data only through the documented API surface. SQL access is not available.
• Skipping audit. Every authenticated call is logged. There is no opt-out.
• Subverting scope enforcement. Sensitive scopes (financial detail, pricing, purchase ledger, agent invocation) default off and must be explicitly granted at key creation. A token holder cannot self-elevate.

Where to go next

• Quick start — generate your first API key and make your first authenticated call in under five minutes.
• Authentication — bearer tokens, OAuth 2.1 for MCP clients, refresh semantics, revocation.
• Scopes & permissions — the scope catalogue, sensitive vs operational scopes, the fine-grained model.
• Rate limits — defaults, headers, 429 handling.
• Errors — error envelope and code reference.
• Endpoint reference — the full surface, rendered from the OpenAPI 3.1 specification via Stoplight Elements. Every route, every parameter, every response shape.

A note on what's stable

The platform's auth layer, scope model, and canonical data shapes are production-grade and stable. The public docs are now live end-to-end — overview, quick start, authentication, scopes, rate limits, errors, and a full OpenAPI 3.1 endpoint reference rendered via Stoplight Elements at /docs/api-reference.

The spec covers 178 operations across the four core modules (Tenders, Project Management, Site Management, Financial) plus shared platform surfaces (discovery, settings, knowledge, documents). Sensitive routes — CVR, cost reports, applications, pricing, purchase ledger — are explicitly marked with x-strict-mode: true in the spec so an integrator can see exactly which scope each operation requires.

If you need an endpoint or auth detail you can't find in the published docs, reach out via the contact form — we'll point you at the right primitives.