keypiece.ai logokeypiece.ai
Log inStart free

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.

Open live help JSONBrowse endpoints

Documentation

Keypiece Integration API

Live reference sourced from /api/v1/help, with sections below for auth, scopes, and every endpoint group.

Reference

IntroductionAuthenticationResponse envelopeScopes

Endpoints

DiscoverySearchIntegration ProfileAccount Control PlaneBoardsListsCardsCommentsChannels and MessagesIncoming WebhooksAutomationsApproval Rules and Pending ApprovalsDocsOpsAgentsAI Audit LogsAI Routing and Policy

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.

23 scopes86 endpointskeypiece-integration-api.md
Review scopes

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 endpoints
  • X-Access-Token: <API_TOKEN>
  • access_token query parameter
  • Authorization: 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"
  }
}

Error shape

{
  "data": null,
  "error": {
    "code": "string",
    "message": "string",
    "details": "any|null"
  },
  "meta": {
    "help": "/api/v1/help",
    "guideFile": "keypiece-integration-api.md"
  }
}

X-Request-Id

Request correlation id.

X-API-Help

/api/v1/help

X-API-Guide-File

keypiece-integration-api.md

Link

</api/v1/help>; rel="help"

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

MethodPathSummary
GET

Public

/api/v1/help

No scopes required.

API self-documentation endpoint (CLI --help equivalent).

Search

MethodPathSummary
GET

Firebase ID token

/api/v1/search

No scopes required.

Search accessible boards, cards, channels, and messages for the signed-in user.

Integration Profile

MethodPathSummary
GET

Auth required

/api/v1/integrations/me/profile

No scopes required.

Read integration profile.

PATCH

Auth required

/api/v1/integrations/me/profile
profile:write

Update integration profile bio.

Account Control Plane

MethodPathSummary
GET

Account API token

/api/v1/account/boards
boards:read

List boards available to the account-token owner.

POST

Account API token

/api/v1/account/boards
boards:create

Create a board. Supports X-Idempotency-Key.

GET

Account API token

/api/v1/account/boards/{boardId}
boards:read

Read board metadata.

PATCH

Account API token

/api/v1/account/boards/{boardId}
boards:update

Update an owned board.

DELETE

Account API token

/api/v1/account/boards/{boardId}
boards:delete

Delete an owned board.

GET

Account API token

/api/v1/account/integrations
integrations:read

List integrations created by the account.

POST

Account API token

/api/v1/account/integrations
integrations:create

Create a board-scoped integration and reveal its API token once.

GET

Account API token

/api/v1/account/integrations/{integrationId}
integrations:read

Read an integration.

PATCH

Account API token

/api/v1/account/integrations/{integrationId}
integrations:update

Update an integration and its board access.

DELETE

Account API token

/api/v1/account/integrations/{integrationId}
integrations:delete

Delete an integration.

POST

Account API token

/api/v1/account/integrations/{integrationId}/rotate
integrations:rotate

Rotate an integration key and reveal the replacement once.

Boards

MethodPathSummary
GET

Auth required

/api/v1/boards
boards:read

List boards.

GET

Auth required

/api/v1/boards/{boardId}
boards:read

Get board.

PATCH

Auth required

/api/v1/boards/{boardId}
boards:write

Update board.

GET

Auth required

/api/v1/boards/{boardId}/labels
boards:read

List board labels available for card assignment.

POST

Auth required

/api/v1/boards/{boardId}/labels
cards:write

Create a board label for use on cards.

GET

Auth required

/api/v1/boards/{boardId}/labels/{labelId}
boards:read

Get one board label.

PATCH

Auth required

/api/v1/boards/{boardId}/labels/{labelId}
cards:write

Update a board label and synchronize cards already using it.

DELETE

Auth required

/api/v1/boards/{boardId}/labels/{labelId}
cards:write

Delete a board label and remove it from cards already using it.

Lists

MethodPathSummary
GET

Auth required

