API for developers

This page gets you to a first successful call in about five minutes. The full reference lists every operation with its parameters, an example response and the errors it can return; the machine-readable form is at openapi.v1.json (OpenAPI 3.1, generated from the same code as these pages).

Requirements

The interface is part of the Team and Enterprise plans. A team admin or owner creates the first key under Team → Integrations & API in the app; that needs the team right schnittstellen (the owner has it by default and can grant it to others).

Quickstart

curl https://app.sip.coach/api/public/v1/me \
  -H "Authorization: Bearer sipk_live_ab12cd34_…"

import httpx

response = httpx.get(
    "https://app.sip.coach/api/public/v1/me",
    headers={"Authorization": "Bearer sipk_live_ab12cd34_…"},
)
print(response.json())

const res = await fetch("https://app.sip.coach/api/public/v1/me", {
  headers: { Authorization: "Bearer sipk_live_ab12cd34_…" },
});
console.log(await res.json());

<?php
$context = stream_context_create(["http" => ["header" =>
    "Authorization: Bearer sipk_live_ab12cd34_…"]]);
$response = file_get_contents("https://app.sip.coach/api/public/v1/me", false, $context);
echo $response;

{
  "tenant_id": "6a9c3e3e-9b8e-4b7b-9e9d-2b7b1a2c3d4e",
  "kind": "team",
  "scopes": [
    "users:read",
    "trainings:read",
    "evaluations:read"
  ],
  "rate_limit_per_min": 600,
  "privacy": {
    "member_detail_enabled": true
  }
}

Authentication

Every request carries the key in Authorization: Bearer sipk_live_<prefix>_<secret>. The key belongs to the team, not a person; its scopes are fixed when it is created (widening them means creating a new key). Revocation takes effect immediately; rotation lets the old and new key overlap for a chosen grace period.

The app also offers the templates "Read only" (every :read scope) and "Read and assignments" (adds assignments:write) when creating a key, or a custom selection from the table above.

Tenancy and rights

The tenant is fixed the moment the key is created — no call names a team, in the path or the body. A foreign id returns 404, exactly like one that never existed: from the outside, the two are indistinguishable.

Errors

Every error follows RFC 9457 (application/problem+json). code is stable and never localized; title follows Accept-Language (de or en).

{
  "type": "https://sip.coach/entwickler/api/fehler#insufficient_scope",
  "title": "Insufficient scope",
  "status": 403,
  "code": "insufficient_scope",
  "detail": "scope 'assignments:write' required",
  "request_id": "a7e8b2c1-4d3e-4f5a-9b6c-7d8e9f0a1b2c",
  "required_scope": "assignments:write"
}

Every code with an explanation: Error codes.

Rate limits and idempotency

120 requests per minute per key, plus a per-tenant limit your team can configure (default 600/minute) — whichever is tighter applies. Every response carries RateLimit-Limit, RateLimit-Remaining and RateLimit-Reset.

POST calls accept an Idempotency-Key header (up to 100 characters, valid 24 hours): the same key with the same body returns the first response again without repeating the action; the same key with a different body returns 422 idempotency_mismatch.

Pagination

List routes (e.g. GET /users, GET /assignments) accept ?limit= (default 50, maximum 200) and ?cursor=, and respond with a data field (the list) and next_cursor. next_cursor is an opaque value — do not interpret it as a page number or offset, just pass it back unchanged on the next call; null means there is no further page.

Versioning

Path version v1. Within v1, only additive changes (new fields, new routes, new webhook event types) — ignore unknown response fields. A breaking change ships as v2 alongside v1 for at least twelve months, announced via Deprecation/Sunset response headers and an email to every admin with an active key.

Privacy

The team's privacy switches apply to the API exactly as they do in the app. With member_detail_enabled off, routes with per-person data return only aggregates or 403 privacy_restricted, and webhook bodies carry neither a score nor a user_id.

CRM connections

A connected CRM system is set up in the app, under Team → CRM connections — not through this API. Once a connection is active, GET /crm/deals returns the synchronized deals and GET /crm/objections the team's objection catalog; both routes are read-only, paginated like any other list route.

Where to go next