Introduction

The FileTag Kanban API is a stable, versioned HTTP API at /api/kanban/v1 for agents and third-party integrations that need to read and manage boards, columns, cards, and collaboration resources (assignees, labels, subtasks, comments, attachments) in FileTag.

:::info Beta

/api/kanban/v1 is currently in controlled beta. The contract documented here is the one the API implements, but access is limited while the rollout gates close. See Changelog and deprecation policy for what beta means and how general availability is announced.

:::

What this site covers

• Getting started — a complete copy-paste sequence from creating a token to moving your first card.
• Authentication and Scopes — how scoped Personal Access Tokens (PATs) work and which scope each operation needs.
• Core concepts — boards and visibility, columns and ordering, cards and completion, collaboration resources, and file attachments.
• Reliability — errors and request IDs, pagination, idempotency, optimistic concurrency, and rate limits.
• Step-by-step integration guides.
• The full API reference, generated directly from the published OpenAPI contract.

Conventions at a glance

• Base URL (production): https://app.filetag.ai/api/kanban/v1
• JSON properties use snake_case; timestamps are RFC 3339 UTC; identifiers are UUID strings.
• Every request is authenticated with a workspace-scoped PAT sent as a Bearer token.
• Successful responses wrap the resource in a data envelope; errors use a single error envelope with a stable machine-readable code and a request ID.
• Mutating POST requests require an Idempotency-Key header; version-guarded writes require If-Match. See Idempotency and Optimistic concurrency.

The API reference is generated from openapi/kanban-v1.yaml in the octopus repository, the same contract validated by the API's automated tests. This site does not provide an interactive request console; every example is meant to be copied and run from your own terminal or code.