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.

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": "org123_api_acme",
  "client_secret": "kairo_sk_live_...",
  "scope": "portfolios.read projects.write"
}

Response:

{
  "access_token": "<jwt>",
  "token_type": "Bearer",
  "expires_in": 3600
}

Use the token in all subsequent requests:

Authorization: Bearer <access_token>

Rotation and revocation

• Rotation: create a new secret from the console. The previous secret remains active during a transition window.
• Revocation: set the client to status=revoked. All new token requests are immediately rejected. Tokens already issued are invalidated via a revokedAt check on the backend.

---

Available endpoints

All endpoints are prefixed with /api/public/v1 and require a valid Bearer token.

Portfolios

Method	Route	Description	Required scope
GET	/portfolios	Paginated list of portfolios	portfolios.read
POST	/portfolios	Create a portfolio	portfolios.write
GET	/portfolios/{portfolioId}	Portfolio details	portfolios.read

Projects

Method	Route	Description	Required scope
GET	/projects	List/filter projects	projects.read
POST	/projects	Create a project	projects.write
PATCH	/projects/{projectId}	Update project metadata	projects.write
POST	/projects/{projectId}:recompute	Trigger planning recompute	planning.trigger

Tasks and resources

Method	Route	Description	Required scope
GET / POST / PATCH	/projects/{projectId}/tasks	Task management	tasks.read / tasks.write
GET / POST / PATCH / DELETE	/projects/{projectId}/resources	Resource management	resources.read / resources.write

Organization and members

Method	Route	Description	Required scope
GET	/organization	Plan info, seats, status	organization.read
GET / POST / PATCH	/members	List, invite, deactivate members	members.manage

---

Pagination and filtering

Lists use a cursor-based pagination system.

• pageSize: number of items per page (between 1 and 100).
• pageToken: next-page cursor (base64-encoded), returned as nextPageToken.

Projects support additional filters: portfolioId, status, updatedAfter.

---

Idempotency

For sensitive creation operations (e.g. importing projects), add an Idempotency-Key header to your request. If the same key is sent more than once, the response from the first request is returned without creating a duplicate.

---

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

Event	Description
planning.recompute.completed	Planning recompute finished. Includes bufferConsumption, progress, status.
planning.buffer_overflow	Buffer exceeds the critical threshold (1.0). Includes threshold and exceededAt.

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}").

Always verify this signature server-side to authenticate the origin of the event.

Rotate the webhook secret

Use POST /api/public/v1/webhooks/{id}/rotate-secret to renew the signing secret for a webhook.

---

Available scopes

Scope	Access granted
portfolios.read	Read portfolios
portfolios.write	Create and update portfolios
projects.read	Read projects
projects.write	Create and update projects
tasks.read	Read tasks
tasks.write	Create and update tasks
resources.read	Read resources
resources.write	Manage resources
planning.trigger	Trigger planning recompute
organization.read	Read organization information
members.manage	Manage members
webhooks.manage	Manage webhooks

---