API

Kanera's public API lets you build integrations around the same work your team manages in the app: workspaces, boards, cards, lists, comments, checklists, notes, attachments, labels, custom fields, assigned work, activity, and external links.

Use the API when Kanera needs to connect to another system, power an internal workflow, migrate data, build reports, or let another tool create and update Kanera work.

What you can build

Common API use cases include:

• Sync Kanera cards with another work tracker.
• Create cards from forms, support tickets, chat messages, or CRM records.
• Build custom reporting dashboards from boards, assigned work, labels, custom fields, and activity.
• Import work into Kanera from another system.
• Keep external records linked to Kanera cards or notes.
• Add comments or status updates from another tool.
• Upload and attach files to cards or notes.
• Read activity history for audit, reporting, or automation.

Kanera is workspace-first, so integrations should be designed around the workspace. Lists, labels, and custom fields are shared across boards in the workspace, which makes cross-board reporting and sync workflows much easier to keep consistent.

API reference

The public API service includes the endpoint-level reference:

Path	Use
/docs	Interactive Scalar API reference.
/swagger	Swagger UI reference.
/openapi.json	OpenAPI document for SDK generation and tooling.

For self-hosted installs, open those paths on your public API service. For example:

https://api.example.com/docs
https://api.example.com/swagger
https://api.example.com/openapi.json

Use this page as the getting-started guide, then use the API reference for exact endpoint paths, request bodies, response schemas, and available webhook event types.

Create an API key

1. Open the workspace.
2. Go to Workspace settings -> API.
3. Create a workspace API key.
4. Choose the smallest scope that fits the integration.
5. Copy the secret when it is shown.

API keys are workspace-scoped. A key can only access resources in the workspace where it was created and where it still has access.

The secret is shown once. Store it in your integration's secret manager or environment variables.

API key scopes

Scope	Use it when
Read	The integration only needs to read, search, report, or export Kanera data.
Write	The integration needs to create or update work, such as cards, comments, labels, assignees, custom field values, notes, or attachments.
Admin	The integration needs admin-level public API operations where supported. Use this sparingly.

Use separate API keys for separate integrations. This makes access easier to revoke, rotate, and audit.

Authentication

Send the API key as a bearer token:

curl "$KANERA_PUBLIC_API_URL/api/v1/workspaces" \
  -H "Authorization: Bearer kanera_live_..."

Kanera API keys use prefixes for the environment:

Prefix	Environment
kanera_live_...	Production
kanera_stg_...	Staging
kanera_dev_...	Development
kanera_test_...	Test

Missing or invalid keys return 401. Valid keys without permission for a resource or operation return 403.

Base URL and versioning

REST endpoints live under /api/v1 on the public API service.

For example:

https://api.example.com/api/v1/workspaces

Operational helper paths such as /docs, /swagger, /openapi.json, signed media URLs, and webhook event discovery may live outside the /api/v1 prefix. Treat signed media URLs returned by the API as opaque URLs and use them as provided.

First requests

Start by listing workspaces the API key can access:

curl "$KANERA_PUBLIC_API_URL/api/v1/workspaces" \
  -H "Authorization: Bearer $KANERA_API_KEY"

Then list boards in a workspace:

curl "$KANERA_PUBLIC_API_URL/api/v1/workspaces/$WORKSPACE_ID/boards" \
  -H "Authorization: Bearer $KANERA_API_KEY"

Open a board to get the board, workspace lists, visible cards, members, labels, and custom fields needed to render or sync work:

curl "$KANERA_PUBLIC_API_URL/api/v1/boards/$BOARD_ID/open" \
  -X POST \
  -H "Authorization: Bearer $KANERA_API_KEY"

Create a card:

curl "$KANERA_PUBLIC_API_URL/api/v1/boards/$BOARD_ID/lists/$LIST_ID/cards" \
  -X POST \
  -H "Authorization: Bearer $KANERA_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"title":"Follow up with Acme"}'

Update a card:

