Public API

The contract

The OpenAPI 3.0 document is served without a key and generated from the code that answers: it cannot describe anything other than what the API actually returns. This is what you hand to a client generator.

Open openapi.json

Getting started

Create a key from the dashboard, under Configuration. Its secret is shown once — copy it right away; Cadanse keeps only a fingerprint and cannot show it again.

Check it against the identity route, which requires no scope and returns your studio, your scopes and your remaining quota:

curl -H "Authorization: Bearer cad_..." \
  https://cadanse.app/api/v1/moi

Then read a collection. Every response carries “data” and “next”; feed “next” back as “apres” until it comes back null.

curl -H "Authorization: Bearer cad_..." \
  "https://cadanse.app/api/v1/familles?limite=100"

120 requests per minute and 20000 per day, per key. Going over returns 429 with a “Retry-After” header. The counter is closed by default: if it is unreachable, the request is refused rather than let through.

Pagination and filtering

The three parameters every collection accepts.

Collections

Each one requires the “<resource>:lecture” scope (for example “familles:lecture”; courses, camps, events and performances expose no family contact details). The listed fields are exhaustive: what is not there does not leave Cadanse.

Writing

Each write requires the “<resource>:ecriture” scope (for example “inscriptions:ecriture”), and recording a payment has its own “paiements:ecriture” scope, ticked separately. Each one goes through the same rule as the matching dashboard screen: an enrolment refused on screen is refused here, and the error code names the rule that refused it. The listed fields are the only ones accepted; an unknown field, or one the API does not read, returns 400.

The “Idempotency-Key” header is mandatory: a value of yours, unique per write. Retrying with the same key returns the original response for 24 hours, along with the “Idempotent-Replayed: true” header — that is what lets you retry without risking a second enrolment. The same key with a different body returns 409; a refused write, on the other hand, frees the key, so you can fix your payload and retry with the same one.

One creation, and the same call sent again:

curl -X POST -H "Authorization: Bearer cad_..." \
  -H "Idempotency-Key: 8f1c-..." \
  -H "Content-Type: application/json" \
  -d '{"lastName":"…","contactEmail":"…"}' \
  https://cadanse.app/api/v1/familles

Errors

Every error returns the same shape: “error.code” and “error.message”. The code is contractual; the message may be reworded.

Outgoing webhooks

The API is read and written at your initiative; webhooks come to you. A destination is set up from the dashboard, under Configuration: an HTTPS address, the subscribed events, and a signing secret shown once. Cadanse POSTs “application/json” there on every event.

Verifying the signature

Every request carries the “Cadanse-Signature” header, shaped “t=<milliseconds>,v1=<hex>”: “v1” is the HMAC-SHA256 of the text “<t>.<raw body>”, keyed with your secret. Verify the RAW body, before any deserialization. Check the signature FIRST and the timestamp second: rejecting on age before proving authenticity tells whoever is writing to you which clock you accept. Past 5 minutes, refuse — that is what stops a body captured once from being replayed at your end. The “Cadanse-Event” header names the event, so you can route without reading the body.

Cadanse-Signature: t=1776171600000,v1=<hex>
Cadanse-Event: inscription.creee

The envelope

Always the same shape: “id”, “type”, “createdAt”, “studioId” and “data”. “id” is the DELIVERY's, not the object's: retries of one delivery repeat it — that is what lets you deduplicate — and a manually replayed delivery carries a new one. “createdAt” is the moment of the event; no payload carries a second timestamp. The fields of “data” are identifiers: full records are read from the collections above.

Retries

A 2xx response closes the delivery. Otherwise 3 retries, at 1 h, 6 h, 24 h, then nothing: an event delivered three days late informs nobody. The whole window is 48 h. Answer quickly — a call is abandoned past 2 seconds — and do your work after answering. The dashboard shows every delivery, its response code and your server's error message; an exhausted delivery can be replayed by hand from there.

The events

Subscribing to an event that sends nothing yet is allowed, and the right-hand column says so: it is the real state, read from the code that emits.

Connectors

Zapier, Make and assistants that speak MCP plug into everything above, and into nothing else: the same key, the same scopes, the same quota, the same log. A connector does not open one more door — it walks through a door you already opened, and the key can be revoked from the dashboard.

Zapier and Make

Nothing to install: create an “API key” connection with the “Authorization” header and, as its value, “Bearer” followed by your key. Test it against https://cadanse.app/api/v1/moi — that route answers whatever the key's scopes are, and returns the studio name and the list of what the key allows.

Your triggers are the webhooks above. Both Zapier and Make hand you a listening URL: paste it into the dashboard and tick the events you want. Neither verifies the signature for you — have a code step verify it before acting on a payload, using the recipe given above.

Your actions are the writes above, called from an “HTTP request” step. Always fill in “Idempotency-Key”: otherwise a scenario the platform replays after an outage would create the same record twice.

MCP server

An assistant that speaks MCP connects to https://cadanse.app/api/v1/mcp — HTTP transport, POST requests, the same “Authorization” header. Your studio decides: connecting an assistant sends data out to a tool you choose, under a key you create and can revoke.

{
  "mcpServers": {
    "cadanse": {
      "type": "http",
      "url": "https://cadanse.app/api/v1/mcp",
      "headers": {
        "Authorization": "Bearer cad_..."
      }
    }
  }
}

The server exposes 9 read tools and 5 write tools — exactly the collections and writes documented above, and no others. A tool is named after its operation, in lowercase with underscores:

lister_familles, lister_eleves, lister_cours, lister_inscriptions, lister_presences, lister_paiements, lister_evenements, lister_camps, lister_representations, creer_famille, creer_eleve, creer_inscription, marquer_presence, creer_paiement

The catalogue depends on the key: “tools/list” returns only the tools its scopes cover. A tool outside those scopes does not exist for that key — calling it answers “unknown tool”, which avoids teaching a prober which scopes exist.

JSON-RPC batches are refused: one call is one request, and one request is one unit of quota. Reads made over MCP are logged like the others — one window per key, per collection, per day — in the same log the studio can read back.

Write tools act immediately, and what they write is visible to staff and families. Each accepts an optional “cleIdempotence” argument: without it, two identical calls make two writes — deliberately, since two cash payments of the same amount on the same Saturday are two payments. The audit log records every write, whether it came from an assistant or from an HTTP call.

Why this page cannot lie

It is rendered from the same document as openapi.json, which is itself generated from the serializers that write the responses. A field removed from the code disappears from here with nobody thinking about it; a documented field that is not served cannot be written.