Attachments
A file of a card, of a comment, of a document or of an attachment custom property. Give the bytes with file_path (under files/) or keep them in the cloud with url; a document accepts only file_path. attached_to names what the file belongs to: a card, a comment or a document. For a card, property_ref names a custom property of type attachment, and the file is then a value of that property on that card. To show a file in a text write attachment://<external_id> with the external_id of this record, percent-encoding spaces, quotes, parentheses, brackets, < and > in it: a card text (description, history, comments) may show files attached to the card, to its comments and to its attachment properties, and the data of a document shows files attached to that document. An unknown external_id is an error, and a linked file's file_path cannot contain ", <, > or &.
A record of this entity needs records of other entities in the package: Cards or Comments or Documents.
Files in the package
List every file of this entity in resource_files of the manifest, with "resource": "attachments". An entity can have any number of files. See Bundle format.
[
{
"resource": "attachments",
"path": "resources/attachments.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.Constraints: 1–512 characters. |
attached_to | PolymorphicRef | Yes | What the file belongs to: an object with resource (cards, comments or documents) and the external_id of that record.Constraints: resource is one of cards, comments, documents. |
name | string | Yes | The name users see for the file, for example report.txt.Constraints: 1–512 characters. |
file_path | string | When url is absent | Where the file is inside the package, relative to the files/ directory, for example report.txt. No leading slash, "." or ".." segments, backslashes, NUL characters or links. It cannot start with emails/ or index/, cannot be exactly "undefined", and cannot contain % followed by two hexadecimal digits or a ~ segment: the target keeps or changes those names.Constraints: at least 1 character. Rule: Exactly one of file_path and url. |
size | integer | When file_path is given | Size of the file in bytes, for example 48213 for a 47 KB file. Required with file_path, where it is checked against the real file; optional with url.Constraints: >= 0. |
url | string | When file_path is absent | Web address of a file that stays in the cloud (http or https only), for example a shared-drive link. The file is not copied; users open it by this link. Use it instead of file_path.Constraints: at most 4098 characters; pattern ^https?://; format uri. Rule: Exactly one of file_path and url. |
author_ref | Ref<users>? refers to Users | No | The user who created the record, by the external_id of a users record, for example u-ava. Leave it out or use null when the author is unknown or has left. |
card_cover | boolean | No | Whether the file is the cover picture of the card. At most one cover per card. Default: Rule: Only when attached_to is a card; at most one cover per card. |
created_at | Timestamp | No | When the file was added. For a file of a comment it defaults to the time of the comment. Constraints: RFC 3339 with a time zone. Default: |
mime_type | string? | No | MIME type of the file, for example text/plain.Constraints: at most 128 characters. |
property_ref | Ref<custom_properties>? refers to Custom properties | No | For a file that is a value of a custom property of the card: the property, by the external_id of a custom_properties record of type attachment. Only when attached_to is a card. The file is then listed under that property, not among the attachments of the card.Rule: A property of type attachment. |
sha256 | string | No | SHA-256 checksum of the file as 64 lowercase hex characters. It is checked against the real file when given; not allowed with url.Constraints: pattern ^[0-9a-f]{64}$. |
References
Refers to
attached_to→ Cards, Comments, Documentsauthor_ref→ Usersproperty_ref→ Custom properties
Show on the entity map
Example
A record of this entity:
{
"external_id": "at-mrr-report",
"attached_to": {
"resource": "cards",
"external_id": "k-mrr"
},
"file_path": "report.txt",
"name": "report.txt",
"mime_type": "text/plain",
"size": 2,
"sha256": "565339bc4d33d72817b583024112eb7f5cdf3e5eef0252d6ec1b9c9a94e12bb3",
"author_ref": "u-ava",
"created_at": "2026-02-10T15:00:00Z"
}Rules
- exactly one of file_path and url; size goes with file_path; sha256 only with file_path.
- a file attached to a document has file_path only.
- card_cover only when attached_to is a card.
- property_ref only when attached_to is a card.
- a file of a property is not a cover.
- Among the records with the same attached_to, at most 1 can have card_cover = true.
Related entities
Cards, Comments, Custom properties, Documents, Users
Check after the import
After the import, the records of this entity can be checked on Cards › Retrieve card.
JSON Schema
attachments.json
