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 (coming soon) — bearer tokens, OAuth 2.1 for MCP clients, refresh semantics, revocation.
• Scopes & permissions (coming soon) — the scope catalogue, sensitive vs operational scopes, the fine-grained model.
• Rate limits (coming soon) — defaults, headers, 429 handling.
• Endpoint reference (coming soon) — the full surface, rendered from the OpenAPI 3.1 specification.

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 site you're reading is new — we'll expand it iteratively as more endpoints land and more vendor integrations come online. Section status:

• Live now: Overview, Quick start.
• Coming soon: Authentication, Scopes & permissions, Rate limits, Errors, Endpoint reference.

If you need a specific endpoint reference or auth detail before the relevant page lands, reach out via the contact form — we'll point you at the right primitives.