KairoProject Public API

The KairoProject public API lets your external tools and systems interact directly with your project management data: portfolios, projects, tasks, resources, logged time, and more. 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.

Public API URL

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

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

Authentication

The API offers two OAuth 2.0 flows depending on your integration context: client_credentials for a server-to-server integration (your ERP holds the secret directly), and authorization_code + PKCE for an agent that needs an end user's explicit consent without ever seeing their password. 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, never exceeded regardless of configuration).

Server-to-server authentication (client_credentials)

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>

User-consent authentication (authorization_code + PKCE)

Use this flow when an agent (Claude.ai, ChatGPT) needs to act on behalf of a specific user, with their explicit consent, without ever holding their password.

1. Discovery — the agent reads the available endpoints:

   curl https://app.kairoproject.com/.well-known/oauth-authorization-server
   

2. Generate the PKCE pair (a random code_verifier, and code_challenge = SHA-256 encoded as base64url):

   import { randomBytes, createHash } from "node:crypto";
   
   const codeVerifier = randomBytes(32).toString("base64url");
   const codeChallenge = createHash("sha256").update(codeVerifier).digest("base64url");
   

3. Open the browser to the consent screen:

   https://app.kairoproject.com/api/public/oauth/authorize
     ?response_type=code
     &client_id=org_demo-api-1234
     &redirect_uri=https://integrator.example.com/callback
     &code_challenge=<codeChallenge>
     &code_challenge_method=S256
     &scope=portfolios.read+tasks.write
     &state=<random-anti-csrf-value>
   

4. The user signs in, reviews the requested permissions, and clicks Authorize. KairoProject redirects to redirect_uri?code=<code>&state=<state> (the code expires after 10 minutes).
5. Exchange the code for a token, using the code_verifier generated in step 2:

   curl -X POST https://app.kairoproject.com/api/public/oauth/token \
     -H "Content-Type: application/json" \
     -d '{
       "grant_type": "authorization_code",
       "client_id": "org_demo-api-1234",
       "client_secret": "kairo_sk_...",
       "code": "<code>",
       "redirect_uri": "https://integrator.example.com/callback",
       "code_verifier": "<codeVerifier>"
     }'
   

   Response identical to the client_credentials flow, plus a refresh_token if the offline_access scope was requested.

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). Access is cut immediately: every request re-checks the client's status, including for a token issued before revocation. There is no delay to wait out — a compromised token stops working as soon as the client is revoked, without waiting for its natural expiry. After a reactivation, tokens issued before the revocation remain rejected; only those issued after the reactivation are valid.

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, domainId (must reference an existing domain from the Domains & Phases library, see below — 404 otherwise).

Portfolio CCPM priority decision and strategic resource assessment (the constraint, in Theory of Constraints terms) — computed on demand on every call, never cached. Indicates which project to protect first and which resource, if given more capacity, would improve the whole portfolio the most. Only covers released: true projects.

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 (an equivalent /portfolios/:id/resources[...] and /portfolios/:id/teams[...] path exists and operates on the same collection, without triggering a recompute). The projectId in the URL is used solely to trigger a planning recompute for the affected project after a mutation.

load-timeline returns a resource's weekly load curve (planned hours vs. capacity) — indicative only: it doesn't distinguish tasks co-assigned to multiple resources, nor team-based assignments.

Domains & Phases

Shared reference data (independent of any specific portfolio) used to categorize tasks by phase and color the Gantt chart.

PATCH /domains/:id replaces name and/or the entire phases array — not a merge. To add/update/remove a single phase without resubmitting the others, prefer the dedicated .../phases[/:phaseId] endpoints. DELETE /domains/:id is refused (400) if a portfolio still references this domain. A phase's color must belong to the allowed palette (18 predefined colors).

Clients

A client is a billable third party (account-level, never nested under a portfolio) — typically the name/ERP code of a project's end client.

PATCH always overwrites any existing attachment (the ERP is the source of truth). If clientId doesn't match any existing client, a new one is automatically created rather than rejected.

Project import

Creates a complete project (tasks, resources, teams, calendars) in a single call from a kairo-project-export object — for migrating from a third-party tool (Jira, MS Project, Asana, Excel) or generating a project from a spec document. Re-importing with the same project externalId updates the same resource instead of creating a duplicate.

Timesheet

Log of hours worked, for reporting and cost calculation. Two origins: source: "auto" (auto-generated whenever PATCH .../tasks/:taskId changes ettcHours) and source: "manual". Creating or correcting an entry does not modify ettcHours on the associated task and doesn't trigger any planning recompute.

.../adjustments corrects an entry that's already exported (locked) without ever rewriting the original — an accounting credit-note pattern. Fails with 400 if the referenced entry isn't exported yet (use a normal PATCH instead). durationHours is signed (negative to subtract, positive to add).

Qualified delay causes (buffer)

Log of qualified delay causes — each event corresponds to a CCPM buffer consumption attributed to a specific cause (source data for the delay-cause Pareto chart). categoryId: null declassifies the event as "Uncategorized." Renaming or deleting a category never affects categoryNameSnapshot on already-qualified events — the Pareto history stays stable over time.

Cost

Computed from timesheet entries (durationHours × hourlyRate) — never persisted, recomputed on every call. If no resource has a hourlyRate set, cost fields are null rather than 0, to distinguish "no rate configured" from "zero cost."

PERT presets and delay risk (ML)

PERT presets (optimistic/median/pessimistic speeds) convert a quantity of work into hours before an import or task creation. /risk returns a delay probability predicted by an ML model trained on the organization's history (horizonDays, default 7, bounded between 7 and 21); source: "fallback" means no trained model is available for this scope.

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://app.kairoproject.com/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.

OpenAPI and SDK generation

The API's full technical contract is available as an OpenAPI 3.1 spec. Two main uses:

• Publish the spec to your teams or integration partners.
• Generate a typed SDK instead of writing HTTP calls by hand:

  npx openapi-typescript docs/api/public-api-openapi.yaml --output sdk/public-api.ts
  

  The generated file exposes types (Portfolio, Resource, Member, etc.) and can be published as an internal package.

For other languages, openapi-generator-cli can start from the same spec:

openapi-generator-cli generate -i docs/api/public-api-openapi.yaml -g go

Error codes

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