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 (coming soon) 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 (coming soon).

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 the Authentication page (coming soon) if you need OAuth 2.1 for an MCP client or fine-grained scope details.
• Read the Endpoint reference (coming soon) for the full surface — every route, every parameter, every response shape.

Need an endpoint that isn't documented yet? Contact us through the dashboard. Most of the platform's 175+ routes are vendor-accessible today; the docs catch up week by week.