Org API v1 Reference

Overview

The Org API v1 is the enterprise API for the orchestra operating layer. It is scoped to one organization and uses your workspace slug in the path.

Base path:

/api/org/v1/{slug}

{slug} is your organization's workspace slug. Responses are JSON and return Cache-Control: no-store.

Authentication

Create an org API key in Settings -> API & webhooks. The secret is shown once, so store it securely.

Send it as a bearer token:

Authorization: Bearer abo_org_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx

A key is bound to one organization. Requesting another organization's slug with your key returns 404.

Response envelope

Success:

{ "success": true, "data": { "id": "..." } }

Error:

{
  "success": false,
  "error": {
    "message": "...",
    "code": "API_SCOPE_MISSING",
    "details": {}
  }
}

List endpoints wrap items in a page object:

{
  "success": true,
  "data": {
    "items": [],
    "page": 1,
    "limit": 50,
    "total": 120,
    "totalPages": 3
  }
}

Status codes

Scopes

Read endpoints

Write endpoints

The organization is always taken from your key. A foreign id in any write returns 404.

Webhooks

Register endpoints in Settings -> API & webhooks. Choose event types. A per-endpoint signing secret is shown once.

Each live attempt preserves the original Kalinklo signature and also carries the Standard Webhooks headers:

X-Kalinklo-Signature: sha256=<hex HMAC-SHA256 of the raw body using your signing secret>
webhook-id: <stable event id>
webhook-timestamp: <Unix attempt timestamp>
webhook-signature: v1,<base64 HMAC-SHA256>

The standard signature covers webhook-id.webhook-timestamp.raw-body. The event id remains stable across retries; the timestamp and signature are refreshed for each attempt. Verify the exact raw request bytes before parsing JSON. Existing receivers may keep verifying X-Kalinklo-Signature while migrating to a Standard Webhooks verifier.

Payload shape:

{
  "id": "evt_...",
  "type": "production.created",
  "createdAt": "2026-...",
  "data": {}
}

Event types:

• production.created
• production.updated
• service.updated
• member_request.created
• member_request.updated
• resource_booking.created
• resource_booking.cancelled
• tour.updated
• report.generated
• checklist_item.completed
• engagement.updated

Delivery status in v1

v1 records, signs (HMAC-SHA256), and delivers each webhook over outbound HTTPS. An egress worker runs every few minutes, retrying with backoff, recording each attempt's response status, and enforcing SSRF controls (private hosts blocked, DNS re-validated at connect time, redirects refused).

Each emitted event creates a signed delivery you can inspect in the delivery log, where every attempt shows its HTTP response status. The Send test button records a SIMULATED delivery without calling your endpoint — use it to preview the payload and signature. Real events are delivered live.

All currently emitted events:

• production.created
• production.updated
• service.updated
• resource_booking.created
• resource_booking.cancelled
• member_request.created
• member_request.updated
• tour.updated
• report.generated
• checklist_item.completed
• engagement.updated

Delivery is asynchronous and at-least-once. Deduplicate on the stable webhook-id or payload id, and return a successful status only after durably accepting the event.

Not included in v1

Org API v1 does not include dangerous writes such as deleting organizations or members, payroll mutation, contract signing, payments, real email sends, permission changes, API-key management through the API, OAuth2 app authorization, GraphQL, or engagement and financial API data.

Related docs

• Auth and Rate Limits
• Telemetry and Status
• Public Endpoints