Quick start

This page takes you from no credentials to a working API call. Five steps, about five minutes.

Before you begin

You need:

• A Construction AI tenant with at least one admin user (you).
• Access to the dashboard at app.constructionai.io.
• A terminal with curl, or your HTTP client of choice.

1. Generate an API key

In the dashboard, navigate to Settings → Integrations → API Keys.

Click Create new key. You'll be prompted for:

• Name — a label for the key (e.g. "Local development", "VendorX integration", "Internal agent"). Anything you'll recognise later.
• Description (optional) — free-text notes.
• Scopes — what this key is allowed to do. Pick only the scopes you need; defaults are minimal. See Scopes & permissions for the full catalogue. For this quick-start, select read:projects and read:rfis.
• Allowed projects (optional) — restrict the key to specific projects rather than the whole tenant.
• Rate limit (RPM / daily) — defaults are 60 requests per minute and 10,000 per day. Leave as-is for now.
• Expiry (optional) — when the key should stop working. Leave blank for a long-lived key.

Click Create. The plaintext key is shown once. Copy it. We never store the plaintext — only a SHA-256 hash — so if you lose it, you create a new one. The key looks like:

cai_sk_live_a1b2c3d4e5f6g7h8i9j0k1l2m3n4o5p6

2. Make your first authenticated call

The simplest test: list your projects.

curl -H "Authorization: Bearer cai_sk_live_..." \
     https://app.constructionai.io/api/construction-pm/projects

If everything's working you'll get a JSON response like:

{
  "success": true,
  "data": [
    {
      "id": "11111111-1111-1111-1111-111111111111",
      "name": "Manchester Office Refurbishment",
      "status": "active",
      "...": "..."
    }
  ]
}

If you see { "success": false, "error": "unauthorized" } — the key is invalid, expired, or revoked. Double-check you copied it correctly. The leading cai_sk_live_ prefix is part of the key, not a label.

If you see { "success": false, "error": "forbidden", "message": "API key lacks read scope" } — the key was created without read:projects. Edit the key in the dashboard or create a new one with the scope.

3. Query a specific project

Once you have a project ID from step 2:

curl -H "Authorization: Bearer cai_sk_live_..." \
     https://app.constructionai.io/api/construction-pm/projects/<projectId>

Returns the full canonical project object. The shape is documented in the Endpoint reference.

4. List RFIs on the project

curl -H "Authorization: Bearer cai_sk_live_..." \
     https://app.constructionai.io/api/construction-pm/projects/<projectId>/rfis

Same pattern — bearer token, RESTful URL, JSON response. Filtering, pagination, and search are supported via query parameters; see the Endpoint reference.

5. Discover what else is available

We publish a metadata endpoint that lists every module the API exposes, the current scope catalogue, and rate-limit defaults:

curl https://app.constructionai.io/api/construction-pm/agent-info

This endpoint requires no authentication. It's intended for agents and integrators to self-check the platform's advertised capabilities at startup.

Code samples in other languages

TypeScript (Node.js with native fetch):

const apiKey = process.env.CAI_API_KEY!;
const baseUrl = 'https://app.constructionai.io';
 
const response = await fetch(`${baseUrl}/api/construction-pm/projects`, {
  headers: { 'Authorization': `Bearer ${apiKey}` },
});
 
const { data: projects } = await response.json();
console.log(`Found ${projects.length} projects`);

Python (with requests):

import os
import requests
 
api_key = os.environ['CAI_API_KEY']
base_url = 'https://app.constructionai.io'
 
response = requests.get(
    f'{base_url}/api/construction-pm/projects',
    headers={'Authorization': f'Bearer {api_key}'},
)
 
projects = response.json()['data']
print(f'Found {len(projects)} projects')

Common gotchas

• cai_sk_live_ is part of the key, not a label. Don't strip it.
• Keys are shown once. If you lose the plaintext, create a new key. We only store hashes.
• Scopes default to minimal. A key without read:projects will get 403 on the projects endpoint, even if you're the tenant admin. Scope choices are deliberate.
• Rate limits return HTTP 429. When you hit a limit, the response includes a Retry-After header in seconds. Honour it.
• Tenant context is implicit. The token resolves to one tenant. You cannot read across tenants by changing a header — every request is scoped automatically.

What's next

Now that you have a working key:

• Explore the Overview to understand the broader architectural picture.
• Read Authentication for OAuth 2.1 (MCP clients), refresh semantics, and impersonation details.
• Read Scopes & permissions to pick the minimal scope set for your integration.
• Browse the full Endpoint reference — every route, every parameter, every response shape, rendered from the published OpenAPI 3.1 spec.

Need an endpoint that isn't documented? Contact us through the dashboard. All 178 read endpoints across the four core modules are live in the spec; write endpoints land iteratively as the vendor write surface hardens.