Skip to main content
KalinkloOS
Developer portal

Developer docs

Org API v1 Reference

Organization-scoped REST endpoints, scopes, webhook signing, and current v1 limits.

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

StatusMeaning
401Missing, malformed, invalid, or revoked key
403Key lacks the endpoint's scope
404Slug is not this key's org, or the resource is not in this org
409Resource-booking time conflict
422Validation error
429Rate limit exceeded per key

Scopes

ScopeGrants
org:read:operationsProductions, services, works, performance history, tours, reports metadata, org info
org:read:personnelPersonnel roster names, role, and section. Emails are not exposed.
org:read:resourcesResources, rooms, and instrument inventory. Serials and insured values are not exposed.
org:write:contactsCreate and update address-book contacts
org:write:bookingsCreate and cancel resource bookings
org:write:checklistCreate and complete production checklist items
org:write:requestsCreate member requests

Read endpoints

MethodPathScopeNotes
GET/org:read:operationsOrganization info
GET/productionsorg:read:operationsSupports status, q, page, and limit
GET/productions/{id}org:read:operationsIncludes its services
GET/servicesorg:read:operationsSupports productionId, from, to, page, and limit
GET/worksorg:read:operationsRepertoire
GET/membersorg:read:personnelSupports q, page, and limit; no emails
GET/resourcesorg:read:resourcesRooms and resources
GET/instrumentsorg:read:resourcesNo serials or insured values
GET/toursorg:read:operationsTours
GET/reportsorg:read:operationsReport metadata only; no row data
GET/performance-historyorg:read:operationsSupports search, composer, conductor, from, and to

Write endpoints

MethodPathScopeBody
POST/contactsorg:write:contacts{ name, type, company?, email?, phone?, city?, country?, role?, notes?, tags? }
PATCH/contacts/{id}org:write:contactsFull contact representation
POST/resource-bookingsorg:write:bookings{ resourceId, title, startAt, endAt, notes? }
PATCH/resource-bookings/{id}/cancelorg:write:bookingsNo body required
POST/productions/{id}/checklistorg:write:checklist{ label }
PATCH/productions/{id}/checklist/{itemId}org:write:checklist{ done?: boolean }
POST/member-requestsorg:write:requests{ membershipId, type, subject, body?, startDate?, endDate? }

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.

Payloads carry this signature header:

X-Kalinklo-Signature: sha256=<hex HMAC-SHA256 of the raw body using your signing secret>

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 and signs webhook deliveries. It does not make live outbound HTTP calls to your URL yet.

Each emitted event creates a signed delivery with status PENDING that you can inspect in the delivery log. The Send test button records a SIMULATED delivery. Live outbound delivery with retries and egress controls is a future step, so do not depend on receiving live HTTP callbacks in v1.

Currently emitted events:

  • production.created
  • production.updated
  • resource_booking.created
  • resource_booking.cancelled
  • member_request.created
  • checklist_item.completed

Reserved event types can be subscribed to, but their emit points are not all wired yet. The settings UI marks reserved events.

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, live webhook delivery, OAuth2 app authorization, GraphQL, or engagement and financial data.

Related docs