Cards

Create a card with optional inline checklist

Pass ifSimilar: 'reject' to be refused with 409 CONFLICT and details: { similar: [{ cardKey, title, similarity }] } — the titles on the workspace's boards you can read with trigram similarity >= 0.5, at most five, best first; a private board you are not a member of is never consulted — instead of creating a near-duplicate. Default is 'create'. A description over the 2000-character cap answers 400 VALIDATION_ERROR with details: { rule: 'index-card', limit: 2000, hint } — the hint names the index-card split of card-authoring.md; the validation message itself carries the same hint, which is also what MCP callers receive, in the same envelope, since the server validates tool inputs itself (2026-09-11). kind: 'guidance' cannot be set at creation by a Bearer token, grant or not (403 FORBIDDEN, details.reason: 'no_consent_path'): create the card, then promote it with updateCard under a guidance write grant with confirm: 'guidance' and expectedUpdatedAt; a workspace owner or admin sets it from the web app directly.

post/api/boards/{boardId}/cards

Request

Base URL: https://tre-app.com
URL: https://tre-app.com/api/boards/{boardId}/cards
Auth: HTTP bearer

Headers

Idempotency-Keystring

Opaque 1–200 character key. The same user, endpoint, and key replay the cached response for 24 hours when the request body fingerprint matches. A reused key with a different body answers 422 IDEMPOTENCY_KEY_REUSED; the same key while the original is still in flight answers 409 CONFLICT.

Request body

titlestring required

listIdstring uuid required

descriptionstring

Concise narrative context carrying only the current truth, written under fixed uppercase labels: PURPOSE: …, a dated STATUS YYYY-MM-DD: … line rewritten in place (preserve its date during editorial corrections), NEXT STEP: action → who (who acts: the name of a person, the name of a token, or waiting for <name> (<organisation>); a date only when real) — or the Italian set SCOPO / STATO / PROSSIMO PASSO. The server reads that dated line for freshness and staleness; the colon is the canonical delimiter, a dash is accepted and normalized to it. A line break is stored as \n: \r\n or a lone \r is accepted and normalized to it, so the text you read back can differ from the text you sent by those characters. History belongs in dated card comments, never in layered corrections here. Do not place a mutable list of independently trackable records or steps here; use checklist items.

colorstring

startDatestring date nullable

Start of the retained plan (not an observed start). For one exact operational deadline, pass the same ISO day in startDate and endDate. Never infer it from a reference date.

endDatestring date nullable

End of the retained plan (not an observed completion). For one exact operational deadline, pass the same ISO day in startDate and endDate.

scheduleState'unclassified' | 'planned' | 'suspended' | 'cancelled'

Meaning of the retained schedule; one server rule on every surface. Omit it: a create with a planned date is stored as planned, one without as unclassified; on update, touching a planned date promotes unclassified to planned, clearing both planned dates resets to unclassified, any other stored state is kept. Send suspended or cancelled explicitly; a non-unclassified state with both planned dates null is refused (400 BAD_REQUEST).

actualStartDatestring date nullable

Observed start, explicitly recorded from evidence. Independent of the schedule; null means unknown, never not started.

actualEndDatestring date nullable

Observed end, explicitly recorded from evidence. May fall outside the plan. Null means unknown, never incomplete.

verifiedOnstring date nullable

Day the named source was actually checked, never later than the server UTC day. Independent of updatedAt and the status date in the description; never advance for editorial work.

verificationSourcestring nullable

Source reference and scope of the last factual verification (document, record, URL or cardKey). Set or clear together with verifiedOn.

assigneeUserIdsstring[]

What the card is for: control | work | reference | decision | digest | guidance. guidance cannot be set at creation by a token (403): create the card, then promote it with update_card under a guidance write grant (Settings → API tokens → Allow guidance writes) with confirm: 'guidance' and expectedUpdatedAt; a workspace owner or admin sets it from the web app directly.

ifSimilar'create' | 'reject'

Duplicate guard over the titles on boards you can read in the workspace (trigram similarity >= 0.5, at most five): 'reject' answers 409 CONFLICT with details.similar and creates nothing; the default 'create' creates the card and returns those titles as similar in the response, so a near-duplicate is never silent.

Response

Success

idstring uuid required

boardIdstring uuid required

listIdstring uuid required

cardNumberinteger required

cardKeystring required

titlestring required

descriptionstring required

colorstring required

orderinteger required

startDatestring date nullable required

endDatestring date nullable required

scheduleState'unclassified' | 'planned' | 'suspended' | 'cancelled' required

Meaning of the retained schedule. Unclassified means its intent has not been reviewed; suspended/cancelled retain the plan for retrospective comparison.

actualStartDatestring date nullable required

Observed start, explicitly recorded from evidence. Independent of the schedule; null means unknown, never not started.

actualEndDatestring date nullable required

Observed end, explicitly recorded from evidence. May fall outside the plan. Null means unknown, never incomplete.

verifiedOnstring date nullable required

Day the named source was actually checked, never later than the server UTC day. Independent of updatedAt and the status date in the description; never advance for editorial work.

verificationSourcestring nullable required

Source reference and scope of the last factual verification (document, record, URL or cardKey). Set or clear together with verifiedOn.

createdAtstring date-time required

updatedAtstring date-time required

createdByUserIdstring uuid nullable required

assigneeUserIdsstring[] required

Changes

No recorded changes to this operation across all 1 revision of this API.