Developers

Integration API

For developers: what your code can do with a connection token, and where the full contract is.

The integration API lets your own code, or another app such as Max, work with Chaos through a connection. Each connection has its own token, permissions and list of items.

What it can do

• List the forms and quizzes the connection can reach, with their titles and status, and read their questions.
• Create drafts and update drafts. You review and publish them in Chaos.
• Read privacy-safe summaries: counts only, hidden until at least 5 people have responded.
• Create and manage its own webhooks, which never include answers.

What it cannot do

• Publish, close or delete anything.
• Read individual responses, answer text, names, emails or files.
• Add file upload questions, logic, translations or endings. Updating a draft keeps the ones it already has.

Calling the API

• Create a connection under Connections and copy its token. The page shows the API address to call.
• Send the token as Authorization: Bearer <token> on every request. Bodies are JSON.
• Requests that change something need an Idempotency-Key header, so a retry never creates a second draft.
• Each connection has a request limit per minute. The response headers say how much is left.

The full contract, with every endpoint, error code and versioning rule, is in the integration API document, version 1.