openapi: 3.1.0 info: title: Craaft API version: "1.0.0" description: | Personal-access-token API for Craaft. See `docs/api.md` for the narrative guide, rate limits, and worked examples. contact: name: Craaft servers: - url: https://craaft.io/api/v1 description: Production - url: http://localhost:8080/api/v1 description: Local security: - bearerAuth: [] components: securitySchemes: sessionAuth: type: apiKey in: cookie name: craaft_session description: | Browser session cookie (`__Host-craaft_session` in production, `craaft_session` in dev), set at sign-in. Not obtainable through this API - it's here only so the handful of session-only routes below (the OAuth consent screen's own endpoints, connected-apps management) can be marked accurately. They reject both bearer schemes with a 403. bearerAuth: type: http scheme: bearer bearerFormat: cra_<24 base64url chars> description: | Two token schemes, same permissions. `cra_<24 base64url chars>` is a personal access token minted in Settings, doesn't expire on its own, and is revoked from the same page. `cro_<32 base64url chars>` is an OAuth access token issued to an OAuth client (an MCP client such as Claude) via the authorization-code-with-PKCE flow; it expires after 1 hour and the client refreshes it. Either token authenticates as the user who authorized it, with that user's exact permissions. A token can be read-only: a personal access token created with access `read`, or an OAuth grant with scope `craaft:read`. A read-only token can send GET, HEAD and OPTIONS; any other method gets `403` with "this token is read-only; this request needs a token with read and write access", before the request is handled. A token can also be limited to chosen boards. Other boards then behave as if they don't exist (`404`, or left out of lists), and `POST /projects`, `/imports`, `/members` and `/invitations` answer `403` with "this token is limited to some boards; this request needs a token for all boards". OAuth clients discover every endpoint they need - authorization, token, dynamic client registration, revocation - at `/.well-known/oauth-authorization-server` (RFC 8414); they don't need to be told the URLs out of band. schemas: Error: type: object required: [error] properties: error: { type: string } User: type: object required: [id, email, name, username, avatarUrl, hasPassword, emailVerified, newsletterSubscribed, newsletterAvailable, emailNotifications, isSuperAdmin, twoFactorEnabled] properties: id: { type: string, format: uuid } email: { type: string, format: email } name: { type: string } username: { type: string } avatarUrl: { type: string, description: "Empty when no upload; otherwise /api/v1/users/{id}/avatar" } hasPassword: type: boolean description: "False for OAuth-only users (no password set). The hash itself is never returned." emailVerified: type: boolean description: | Whether the address has been confirmed. Currently a soft gate - every endpoint still works for an unverified user - so treat it as a prompt to nudge, not as an authorization signal. pendingEmail: type: string format: email description: | Present while an email change waits for confirmation. `email` stays the current address until the link sent to this one is opened. twoFactorEnabled: type: boolean description: | Whether the user has two-factor sign-in on. Managed from Settings → Security through session-only routes (`/me/2fa*`); personal access tokens and MCP tokens are not affected by it. newsletterSubscribed: { type: boolean } emailNotifications: type: boolean description: | Whether card-activity emails are sent (mentions, assignments, and activity on followed cards that stays unread for a few minutes). Defaults to true. Account email such as password resets is always sent. newsletterAvailable: type: boolean description: | False when the newsletter feature isn't configured on the deployment at all, which is different from being unsubscribed. isSuperAdmin: type: boolean description: | Whether the user can reach the `/admin` dashboard. Informational only - the real gate is server-side, and the admin endpoints are session-authenticated, so a token cannot use them. csrfToken: type: string description: | Present only for cookie/session callers, who need it to send mutations. Omitted for bearer-token callers, since CSRF does not apply to a credential that isn't attached automatically. Project: type: object required: [id, workspaceId, name, createdAt, updatedAt] properties: id: { type: string, format: uuid } workspaceId: { type: string, format: uuid } name: { type: string, maxLength: 200 } description: { type: string } brief: { type: string, maxLength: 20000, description: "The board brief (Markdown): goals, constraints, voice, decisions and links for anyone working on the board. On GET and PATCH /projects/{id} only; the list leaves it out. Every card's prompt ends with it." } isFavorite: { type: boolean } publicToken: { type: string, description: "Non-empty when public sharing is on" } backgroundImage: { type: string } backgroundColor: { type: string, description: "Board background hex color (#rrggbb), empty when unset; mutually exclusive with backgroundImage" } colorScheme: { type: string } textColor: { type: string, enum: [dark, light] } showMilestones: { type: boolean, description: "Whether the board's top bar shows the milestones button. Off on new boards (since 28 October 2026); boards made before then keep it on unless changed." } showArchived: { type: boolean, description: "Whether the board's top bar shows the archived cards button. Off on new boards (since 28 October 2026); boards made before then keep it on unless changed." } showFiles: { type: boolean, description: "Whether the board's top bar shows the files button. Off on new boards (since 28 October 2026); boards made before then keep it on unless changed." } showStandup: { type: boolean, description: "Whether the board's top bar shows the standup button. Off on new boards (since 28 October 2026); boards made before then keep it on unless changed." } showActivity: { type: boolean, description: "Whether the board's top bar shows the activity button. Off by default. The /projects/{id}/activity feed answers either way." } personCardLimit: { type: integer, minimum: 1, maximum: 999, nullable: true, description: "The most active cards one person should hold on the board; null means no limit. Visual only: the Workload panel and /projects/{id}/workload flag people over it, and nothing stops an assignment. On GET and PATCH /projects/{id} only; the list leaves it out." } myRole: type: string enum: [owner, admin, member] description: "Caller's role in the project's *workspace* (distinct from myBoardRole)." visibility: type: string enum: [private, workspace] description: | `private` (default): only users with an explicit grant (plus workspace owners/admins) see the board. `workspace`: every workspace member is an implicit contributor. myBoardRole: type: string enum: [admin, contributor] description: | Caller's effective role on the board. Workspace owners and admins are always `admin`; explicit grants resolve to `admin` or `contributor`; on a `workspace`-visibility board, plain workspace members default to `contributor`. canUploadAttachments: type: boolean description: | Whether cards on this board accept file attachments. Reflects the board's *workspace* plan (Pro), NOT the caller's own plan - so a Free user collaborating on a Pro workspace's board sees `true`. Matches the server's upload gate; the SPA uses it to show/hide the attachment dropzone. totalCards: { type: integer } columnCounts: { type: object, additionalProperties: { type: integer } } workspaceName: type: string description: "Workspace display name; populated on list responses." members: type: array description: "Capped avatar-stack preview on list responses only." items: { $ref: "#/components/schemas/ProjectMemberPreview" } columns: type: array items: { $ref: "#/components/schemas/Column" } createdAt: { type: string, format: date-time } updatedAt: { type: string, format: date-time } ProjectMemberPreview: type: object required: [id, name, avatarUrl] properties: id: { type: string, format: uuid } name: { type: string } avatarUrl: { type: string, description: "Empty when no upload; otherwise /api/v1/users/{id}/avatar" } BoardMember: type: object required: [userId, name, email, username, avatarUrl, role, source, createdAt] properties: userId: { type: string, format: uuid } name: { type: string } email: { type: string, format: email } username: { type: string } avatarUrl: { type: string, description: "Empty when no upload; otherwise /api/v1/users/{id}/avatar" } role: { type: string, enum: [admin, contributor] } source: type: string enum: [explicit, workspace-admin, workspace-visible] description: | How this row gets access. `explicit` = stored `project_members` row. `workspace-admin` = implicit because they're a workspace owner/admin. `workspace-visible` = implicit because the project is `visibility=workspace`. createdAt: { type: string, format: date-time } BoardMemberInput: type: object required: [userId, role] properties: userId: { type: string, format: uuid } role: { type: string, enum: [admin, contributor] } BoardAccess: type: object required: [projectId, name, role] properties: projectId: { type: string, format: uuid } name: { type: string, maxLength: 200 } role: { type: string, enum: [admin, contributor] } InvitationGrant: type: object required: [projectId, name, role] properties: projectId: { type: string, format: uuid } name: { type: string, maxLength: 200 } role: { type: string, enum: [admin, contributor] } Member: type: object required: [userId, email, name, role, avatarUrl, joinedAt] properties: userId: { type: string, format: uuid } email: { type: string, format: email } name: { type: string } role: { type: string, enum: [owner, admin, member] } avatarUrl: { type: string, description: "Empty when no upload; otherwise /api/v1/users/{id}/avatar" } joinedAt: { type: string, format: date-time } boardAccess: type: array description: | Explicit board grants the caller is allowed to see. Omitted when the row is a workspace owner/admin (implicit access to every board) OR when a non-admin caller is reading someone else's row. Empty array means "this member has no explicit grants". items: { $ref: "#/components/schemas/BoardAccess" } InvitationCreate: type: object required: [email, role] properties: email: { type: string, format: email } role: { type: string, enum: [admin, member] } boardGrants: type: array description: | Optional, only honoured for `role: "member"` invitations (admins auto-see every board). Persisted alongside the invitation and applied atomically on accept. items: type: object required: [projectId, role] properties: projectId: { type: string, format: uuid } role: { type: string, enum: [admin, contributor] } Invitation: type: object required: [id, email, role, invitedBy, invitedByName, createdAt, expiresAt, boardGrants] properties: id: { type: string, format: uuid } email: { type: string, format: email } role: { type: string, enum: [admin, member] } invitedBy: { type: string, format: uuid } invitedByName: { type: string } createdAt: { type: string, format: date-time } expiresAt: { type: string, format: date-time } boardGrants: type: array items: { $ref: "#/components/schemas/InvitationGrant" } Column: type: object required: [id, key, title, position] properties: id: { type: string, format: uuid } key: { type: string, description: "Stable identifier for cards.column" } title: { type: string, maxLength: 80 } color: { type: string, description: "Optional palette token; empty for default" } position: { type: number } isDone: { type: boolean } cardLimit: { type: integer, nullable: true } Card: type: object required: [id, projectId, column, title, position, createdAt, updatedAt] properties: id: { type: string, format: uuid } projectId: { type: string, format: uuid } column: { type: string } title: { type: string, maxLength: 500 } description: type: string description: | Full body on GET /cards/{id}, PATCH, create, and /detail. Omitted from GET /projects/{id}/cards and lean SSE card.updated events (position-only moves). position: { type: number } dueDate: { type: string, format: date-time, nullable: true } assignedUserId: { type: string, format: uuid, nullable: true } assignedUserName: { type: string, nullable: true } size: { type: integer, nullable: true, description: "Optional integer size estimate; null when unset" } priority: { type: string, nullable: true, enum: [low, medium, high, urgent, null] } createdBy: { type: string, format: uuid, nullable: true } createdByName: { type: string, nullable: true } updatedBy: { type: string, format: uuid, nullable: true } updatedByName: { type: string, nullable: true } attachmentCount: { type: integer } checklistDone: { type: integer, description: "Completed checklist items (denormalized count)" } checklistTotal: { type: integer, description: "Total checklist items (denormalized count)" } tags: type: array maxItems: 12 items: { type: string, maxLength: 32 } following: { type: boolean, description: "Whether the authenticated caller follows this card" } createdAt: { type: string, format: date-time } updatedAt: { type: string, format: date-time } SearchResult: type: object description: One GET /search hit. Carries no due date, assignee or priority. required: [id, projectId, projectName, columnKey, columnTitle, title, description, updatedAt, archived] properties: id: { type: string, format: uuid } projectId: { type: string, format: uuid } projectName: { type: string } columnKey: { type: string } columnTitle: { type: string } title: { type: string, maxLength: 500 } description: type: string description: Snippet of at most 180 characters (not the full body). updatedAt: { type: string, format: date-time } archived: { type: boolean } UpcomingCard: type: object description: One due-dated card in the GET /cards/focus `due` bucket. assignedUserId, assignedUserName and priority are omitted (not null) when unset. required: [id, projectId, projectName, columnKey, columnTitle, title, dueDate] properties: id: { type: string, format: uuid } projectId: { type: string, format: uuid } projectName: { type: string } columnKey: { type: string } columnTitle: { type: string } title: { type: string, maxLength: 500 } dueDate: { type: string, format: date-time } assignedUserId: { type: string, format: uuid } assignedUserName: { type: string } priority: { type: string, enum: [low, medium, high, urgent] } Comment: type: object required: [id, cardId, authorId, body, createdAt] properties: id: { type: string, format: uuid } cardId: { type: string, format: uuid } authorId: { type: string, format: uuid } body: { type: string, maxLength: 5000 } createdAt: { type: string, format: date-time } updatedAt: { type: string, format: date-time } ChecklistItem: type: object required: [id, cardId, text, done, position, createdAt, updatedAt] properties: id: { type: string, format: uuid } cardId: { type: string, format: uuid } text: { type: string } done: { type: boolean } position: { type: number, format: double } createdAt: { type: string, format: date-time } updatedAt: { type: string, format: date-time } Milestone: type: object required: [id, projectId, name, dueOn, createdAt, updatedAt] properties: id: { type: string, format: uuid } projectId: { type: string, format: uuid } name: { type: string, maxLength: 200 } dueOn: { type: string, format: date } achievedAt: { type: string, format: date-time, nullable: true } createdAt: { type: string, format: date-time } updatedAt: { type: string, format: date-time } VersionInfo: type: object description: | Build-info triplet stamped in at link time via `-X` ldflags. A plain `go run` leaves the defaults in place, so `dev` / `unknown` means an unstamped build rather than a broken one. required: [version, commit, buildTime] properties: version: { type: string, description: "Release tag, or `dev` when unstamped" } commit: { type: string, description: "Short commit SHA, or `unknown` when unstamped" } buildTime: { type: string, description: "RFC3339 build timestamp, or `unknown` when unstamped" } PublicBoard: type: object description: | Read-only snapshot returned by the unauthenticated `GET /public/projects/{token}` endpoint. A trimmed projection of the board: no workspace/ownership fields, no card metadata beyond priority + assignee. required: [project, columns, cards] properties: project: type: object required: [id, name, updatedAt] properties: id: { type: string, format: uuid } name: { type: string, maxLength: 200 } description: { type: string } backgroundImage: { type: string } backgroundColor: { type: string } colorScheme: { type: string } textColor: { type: string, enum: [dark, light] } updatedAt: { type: string, format: date-time } columns: type: array items: type: object required: [key, title, position] properties: key: { type: string } title: { type: string, maxLength: 80 } color: { type: string } position: { type: number, format: double } isDone: { type: boolean } cards: type: array items: type: object required: [id, column, position, title] properties: id: { type: string, format: uuid } column: { type: string, description: "column.key" } position: { type: number, format: double } title: { type: string, maxLength: 500 } description: { type: string } priority: { type: string, enum: [low, medium, high, urgent], nullable: true } assignedUserId: { type: string, format: uuid, nullable: true } assignedUserName: { type: string, nullable: true } assignedUserAvatarUrl: { type: string } BulkCardsResponse: type: object required: [cards] properties: cards: type: array description: "Affected cards, in request order" items: { $ref: "#/components/schemas/Card" } Attachment: type: object required: [id, cardId, name, size, contentType, uploadedBy, uploadedByName, createdAt] properties: id: { type: string, format: uuid } cardId: { type: string, format: uuid } name: { type: string, description: "Original filename" } size: { type: integer, format: int64, description: "Byte size" } contentType: { type: string } uploadedBy: { type: string, format: uuid } uploadedByName: { type: string } createdAt: { type: string, format: date-time } AttentionCard: type: object required: [id, projectId, projectName, columnKey, columnTitle, title, updatedAt, staleInProgress, highPriority, idleByMe] properties: id: { type: string, format: uuid } projectId: { type: string, format: uuid } projectName: { type: string } columnKey: { type: string } columnTitle: { type: string } title: { type: string, maxLength: 500 } updatedAt: { type: string, format: date-time } assignedUserId: { type: string, format: uuid, nullable: true } assignedUserName: { type: string, nullable: true } priority: { type: string, nullable: true, enum: [low, medium, high, urgent, null] } staleInProgress: { type: boolean } highPriority: { type: boolean } idleByMe: { type: boolean } CardEvent: type: object description: | One activity-log entry. `moved` is a column change within the board (values are column keys). `moved_board` is a move to another board (values are `:`); its `fromName` / `toName` are board names and `fromDetail` / `toDetail` column titles, each omitted when the caller can't access that board (show it as "another board"). For `assignee`, `fromName` / `toName` are user names. Clients should ignore types they don't recognise. required: [id, type, createdAt] properties: id: { type: string, format: uuid } type: { type: string, enum: [moved, moved_board, priority, assignee] } fromValue: { type: string, nullable: true } toValue: { type: string, nullable: true } fromName: { type: string, nullable: true } toName: { type: string, nullable: true } fromDetail: { type: string, nullable: true, description: "moved_board only: source column title" } toDetail: { type: string, nullable: true, description: "moved_board only: target column title" } actorId: { type: string, format: uuid, nullable: true } actorName: { type: string, nullable: true } createdAt: { type: string, format: date-time } BoardActivity: type: object description: | One board activity feed entry. `fromValue` / `toValue` depend on the type: column keys for `moved` (`fromName` / `toName` are the column titles, omitted for a column since deleted), `:` for `moved_board` (named as in CardEvent, recorded on both boards, and omitted along with the names for a board the caller can't access), priorities for `priority`, user ids for `assignee` (`fromName` / `toName` are names), and column titles for the column types. `cardId` is present only while the card is still on this board; `cardTitle` is its current title then, and the title it had when the change happened once it has gone. For `comment`, `excerpt` is the first 140 characters while the comment and card exist, and `commentDeleted` is true once the comment is gone. Clients should ignore types they don't recognise. required: [id, type, createdAt] properties: id: { type: string, format: uuid } type: type: string enum: [card_created, card_archived, card_restored, card_deleted, moved, moved_board, priority, assignee, comment, column_created, column_renamed, column_deleted] fromValue: { type: string, nullable: true } toValue: { type: string, nullable: true } fromName: { type: string, nullable: true } toName: { type: string, nullable: true } fromDetail: { type: string, nullable: true, description: "moved_board only: source column title" } toDetail: { type: string, nullable: true, description: "moved_board only: target column title" } actorId: { type: string, format: uuid, nullable: true } actorName: { type: string, nullable: true, description: "Omitted when the user has been deleted" } cardId: { type: string, format: uuid, nullable: true } cardTitle: { type: string, nullable: true } cardArchived: { type: boolean, description: "The card is on this board but archived" } excerpt: { type: string, nullable: true } commentDeleted: { type: boolean } createdAt: { type: string, format: date-time } CardDetail: type: object description: Envelope for GET /cards/{id}/detail (one authorised round-trip for the card modal). required: [card, comments, events, checklist, attachments] properties: card: { $ref: "#/components/schemas/Card" } comments: type: array items: { $ref: "#/components/schemas/Comment" } events: type: array description: Newest 100 events, oldest-first items: { $ref: "#/components/schemas/CardEvent" } checklist: type: array items: { $ref: "#/components/schemas/ChecklistItem" } attachments: type: array items: { $ref: "#/components/schemas/Attachment" } github: { $ref: "#/components/schemas/CardGitHub" } GitHubBinding: type: object properties: projectId: { type: string, format: uuid } installationId: { type: integer } accountLogin: { type: string } repoId: { type: integer } fullName: { type: string } openColumn: { type: string, nullable: true } mergedColumn: { type: string, nullable: true } suspended: { type: boolean, description: "The app is suspended on the account; pull requests don't update cards" } LinkedPullRequest: type: object properties: id: { type: string, format: uuid } cardId: { type: string, format: uuid } repo: { type: string } number: { type: integer } title: { type: string } url: { type: string } state: { type: string, enum: [open, closed, merged] } draft: { type: boolean } author: { type: string } branch: { type: string } updatedAt: { type: string, format: date-time } CardGitHub: type: object properties: enabled: { type: boolean } repo: { type: string, nullable: true, description: "The board's repository, or null when it isn't connected" } pullRequests: type: array items: { $ref: "#/components/schemas/LinkedPullRequest" } branches: type: array items: type: object properties: repo: { type: string } name: { type: string } url: { type: string } createdAt: { type: string, format: date-time } ImportRequest: type: object required: [file] properties: file: type: string format: binary description: The export file, up to 5 MB source: type: string enum: [trello, csv, jira, asana, craaft] description: Detected from the file when omitted mapping: type: string description: | CSV sources only. A JSON object mapping craaft fields to CSV header names, for example `{"title":"Summary","column":"Status"}`. Fields: `title` (required), `description`, `column`, `dueDate`, `priority`, `tags`, `assignee`, `archived`. It replaces the server's suggested mapping, so send every field to import. name: type: string description: Board name. Defaults to the name in the file. ImportPreview: type: object required: [source, name, columns, totals, assignees, access, warnings] properties: source: { type: string, enum: [trello, csv, jira, asana, craaft] } name: { type: string, maxLength: 200 } columns: type: array items: type: object required: [title, isDone, cards] properties: title: { type: string, maxLength: 80 } isDone: { type: boolean } cards: { type: integer } totals: type: object required: [cards, archived, comments, checklistItems, tags] properties: cards: { type: integer } archived: { type: integer } comments: { type: integer } checklistItems: { type: integer } tags: { type: integer } assignees: type: object required: [matched, unmatched] properties: matched: type: array items: type: object required: [source, userId, name] properties: source: { type: string } userId: { type: string } name: { type: string } unmatched: type: array items: { type: string } access: type: array description: | Matched assignees the import adds to the new private board as contributors: everyone matched except you and the workspace owners and admins, who already see every board. items: type: object required: [userId, name] properties: userId: { type: string } name: { type: string } warnings: type: array items: type: object required: [code, message] properties: code: { type: string, example: closed_lists_skipped } message: { type: string } csv: type: object description: Present only for CSV sources (generic, Jira and Asana) properties: headers: type: array items: { type: string } mapping: type: object description: The mapping in use, as sent or as suggested additionalProperties: { type: string } sample: type: array description: The first 3 data rows items: type: array items: { type: string } ProjectExport: type: object required: [version, exportedAt, project, columns, cards] properties: version: { type: integer, example: 2, description: "Export format version. 2 adds columns[].isDone, columns[].cardLimit and cards[].checklist" } exportedAt: { type: string, format: date-time } project: type: object required: [id, name, isFavorite, createdAt, updatedAt] properties: id: { type: string } name: { type: string, maxLength: 200 } description: { type: string } isFavorite: { type: boolean } createdAt: { type: string, format: date-time } updatedAt: { type: string, format: date-time } columns: type: array items: type: object required: [key, name, position] properties: key: { type: string } name: { type: string, maxLength: 80 } color: { type: string } position: { type: number, format: double } isDone: { type: boolean, description: Version 2 } cardLimit: { type: integer, description: "Version 2. Omitted when unset" } cards: type: array items: type: object required: [id, title, columnKey, position, createdAt, updatedAt] properties: id: { type: string } title: { type: string, maxLength: 500 } description: { type: string } columnKey: { type: string } position: { type: number, format: double } dueDate: { type: string, format: date-time, nullable: true } priority: { type: string } size: { type: integer, nullable: true } assignee: { $ref: "#/components/schemas/ProjectExportUser" } checklist: type: array description: Version 2. Omitted when the card has no checklist items items: type: object required: [text, done] properties: text: { type: string, maxLength: 1000 } done: { type: boolean } createdBy: { $ref: "#/components/schemas/ProjectExportUser" } createdAt: { type: string, format: date-time } updatedAt: { type: string, format: date-time } comments: type: array items: type: object required: [author, body, createdAt] properties: author: { $ref: "#/components/schemas/ProjectExportUser" } body: { type: string } createdAt: { type: string, format: date-time } attachments: type: array items: type: object required: [filename, size, uploadedAt] properties: filename: { type: string } size: { type: integer, format: int64 } uploader: { $ref: "#/components/schemas/ProjectExportUser" } uploadedAt: { type: string, format: date-time } ProjectExportUser: type: object required: [username, name] properties: username: { type: string } name: { type: string } BoardTemplate: type: object required: [key, name, description, columns] properties: key: { type: string, description: "Unique identifier for the template (e.g. 'kanban', 'sprint')" } name: { type: string, description: "Display name" } description: { type: string, description: "What this template is designed for" } columns: type: array items: { $ref: "#/components/schemas/BoardTemplateColumn" } BoardTemplateColumn: type: object required: [title, isDone, color] properties: title: { type: string } isDone: { type: boolean, description: "Whether cards in this column are considered complete" } color: { type: string, description: "Optional palette token (e.g. 'green', 'purple'); empty string for default" } WebhookDelivery: type: object required: [event, status, statusCode, attempts, error, createdAt] properties: event: { type: string, description: "The broadcast event name (e.g. 'card.created')" } status: { type: string, enum: [delivered, failed], description: "Delivery outcome" } statusCode: { type: integer, description: "HTTP status code from the webhook URL" } attempts: { type: integer, description: "Number of delivery attempts" } error: { type: string, description: "Error message when status is failed; empty string on success (never null)" } createdAt: { type: string, format: date-time } WebhookSubscription: type: object required: [id, endpointId, url, description, format, events, active, createdAt] properties: id: { type: string, format: uuid, description: "Subscription id (the handle for update/delete)" } endpointId: { type: string, format: uuid, description: "Endpoint id at the workspace level" } url: { type: string, format: uri, description: "The target URL for deliveries" } secret: { type: string, description: "HMAC signing secret for 'craaft' deliveries (X-Craaft-Signature). Returned only when the webhook is created, so copy it then; to get a new one, delete the webhook and add it again. Slack/Discord deliveries are unsigned and ignore it." } description: { type: string, description: "Optional label" } format: type: string enum: [craaft, slack, discord] description: "Delivery format (craaft=signed JSON envelope; slack/discord=message POST)" events: type: array items: { type: string } description: "Event filter (empty=all events; non-empty=only listed events)" active: { type: boolean } createdAt: { type: string, format: date-time } recentDeliveries: type: array description: "Last few delivery attempts (most recent first), capped at 10" items: { $ref: "#/components/schemas/WebhookDelivery" } InboundEmailAddress: type: object required: [email, token, targetColumn, active, aiEnrich, createdAt] properties: email: { type: string, format: email, description: "The board's inbound email address (auto-generated from token + domain)" } token: { type: string, description: "Routing token; used to construct the address. Unique per board." } targetColumn: { type: string, nullable: true, description: "Column key to place inbound cards; null=first column" } active: { type: boolean, description: "Whether to accept inbound mail to this address" } aiEnrich: { type: boolean, description: "AI cards for email threads are on" } aiAlways: { type: boolean, description: "Every email is written up with AI, not only forwarded threads and long emails" } aiInstructions: { type: string, maxLength: 1000, description: "The board admins' own instructions, sent with the AI prompt after craaft's rules" } createdAt: { type: string, format: date-time } InboundAllowedSender: type: object required: [id, pattern, addedBy, needsOwner, createdAt] properties: id: { type: string, format: uuid } pattern: { type: string, description: "Lower case: an exact address (invoices@stripe.com) or a whole domain (@stripe.com)" } addedBy: type: object nullable: true description: "Who the sender's cards are created as; null once that user is deleted" required: [id, name] properties: id: { type: string, format: uuid } name: { type: string } needsOwner: { type: boolean, description: "True when addedBy is gone or can no longer open the board; the sender's mail is turned away until someone adds it again" } createdAt: { type: string, format: date-time } NotificationCardRef: type: object required: [id, title, projectId, projectName, archived] properties: id: { type: string, format: uuid } title: { type: string } projectId: { type: string, format: uuid } projectName: { type: string } archived: { type: boolean } NotificationActor: type: object required: [id, name] properties: id: { type: string, format: uuid } name: { type: string } NotificationRow: type: object description: | One inbox line. Unread `comment` / `moved` / `updated` notifications on the same card are folded into a single row with kind `"group"`; `mention`, `assigned` and `due` rows, and any already-read row, are never grouped. `ids`, `kinds`, and `details` are parallel arrays with one entry per underlying notification folded into the row (length 1 when the row isn't a group). required: [ids, kind, kinds, details, card, actors, count, createdAt, seen, read] properties: ids: type: array items: { type: string, format: uuid } description: Underlying notification ids folded into this row. kind: type: string enum: [mention, assigned, comment, moved, updated, due, group] description: "\"group\" when this row folds together multiple unread comment/moved/updated notifications on one card; otherwise the single underlying kind." kinds: type: array items: { type: string, enum: [mention, assigned, comment, moved, updated, due] } description: The underlying kind of each id in `ids`, same order. details: type: array items: { type: string } description: | Per-notification detail, meaning depends on kind: `"card"` or `"comment"` for mention, `"column"` or `"board"` for moved, an update-kind string for updated, `"tomorrow"` or `"today"` for due (a due date reminder, which has no actors), `""` for assigned/comment. card: { $ref: "#/components/schemas/NotificationCardRef" } commentId: type: string format: uuid description: | The comment a mention came from (kind `mention`, detail `"comment"`). Omitted for every other row, for mentions made before this field existed, and once the comment is deleted. actors: type: array items: { $ref: "#/components/schemas/NotificationActor" } description: Distinct actors behind this row's notification(s), in the order first seen. excerpt: type: string description: Comment body or similar context, truncated to 280 characters. Omitted when there's nothing to show. count: type: integer description: Number of underlying notifications folded into this row (1 unless kind is "group"). createdAt: type: string format: date-time description: | For a group, the newest member's timestamp, not the oldest. Not a pagination cursor - see `nextBefore` on GET /me/notifications. seen: { type: boolean } read: { type: boolean } NotificationList: type: object description: The GET /me/notifications response envelope (not a bare array). required: [items, nextBefore] properties: items: type: array items: { $ref: "#/components/schemas/NotificationRow" } nextBefore: type: string format: date-time nullable: true description: | Cursor for the next page - pass back as `?before=`. Null when there's nothing older to fetch. This is the `createdAt` of the OLDEST raw notification fetched for this page, before grouping - grouping can make a page hold fewer than `limit` items, so the last item's `createdAt` is NOT a usable cursor (it can be a group's newest member, and re-fetching from it would re-show rows already returned). ConnectedApp: type: object description: | An MCP client (or other OAuth client) the caller has approved via the `/oauth/authorize` consent screen. Backed by an `oauth_grants` row - one per (user, client) pair. required: [id, clientName, redirectHost, verified, createdAt, lastUsedAt] properties: id: { type: string, format: uuid, description: "The grant id. Pass this to DELETE /me/connected-apps/{id} to revoke." } clientName: { type: string, description: "Name the client supplied at dynamic registration (RFC 7591)." } redirectHost: type: string description: | Host (with port, if non-default) of the client's registered redirect URI - shown so the user can recognise which app this is beyond just its self-reported name. verified: type: boolean description: | True for a small allowlist of known first-party MCP client hosts (currently claude.ai and claude.com). Any other client can self-register via dynamic client registration, so this is a hint, not a security boundary. createdAt: { type: string, format: date-time, description: "When the grant was first approved." } lastUsedAt: type: string format: date-time nullable: true description: "Last time this grant's access token was used. Null if never used since approval." responses: ImportBusy: description: | Too many imports are running and none finished within 15 seconds ("Too many imports are running. Try again in a moment"). Retry after the `Retry-After` delay. headers: Retry-After: schema: { type: integer, example: 5 } content: application/json: schema: { $ref: "#/components/schemas/Error" } Unauthorized: description: Missing or invalid token content: application/json: schema: { $ref: "#/components/schemas/Error" } NotFound: description: Resource doesn't exist or caller isn't a member of its workspace content: application/json: schema: { $ref: "#/components/schemas/Error" } RateLimited: description: Per-token rate limit exceeded headers: Retry-After: schema: { type: integer } description: Seconds until the next allowed request content: application/json: schema: { $ref: "#/components/schemas/Error" } SessionOnly: description: | Browser session required - a bearer token (`cra_` or `cro_`) was used against a session-only route and is refused identically to either scheme. content: application/json: schema: { $ref: "#/components/schemas/Error" } paths: /me: get: summary: Current user responses: "200": description: | OK. Browser sessions with no signed-in user, including one that has passed the password step of a two-factor sign-in but not the code step, get a `null` body. content: application/json: schema: { $ref: "#/components/schemas/User" } "401": { $ref: "#/components/responses/Unauthorized" } "429": { $ref: "#/components/responses/RateLimited" } patch: summary: Update profile (partial) requestBody: required: true content: application/json: schema: type: object properties: name: { type: string } email: type: string format: email description: | A new address needs `currentPassword`. It doesn't change `email` yet: it sets `pendingEmail` and emails the new address a link, and opening the link makes the change. Sending the current address cancels a pending change. currentPassword: { type: string } username: { type: string } emailNotifications: type: boolean description: Turn card-activity emails on or off. responses: "200": description: Updated user content: application/json: schema: { $ref: "#/components/schemas/User" } /me/notifications: get: summary: List the caller's notification inbox description: | Returns an envelope, not a bare array: `{"items": [...], "nextBefore": "" | null}`. See `NotificationList` for why `nextBefore` (not the last item's `createdAt`) is the cursor to pass back. parameters: - name: before in: query schema: { type: string, format: date-time } description: RFC3339Nano cursor. Returns notifications older than this timestamp - pass back the previous page's `nextBefore`. - name: limit in: query schema: { type: integer, minimum: 1, maximum: 50, default: 30 } description: Raw rows fetched before grouping. Default 30, clamped to 50. The returned `items` array can be shorter once unread rows on the same card are grouped. - name: unread in: query schema: { type: string, enum: ["1"] } description: Set to `1` to return only unread rows. - name: kind in: query schema: { type: string, enum: [mention, assigned, comment, moved, updated, due] } description: | Return only rows of this kind, for example `mention` to list where the caller was mentioned. The filter applies before `limit`, so pages stay full. responses: "200": description: OK content: application/json: schema: { $ref: "#/components/schemas/NotificationList" } "400": description: "`before` isn't a valid RFC3339 time, or `kind` isn't one of the listed kinds" content: application/json: schema: { $ref: "#/components/schemas/Error" } "401": { $ref: "#/components/responses/Unauthorized" } /me/notifications/count: get: summary: Unseen notification count responses: "200": description: OK content: application/json: schema: type: object required: [unseen] properties: unseen: { type: integer } "401": { $ref: "#/components/responses/Unauthorized" } /me/notifications/seen: post: summary: Mark notifications seen up to a timestamp description: | Silences the "unseen" badge without marking anything read - marking seen and marking read are separate. Takes `upTo` (the newest `createdAt` displayed), not a list of ids. requestBody: required: true content: application/json: schema: type: object required: [upTo] properties: upTo: { type: string, format: date-time, description: RFC3339 timestamp; every unseen notification created at or before this is marked seen. } responses: "200": description: OK content: application/json: schema: type: object required: [unseen] properties: unseen: { type: integer } "400": description: Missing or invalid `upTo` content: application/json: schema: { $ref: "#/components/schemas/Error" } "401": { $ref: "#/components/responses/Unauthorized" } /me/notifications/read: post: summary: Mark specific notifications, or a whole card's, read description: Marking read also marks seen. Send `ids`, `cardId`, or both; at least one is required. requestBody: required: true content: application/json: schema: type: object properties: ids: type: array items: { type: string, format: uuid } maxItems: 200 description: Notification ids to mark read. Unknown or foreign ids are ignored. cardId: type: string format: uuid description: Marks every unread notification on this card read. responses: "200": description: OK content: application/json: schema: type: object required: [unseen] properties: unseen: { type: integer } "400": description: Neither `ids` nor `cardId` sent, or more than 200 ids content: application/json: schema: { $ref: "#/components/schemas/Error" } "401": { $ref: "#/components/responses/Unauthorized" } /me/notifications/read-all: post: summary: Mark every notification read description: No request body. responses: "200": description: OK content: application/json: schema: type: object required: [unseen] properties: unseen: { type: integer } "401": { $ref: "#/components/responses/Unauthorized" } /me/events: get: summary: Server-Sent Events stream of the caller's own notifications description: | Opens a long-lived `text/event-stream` carrying `notification.created` / `notification.updated` events (each `{"unseen": }`), plus a `: ping` comment every 30s to keep the connection warm. No board access check - this is the caller's own per-user stream, the same one a board tab also subscribes to alongside its board events (see GET /projects/{id}/events). Use it on pages with no board open (settings, projects list, the notification bell) instead of opening a board subscription just to keep the bell live. responses: "200": description: An SSE stream (connection stays open). content: text/event-stream: schema: { type: string } "401": { $ref: "#/components/responses/Unauthorized" } /me/connected-apps: get: summary: List OAuth clients (MCP clients) the caller has connected description: | Session-only - see the `sessionAuth` scheme description above for why. Backs Settings → Connected apps in the UI. Newest grant first. security: - sessionAuth: [] responses: "200": description: OK content: application/json: schema: type: array items: { $ref: "#/components/schemas/ConnectedApp" } "403": { $ref: "#/components/responses/SessionOnly" } /me/connected-apps/{id}: parameters: - name: id in: path required: true schema: { type: string, format: uuid } description: The grant id, from ConnectedApp.id. delete: summary: Revoke a connected OAuth client description: | Revokes the grant and every access/refresh token issued under it. The client's next call with either token gets `invalid_grant` / 401 and must send the user through `/oauth/authorize` again. Session-only, like GET /me/connected-apps. security: - sessionAuth: [] responses: "204": { description: Revoked } "403": { $ref: "#/components/responses/SessionOnly" } "404": { $ref: "#/components/responses/NotFound" } /users/{id}/avatar: parameters: - name: id in: path required: true schema: { type: string, format: uuid } get: summary: Download a user's avatar description: | Not gated on workspace membership: avatars are inherently public within the app (assignee badges, mention rows, public boards), so anyone holding the user id can fetch theirs. Served with `X-Content-Type-Options: nosniff`. Bare `404` when the user has never uploaded one - that is the cue to render the initial-and-colour placeholder rather than an error. security: [] responses: "200": description: Image bytes content: application/octet-stream: schema: { type: string, format: binary } "404": description: No uploaded avatar for this user /board-templates: get: summary: List available board templates description: | Fixed catalogue of board templates, the same for every caller (any authenticated user; no plan gate). A template specifies the initial column layout. Pass its `key` as `template` on POST /projects to create a board from it. responses: "200": description: Array of available templates content: application/json: schema: type: array items: { $ref: "#/components/schemas/BoardTemplate" } /projects: get: summary: List projects responses: "200": description: OK content: application/json: schema: type: array items: { $ref: "#/components/schemas/Project" } post: summary: Create a project requestBody: required: true content: application/json: schema: type: object required: [name] properties: name: { type: string, maxLength: 200 } description: { type: string } template: type: string description: | Optional board template key (from GET /board-templates). Empty string or omitted = use default Kanban layout. responses: "201": description: Created. The response has no `columns`; GET /projects/{id} for the seeded columns and their keys. content: application/json: schema: { $ref: "#/components/schemas/Project" } "400": description: Missing name, or an unknown `template` key content: application/json: schema: { $ref: "#/components/schemas/Error" } "402": description: Plan limit reached (Free tier project cap) /imports/preview: post: summary: Preview a board import description: | Parses an uploaded Trello, Jira, Asana, CSV or craaft export and returns what `POST /imports` would create. Nothing is written. The preview and the import run the same code, so the counts match. `multipart/form-data`, file up to 5 MB. Limits per import: 2,000 cards, 200 columns, 500 checklist items on any one card, 20,000 checklist items and 20,000 comments in all, 200 CSV headers. `source` is detected from the file when omitted. For CSV sources, `mapping` replaces the server's suggested mapping: send every field you want imported. The response then carries a `csv` block with the headers, the mapping in use and the first sample rows. When no title column can be guessed and no `mapping` is sent, the preview still answers `200` with the `csv` block and an empty summary named after the file, so the client can map the title and preview again. Matched assignees who aren't you or a workspace owner or admin are listed in `access`: the import adds them to the new private board as contributors. requestBody: required: true content: multipart/form-data: schema: { $ref: "#/components/schemas/ImportRequest" } responses: "200": description: What the import would create content: application/json: schema: { $ref: "#/components/schemas/ImportPreview" } "400": description: | No file, an unknown `source`, a malformed `mapping`, a file that isn't a recognised export of the given source, a CSV with no `title` in the `mapping` sent, a CSV with more than 200 headers ("This file has too many columns to map. The limit is 200"), or a file that isn't UTF-8 ("Save the file as UTF-8 CSV and try again"). content: application/json: schema: { $ref: "#/components/schemas/Error" } "401": { $ref: "#/components/responses/Unauthorized" } "413": description: The file is over 5 MB content: application/json: schema: { $ref: "#/components/schemas/Error" } "422": description: | Over a limit, worded with the real numbers: more than 2,000 cards ("This file has 2,001 cards. The limit is 2,000"; a CSV stops counting at the limit, "This file has more than 2,000 cards. The limit is 2,000"), more than 200 columns ("This file has 238 columns. The limit is 200"), more than 500 checklist items on a card ("A card has 1,234 checklist items. The limit is 500 per card"), more than 20,000 checklist items or comments in all ("This file has 25,000 comments. The limit is 20,000"); or no cards and no columns to import. content: application/json: schema: { $ref: "#/components/schemas/Error" } "503": { $ref: "#/components/responses/ImportBusy" } /imports: post: summary: Import a board description: | Creates a new board from an uploaded Trello, Jira, Asana, CSV or craaft export. It never writes into an existing board. Takes the same fields as `POST /imports/preview` and runs the same parse. All or nothing: a failed import leaves no board behind. The board is private; each matched assignee listed in the preview's `access` is added to it as a contributor. A craaft export's board description comes across. No notifications are sent (no emails, mention, assignment or follower notifications, no Slack or Discord messages). The new board counts against the workspace's board cap. If the board is created but reloading it fails, the `201` still carries at least `id` and `name`. requestBody: required: true content: multipart/form-data: schema: { $ref: "#/components/schemas/ImportRequest" } responses: "201": description: Created. Shaped like the `POST /projects` response. content: application/json: schema: { $ref: "#/components/schemas/Project" } "400": description: | Same cases as `POST /imports/preview`, and a CSV with no `title` mapping, sent or guessed ("Map a column to the card title") content: application/json: schema: { $ref: "#/components/schemas/Error" } "401": { $ref: "#/components/responses/Unauthorized" } "402": description: Plan limit reached (board cap). Same body as `POST /projects`. content: application/json: schema: type: object required: [error, limit, currentPlan, max, current] properties: error: { type: string, example: project limit reached } limit: { type: string, example: projects } currentPlan: { type: string } max: { type: integer } current: { type: integer } "413": description: The file is over 5 MB content: application/json: schema: { $ref: "#/components/schemas/Error" } "422": description: Over a limit (same cases as `POST /imports/preview`), or no cards and no columns to import content: application/json: schema: { $ref: "#/components/schemas/Error" } "503": { $ref: "#/components/responses/ImportBusy" } /projects/{id}: parameters: - name: id in: path required: true schema: { type: string, format: uuid } get: summary: Get a project (with columns + counts) responses: "200": description: OK content: application/json: schema: { $ref: "#/components/schemas/Project" } "404": { $ref: "#/components/responses/NotFound" } patch: summary: Update a project (partial) requestBody: required: true content: application/json: schema: type: object properties: name: { type: string, maxLength: 200 } description: { type: string } brief: { type: string, maxLength: 20000, description: "Board brief in Markdown. Replaces the whole brief; send an empty string to clear it. Trimmed. Board admins only." } isFavorite: { type: boolean } backgroundImage: { type: string } backgroundColor: { type: string, description: "Hex colour (#rrggbb); mutually exclusive with backgroundImage" } colorScheme: { type: string } textColor: { type: string, enum: [dark, light] } showMilestones: { type: boolean, description: "Show or hide the milestones button in the board's top bar. Board admins only; milestones themselves are kept." } showArchived: { type: boolean, description: "Show or hide the archived cards button in the board's top bar. Board admins only; archived cards are kept." } showFiles: { type: boolean, description: "Show or hide the files button in the board's top bar. Board admins only; files are kept." } showStandup: { type: boolean, description: "Show or hide the standup button in the board's top bar. Board admins only; the `u` shortcut is disabled while hidden." } showActivity: { type: boolean, description: "Show or hide the activity button in the board's top bar. Board admins only. Off by default; the feed is recorded either way." } personCardLimit: { type: integer, minimum: 1, maximum: 999, nullable: true, description: "Set the most active cards one person should hold (the Workload panel), or null to remove the limit. Board admins only." } visibility: type: string enum: [private, workspace] description: | Flip the board between explicit-grant access and workspace-wide implicit access. Board-admin only. responses: "200": description: Updated content: application/json: schema: { $ref: "#/components/schemas/Project" } delete: summary: Delete a project responses: "204": { description: Deleted } /projects/{id}/export: parameters: - name: id in: path required: true schema: { type: string, format: uuid } get: summary: Export a project as JSON or CSV description: | Returns a versioned JSON envelope containing the project, its columns, cards (with metadata and checklists), comments, and attachment metadata. Attachment bytes are not included. Available on every plan. With `format=csv` the response is `text/csv` with one row per card, prefixed with a UTF-8 BOM so Excel decodes it as UTF-8 rather than the system ANSI codepage. Parse it as `utf-8-sig` or strip the three leading bytes. CSV can't carry the envelope's nesting, so comments and attachments collapse to `comment_count` / `attachment_count` - JSON stays the lossless format. Timestamps are RFC3339 UTC, `tags` is comma-joined, and unset optional fields are empty cells. Cells starting with `=`, `+`, `-` or `@` are prefixed with a single quote so spreadsheets treat user-entered card text as text rather than a formula. parameters: - name: format in: query required: false description: Output format. Defaults to `json`. schema: type: string enum: [json, csv] default: json responses: "200": description: Export payload headers: Cache-Control: schema: { type: string, example: "no-store" } description: Always `no-store` - exports are per-user and shouldn't be cached. Content-Disposition: schema: { type: string, example: 'attachment; filename="my-project-2026-05-08.json"' } description: Triggers a file download in browsers. The extension follows `format`. content: application/json: schema: { $ref: "#/components/schemas/ProjectExport" } text/csv: schema: type: string example: | card_id,title,description,column_key,column_name,position,due_date,priority,size,tags,assignee_username,assignee_name,created_by_username,created_by_name,created_at,updated_at,archived_at,comment_count,attachment_count 8f1c…,Write spec,,todo,To Do,1.5,2026-06-01T09:30:00Z,high,3,"backend,spec",alice,Alice,bob,Bob,2026-04-01T00:00:00Z,2026-05-01T00:00:00Z,,2,1 "400": description: Unsupported `format` - expected `json` or `csv` content: application/json: schema: { $ref: "#/components/schemas/Error" } "404": { $ref: "#/components/responses/NotFound" } /projects/{id}/cards: parameters: - name: id in: path required: true schema: { type: string, format: uuid } get: summary: List cards in a project responses: "200": description: Ordered by (column, position, createdAt). Description is omitted; fetch GET /cards/{id} or /detail for the body. content: application/json: schema: type: array items: { $ref: "#/components/schemas/Card" } post: summary: Create a card requestBody: required: true content: application/json: schema: type: object required: [title, column, position] properties: title: { type: string, maxLength: 500 } column: { type: string, description: "column.key" } position: { type: number, description: "Fractional - drop midpoint between siblings" } description: { type: string } responses: "201": description: Created content: application/json: schema: { $ref: "#/components/schemas/Card" } /projects/{id}/files: get: summary: List and search the files on a board description: | Every file attached to the board's cards (archived cards included), newest first. Every word of q must appear (case-insensitive substring) in the file name, card title, card description, uploader name or content type. parameters: - { name: id, in: path, required: true, schema: { type: string, format: uuid } } - { name: q, in: query, schema: { type: string } } - { name: limit, in: query, schema: { type: integer, minimum: 1, maximum: 200, default: 100 } } - { name: before, in: query, schema: { type: string, format: date-time } } responses: "200": description: A page of files content: application/json: schema: type: object properties: total: { type: integer } nextBefore: { type: string, format: date-time } items: type: array items: type: object properties: id: { type: string, format: uuid } name: { type: string } size: { type: integer } contentType: { type: string } createdAt: { type: string, format: date-time } uploadedBy: { type: string } uploadedByName: { type: string } card: type: object properties: id: { type: string, format: uuid } title: { type: string } column: { type: string } archived: { type: boolean } "400": { description: before is not an RFC3339 timestamp } "404": { description: Board not found or not visible to the caller } /projects/{id}/activity: parameters: - name: id in: path required: true schema: { type: string, format: uuid } get: summary: Board activity feed description: | What happened on the board, newest first: cards added, moved, archived, restored and deleted, priority and assignee changes, comments, and columns added, renamed and deleted. Entries for a deleted card stay, without a `cardId`. Entries are kept for 12 months. Page with `before`: pass the previous page's `nextBefore` until it comes back null. parameters: - name: before in: query schema: { type: string } description: The previous page's `nextBefore`. Opaque. - name: limit in: query schema: { type: integer, minimum: 1, maximum: 100, default: 50 } description: Values over 100 clamp to 100. - name: actor in: query schema: { type: string, format: uuid } description: Only changes made by this user. - name: type in: query schema: { type: string, example: "moved,moved_board" } description: Comma-separated `BoardActivity.type` values. responses: "200": description: One page of entries, newest first content: application/json: schema: type: object required: [items, nextBefore] properties: items: type: array items: { $ref: "#/components/schemas/BoardActivity" } nextBefore: type: string nullable: true description: Pass as `before` for the next page; null on the last page. "400": description: Invalid `before`, `limit`, `actor` or `type` content: application/json: schema: { $ref: "#/components/schemas/Error" } "404": { $ref: "#/components/responses/NotFound" } /projects/{id}/workload: parameters: - name: id in: path required: true schema: { type: string, format: uuid } get: summary: Open cards per person description: | Who holds how much on the board. A card is open when it isn't archived and isn't in a done column. Open cards in the board's first open column are queued, unless that column has a card limit; open cards in every other open column are active. `overLimit` is true when the board has a `personCardLimit` and the person's active cards are above it. Due dates are compared as UTC dates. Only people with at least 1 open card are listed, sorted by name, with the unassigned row (`userId` null) last; list the board's members to see who has nothing. responses: "200": description: The board's workload content: application/json: schema: type: object required: [personCardLimit, people] properties: personCardLimit: { type: integer, nullable: true, description: "The board's per-person limit, or null." } people: type: array items: type: object required: [userId, name, active, queued, overdue, dueSoon, highPriority, overLimit] properties: userId: { type: string, format: uuid, nullable: true, description: "Null for the unassigned row." } name: { type: string } active: { type: integer } queued: { type: integer } overdue: { type: integer, description: "Open cards due before today." } dueSoon: { type: integer, description: "Open cards due today or in the next 6 days." } highPriority: { type: integer, description: "Open cards with high or urgent priority." } overLimit: { type: boolean } "404": { $ref: "#/components/responses/NotFound" } /projects/{id}/cards/archived: parameters: - name: id in: path required: true schema: { type: string, format: uuid } get: summary: List a board's archived cards description: | Archived cards on the board, most recently archived first, capped at 200. Same shape as the board list plus `archivedAt`. Older archived cards stay reachable through search. An inaccessible board returns an empty list. responses: "200": description: Archived cards, newest first content: application/json: schema: type: array items: allOf: - { $ref: "#/components/schemas/Card" } - type: object required: [archivedAt] properties: archivedAt: { type: string, format: date-time } /projects/{id}/cards/bulk: parameters: - name: id in: path required: true schema: { type: string, format: uuid } post: summary: Create up to 100 cards in one transaction description: | All-or-nothing batch create - one invalid item rolls back the whole batch and the error names the offending index (`cards[3]: …`). Cards without an explicit `position` append to the end of their column in request order. Unlike the single-card create, the assignee is NOT defaulted to the caller. Bulk requests never send notification emails; activity events and SSE broadcasts fire normally. Body limit 1 MiB. requestBody: required: true content: application/json: schema: type: object required: [cards] properties: cards: type: array maxItems: 100 items: type: object required: [title, column] properties: title: { type: string, maxLength: 500 } column: { type: string, description: "column.key" } description: { type: string } position: { type: number, description: "Omit to append to the end of the column" } dueDate: { type: string, format: date-time } assignedUserId: { type: string, format: uuid } size: { type: integer } priority: { type: string, enum: [low, medium, high, urgent] } tags: type: array maxItems: 12 items: { type: string, maxLength: 32 } responses: "201": description: Created cards, in request order content: application/json: schema: { $ref: "#/components/schemas/BulkCardsResponse" } "400": description: Invalid item (message names the index), too many items, or invalid column/assignee content: application/json: schema: { $ref: "#/components/schemas/Error" } "404": { $ref: "#/components/responses/NotFound" } /projects/{id}/cards/rebalance: parameters: - name: id in: path required: true schema: { type: string, format: uuid } post: summary: Rewrite a column's card order in one transaction description: | Renumbers the listed cards onto `column` with positions 1, 2, 3, … in request order. Sized for a real column (up to 10 000 ids), not an import batch - the board uses this when a drop can no longer find a representable midpoint between two neighbours. All ids must already belong to this board (`404` otherwise). Within-board column changes are recorded to each card's activity log. All-or- nothing; no notification emails. Body limit 1 MiB. requestBody: required: true content: application/json: schema: type: object required: [ids, column] properties: ids: type: array maxItems: 10000 items: { type: string, format: uuid } column: { type: string, description: "Target column.key" } responses: "200": description: Rewritten cards, in request order content: application/json: schema: { $ref: "#/components/schemas/BulkCardsResponse" } "400": description: Missing fields or too many items content: application/json: schema: { $ref: "#/components/schemas/Error" } "404": description: A referenced card isn't on this board or isn't accessible content: application/json: schema: { $ref: "#/components/schemas/Error" } "422": description: The target column no longer exists content: application/json: schema: { $ref: "#/components/schemas/Error" } /projects/{id}/background-image: parameters: - name: id in: path required: true schema: { type: string, format: uuid } post: summary: Upload a board background image description: | Board admins only (workspace owners/admins, or explicit board admins). `multipart/form-data` with a single `file` part, max 10 MiB. The declared part `Content-Type` must be one of `image/png`, `image/jpeg`, `image/webp`, `image/gif` AND must match what the leading bytes actually sniff as, so a renamed file is rejected rather than stored. Returns the updated project. requestBody: required: true content: multipart/form-data: schema: type: object required: [file] properties: file: { type: string, format: binary } responses: "200": description: Updated project content: application/json: schema: { $ref: "#/components/schemas/Project" } "400": description: | Unparseable multipart body, a missing or empty `file` part, a type outside the PNG/JPEG/WebP/GIF set, or a declared type that does not match what the leading bytes sniff as. content: application/json: schema: { $ref: "#/components/schemas/Error" } "401": { $ref: "#/components/responses/Unauthorized" } "404": { $ref: "#/components/responses/NotFound" } "413": description: File exceeds the 10 MiB limit get: summary: Download the board background image description: | Streams the stored bytes to a caller with board access. Bare `404` (no JSON body) when the board has no background set. responses: "200": description: Image bytes content: application/octet-stream: schema: { type: string, format: binary } "401": { $ref: "#/components/responses/Unauthorized" } "404": description: No background set, or no board access delete: summary: Remove the board background image description: Board admins only. Returns the updated project. responses: "200": description: Updated project content: application/json: schema: { $ref: "#/components/schemas/Project" } "401": { $ref: "#/components/responses/Unauthorized" } "404": { $ref: "#/components/responses/NotFound" } /projects/{id}/tags: parameters: - name: id in: path required: true schema: { type: string, format: uuid } get: summary: Distinct tags used on a project's cards description: Sorted, de-duplicated union of tags across the board's cards (including archived). responses: "200": description: OK content: application/json: schema: type: array items: { type: string } "404": { $ref: "#/components/responses/NotFound" } /projects/{id}/share: parameters: - name: id in: path required: true schema: { type: string, format: uuid } post: summary: Enable public sharing (mint a read-only share token) description: | Generates a fresh public token; revoking and re-enabling mints a new one. The read-only board is then reachable at `/share/{publicToken}`. responses: "200": description: Sharing enabled content: application/json: schema: type: object required: [publicToken] properties: publicToken: { type: string } "404": { $ref: "#/components/responses/NotFound" } delete: summary: Revoke public sharing description: Clears the share token; existing links stop working immediately. responses: "204": { description: Sharing disabled } "404": { $ref: "#/components/responses/NotFound" } /cards/{id}: parameters: - name: id in: path required: true schema: { type: string, format: uuid } get: summary: Get a single card description: | Returns the same shape `PATCH /cards/{id}` responds with, including `following`. `404` when the card does not exist OR the caller has no access to its board - the two are intentionally indistinguishable. responses: "200": description: OK content: application/json: schema: { $ref: "#/components/schemas/Card" } "401": { $ref: "#/components/responses/Unauthorized" } "404": { $ref: "#/components/responses/NotFound" } patch: summary: Update a card (metadata + drag-drop) requestBody: required: true content: application/json: schema: type: object properties: title: { type: string, maxLength: 500 } description: { type: string } column: { type: string } position: { type: number } dueDate: { type: string, format: date-time, nullable: true } assignedUserId: { type: string, format: uuid, nullable: true } size: { type: integer, nullable: true } priority: { type: string, nullable: true, enum: [low, medium, high, urgent, null] } tags: type: array maxItems: 12 items: { type: string, maxLength: 32 } description: "Replaces the card's tag set when present. Send `[]` to clear." responses: "200": description: Updated content: application/json: schema: { $ref: "#/components/schemas/Card" } delete: summary: Delete a card responses: "204": { description: Deleted } /cards/{id}/detail: parameters: - name: id in: path required: true schema: { type: string, format: uuid } get: summary: Card plus nested collections in one envelope description: | Returns the card (with description) plus comments, events (newest 100, oldest-first), checklist, and attachments. Prefer this over five sequential GETs when opening a card modal. responses: "200": description: OK content: application/json: schema: { $ref: "#/components/schemas/CardDetail" } "401": { $ref: "#/components/responses/Unauthorized" } "404": { $ref: "#/components/responses/NotFound" } /cards/{id}/prompt: parameters: - name: id in: path required: true schema: { type: string, format: uuid } get: summary: The card as a Markdown brief for an AI tool description: | The text behind Copy as prompt in the web app: title, board, column, priority, due date, size, assignee, tags, the card link and ID, description, checklist, the 10 newest comments (each cut at 1,000 characters) and attachment names and sizes, then the board brief. Attachments are named, not linked, because their URLs need a signed-in session. Activity history is left out. The MCP tool and SDKs return this same text. responses: "200": description: OK content: application/json: schema: type: object required: [cardId, prompt] properties: cardId: { type: string, format: uuid } prompt: type: string description: Markdown "401": { $ref: "#/components/responses/Unauthorized" } "404": { $ref: "#/components/responses/NotFound" } /cards/bulk: patch: summary: Apply up to 100 partial card updates in one transaction description: | All-or-nothing batch update. Each item is `{ "id": … }` plus any fields the single-card PATCH accepts, with identical semantics (present = apply, `null` = clear, absent = leave alone). Column / priority / assignee changes are recorded to each card's activity log. One invalid item or missing card fails the whole batch and the error names the offending index. Bulk requests never send notification emails. Body limit 1 MiB. requestBody: required: true content: application/json: schema: type: object required: [cards] properties: cards: type: array maxItems: 100 items: type: object required: [id] properties: id: { type: string, format: uuid } title: { type: string, maxLength: 500 } description: { type: string } column: { type: string } position: { type: number } dueDate: { type: string, format: date-time, nullable: true } assignedUserId: { type: string, format: uuid, nullable: true } size: { type: integer, nullable: true } priority: { type: string, nullable: true, enum: [low, medium, high, urgent, null] } tags: type: array maxItems: 12 items: { type: string, maxLength: 32 } responses: "200": description: Updated cards, in request order content: application/json: schema: { $ref: "#/components/schemas/BulkCardsResponse" } "400": description: Invalid item - message names the index content: application/json: schema: { $ref: "#/components/schemas/Error" } "404": description: A referenced card doesn't exist or isn't accessible; nothing was applied content: application/json: schema: { $ref: "#/components/schemas/Error" } /cards/bulk/move: post: summary: Move up to 100 cards to a column in one transaction description: | Without `targetProjectId`, sweeps the cards to a column on their own board - every id must belong to the same board (400 otherwise). With `targetProjectId`, moves the batch to that board instead (same workspace only, mirroring the single-card move). Moved cards append to the end of the target column in request order. Within-board column changes are recorded to each card's activity log. All-or-nothing; no notification emails. requestBody: required: true content: application/json: schema: type: object required: [ids, column] properties: ids: type: array maxItems: 100 items: { type: string, format: uuid } column: { type: string, description: "Target column.key" } targetProjectId: type: string format: uuid description: "Optional destination board (same workspace)" responses: "200": description: Moved cards, in request order content: application/json: schema: { $ref: "#/components/schemas/BulkCardsResponse" } "400": description: Missing fields, too many items, or ids span multiple boards without a targetProjectId content: application/json: schema: { $ref: "#/components/schemas/Error" } "404": description: A card or the target board doesn't exist / isn't accessible; nothing was moved content: application/json: schema: { $ref: "#/components/schemas/Error" } "422": description: Target column doesn't exist content: application/json: schema: { $ref: "#/components/schemas/Error" } /cards/focus: get: summary: Focus view - due-dated cards + cards needing attention description: | Two buckets across every board you can see: `due` (cards with a due date) and `attention` (cards flagged stale, high priority, or idle-and-assigned-to-you). parameters: - name: only in: query required: false description: "`due` returns only the due bucket; `attention` is empty and the hygiene counts are 0. Faster when that's all you need." schema: { type: string, enum: [due] } responses: "200": description: OK content: application/json: schema: type: object required: [due, attention, hygiene] properties: due: type: array items: { $ref: "#/components/schemas/UpcomingCard" } attention: type: array items: { $ref: "#/components/schemas/AttentionCard" } hygiene: type: object description: Per-category counts for the hygiene drill-downs. required: [ghosts, longInProgress, mineNoDate] properties: ghosts: { type: integer } longInProgress: { type: integer } mineNoDate: { type: integer } /cards/hygiene: get: summary: Board-hygiene drill-down parameters: - name: type in: query required: true schema: { type: string, enum: [ghosts, stuck, mine_no_date] } description: | `ghosts` = cards with no due date, priority, or assignee; `stuck` = not updated in 14+ days; `mine_no_date` = assigned to you with no due date. responses: "200": description: Cards in the chosen hygiene category content: application/json: schema: type: array items: { $ref: "#/components/schemas/AttentionCard" } "400": description: Unknown hygiene type content: application/json: schema: { $ref: "#/components/schemas/Error" } /cards/{id}/move: parameters: - name: id in: path required: true schema: { type: string, format: uuid } post: summary: Move a card to another board description: | Relocates a card to another board in the same workspace that you can edit, into the chosen column (appended to the end). Keeps all card metadata, comments, and attachments. requestBody: required: true content: application/json: schema: type: object required: [targetProjectId, column] properties: targetProjectId: { type: string, format: uuid } column: { type: string, description: "Target column.key on the destination board" } responses: "200": description: The moved card content: application/json: schema: { $ref: "#/components/schemas/Card" } "400": description: Missing fields, or the target is the card's current board content: application/json: schema: { $ref: "#/components/schemas/Error" } "404": { $ref: "#/components/responses/NotFound" } "422": description: Target column doesn't exist on the destination board content: application/json: schema: { $ref: "#/components/schemas/Error" } /cards/{id}/archive: parameters: - name: id in: path required: true schema: { type: string, format: uuid } post: summary: Archive a card description: | Takes the card off the board without deleting it. It stays searchable and listed under GET /projects/{id}/cards/archived until restored. Archiving an already-archived card returns 404. responses: "200": description: Archived content: application/json: schema: type: object required: [archived, id] properties: archived: { type: boolean } id: { type: string, format: uuid } "404": { $ref: "#/components/responses/NotFound" } /cards/{id}/restore: parameters: - name: id in: path required: true schema: { type: string, format: uuid } post: summary: Restore an archived card description: | Puts an archived card back on its board, in the column and position it was archived from. Restoring a card that isn't archived returns 404. responses: "200": description: The restored card content: application/json: schema: { $ref: "#/components/schemas/Card" } "404": { $ref: "#/components/responses/NotFound" } /cards/{id}/events: parameters: - name: id in: path required: true schema: { type: string, format: uuid } get: summary: Card activity log (moves, priority + assignee changes) responses: "200": description: Events, oldest first content: application/json: schema: type: array items: { $ref: "#/components/schemas/CardEvent" } "404": { $ref: "#/components/responses/NotFound" } /cards/{id}/comments: parameters: - name: id in: path required: true schema: { type: string, format: uuid } get: summary: List comments (oldest first) responses: "200": description: OK content: application/json: schema: type: array items: { $ref: "#/components/schemas/Comment" } post: summary: Add a comment requestBody: required: true content: application/json: schema: type: object required: [body] properties: body: type: string maxLength: 5000 description: Markdown. Capped at 5000 characters; longer bodies return 400. responses: "201": description: Created content: application/json: schema: { $ref: "#/components/schemas/Comment" } /cards/{id}/follow: parameters: - name: id in: path required: true schema: { type: string, format: uuid } post: summary: Follow a card description: | Subscribe to future notifications for this card. Idempotent - already following returns 204. API keys may call this endpoint. responses: "204": { description: Following } "401": { $ref: "#/components/responses/Unauthorized" } "404": { $ref: "#/components/responses/NotFound" } delete: summary: Unfollow a card description: | Unsubscribe from future notifications for this card. Idempotent when not following. 404 when the card doesn't exist or the caller has no board access. responses: "204": { description: Unfollowed } "401": { $ref: "#/components/responses/Unauthorized" } "404": { $ref: "#/components/responses/NotFound" } /cards/{id}/checklist: parameters: - name: id in: path required: true schema: { type: string, format: uuid } get: summary: List a card's checklist items description: Flat list of `{text, done}` items, ordered by position. responses: "200": description: OK content: application/json: schema: type: array items: { $ref: "#/components/schemas/ChecklistItem" } "401": { $ref: "#/components/responses/Unauthorized" } "404": { $ref: "#/components/responses/NotFound" } post: summary: Add a checklist item description: Any board member may add an item; it's appended to the end. requestBody: required: true content: application/json: schema: type: object required: [text] properties: text: { type: string, maxLength: 1000 } responses: "201": description: Created content: application/json: schema: { $ref: "#/components/schemas/ChecklistItem" } "400": description: Missing/blank text or text too long content: application/json: schema: { $ref: "#/components/schemas/Error" } "401": { $ref: "#/components/responses/Unauthorized" } "404": { $ref: "#/components/responses/NotFound" } /checklist/{id}: parameters: - name: id in: path required: true schema: { type: string, format: uuid } patch: summary: Update a checklist item (partial) description: Any board member may edit an item's `text` and/or `done` state. requestBody: required: true content: application/json: schema: type: object properties: text: { type: string, maxLength: 1000 } done: { type: boolean } responses: "200": description: Updated content: application/json: schema: { $ref: "#/components/schemas/ChecklistItem" } "400": description: Blank text or text too long content: application/json: schema: { $ref: "#/components/schemas/Error" } "401": { $ref: "#/components/responses/Unauthorized" } "404": { $ref: "#/components/responses/NotFound" } delete: summary: Delete a checklist item description: Any board member may delete an item. responses: "204": { description: Deleted } "401": { $ref: "#/components/responses/Unauthorized" } "404": { $ref: "#/components/responses/NotFound" } /projects/{id}/milestones: parameters: - name: id in: path required: true schema: { type: string, format: uuid } get: summary: List a project's milestones description: Ordered by dueOn ascending, then createdAt as a tie-break. Any board member may read. responses: "200": description: Milestones for the project content: application/json: schema: type: array items: { $ref: "#/components/schemas/Milestone" } "401": { $ref: "#/components/responses/Unauthorized" } "404": { $ref: "#/components/responses/NotFound" } post: summary: Add a milestone description: Board admins only (workspace owners/admins, or explicit board admins). requestBody: required: true content: application/json: schema: type: object required: [name, dueOn] properties: name: { type: string, maxLength: 200 } dueOn: { type: string, format: date } responses: "201": description: Created content: application/json: schema: { $ref: "#/components/schemas/Milestone" } "400": description: Missing/blank name, name too long, or invalid dueOn content: application/json: schema: { $ref: "#/components/schemas/Error" } "401": { $ref: "#/components/responses/Unauthorized" } "403": description: Caller is a board member but not an admin content: application/json: schema: { $ref: "#/components/schemas/Error" } "404": { $ref: "#/components/responses/NotFound" } /milestones/{id}: parameters: - name: id in: path required: true schema: { type: string, format: uuid } patch: summary: Update a milestone (partial) description: | Board admins only. Setting `achieved: true` stamps `achievedAt` once (re-sending `true` keeps the original stamp); `achieved: false` clears it. requestBody: required: true content: application/json: schema: type: object properties: name: { type: string, maxLength: 200 } dueOn: { type: string, format: date } achieved: { type: boolean } responses: "200": description: Updated content: application/json: schema: { $ref: "#/components/schemas/Milestone" } "400": description: Blank name, name too long, or invalid dueOn content: application/json: schema: { $ref: "#/components/schemas/Error" } "401": { $ref: "#/components/responses/Unauthorized" } "403": description: Caller is a board member but not an admin content: application/json: schema: { $ref: "#/components/schemas/Error" } "404": { $ref: "#/components/responses/NotFound" } delete: summary: Delete a milestone description: Board admins only. responses: "204": { description: Deleted } "401": { $ref: "#/components/responses/Unauthorized" } "403": description: Caller is a board member but not an admin content: application/json: schema: { $ref: "#/components/schemas/Error" } "404": { $ref: "#/components/responses/NotFound" } /projects/{id}/webhooks: parameters: - name: id in: path required: true schema: { type: string, format: uuid } get: summary: List webhooks for a board description: | Board admins only. Returns the list of webhook subscriptions plus a catalogue of available broadcast event names for the filter picker. A Free board returns `403`; a Pro board with no webhooks returns an empty list. responses: "200": description: OK content: application/json: schema: type: object required: [webhooks, eventCatalogue] properties: webhooks: type: array items: { $ref: "#/components/schemas/WebhookSubscription" } eventCatalogue: type: array description: "Broadcast event names (card.created, card.updated, card.deleted, etc.)" items: { type: string } "401": { $ref: "#/components/responses/Unauthorized" } "403": description: Caller is a board member but not an admin content: application/json: schema: { $ref: "#/components/schemas/Error" } "402": description: Board is on Free plan; webhooks are Pro-only content: application/json: schema: { $ref: "#/components/schemas/Error" } "404": { $ref: "#/components/responses/NotFound" } post: summary: Create a webhook subscription description: | Board admins on Pro boards only. Registers a new endpoint and subscribes this board to events. The response carries the signing secret, and no later read does. The URL must be absolute http(s); a literal private, loopback or link-local IP is rejected, and delivery re-checks the resolved address so DNS can't route around it. requestBody: required: true content: application/json: schema: type: object required: [url] properties: url: { type: string, format: uri } description: { type: string } format: type: string enum: [craaft, slack, discord] default: craaft description: | Delivery format (omitted or empty = craaft). 'craaft' sends a signed JSON envelope; 'slack' and 'discord' POST message JSON to webhook URLs registered with those services (unsigned). Slack and Discord messages are grouped per card: changes are sent as one message once the card has been quiet for a minute (at most 5 minutes after the first change). A bulk request is one message for the whole request; a column rebalance sends none. events: type: array items: { type: string } description: "Event filter; empty=subscribe to all events" responses: "201": description: Created content: application/json: schema: { $ref: "#/components/schemas/WebhookSubscription" } "400": description: Malformed body or SSRF-rejected URL content: application/json: schema: { $ref: "#/components/schemas/Error" } "401": { $ref: "#/components/responses/Unauthorized" } "402": description: Free plan content: application/json: schema: { $ref: "#/components/schemas/Error" } "403": description: Not a board admin content: application/json: schema: { $ref: "#/components/schemas/Error" } "404": { $ref: "#/components/responses/NotFound" } /webhooks/{id}: parameters: - name: id in: path required: true schema: { type: string, format: uuid } description: Subscription id (from GET /projects/{projectId}/webhooks) patch: summary: Update a webhook subscription description: | Board admins on Pro boards only (authz via subscription lookup). Partial update - send only the fields to change. A downgraded (Free) board gets 402 here; DELETE stays open so it can still clean up. requestBody: required: true content: application/json: schema: type: object properties: url: { type: string, format: uri } description: { type: string } format: { type: string, enum: [craaft, slack, discord] } events: type: array items: { type: string } active: { type: boolean } responses: "200": description: Updated content: application/json: schema: { $ref: "#/components/schemas/WebhookSubscription" } "400": description: Malformed body or invalid format/events content: application/json: schema: { $ref: "#/components/schemas/Error" } "401": { $ref: "#/components/responses/Unauthorized" } "402": description: Free plan - integrations need Pro content: application/json: schema: { $ref: "#/components/schemas/Error" } "403": description: Not a board admin content: application/json: schema: { $ref: "#/components/schemas/Error" } "404": { $ref: "#/components/responses/NotFound" } delete: summary: Delete a webhook subscription description: Board admin only. Not plan-gated so downgraded boards can clean up. responses: "204": { description: Deleted } "401": { $ref: "#/components/responses/Unauthorized" } "403": description: Not a board admin content: application/json: schema: { $ref: "#/components/schemas/Error" } "404": { $ref: "#/components/responses/NotFound" } /projects/{id}/github: parameters: - name: id in: path required: true schema: { type: string, format: uuid } get: summary: The board's GitHub connection description: | `enabled` is false when this server has no GitHub App. `canConnect` is true for workspace owners and admins, who can install the app. `binding` is the board's repository and the columns pull requests move cards to, or null. responses: "200": description: OK content: application/json: schema: type: object properties: enabled: { type: boolean } canConnect: { type: boolean } installations: type: array items: type: object properties: id: { type: integer } accountLogin: { type: string } accountType: { type: string } suspended: { type: boolean } binding: nullable: true allOf: [{ $ref: "#/components/schemas/GitHubBinding" }] "404": { $ref: "#/components/responses/NotFound" } put: summary: Connect the board to a repository (workspace owners and admins) requestBody: required: true content: application/json: schema: type: object required: [installationId, repoId] properties: installationId: { type: integer } repoId: { type: integer } openColumn: { type: string, nullable: true, description: "Column key a card moves to when a pull request naming it opens; null: don't move" } mergedColumn: { type: string, nullable: true, description: "Column key a card moves to when the pull request merges; null: don't move" } responses: "200": description: OK content: application/json: schema: { $ref: "#/components/schemas/GitHubBinding" } "400": { description: "Unknown installation, a repository the app can't reach, or an invalid column" } "403": { description: "Not a workspace owner or admin" } "404": { $ref: "#/components/responses/NotFound" } delete: summary: Disconnect the board (workspace owners and admins) responses: "204": { description: Disconnected. Links already on cards stay but stop updating. } "403": { description: "Not a workspace owner or admin" } "404": { $ref: "#/components/responses/NotFound" } /projects/{id}/github/repos: parameters: - name: id in: path required: true schema: { type: string, format: uuid } get: summary: Repositories the workspace's GitHub installations can reach (workspace owners and admins) responses: "200": description: OK content: application/json: schema: type: array items: type: object properties: installationId: { type: integer } accountLogin: { type: string } id: { type: integer } fullName: { type: string } defaultBranch: { type: string } private: { type: boolean } "403": { description: "Not a workspace owner or admin" } "404": { $ref: "#/components/responses/NotFound" } /projects/{id}/github/pulls: parameters: - name: id in: path required: true schema: { type: string, format: uuid } get: summary: Pull requests linked to the board's live cards responses: "200": description: OK content: application/json: schema: type: array items: { $ref: "#/components/schemas/LinkedPullRequest" } "404": { $ref: "#/components/responses/NotFound" } /projects/{id}/github/install: parameters: - name: id in: path required: true schema: { type: string, format: uuid } post: summary: Link to install the craaft GitHub App description: | Signed-in sessions only, for workspace owners and admins. GitHub sends the person back to the board's settings once it's installed. responses: "200": description: OK content: application/json: schema: type: object properties: url: { type: string } "403": { description: "A token, or not a workspace owner or admin" } /cards/{id}/github: parameters: - name: id in: path required: true schema: { type: string, format: uuid } get: summary: The card's pull requests and branches responses: "200": description: OK content: application/json: schema: { $ref: "#/components/schemas/CardGitHub" } "404": { $ref: "#/components/responses/NotFound" } /cards/{id}/github/pulls: parameters: - name: id in: path required: true schema: { type: string, format: uuid } post: summary: Link a pull request to the card by its URL requestBody: required: true content: application/json: schema: type: object required: [url] properties: url: { type: string, example: "https://github.com/owner/repo/pull/123" } responses: "200": description: The card's GitHub view after linking content: application/json: schema: { $ref: "#/components/schemas/CardGitHub" } "400": { description: "Not a pull request URL, the board isn't connected, or the pull request isn't in the board's repository" } "404": { $ref: "#/components/responses/NotFound" } /cards/{id}/github/pulls/{linkId}: parameters: - name: id in: path required: true schema: { type: string, format: uuid } - name: linkId in: path required: true schema: { type: string, format: uuid } delete: summary: Unlink a pull request responses: "204": { description: Unlinked } "404": { $ref: "#/components/responses/NotFound" } /cards/{id}/github/branch: parameters: - name: id in: path required: true schema: { type: string, format: uuid } post: summary: Create a branch named after the card description: | Makes `-` (for example `a82d-fix-search`) from the repository's default branch. A branch that already exists is linked instead, with `existed: true`. responses: "200": description: OK content: application/json: schema: type: object properties: name: { type: string } url: { type: string } repo: { type: string } existed: { type: boolean } "400": { description: "The board isn't connected to a repository" } "404": { $ref: "#/components/responses/NotFound" } /projects/{id}/inbound-email: parameters: - name: id in: path required: true schema: { type: string, format: uuid } get: summary: Get inbound email address for a board description: | Board admins on Pro boards only. Returns the configured intake address (if enabled) or `{enabled: false}` when not yet set up. responses: "200": description: OK content: application/json: schema: type: object required: [enabled, aiAvailable, aiUsage] properties: enabled: { type: boolean } aiAvailable: { type: boolean, description: "Whether this server can write AI cards (has an AI key)" } aiUsage: type: object required: [used, limit] description: "AI cards used this calendar month (UTC) across the board's workspace, against the plan's monthly limit. Past the limit, email threads become standard cards until the month ends." properties: used: { type: integer } limit: { type: integer, description: "50 on Pro" } address: allOf: - { $ref: "#/components/schemas/InboundEmailAddress" } nullable: true description: "Present only when enabled=true" senders: type: array description: "Allowed senders beyond the board's members. Present only when enabled=true" items: { $ref: "#/components/schemas/InboundAllowedSender" } turnedAway: type: array description: "Senders dropped in the last 7 days, most recent first. Present only when enabled=true" items: type: object required: [from, reason, count, lastSeen] properties: from: { type: string } reason: { type: string, description: "For example not_member, no_board_access, unverified, allowed_sender_no_owner, daily_limit" } count: { type: integer } lastSeen: { type: string, format: date-time } "401": { $ref: "#/components/responses/Unauthorized" } "402": description: Free plan content: application/json: schema: { $ref: "#/components/schemas/Error" } "403": description: Not a board admin content: application/json: schema: { $ref: "#/components/schemas/Error" } "404": { $ref: "#/components/responses/NotFound" } post: summary: Enable inbound email for a board description: | Board admins on Pro boards only. Generates and returns a new intake address. Returns 409 if the board already has an address (revoke or update instead). requestBody: required: true content: application/json: schema: type: object properties: targetColumn: type: string nullable: true description: "Optional column key; null or omitted=first column" aiEnrich: { type: boolean, description: "Turn on AI cards for email threads" } responses: "201": description: Created content: application/json: schema: { $ref: "#/components/schemas/InboundEmailAddress" } "401": { $ref: "#/components/responses/Unauthorized" } "402": description: Free plan content: application/json: schema: { $ref: "#/components/schemas/Error" } "403": description: Not a board admin content: application/json: schema: { $ref: "#/components/schemas/Error" } "404": { $ref: "#/components/responses/NotFound" } "409": description: Inbound email already enabled for this board, or AI requested but not configured on this server content: application/json: schema: { $ref: "#/components/schemas/Error" } patch: summary: Update inbound email configuration description: | Board admins on Pro boards only. Partially update: active status, target column, or rotate the token. Send the desired fields only. A downgraded (Free) board gets 402 here; DELETE stays open so it can still switch the address off. requestBody: required: true content: application/json: schema: type: object properties: active: { type: boolean } targetColumn: type: string nullable: true description: "Column key; empty string clears to first column" rotate: { type: boolean, description: "Generate a new token if true" } aiEnrich: { type: boolean } aiAlways: { type: boolean, description: "Write every email up with AI, not only forwarded threads and long emails" } aiInstructions: { type: string, maxLength: 1000, description: "Your own instructions for the AI; empty string clears" } responses: "200": description: Updated content: application/json: schema: { $ref: "#/components/schemas/InboundEmailAddress" } "401": { $ref: "#/components/responses/Unauthorized" } "402": description: Free plan - integrations need Pro content: application/json: schema: { $ref: "#/components/schemas/Error" } "403": description: Not a board admin content: application/json: schema: { $ref: "#/components/schemas/Error" } "404": { $ref: "#/components/responses/NotFound" } "409": { description: "aiEnrich true but AI is not configured on this server", content: { application/json: { schema: { $ref: "#/components/schemas/Error" } } } } delete: summary: Disable inbound email for a board description: Board admins only. Not plan-gated so downgraded boards can disable. responses: "204": { description: Deleted } "401": { $ref: "#/components/responses/Unauthorized" } "403": description: Not a board admin content: application/json: schema: { $ref: "#/components/schemas/Error" } "404": { $ref: "#/components/responses/NotFound" } /projects/{id}/inbound-email/senders: parameters: - name: id in: path required: true schema: { type: string, format: uuid } post: summary: Allow a sender to email the board description: | Board admins on Pro boards only. Adds an address or a whole domain to the board's allowed senders. The caller becomes its owner: cards from it are created as the caller, with a first line saying who sent them. Mail must still pass SPF, DKIM and DMARC, and allowed senders can make up to 200 cards a day per board. requestBody: required: true content: application/json: schema: type: object required: [pattern] properties: pattern: { type: string, description: "invoices@stripe.com, or @stripe.com for the whole domain" } responses: "201": description: Added content: application/json: schema: { $ref: "#/components/schemas/InboundAllowedSender" } "400": description: Invalid pattern, a whole free email provider such as @gmail.com, or the board already has 50 content: application/json: schema: { $ref: "#/components/schemas/Error" } "401": { $ref: "#/components/responses/Unauthorized" } "402": description: Free plan content: application/json: schema: { $ref: "#/components/schemas/Error" } "403": description: Not a board admin content: application/json: schema: { $ref: "#/components/schemas/Error" } "404": { description: "Not found, or email to card is off", content: { application/json: { schema: { $ref: "#/components/schemas/Error" } } } } "409": { description: "Already allowed", content: { application/json: { schema: { $ref: "#/components/schemas/Error" } } } } /projects/{id}/inbound-email/senders/{senderId}: parameters: - name: id in: path required: true schema: { type: string, format: uuid } - name: senderId in: path required: true schema: { type: string, format: uuid } delete: summary: Remove an allowed sender description: Board admins only. Not plan-gated. responses: "204": { description: Removed } "401": { $ref: "#/components/responses/Unauthorized" } "403": description: Not a board admin content: application/json: schema: { $ref: "#/components/schemas/Error" } "404": { $ref: "#/components/responses/NotFound" } /projects/{id}/events: parameters: - name: id in: path required: true schema: { type: string, format: uuid } get: summary: Server-Sent Events stream for a board (realtime) description: | Opens a long-lived `text/event-stream` of `card.created` / `card.updated` / `card.deleted` (and checklist) events scoped to one project, plus a `: ping` comment every 30s to keep the connection warm. Also carries the caller's own `notification.created` / `notification.updated` events (each `{"unseen": <n>}`) - a board tab subscribes to both the board topic and the caller's per-user notification topic on the same stream, so the notification bell stays live without a second connection. See GET /me/events for the per-user stream on pages with no board open. Token-authenticated callers can subscribe, but typical API workflows poll the REST endpoints - the stream exists primarily for the SPA. responses: "200": description: An SSE stream (connection stays open). content: text/event-stream: schema: { type: string } "401": { $ref: "#/components/responses/Unauthorized" } "404": { $ref: "#/components/responses/NotFound" } /public/projects/{token}: parameters: - name: token in: path required: true schema: { type: string } get: summary: Read-only public board snapshot (no auth) operationId: getPublicBoard description: | Unauthenticated read of a board that has public sharing enabled. The share token is the access check; revoking sharing (or minting a new token) invalidates old links immediately. Returns a trimmed projection - no workspace, ownership, or private metadata. security: [] responses: "200": description: OK content: application/json: schema: { $ref: "#/components/schemas/PublicBoard" } "404": description: No board with this share token (or sharing revoked) content: application/json: schema: { $ref: "#/components/schemas/Error" } /public/projects/{token}/background-image: parameters: - name: token in: path required: true schema: { type: string } get: summary: Download a shared board's background image description: | Unauthenticated, gated entirely by the share token in the URL - the same blob `/projects/{id}/background-image` serves to members. Bare `404` when the token is unknown or the board has no background set. security: [] responses: "200": description: Image bytes content: application/octet-stream: schema: { type: string, format: binary } "404": description: Unknown token, or no background set /cards/{id}/attachments: parameters: - name: id in: path required: true schema: { type: string, format: uuid } get: summary: List attachments on a card responses: "200": description: OK content: application/json: schema: type: array items: { $ref: "#/components/schemas/Attachment" } "404": { $ref: "#/components/responses/NotFound" } post: summary: Upload a file to a card description: | Multipart upload with a single `file` part. Bytes flow through the API to object storage (max **25 MiB** per file). Requires the card's workspace to be on a paid plan - Free workspaces receive `402`. requestBody: required: true content: multipart/form-data: schema: type: object required: [file] properties: file: type: string format: binary description: The file to attach responses: "201": description: Created content: application/json: schema: { $ref: "#/components/schemas/Attachment" } "400": description: Missing/empty file or malformed multipart body content: application/json: schema: { $ref: "#/components/schemas/Error" } "402": description: Workspace plan does not allow uploads content: application/json: schema: { $ref: "#/components/schemas/Error" } "404": { $ref: "#/components/responses/NotFound" } "413": description: File exceeds the 25 MiB limit content: application/json: schema: { $ref: "#/components/schemas/Error" } /attachments/{id}: parameters: - name: id in: path required: true schema: { type: string, format: uuid } get: summary: Download attachment bytes parameters: - name: inline in: query required: false schema: { type: string, enum: ["1"] } description: | Request inline rendering rather than download. Honoured only for playable audio/video content types (audio/webm, audio/ogg, audio/mpeg, audio/mp4, audio/wav, video/webm, video/mp4); every other type is served as an attachment regardless, so this can never be used to render an uploaded document in the app's origin. description: | Streams the file with its stored `Content-Type` and a `Content-Disposition: attachment` header (or `inline` - see the `inline` parameter). Returns bare `404` (no JSON body) when the attachment or its bytes are missing. responses: "200": description: File bytes content: application/octet-stream: schema: type: string format: binary "404": description: Attachment not found or bytes unavailable delete: summary: Delete an attachment description: Removes metadata and storage bytes (best-effort on storage). responses: "204": { description: Deleted } "404": { $ref: "#/components/responses/NotFound" } /comments/{id}: parameters: - name: id in: path required: true schema: { type: string, format: uuid } patch: summary: Edit (author only) requestBody: required: true content: application/json: schema: type: object required: [body] properties: body: type: string maxLength: 5000 description: Markdown. Capped at 5000 characters; longer bodies return 400. responses: "200": description: Updated content: application/json: schema: { $ref: "#/components/schemas/Comment" } delete: summary: Delete (author or workspace owner/admin) responses: "204": { description: Deleted } /search: get: summary: Cross-project card search parameters: - name: q in: query required: true schema: { type: string } - name: limit in: query schema: { type: integer, minimum: 1, maximum: 50, default: 20 } description: | Missing or non-positive values use the default of 20; values above 50 clamp to 50 (so `limit=100` returns up to 50 rows). responses: "200": description: OK content: application/json: schema: type: object properties: cards: type: array items: { $ref: "#/components/schemas/SearchResult" } /columns/{id}: parameters: - name: id in: path required: true schema: { type: string, format: uuid } patch: summary: Update a column requestBody: required: true content: application/json: schema: type: object properties: title: { type: string, maxLength: 80 } color: { type: string, nullable: true, description: "Palette token. null or \"\" resets to the default colour; omit to leave it unchanged" } position: { type: number } isDone: { type: boolean } cardLimit: { type: integer, nullable: true } responses: "200": description: Updated content: application/json: schema: { $ref: "#/components/schemas/Column" } delete: summary: Delete a column (409 if it holds live cards) description: | Only LIVE cards block the delete. Archived cards in the column are reassigned to the board's first column (by position) and the delete proceeds - they keep existing and stay archived, so nothing that is still searchable is destroyed. Their recorded column changes, which is unavoidable once their real column is gone. A column that is the board's only column and holds archived cards has nowhere to reassign them to, so it still returns 409. responses: "204": { description: Deleted } "409": description: Column still has live cards content: application/json: schema: { $ref: "#/components/schemas/Error" } /columns/{id}/archive: parameters: - name: id in: path required: true schema: { type: string, format: uuid } post: summary: Archive all cards in a column description: | Soft-archives every live card in the column - they leave the board but stay searchable. Only applies to a column flagged `isDone`. On any other column this still answers `200` with `{"archived": 0}` rather than an error, so check the count instead of relying on the status code. responses: "200": description: Count and ids of the cards archived content: application/json: schema: type: object required: [archived, ids] properties: archived: { type: integer } ids: type: array description: Archived card ids, for an undo via POST /cards/{id}/restore items: { type: string, format: uuid } "404": { $ref: "#/components/responses/NotFound" } /projects/{id}/columns: parameters: - name: id in: path required: true schema: { type: string, format: uuid } post: summary: Add a column to a project requestBody: required: true content: application/json: schema: type: object required: [title] properties: title: { type: string, maxLength: 80 } responses: "201": description: Created content: application/json: schema: { $ref: "#/components/schemas/Column" } /projects/{id}/members: parameters: - name: id in: path required: true schema: { type: string, format: uuid } get: summary: List everyone who can see the board operationId: listBoardMembers description: | Returns explicit `project_members` grants alongside implicit rows for workspace owners/admins and (when the board is workspace-visible) every workspace member. The `source` field discriminates the three kinds. Any caller who can see the board may read this. responses: "200": description: OK content: application/json: schema: type: array items: { $ref: "#/components/schemas/BoardMember" } "401": { $ref: "#/components/responses/Unauthorized" } "404": { $ref: "#/components/responses/NotFound" } post: summary: Add a workspace member to the board operationId: addBoardMember description: | Board-admin only. The target must already be a workspace member; otherwise 404. Roles for workspace owners/admins are implicit, so explicit grants are only stored for workspace `member`s. requestBody: required: true content: application/json: schema: { $ref: "#/components/schemas/BoardMemberInput" } responses: "201": description: Created content: application/json: schema: type: object required: [userId, role, createdAt] properties: userId: { type: string, format: uuid } role: { type: string, enum: [admin, contributor] } createdAt: { type: string, format: date-time } "400": description: Missing / invalid role content: application/json: schema: { $ref: "#/components/schemas/Error" } "401": { $ref: "#/components/responses/Unauthorized" } "404": { $ref: "#/components/responses/NotFound" } /projects/{id}/members/{userId}: parameters: - name: id in: path required: true schema: { type: string, format: uuid } - name: userId in: path required: true schema: { type: string, format: uuid } patch: summary: Change an explicit board grant's role operationId: updateBoardMember description: | Board-admin only. 404 if there's no explicit `project_members` row for the target (i.e. their access is implicit via workspace role or workspace-visibility). requestBody: required: true content: application/json: schema: type: object required: [role] properties: role: { type: string, enum: [admin, contributor] } responses: "200": description: Updated content: application/json: schema: type: object required: [userId, role, createdAt] properties: userId: { type: string, format: uuid } role: { type: string, enum: [admin, contributor] } createdAt: { type: string, format: date-time } "400": description: Missing / invalid role content: application/json: schema: { $ref: "#/components/schemas/Error" } "401": { $ref: "#/components/responses/Unauthorized" } "404": { $ref: "#/components/responses/NotFound" } delete: summary: Remove an explicit board grant operationId: removeBoardMember description: | Board-admin only, except a contributor may remove themselves. 404 if no explicit grant exists for the target. responses: "204": { description: Removed } "401": { $ref: "#/components/responses/Unauthorized" } "404": { $ref: "#/components/responses/NotFound" } /members: get: summary: List workspace members operationId: listMembers responses: "200": description: | Workspace members. `boardAccess` is attached on rows the caller is allowed to see (their own row, or every row when the caller is owner/admin); omitted on owner/admin rows since they have implicit access to every board. content: application/json: schema: type: array items: { $ref: "#/components/schemas/Member" } "401": { $ref: "#/components/responses/Unauthorized" } /members/{userId}: parameters: - name: userId in: path required: true schema: { type: string, format: uuid } patch: summary: Change a member's workspace role operationId: updateMemberRole description: | Owner/admin only. Flips a member between `admin` and `member`. The owner role can't be set or changed here. requestBody: required: true content: application/json: schema: type: object required: [role] properties: role: { type: string, enum: [admin, member] } responses: "200": description: Updated content: application/json: schema: { $ref: "#/components/schemas/Member" } "400": description: Missing / invalid role content: application/json: schema: { $ref: "#/components/schemas/Error" } "401": { $ref: "#/components/responses/Unauthorized" } "403": description: Caller isn't a workspace owner/admin content: application/json: schema: { $ref: "#/components/schemas/Error" } "404": { $ref: "#/components/responses/NotFound" } delete: summary: Remove a member from the workspace operationId: removeMember description: Admin/owner only. Revokes membership and closes the member's open SSE streams. responses: "204": { description: Removed } "401": { $ref: "#/components/responses/Unauthorized" } "403": description: Caller isn't a workspace owner/admin content: application/json: schema: { $ref: "#/components/schemas/Error" } "404": { $ref: "#/components/responses/NotFound" } /invitations: get: summary: List pending invitations operationId: listInvitations responses: "200": description: Pending invitations, each with its `boardGrants` array. content: application/json: schema: type: array items: { $ref: "#/components/schemas/Invitation" } "401": { $ref: "#/components/responses/Unauthorized" } post: summary: Invite a user by email operationId: createInvitation description: | `boardGrants` is optional and only honoured for `role: "member"` invitations - admin invitations auto-see every board. Grants are persisted alongside the invitation and applied atomically when the invitee accepts. When the email already belongs to a verified account, the invite is accepted on the spot and `consumed` is `true` (the person is now a member). An unverified account leaves the invite pending until the address is confirmed. requestBody: required: true content: application/json: schema: { $ref: "#/components/schemas/InvitationCreate" } responses: "201": description: Created. The invitation is wrapped, not returned bare. content: application/json: schema: type: object required: [invitation, consumed] properties: invitation: { $ref: "#/components/schemas/Invitation" } consumed: type: boolean description: True when an existing verified account was added immediately "400": description: Malformed body or invalid role content: application/json: schema: { $ref: "#/components/schemas/Error" } "401": { $ref: "#/components/responses/Unauthorized" } "409": description: Email already a member or has a pending invitation content: application/json: schema: { $ref: "#/components/schemas/Error" } /invitations/{id}: parameters: - name: id in: path required: true schema: { type: string, format: uuid } delete: summary: Revoke a pending invitation operationId: revokeInvitation description: Owner/admin only. Deletes a pending invite so its accept link stops working. responses: "204": { description: Revoked } "401": { $ref: "#/components/responses/Unauthorized" } "403": description: Caller isn't a workspace owner/admin content: application/json: schema: { $ref: "#/components/schemas/Error" } "404": { $ref: "#/components/responses/NotFound" } /version: get: summary: Build information for the running server operationId: getVersion description: | Unauthenticated so monitoring can poll it without managing credentials, and cheap enough to use as a liveness probe: it touches neither the database nor the session store. Use it to confirm which artifact is live without shelling into a container. security: [] responses: "200": description: OK content: application/json: schema: { $ref: "#/components/schemas/VersionInfo" }