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, assignments, 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, assignments, 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 integrations can target standalone boards or workspaces. A standalone board has its own lists, labels, and custom fields. A workspace shares those resources across its boards, which makes cross-board reporting and sync workflows easier to keep consistent.

API reference

Kanera REST API is at:

https://api.kanera.app

Detailed endpoint-level reference is available at:

https://api.kanera.app/docs

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 Kanera, open:

https://api.kanera.app/docs
https://api.kanera.app/swagger
https://api.kanera.app/openapi.json

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.

Choose an API key type

Kanera has two API key types. They authenticate the same way, but their access model is different.

Key type	Create it from	Use it when	Access model
Personal API key	Profile settings -> API keys	You are connecting your own script, CLI, or MCP client and want it to work across the boards you can personally access.	Acts as you. It can read and edit board content across every workspace and board you can access, respecting your role on each board. It cannot perform workspace-admin actions.
Workspace or board API key	Workspace settings -> API or Board settings -> API	You are setting up a team integration, service account, webhook producer, sync job, or automation for one workspace or standalone board.	Scoped to that workspace or standalone board. Its Read, Write, or Admin scope controls what the integration can do.

Use a personal key for user-owned workflows. Use a scoped workspace or board key for shared or production integrations that should be owned, rotated, and audited with the destination.

Create a personal API key

1. Open Profile settings.
2. Go to API keys tab.
3. Create a personal API key.
4. Add an optional private label so you can recognize where the key is used.
5. Copy the secret when it is shown.

Personal keys are always tied to the user who created them. They do not have separate read/write/admin scopes: they follow the owner's real board access and role, and activity appears as the owner.

The secret is shown once. Store it in your local secret manager, MCP client configuration, or environment variables.

Create a workspace or board API key

1. Open the workspace or standalone board.
2. Go to Workspace settings -> API or Board 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.

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

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

Workspace 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.

Scopes apply to workspace API keys. Personal API keys do not have scopes; they inherit the owner's board-level permissions and are limited to board content.

Use separate API keys for separate integrations. This makes access easier to revoke, rotate, and audit. For shared systems, prefer workspace keys so access is not tied to one person's personal tooling.

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.

Both personal and workspace keys use the same bearer-token format.

OAuth for AI agents

Kanera also supports OAuth 2.0, so an AI agent can connect through a browser sign-in and consent flow instead of a static API key. OAuth access tokens use the kanera_oauth_... prefix and are sent as bearer tokens just like API keys:

Authorization: Bearer kanera_oauth_...

There are two OAuth paths:

• Interactive agents use the authorization-code flow with PKCE. A person approves the connection once in the browser, and the agent acts as that user. This is how compatible MCP clients such as Claude, ChatGPT, Copilot, and Codex connect without an API key.
• Unattended agents use the client_credentials grant. You create a client id and secret in Workspace settings -> API and exchange them for short-lived tokens, with no browser step. Use these for CI, cron, or server-side agents.

The authorization server publishes its metadata at /.well-known/oauth-authorization-server, with endpoints under /oauth/*. OAuth access tokens are accepted on the public API under /api/v1.

See Connect an AI agent for the full setup, scopes, and how to manage connections.

Base URL and versioning

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

For example:

https://api.kanera.app/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"}'

Board and workspace model

Kanera's API represents both user-facing models:

• A standard workspace contains multiple boards.
• A standalone board is returned with kind: "board" by endpoints that expose its backing container, but users experience it as one independent board.
• Boards contain cards.
• Lists, labels, and custom fields belong only to a standalone board or are shared across every board in a standard workspace.
• Assignment endpoints can return cards assigned across boards in the workspace.
• Private boards are only visible where the API key has access.
• A personal key can see boards across workspaces where its owner has access.
• A workspace key can see boards only inside its one workspace.

This is important when building integrations. Use a standalone board when its schema should stay independent. In a workspace, reuse existing lists and fields so reporting, assignment queries, and custom-field aggregation stay consistent. The Global Work UI can span every board the signed-in person can access, while a workspace API key remains scoped to its one workspace.

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. See Webhooks for setup, delivery verification, and the full list of supported webhook event types.

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

• Connect Kanera to your AI agent
• Connect an AI agent
• Automations
• Global Work
• Custom Fields