/api/v1/boards/{boardId}/lists
lists:read

List lists.

POST

Auth required

/api/v1/boards/{boardId}/lists
lists:write

Create list.

PATCH

Auth required

/api/v1/lists/{listId}
lists:write

Update list.

DELETE

Auth required

/api/v1/lists/{listId}
lists:write

Delete list.

POST

Auth required

/api/v1/boards/{boardId}/lists/reorder
lists:write

Reorder lists.

Cards

MethodPathSummary
GET

Auth required

/api/v1/boards/{boardId}/cards
cards:read

List cards.

POST

Auth required

/api/v1/boards/{boardId}/cards
cards:write

Create card.

POST

Auth required

/api/v1/lists/{listId}/cards
cards:write

Create card in list.

GET

Auth required

/api/v1/cards/{cardId}
cards:read

Get card.

PATCH

Auth required

/api/v1/cards/{cardId}
cards:write

Update card.

DELETE

Auth required

/api/v1/cards/{cardId}
cards:write

Delete card.

POST

Auth required

/api/v1/cards/{cardId}/move
cards:write

Move card.

POST

Auth required

/api/v1/lists/{listId}/cards/reorder
cards:write

Reorder cards in list.

Comments

MethodPathSummary
GET

Auth required

/api/v1/cards/{cardId}/comments
comments:read

List comments.

POST

Auth required

/api/v1/cards/{cardId}/comments
comments:write

Create comment.

PATCH

Auth required

/api/v1/cards/{cardId}/comments/{commentId}
comments:write

Update comment.

DELETE

Auth required

/api/v1/cards/{cardId}/comments/{commentId}
comments:write

Delete comment.

Channels and Messages

MethodPathSummary
GET

Auth required

/api/v1/boards/{boardId}/channels
channels:read

List channels.

POST

Auth required

/api/v1/boards/{boardId}/channels
channels:write

Create channel.

GET

Auth required

/api/v1/boards/{boardId}/channels/{channelId}
channels:read

Get channel.

PATCH

Auth required

/api/v1/boards/{boardId}/channels/{channelId}
channels:write

Update channel.

DELETE

Auth required

/api/v1/boards/{boardId}/channels/{channelId}
channels:write

Delete channel.

GET

Auth required

/api/v1/boards/{boardId}/channels/{channelId}/messages
messages:read

List channel messages.

POST

Auth required

/api/v1/boards/{boardId}/channels/{channelId}/messages
messages:write

Create channel message.

PATCH

Auth required

/api/v1/boards/{boardId}/channels/{channelId}/messages/{messageId}
messages:write

Update channel message.

DELETE

Auth required

/api/v1/boards/{boardId}/channels/{channelId}/messages/{messageId}
messages:write

Delete channel message.

Incoming Webhooks

MethodPathSummary
GET

Auth required

/api/v1/boards/{boardId}/channels/{channelId}/webhooks
webhooks:read

List channel webhooks. Secrets are never returned.

POST

Auth required

/api/v1/boards/{boardId}/channels/{channelId}/webhooks
webhooks:write

Create an incoming webhook. Returns the webhook URL with its secret embedded.

GET

Auth required

/api/v1/boards/{boardId}/channels/{channelId}/webhooks/{webhookId}
webhooks:read

Get webhook. Secret is excluded.

DELETE

Auth required

/api/v1/boards/{boardId}/channels/{channelId}/webhooks/{webhookId}
webhooks:write

Delete webhook.

POST

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

MethodPathSummary
GET

Auth required

/api/v1/boards/{boardId}/automations
boards:read

List board automations.

POST

Auth required

/api/v1/boards/{boardId}/automations
boards:write

Create automation with a trigger and an action.

GET

Auth required

/api/v1/boards/{boardId}/automations/{automationId}
boards:read

Get automation.

PATCH

Auth required

/api/v1/boards/{boardId}/automations/{automationId}
boards:write

Update automation name, enabled state, trigger, or action.

