Cards
The current state of a card: where it is now and what it says. Everything that grows around a card is a separate resource that points back at it: tags, members, checklists, comments, files, links, history and activities. A card needs a board, a column of that board and a type; without lane_ref it goes to the first lane. The cards of one column keep the order of their records, so they stand on the board in that order. Keep the record small and put large collections in their own resources.
A record of this entity needs records of other entities in the package: Boards; Card types; Columns; Users.
Files in the package
List every file of this entity in resource_files of the manifest, with "resource": "cards". An entity can have any number of files. See Bundle format.
[
{
"resource": "cards",
"path": "resources/cards-0001.json"
},
{
"resource": "cards",
"path": "resources/cards-0002.json"
}
]Fields
| Field | Type | Required | Description |
|---|---|---|---|
external_id | string (ExternalId) | Yes | Your own identifier of the record, for example k-mrr, unique within the resource across all of its files and case sensitive. Other records refer to this one by it. The import also keeps it as the external id of the object it creates.Constraints: 1–512 characters. |
board_ref | Ref<boards> refers to Boards | Yes | The board the card is on. Give the external_id of a boards record. |
column_ref | Ref<columns> refers to Columns | Yes | The column the card is in now. It must be a column of the board in board_ref.Rule: A column of the board in board_ref. |
created_at | Timestamp | Yes | When the card was created, for example 2026-01-12T09:30:00Z.Constraints: RFC 3339 with a time zone. |
owner_ref | Ref<users> refers to Users | Yes | The person the card is for, shown in the card header as its owner (requester); usually whoever created the card, for example the reporter of a task. Give the external_id of a users record. |
title | string | Yes | The card's name, for example Monthly recurring revenue. Up to 1024 characters.Constraints: 1–1024 characters. |
type_ref | Ref<card_types> refers to Card types | Yes | The card type, by the external_id of a card_types record. |
archived | boolean | No | Whether the record is archived, that is hidden from active lists but kept. The default is false. Default: |
asap | boolean | No | Marks the card as urgent so it stands out on the board. Default: |
completed_at | Timestamp? | No | When the work on the card was completed. Constraints: RFC 3339 with a time zone. |
description | RichText? | No | The card's main text; give the format with the text. |
due_date | DateValue? | No | The card's deadline. Either a day, {"precision": "date", "value": "2026-03-31"}, or a moment, {"precision": "date_time", "value": "2026-03-31T17:30:00Z"}. A day stays a day; no time is added. A moment keeps only its hours and minutes: the card is due at the end of that minute (17:30:59), as when someone sets a due time in the app.Constraints: a date without time stays a date; it is never turned into midnight. |
estimate_workload | number? | No | Estimated work in hours, for example 12.5, with at most two decimal places. Constraints: >= 0; <= 99999.99. Rule: At most two decimal places. |
expires_later | boolean | No | Marks due_date as a "no later than" deadline: the work may finish earlier, but not after that date. In the app it is the "Expires later" option of the due date, and the deadline on the card shows a mark. It matters only when the card has a due_date; the default is false.Default: |
key | string | No | The key the card is known by now, as PREFIX-NUMBER, for example KPI_MRD_X7Q4-1. NUMBER is a whole number from 1 to 2147483647 without leading zeros, so KPI-7 is valid and KPI-007 is not. PREFIX is the key of the space or folder that issues it, so exactly one space or folder must have it. Leave it out for a card without a key. Keys are unique. Earlier keys of a card cannot be imported.Constraints: at least 3 characters; pattern ^[A-Z][A-Z0-9_]{1,15}-(?:[1-9][0-9]{0,8}|1[0-9]{9}|20[0-9]{8}|21[0-3][0-9]{7}|214[0-6][0-9]{6}|2147[0-3][0-9]{5}|21474[0-7][0-9]{4}|214748[0-2][0-9]{3}|2147483[0-5][0-9]{2}|21474836[0-3][0-9]|214748364[0-7])$. Rule: PREFIX is the key of a space or folder. |
lane_ref | Ref<lanes>? refers to Lanes | No | The lane the card is in. It must be a lane of the board in board_ref; without it the card goes to the first lane of the board, that is the first lanes record of that board.Default: Rule: A lane of the board in board_ref. |
planned_end | DateValue? | No | Planned end of the work. Allowed only together with planned_start.Constraints: a date without time stays a date; it is never turned into midnight. Rule: Only together with planned_start. |
planned_start | DateValue? | No | When work on the card is planned to start; with planned_end it places the card on the timeline of its space. Give a day, {"precision": "date", "value": "2026-04-01"}, which starts at the start hour of the space's timeline (9:00 by default), or a moment, {"precision": "date_time", "value": "2026-04-01T10:00:00Z"}. planned_end needs it, and a dependency in card_planned_relations needs both dates on both cards.Constraints: a date without time stays a date; it is never turned into midnight. |
properties | Map<ExternalId, value> refers to Custom directory records or Custom properties or Users | No | The values of the custom properties of the card. Each key is the external_id of a custom_properties record and each value has the shape the type of that property decides: text for string, multiline_string, email, url and phone; a number for number; true or false for checkbox; a date value for date, for example {"precision": "date", "value": "2026-03-01"} or, with a time, {"precision": "date_time", "value": "2026-04-15T09:00:00Z"}; the external_id of an option (an item of options) of the same property for select, and a list of them, each once, for multi_select; the external_id of a users record for user, and a list of them, each once, for multi_user; the external_id of a custom_directory_records record of the directory of the property for directory; a whole number from 1 to the count of the property for a vote with a rating, and one emoji of the set for a vote with a set of emojis. A property of type attachment has no value here: its files are attachments with property_ref. A property the card has no value for is left out.Rule: The value matches the type of the property. |
size | object? | No | Card size: a number with an optional unit and display text, for example 3, SP, "3 SP". A size can also be text only, for example {"display": "XL"}; value or display must be given. |
size.display | string | Depends on the variant | The size as the card shows it, for example 3 SP, or XL for a T-shirt size. Give value, display or both: without display the card shows value and unit together; a size that is not a number, such as XL, needs only display. Charts count only value.Constraints: at most 267 characters. |
size.value | number | Depends on the variant | Numeric size. |
size.unit | string | No | Unit of value, for example SP for story points or h for hours. Without display the card shows the value and the unit together, for example 3 SP.Constraints: at most 256 characters. |
subscriber_refs | Ref<users>[] refers to Users | No | The users who follow the card and get notified about its changes and moves, by the external_id of users records, for example ["u-ava", "u-omar"]. Each user at most once.Constraints: items are unique. Default: |
tag_refs | Ref<tags>[] refers to Tags | No | The tags on the card, by the external_id of tags records, for example ["t-revenue"]. Each tag at most once.Constraints: items are unique. Default: |
updated_at | Timestamp | No | When the record was last changed, for example 2026-02-10T15:30:00Z.Constraints: RFC 3339 with a time zone. Default: |
updated_by_ref | Ref<users>? refers to Users | No | The user who made the last change, by the external_id of a users record. Leave it out or use null when unknown. |
References
Referenced by
- Activities:
card_ref - Attachments:
attached_to - Card blockers:
blocker_card_ref,card_ref - Card children:
child_card_ref,parent_card_ref - Card history:
card_ref - Card links:
card_ref,linked_card_ref - Card members:
card_ref - Card planned relations:
predecessor_card_ref,successor_card_ref - Card time logs:
card_ref - Checklists:
card_ref - Comments:
card_ref - Iteration cards:
card_ref
Cards
Refers to
board_ref→ Boardscolumn_ref→ Columnslane_ref→ Lanesowner_ref→ Usersproperties→ Custom directory records, Custom properties, Userssubscriber_refs→ Userstag_refs→ Tagstype_ref→ Card typesupdated_by_ref→ Users
Show on the entity map
Example
A record of this entity:
{
"external_id": "k-mrr",
"title": "Monthly recurring revenue",
"description": {
"format": "markdown",
"text": "The sum of all active subscription fees, normalised to one month.\n\n**Includes:** subscriptions, add-ons.\n\n**Excludes:** one-off services."
},
"board_ref": "b-kpi",
"column_ref": "c-live",
"lane_ref": "l-core",
"type_ref": "ct-metric",
"owner_ref": "u-ava",
"created_at": "2026-01-12T09:30:00Z",
"completed_at": "2026-02-10T15:30:00Z",
"due_date": {
"precision": "date",
"value": "2026-03-31"
},
"size": {
"value": 5,
"unit": "SP",
"display": "5 SP"
},
"estimate_workload": 12.5,
"planned_start": {
"precision": "date",
"value": "2026-01-19"
},
"planned_end": {
"precision": "date",
"value": "2026-02-27"
},
"key": "KPI_MRD_X7Q4-1",
"tag_refs": [
"t-revenue",
"t-finance"
],
"properties": {
"cp-priority": "sv-priority-high",
"cp-cadence": [
"sv-cadence-monthly"
],
"cp-target": 1250000,
"cp-go-live": {
"precision": "date",
"value": "2026-03-01"
},
"cp-automated": true,
"cp-source": "Billing warehouse",
"cp-definition": "Annual plans are divided by twelve.\nTrials are not counted.",
"cp-dashboard": "https://dashboards.example.com/mrr",
"cp-steward-email": "finance-data@example.com",
"cp-phone": "+1 555 0100",
"cp-steward": "u-ava",
"cp-stakeholders": [
"u-ava",
"u-omar"
],
"cp-provider": "rec-nimbus",
"cp-impact": 5,
"cp-mood": "🚀"
},
"subscriber_refs": [
"u-ava",
"u-omar"
],
"updated_at": "2026-02-10T15:30:00Z",
"updated_by_ref": "u-ava"
}Rules
- planned_end only together with planned_start.
- The value of key must be unique.
Related entities
Activities, Boards, Card history, Card members, Card types, Columns, Comments, Custom properties, Lanes, Tags
Check after the import
After the import, the records of this entity can be checked on Cards › Retrieve card.
JSON Schema
cards.json
