Skip to main content
KalinkloOS
Developer documentation

Developer portal

Org API v1 Reference

Read and update the operations of one organization with a scoped bearer key. Each endpoint checks the key, organization and required permissions.

Open OpenAPI JSONDownload OpenAPI JSON

Connect one organization

Use /api/org/v1/{slug} with an organization API key from Settings → API & webhooks. Send Authorization: Bearer YOUR_ORG_API_KEY. The key, its scopes and the workspace's enabled capabilities determine access. Keep the key on your server. See authentication and rate limits before connecting.

Read endpoints

Paths below are relative to the base path. New keys default to org:read:operations and org:read:resources. Personnel and contacts require separate read scopes. /members omits email; /instruments omits serial numbers and insured values. Contact endpoints can return contact email and phone, so protect that data.

MethodPathRequired scope
GET/contacts/{id}org:read:contacts
GET/contactsorg:read:contacts
GET/instrumentsorg:read:resources
GET/membersorg:read:personnel
GET/performance-historyorg:read:operations
GET/productions/{id}org:read:operations
GET/productionsorg:read:operations
GET/reportsorg:read:operations
GET/resourcesorg:read:resources
GET/org:read:operations
GET/servicesorg:read:operations
GET/toursorg:read:operations
GET/worksorg:read:operations

Write endpoints

Writes require the corresponding opt-in scope. These are real changes to the organization. Contact PATCH takes the full contact representation; omitted optional fields become empty. Contact DELETE deletes the record. A resource booking reserves a resource, not an artist engagement. Checklist PATCH defaults done to true when omitted. Do not assume a general idempotency-key guarantee.

MethodPathRequired scope
DELETE/contacts/{id}org:write:contacts
PATCH/contacts/{id}org:write:contacts
POST/contactsorg:write:contacts
POST/member-requestsorg:write:requests
PATCH/productions/{id}/checklist/{itemId}org:write:checklist
POST/productions/{id}/checklistorg:write:checklist
PATCH/resource-bookings/{id}/cancelorg:write:bookings
POST/resource-bookingsorg:write:bookings

Body fields

EndpointJSON fields
POST /contacts; PATCH /contacts/{id}{ name, type, company?, email?, phone?, city?, country?, role?, notes?, tags? }
POST /resource-bookings{ resourceId, title, startAt, endAt, notes? }
POST /productions/{id}/checklist{ label }
PATCH /productions/{id}/checklist/{itemId}{ done?: boolean }
POST /member-requests{ membershipId, type, subject, body?, startDate?, endDate? }

Responses and pagination

Successful routes return 200 with { success: true, data: ... } and Cache-Control: no-store. The shape inside data depends on the operation. Paginated lists return the flat page shape below; page is bounded to 1–500 and limit to 1–100 (default 50). /reports instead returns { items, total }: scope-filtered metadata, no report rows or financial reports. Read models may cap their source records; do not treat these lists as an unlimited archive export.

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

Body-parser validation errors return 400; other validation can return 422. A missing scope returns 403, wrong-organization slugs or missing scoped records can return 404, and resource-booking conflicts return 409. Do not assume every invalid foreign identifier has the same status. Use telemetry and status for error handling.

Webhooks and signatures

Configure an HTTPS endpoint and event subscriptions in Settings → API & webhooks. The endpoint signing secret is shown once. Confirm your organization's delivery mode first: the legacy organization webhook channel described here and the secure integration channel do not share an assumed payload contract. The legacy envelope contains id, type, createdAt and data.

Legacy live requests carry X-Kalinklo-Signature (HMAC-SHA256 hex of the raw body) and Standard Webhooks headers webhook-id, webhook-timestamp, webhook-signature. The standard signature covers webhook-id.webhook-timestamp.raw-body. Verify the exact raw bytes, enforce timestamp freshness and deduplicate by event ID; retry timestamps and signatures change, the event ID stays stable.

Supported 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 and current boundaries

Emission is best effort. Live delivery depends on enabled policy, an active subscribed endpoint and the configured worker. Retries can duplicate events; the delivery log can show failures without an HTTP response. Inspect delivery evidence before relying on a connection. Send test records a SIMULATED delivery without calling the endpoint; it does not prove live delivery. Delivery timing and success are not guaranteed.

These routes do not provide organization/member deletion, payroll mutation, contract signing, payments, email sending, permission changes, API-key administration, OAuth2 or GraphQL. Contact deletion is explicitly supported above. The engagement.updated webhook does not expose a financial API. Return to all guides.

Org API v1 Reference · Developer Docs | Kalinklo