curl "$KANERA_PUBLIC_API_URL/api/v1/cards/$CARD_ID" \
  -X PATCH \
  -H "Authorization: Bearer $KANERA_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"description":"Imported from CRM"}'

Workspace model

Kanera's API follows Kanera's workspace model:

• Workspaces contain boards.
• Boards contain cards.
• Lists are shared across every board in a workspace.
• Labels are shared across every board in a workspace.
• Custom fields are shared across every board in a workspace.
• Assigned Work can return cards assigned across boards in the workspace.
• Private boards are only visible where the API key has access.

This is important when building integrations. For example, a sync job should not create a separate "In Progress" list per board unless that is genuinely part of the workspace process. In most cases, it should use the existing workspace list so reporting, Assigned Work, and custom field aggregation stay consistent.

Pagination and errors

List endpoints that support pagination use:

Parameter	Meaning
limit	Number of records to return.
before	Cursor-style filter for records before a timestamp.

Errors return JSON with:

Field	Meaning
code	Stable error code.
message	Human-readable error message.
issues	Optional validation details.

Use the HTTP status code and error code together when deciding whether to retry, fix input, or ask an admin to update access.

Webhooks

Webhooks let external systems react when work changes in Kanera.

Use webhooks when another system should know about changes without polling the API constantly. Common examples include:

• Send important card activity to chat.
• Update an external dashboard.
• Sync changed cards to another system.
• Trigger deployment or review workflows.
• Record Kanera activity in an audit system.

Create webhook endpoints from Workspace settings -> API.

Each webhook destination can receive all events or only selected event types. Use the API reference and webhook event type discovery endpoint to see the available event names for your Kanera version.

Webhook delivery

Kanera sends webhook deliveries as JSON and includes headers you can use to verify the request:

Header	Meaning
X-Kanera-Event-Id	Unique event id.
X-Kanera-Timestamp	Unix timestamp in seconds.
X-Kanera-Signature	sha256= plus an HMAC-SHA256 signature.

The signature is calculated over:

${timestamp}.${rawBody}

using the webhook endpoint secret.

Webhook deliveries are retried when the endpoint returns a non-2xx status or cannot be reached. Kanera records delivery history so you can review failures, retry deliveries, pause destinations, and rotate secrets from the workspace API settings.

Verify webhook signatures

Verify the signature before trusting the payload:

import crypto from "node:crypto";
import express from "express";

const app = express();

app.post("/kanera/webhook", express.raw({ type: "application/json" }), (req, res) => {
  const timestamp = req.header("X-Kanera-Timestamp") ?? "";
  const signature = req.header("X-Kanera-Signature") ?? "";
  const expected = "sha256=" + crypto
    .createHmac("sha256", process.env.KANERA_WEBHOOK_SECRET!)
    .update(`${timestamp}.${req.body.toString("utf8")}`)
    .digest("hex");

  if (!crypto.timingSafeEqual(Buffer.from(signature), Buffer.from(expected))) {
    return res.status(401).send("invalid signature");
  }

  const event = JSON.parse(req.body.toString("utf8"));
  // Handle event.type, event.workspaceId, event.boardId, event.cardId, and event.data.
  res.sendStatus(204);
});

Always verify against the raw request body. If your framework parses JSON before verification, the signature check may fail or become unreliable.

External links

External links let integrations store durable mappings between Kanera records and records in another system.

Use external links when you need sync jobs to be idempotent. For example, a Trello sync can remember which Kanera card maps to which Trello card without putting hidden integration metadata in the card description.

Security recommendations

• Use one API key per integration.
• Use the lowest scope that works.
• Store keys and webhook secrets in a secret manager.
• Rotate keys and webhook secrets when people leave or systems change.
• Do not put API keys in cards, comments, notes, source control, logs, or screenshots.
• Verify webhook signatures before processing payloads.
• Make webhook handlers idempotent because deliveries may be retried.
• Log enough request and event ids to debug sync behavior without logging secrets.

Related pages

• AI MCP
• Automations
• Assigned Work
• Custom Fields