KairoProject Public API

The KairoProject public API lets your external tools and systems interact directly with your project management data: portfolios, projects, tasks, and resources. This guide covers authentication, available endpoints, outbound webhooks, and integration best practices.

Conceptual model

The API strictly follows KairoProject's data hierarchy:

Organisation
├── API Clients           ← your integrations (credentials)
├── Members               ← org users
├── Webhooks              ← event delivery endpoints
└── Portfolio
      ├── Resource         ← shared across all portfolio projects
      ├── Team             ← group of resources, shared
      └── Project
            ├── Root Task      ← structural task (cannot be deleted)
            ├── Task ...       ← your operational tasks
            └── Finish Task    ← structural task (cannot be deleted)

Key points:

• All data is strictly isolated per organisation — a token can never access another organisation's data.
• Resources and teams live at portfolio level, shared across all projects.
• Each project has two structural tasks (root, finish) that cannot be deleted via the API.
• The CCPM recompute (critical chain, buffer) is triggered via POST /projects/{projectId}/recompute?portfolioId=... and returns a synchronous response.

Base URL

https://kairoproject.app/api/public/v1

All dates are ISO 8601 UTC (2026-05-17T10:00:00.000Z).

Authentication

The API uses the OAuth 2.0 client_credentials flow. Each organization can create API clients from the admin console.

Create an API client

An owner or admin creates an API client from the console. On creation, a clientId and a clientSecret are generated — the secret is only shown once.

Each API client holds:

• a name displayed in the console;
• scopes defining the granted permissions;
• a status (active or revoked);
• a token lifetime (tokenTTLSeconds, default 3,600 seconds).

Obtain an access token

POST /api/public/oauth/token

Request body:

{
  "client_id": "org_acme-api-1234",
  "client_secret": "kairo_sk_live_...",
  "scope": "projects.read tasks.write"
}

Response:

{
  "access_token": "eyJhbGciOiJIUzI1NiJ9...",
  "token_type": "Bearer",
  "expires_in": 3600,
  "scope": "projects.read tasks.write"
}

Use the token in all subsequent requests:

Authorization: Bearer <access_token>

Available scopes

Rotation and revocation

• Rotation: create a new secret from the console. The new secret becomes active immediately and the previous secret is disabled during rotation.
• Revocation: revoke the client from the organisation console (API section). New token requests are rejected immediately, and existing tokens may also be invalidated as soon as revocation occurs.

Rate limiting

Each authenticated request is counted in a sliding window per API client. Limits vary based on the most restrictive scope in the request.

Every successful response includes the following headers:

X-RateLimit-Limit: 60
X-RateLimit-Remaining: 47
X-RateLimit-Reset: 1747476120

When the limit is exceeded, the API returns 429 with a uniform JSON body in the form { "error": "..." }. Depending on the endpoint, retry timing information may also be exposed in headers.

Available endpoints

All endpoints are prefixed with /api/public/v1 and require a valid Bearer token. portfolioId is always required as a query param for portfolio sub-resources.

Legend: ✅ Idempotent (repeating the request produces the same result) — ❌ Creates a duplicate

Portfolios

Patchable fields: name, description, aiAssistEnabled.

Projects

Tasks

Updating ettcHours (Estimated Time to Complete — remaining hours) is the progress-reporting mechanism. The root and finish tasks cannot be deleted (returns 422).

Resources and teams

Resources and teams are stored at portfolio level. The projectId in the URL is used solely to trigger a planning recompute for the affected project after a mutation.

Organization and members

POST /members supports two modes: with uid (adds an existing user, returns 200) or with email without uid (creates an invitation, returns 201).

Pagination

Lists use a cursor-based pagination system.

• pageSize: number of items per page (default 25, max 100).
• pageToken: cursor returned as nextPageToken by the previous response.

async function fetchAllProjects(token: string, portfolioId: string) {
  const projects = [];
  let pageToken: string | null = null;
  do {
    const url = new URL("https://kairoproject.app/api/public/v1/projects");
    url.searchParams.set("portfolioId", portfolioId);
    url.searchParams.set("pageSize", "100");
    if (pageToken) url.searchParams.set("pageToken", pageToken);
    const res = await fetch(url, { headers: { Authorization: `Bearer ${token}` } });
    const data = await res.json();
    projects.push(...data.items);
    pageToken = data.nextPageToken;
  } while (pageToken);
  return projects;
}

Outbound webhooks

KairoProject can notify your systems in real time via HTTP webhooks.

Configure a webhook

POST /api/public/v1/webhooks

Required scope: webhooks.manage.

Each webhook associates:

• an HTTPS destination URL;
• a list of events to subscribe to;
• an automatically generated signing secret.

Available events

Verify the signature

Each delivery includes the header:

X-Kairo-Signature: t=<unix>,v1=<digest>

The digest is computed as: HMAC-SHA256(secret, "${t}.${body}").

import { createHmac, timingSafeEqual } from "node:crypto";

function verifyKairoSignature(
  signingSecret: string,
  signatureHeader: string,
  rawBody: string
): boolean {
  const match = signatureHeader.match(/t=([^,]+),v1=([a-f0-9]+)/);
  if (!match) return false;
  const [, timestamp, signature] = match;
  const payload = `${timestamp}.${rawBody}`;
  const expected = createHmac("sha256", signingSecret).update(payload).digest("hex");
  return timingSafeEqual(Buffer.from(expected, "hex"), Buffer.from(signature, "hex"));
}

Discard deliveries with a timestamp older than 5 minutes to protect against replay attacks.

Rotate the webhook secret

Use POST /api/public/v1/webhooks/{id}/rotate-secret to renew the signing secret for a webhook. The old value is revoked as soon as rotation occurs.

Error codes

All errors return a uniform JSON body: { "error": "Explicit description of the problem." }