Have you activated the API and created your key? Head over to How to use the Kraaft API to get started ⚡
This article gathers the subtleties you only discover by testing the API in depth — keep it handy if your Make scenario gets stuck, if a field looks odd, or if you can’t find a conversation created via the API 🕵️
📦 The API resources, in detail
🗂️ Workspaces — lists the workspaces accessible with your key
📋 Schemas — gives you the structure of a report (the fields, and for choice fields, the mapping between each
idand its label)📝 Records — lists, reads, creates and updates the reports of a given schema
💬 Conversations (Rooms) — reads, creates and updates a conversation, manages its members, and sends messages (text and files)
⚡ Events — lists past events or stays connected to receive them in real time, as soon as a report changes
🤖 Connecting to Make, n8n or Zapier
✅ Make — install the Kraaft app directly from make.kraaft.co: authentication happens via OAuth, in one click, no need to copy an API key by hand anymore
🔧 n8n, Zapier and others — no native Kraaft connector yet: use your tool’s HTTP or API request module, with your Kraaft API key as a Bearer token
🔒 The 4 key roles, what they actually do
Every API key has a role, just like a regular Kraaft user: External, Standard, Administrator, Owner 👤 But their real behavior has a few surprises ⬇️
🚫 External — cannot create a conversation (missing "Room.create" error). It can only act (send a message, create a report) in conversations it’s already a member of
⚠️ Standard — can create a conversation, BUT is not automatically added as a member! Remember to call the endpoint that adds a member to the conversation right after — with an Admin/Owner key, or another key that’s already a member, otherwise the Standard key stays locked out of reading or writing to the conversation it just created
✅ Administrator & Owner — full access to the workspace, without needing to be a member of a conversation: they see and edit every non-private conversation, even ones they just created
💡 The right move if you’re stuck: if your Make scenario with a Standard key "sees nothing" or "breaks right after creating a conversation", it’s very likely this conversation-membership trap — not a bug. Two options: use an Admin/Owner key for that scenario, or have your key added as a member by someone who already has access to the conversation.
🆔 Resolving an ID into a label
Choice fields (status, categories…) and user fields don’t return the label shown in the app — only a technical identifier 🔢
✅ For a choice field: fetch the report’s schema (
GET Schema) — each option lists itsidandlabel, you just need to match them up❌ For a user: no automatic API solution — there’s no endpoint that returns a user’s name or email from their ID. Ask our support for an export of your workspace’s IDs to match them up
🧩 Understanding list and table fields via the API
For a report with simple fields (text, number, checkbox, date, choice, photo), the schema gives you all the data directly. For list and table fields — common in reports (timesheets, materials, inspections) — the structure is more complex 🧩
Example: a weekly timesheet. In the app, the "Weekly timesheet" field shows one section per day (Monday, Tuesday…) with several fields each. Through the API, this same field returns:
"weekly_timesheet": { "type": "multiple", "ofType": "recordId", "value": ["id_monday", "id_tuesday", "id_wednesday", ...] }In short: the API works well for simple fields, but not yet in detail for list and table fields — the precise content of each row isn’t directly accessible.
⚡ Filtering and real time: what exists
Two advanced capabilities exist and are worth knowing about, without going into detail here (the developers.kraaft.co docs cover all of it):
🔍 Server-side filtering — report and event lists accept a filter parameter (for example: only reports whose status changed) instead of fetching everything and sorting it yourself
📡 Real-time events — besides polling the API at regular intervals, you can stay connected and receive every change as it happens (handy for a reactive integration, e.g. notifying an ERP in under a second)
🚫 What’s still not possible today
⚠️ Not yet possible via the API
🗑️ Deleting a report or a conversation — only archiving a conversation is possible, not deletion
👤 Automatically retrieving the name or email of a user from their ID — ask our support for an export if you need it (see above)