Keypiece Integration API
Token-authenticated API for boards, cards, channels, docs, incoming webhooks, automations, approval workflows, standups, calendar, issues, agent delegation and Ralph workflows, AI routing configuration, and AI audit logs.
Documentation
Keypiece Integration API
Live reference sourced from /api/v1/help, with sections below for auth, scopes, and every endpoint group.
Getting started
This page renders the same API help model exposed by /api/v1/help, including scopes, auth modes, headers, and endpoint groups. Use it as the human-readable surface, and use the JSON endpoint for tooling.
Connect Keypiece to AI tools (MCP)
Keypiece has a remote Model Context Protocol connector at https://www.keypiece.ai/mcp. Add that URL to an MCP-compatible AI client, sign in to Keypiece, and choose the boards and permissions the client may use.
What users can do
- Read only the boards they authorize.
- Create or update cards and comments when they grant write access.
- Revoke the connection at any time from Keypiece.
Where it works
- Claude custom connectors.
- Cursor remote MCP configuration.
- ChatGPT custom apps where the workspace plan and owner enable MCP.
Workspace products may require an owner or administrator to add and publish the connector once. The MCP endpoint uses OAuth; do not paste a Keypiece API token into a connector URL.
Turn external events into Issue Tracker cards
Workspace owners can open Issue Tracker → Inbound issue webhooks and create a webhook for an error monitor, support form, or any other service. Each accepted event becomes an Issue Tracker report and one linked Backlog card in that workspace.
Setup
- Enable Issue Tracker for the workspace.
- Create an inbound webhook and save its secret immediately.
- Configure the sending service to POST JSON with that secret in the header.
Safety built in
- Only the workspace owner can create, view, or disable a webhook.
- The secret is shown once and stored only as a hash.
- Retries are idempotent; delivery size and rate are limited.
POST https://www.keypiece.ai/api/issue-webhooks/{webhookId}
Content-Type: application/json
X-Keypiece-Webhook-Secret: {one-time secret}
Idempotency-Key: provider-event-123
{
"title": "Checkout is failing",
"description": "Pay button returns an error.",
"type": "bug",
"severity": 8,
"reporter": { "email": "support@example.com" }
}Accepted fields include title, description (or issue), type, severity, reporter, and externalId. Reuse Idempotency-Key or externalId whenever a provider retries an event.
Agent conventions
Cards owned by an integration are worked through an iterative loop, not completed in one shot. If you create or take ownership of a card, you are expected to write a plan onto it and then advance that plan one bounded step at a time.
The board UI reads ralphLoop directly. A card with an integration assignee and no todos displays "Pending AI to provide TODO for this card" and shows no progress, and a runCount that never moves means the card looks stalled to every human on the board.
Expected of an agent
- When you create a card for yourself, or assign yourself to one, populate ralphLoop.todos with concrete steps and write ralphLoop.definitionOfDone in the same request.
- Do the work in bounded steps. Increment ralphLoop.runCount by 1 per step and append one entry to ralphLoop.logs describing what changed.
- Mark todos done progressively as they complete. Do not flip every todo to done in a single step.
- Advance ralphLoop.status through todo, doing, then review once all todos are done. Leave the final done transition to a human unless the board says otherwise.
- Set ralphLoop.nextRunAt when you know when you will next act. It is not currently displayed on the board, but POST /api/v1/agents/ralph/run and the GET preview both read it to decide what is due.
- ralphLoop is replaced as a whole object. GET the card, modify the object, PATCH the full result.
Anti-patterns
- Creating a card with an integration assignee and an empty checklist and no todos.
- Leaving runCount at 0 while editing the card repeatedly.
- Writing a single todo that restates the card title instead of a plan.
- Jumping status straight from pending_todo_generation to done.
Loop stages: pending_todo_generation → todo → doing → review → done · Write with PATCH /api/v1/cards/{cardId}?boardId={boardId} · Full guide at /api/v1/guide
Authentication
The API accepts multiple token transport modes and supports wildcard scopes for broader integration tokens.
Methods
Authorization: Bearer <API_TOKEN>Authorization: Bearer <ACCOUNT_API_TOKEN> for permitted board-work endpoints and /api/v1/account/* control-plane endpointsX-Access-Token: <API_TOKEN>access_token query parameterAuthorization: Bearer <FIREBASE_ID_TOKEN> for workspace-authenticated AI routing endpoints
Wildcard scopes
* (all scopes)<namespace>:* (all scopes in a namespace, e.g. cards:*)
Response envelope
Success and error responses share the same envelope and help metadata, making client integrations predictable.
Success shape
{
"data": "object|array|null",
"error": null,
"meta": {
"help": "/api/v1/help",
"guideFile": "keypiece-integration-api.md",
"guide": "/api/v1/guide",
"hints": "array — advisory convention warnings, present only when something on the write needs attention. Each entry is { code, message, docs }. Never an error; safe to log and act on."
}
}Error shape
{
"data": null,
"error": {
"code": "string",
"message": "string",
"details": "any|null"
},
"meta": {
"help": "/api/v1/help",
"guideFile": "keypiece-integration-api.md",
"guide": "/api/v1/guide"
}
}X-Request-Id
Request correlation id.
X-API-Help
/api/v1/help
X-API-Guide-File
keypiece-integration-api.md
X-API-Guide
/api/v1/guide
Link
</api/v1/help>; rel="help", </api/v1/guide>; rel="describedby"
Scopes
Identity
profile:write
Update integration profile fields such as bio shown in board sidebars.
Workspace and Docs
boards:read
Read board metadata and automations.
boards:write
Update board-level settings and manage automations.
board:read
Read board approval rules and pending approvals.
board:write
Manage approval rules and resolve pending approvals.
docs:read
List and read board docs.
docs:write
Create and update board docs.
Planning
lists:read
Read board lists.
lists:write
Create, update, delete, and reorder lists.
cards:read
Read cards.
cards:write
Create, update, delete, move, and reorder cards.
comments:read
Read card comments.
comments:write
Create, update, and delete comments.
Channels and Messages
channels:read
Read channels.
channels:write
Create, update, and delete channels.
messages:read
Read channel messages and delegation chains.
messages:write
Create, update, and delete channel messages, and interrupt delegation chains.
webhooks:read
List and read channel incoming webhooks.
webhooks:write
Create and delete channel incoming webhooks.
Ops and Reporting
standups:read
Read standup entries.
standups:write
Create, update, and delete standup entries.
calendar:read
Read calendar events and due dates.
issues:read
Read issue tracker data.
Discovery
Public
/api/v1/helpNo scopes required.
API self-documentation endpoint (CLI --help equivalent). Includes the guidance block describing how this workspace expects AI agents to work cards.
Public
/api/v1/guideNo scopes required.
Long-form integration guide as markdown, including the full agentic loop state machine.
Search
Firebase ID token
/api/v1/searchNo scopes required.
Search accessible boards, cards, channels, and messages for the signed-in user.
Integration Profile
Auth required
/api/v1/integrations/me/profileNo scopes required.
Read integration profile.
Auth required
/api/v1/integrations/me/profileUpdate integration profile bio.
Account Control Plane
Account API token
/api/v1/account/boardsList boards available to the account-token owner.
Account API token
/api/v1/account/boardsCreate a board. Supports X-Idempotency-Key.
Account API token
/api/v1/account/boards/{boardId}Read board metadata.
Account API token
/api/v1/account/boards/{boardId}Update an owned board.
Account API token
/api/v1/account/boards/{boardId}Delete an owned board.
Account API token
/api/v1/account/integrationsList integrations created by the account.
Account API token
/api/v1/account/integrationsCreate a board-scoped integration and reveal its API token once.
Account API token
/api/v1/account/integrations/{integrationId}Read an integration.
Account API token
/api/v1/account/integrations/{integrationId}Update an integration and its board access.
Account API token
/api/v1/account/integrations/{integrationId}Delete an integration.
Account API token
/api/v1/account/integrations/{integrationId}/rotateRotate an integration key and reveal the replacement once.
Boards
Auth required
/api/v1/boardsList boards.
Auth required
/api/v1/boards/{boardId}Get board.
Auth required
/api/v1/boards/{boardId}Update board.
Auth required
/api/v1/boards/{boardId}/labelsList board labels available for card assignment.
Auth required
/api/v1/boards/{boardId}/labelsCreate a board label for use on cards.
Auth required
/api/v1/boards/{boardId}/labels/{labelId}Get one board label.
Auth required
/api/v1/boards/{boardId}/labels/{labelId}Update a board label and synchronize cards already using it.
Auth required
/api/v1/boards/{boardId}/labels/{labelId}Delete a board label and remove it from cards already using it.
Lists
Auth required
/api/v1/boards/{boardId}/listsList lists.
Auth required
/api/v1/boards/{boardId}/listsCreate list.
Auth required
/api/v1/lists/{listId}Update list.
Auth required
/api/v1/lists/{listId}Delete list.
Auth required
/api/v1/boards/{boardId}/lists/reorderReorder lists.
Cards
Auth required
/api/v1/boards/{boardId}/cardsList cards.
Auth required
/api/v1/boards/{boardId}/cardsCreate card.
Auth required
/api/v1/lists/{listId}/cardsCreate card in list.
Auth required
/api/v1/cards/{cardId}Get card.
Auth required
/api/v1/cards/{cardId}Update card.
Auth required
/api/v1/cards/{cardId}Delete card.
Auth required
/api/v1/cards/{cardId}/moveMove card.
Auth required
/api/v1/lists/{listId}/cards/reorderReorder cards in list.
Channels and Messages
Auth required
/api/v1/boards/{boardId}/channelsList channels.
Auth required
/api/v1/boards/{boardId}/channelsCreate channel.
Auth required
/api/v1/boards/{boardId}/channels/{channelId}Get channel.
Auth required
/api/v1/boards/{boardId}/channels/{channelId}Update channel.
Auth required
/api/v1/boards/{boardId}/channels/{channelId}Delete channel.
Auth required
/api/v1/boards/{boardId}/channels/{channelId}/messagesList channel messages.
Auth required
/api/v1/boards/{boardId}/channels/{channelId}/messagesCreate channel message.
Auth required
/api/v1/boards/{boardId}/channels/{channelId}/messages/{messageId}Update channel message.
Auth required
/api/v1/boards/{boardId}/channels/{channelId}/messages/{messageId}Delete channel message.
Incoming Webhooks
Auth required
/api/v1/boards/{boardId}/channels/{channelId}/webhooksList channel webhooks. Secrets are never returned.
Auth required
/api/v1/boards/{boardId}/channels/{channelId}/webhooksCreate an incoming webhook. Returns the webhook URL with its secret embedded.
Auth required
/api/v1/boards/{boardId}/channels/{channelId}/webhooks/{webhookId}Get webhook. Secret is excluded.
Auth required
/api/v1/boards/{boardId}/channels/{channelId}/webhooks/{webhookId}Delete webhook.
Webhook secret via secret query parameter or X-Webhook-Secret header
/api/webhooks/{webhookId}No scopes required.
Public webhook trigger. Posts a message to the webhook's channel.
Automations
Auth required
/api/v1/boards/{boardId}/automationsList board automations.
Auth required
/api/v1/boards/{boardId}/automationsCreate automation with a trigger and an action.
Auth required
/api/v1/boards/{boardId}/automations/{automationId}Get automation.
Auth required
/api/v1/boards/{boardId}/automations/{automationId}Update automation name, enabled state, trigger, or action.
Auth required
/api/v1/boards/{boardId}/automations/{automationId}Delete automation.
Approval Rules and Pending Approvals
Auth required
/api/v1/boards/{boardId}/approval-rulesList approval rules for the board.
Auth required
/api/v1/boards/{boardId}/approval-rulesCreate an approval rule gating an integration action behind human sign-off.
Auth required
/api/v1/boards/{boardId}/approval-rulesReplace all approval rules for the board.
Auth required
/api/v1/boards/{boardId}/pending-approvalsList pending approval records, newest first.
Auth required
/api/v1/boards/{boardId}/pending-approvals/{approvalId}Get one pending approval record.
Auth required
/api/v1/boards/{boardId}/pending-approvals/{approvalId}Resolve a pending approval.
Docs
Auth required
/api/v1/boards/{boardId}/docsList board docs, sharing config, tab metadata, and derived comment threads.
Auth required
/api/v1/boards/{boardId}/docsCreate a doc or subtab, including emoji and rich editor content.
Auth required
/api/v1/boards/{boardId}/docs/{docId}Read one doc, including its derived threaded comments.
Auth required
/api/v1/boards/{boardId}/docs/{docId}Edit a doc, including rich editor JSON, comment threads, emoji, and subtab placement.
Ops
Auth required
/api/v1/boards/{boardId}/standupsRead standups.
Auth required
/api/v1/boards/{boardId}/standupsCreate standup response.
Auth required
/api/v1/boards/{boardId}/standupsUpdate standup response.
Auth required
/api/v1/boards/{boardId}/standupsDelete standup response.
Auth required
/api/v1/boards/{boardId}/calendarRead calendar.
Auth required
/api/v1/boards/{boardId}/issuesRead issues.
Agents
Auth required
/api/v1/agents/ralph/runPreview the agentic-loop queue without mutating anything. Returns each integration-owned card with its current ralphLoop so you can see which cards still need todos.
Auth required
/api/v1/agents/ralph/runRun one bounded loop iteration over every card assigned to this integration: generate todos where missing, advance status, complete some todos, increment runCount and stamp nextRunAt. Takes no body.
Auth required
/api/v1/boards/{boardId}/delegation-chainsList agent delegation chains aggregated from recent channel messages.
Auth required
/api/v1/boards/{boardId}/delegation-chains/{chainId}/interruptInterrupt a delegation chain by posting an interrupt marker to its channel.
AI Audit Logs
Firebase ID token
/api/v1/workspaces/{workspaceId}/ai-audit-logsNo scopes required.
List AI audit logs for a workspace the signed-in user belongs to.
AI Routing and Policy
Firebase ID token
/api/organizations/ai-routingNo scopes required.
Read organization AI config, including defaultModel and effortModelMap for extra_low, low, medium, high, and extra_high.
Firebase ID token
/api/organizations/ai-routingNo scopes required.
Create or replace organization AI config, including defaultModel and effortModelMap for card-effort routing.
Firebase ID token
/api/organizations/ai-routingNo scopes required.
Update organization AI config, including defaultModel and effortModelMap for card-effort routing.
Firebase ID token
/api/ai/route-configNo scopes required.
Read per-role effort-based model-routing config.
Firebase ID token
/api/ai/route-configNo scopes required.
Create or update per-role effort-based model-routing config.
Firebase ID token
/api/ai/route-configNo scopes required.
Delete per-role model-routing config so built-in defaults apply again.
Comments
Auth required
/api/v1/cards/{cardId}/commentsList comments.
Auth required
/api/v1/cards/{cardId}/commentsCreate comment.
Auth required
/api/v1/cards/{cardId}/comments/{commentId}Update comment.
Auth required
/api/v1/cards/{cardId}/comments/{commentId}Delete comment.