DELETE

Auth required

/api/v1/boards/{boardId}/automations/{automationId}
boards:write

Delete automation.

Approval Rules and Pending Approvals

MethodPathSummary
GET

Auth required

/api/v1/boards/{boardId}/approval-rules
board:read

List approval rules for the board.

POST

Auth required

/api/v1/boards/{boardId}/approval-rules
board:write

Create an approval rule gating an integration action behind human sign-off.

PATCH

Auth required

/api/v1/boards/{boardId}/approval-rules
board:write

Replace all approval rules for the board.

GET

Auth required

/api/v1/boards/{boardId}/pending-approvals
board:read

List pending approval records, newest first.

GET

Auth required

/api/v1/boards/{boardId}/pending-approvals/{approvalId}
board:read

Get one pending approval record.

PATCH

Auth required

/api/v1/boards/{boardId}/pending-approvals/{approvalId}
board:write

Resolve a pending approval.

Docs

MethodPathSummary
GET

Auth required

/api/v1/boards/{boardId}/docs
docs:read

List board docs, sharing config, tab metadata, and derived comment threads.

POST

Auth required

/api/v1/boards/{boardId}/docs
docs:write

Create a doc or subtab, including emoji and rich editor content.

GET

Auth required

/api/v1/boards/{boardId}/docs/{docId}
docs:read

Read one doc, including its derived threaded comments.

PATCH

Auth required

/api/v1/boards/{boardId}/docs/{docId}
docs:write

Edit a doc, including rich editor JSON, comment threads, emoji, and subtab placement.

Ops

MethodPathSummary
GET

Auth required

/api/v1/boards/{boardId}/standups
standups:read

Read standups.

POST

Auth required

/api/v1/boards/{boardId}/standups
standups:write

Create standup response.

PATCH

Auth required

/api/v1/boards/{boardId}/standups
standups:write

Update standup response.

DELETE

Auth required

/api/v1/boards/{boardId}/standups
standups:write

Delete standup response.

GET

Auth required

/api/v1/boards/{boardId}/calendar
calendar:read

Read calendar.

GET

Auth required

/api/v1/boards/{boardId}/issues
issues:read

Read issues.

Agents

MethodPathSummary
GET

Auth required

/api/v1/agents/ralph/run
boards:readcards:read

Preview Ralph queue without mutating.

POST

Auth required

/api/v1/agents/ralph/run
boards:readlists:readcards:readcards:write

Run one Ralph loop iteration.

GET

Auth required

/api/v1/boards/{boardId}/delegation-chains
messages:read

List agent delegation chains aggregated from recent channel messages.

POST

Auth required

/api/v1/boards/{boardId}/delegation-chains/{chainId}/interrupt
messages:write

Interrupt a delegation chain by posting an interrupt marker to its channel.

AI Audit Logs

MethodPathSummary
GET

Firebase ID token

/api/v1/workspaces/{workspaceId}/ai-audit-logs

No scopes required.

List AI audit logs for a workspace the signed-in user belongs to.

AI Routing and Policy

MethodPathSummary
GET

Firebase ID token

/api/organizations/ai-routing

No scopes required.

Read organization AI config, including defaultModel and effortModelMap for extra_low, low, medium, high, and extra_high.

POST

Firebase ID token

/api/organizations/ai-routing

No scopes required.

Create or replace organization AI config, including defaultModel and effortModelMap for card-effort routing.

PATCH

Firebase ID token

/api/organizations/ai-routing

No scopes required.

Update organization AI config, including defaultModel and effortModelMap for card-effort routing.

GET

Firebase ID token

/api/ai/route-config

No scopes required.

Read per-role effort-based model-routing config.

PUT

Firebase ID token

/api/ai/route-config

No scopes required.

Create or update per-role effort-based model-routing config.

DELETE

Firebase ID token

/api/ai/route-config

No scopes required.

Delete per-role model-routing config so built-in defaults apply again.