Documents
A document of the knowledge base, such as a handbook page. Its place is given by parent_ref: a space, a folder or another document (no cycles). The text is data; files are attachments attached to the document and shown with attachment://<external_id>, and comments are document_comments. Without sort_order a document goes after the siblings that have one; siblings without it keep the order in which their files are listed in resource_files, and then the order of their records.
A record of this entity needs records of other entities in the package: Documents or Folders or Spaces.
Files in the package
List every file of this entity in resource_files of the manifest, with "resource": "documents". An entity can have any number of files. See Bundle format.
[
{
"resource": "documents",
"path": "resources/documents.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. |
data | RichText | Yes | The document text; give the format with the text. Show an attached file with attachment://<external_id> of an attachments record attached to this document. |
parent_ref | PolymorphicRef | Yes | Where the document sits: an object with resource (spaces, folders or documents) and the external_id of that record.Constraints: resource is one of spaces, folders, documents. |
title | string | Yes | Title of the document, for example North Star metrics.Constraints: 1–256 characters. |
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. |
created_at | Timestamp | No | When the record was created, with a time zone, for example 2026-01-12T09:30:00Z.Constraints: RFC 3339 with a time zone. Default: |
sort_order | number | No | Position among the records next to it; a smaller number goes first and it must be greater than 0. Left out, the record goes to the end of the list. Constraints: > 0. 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
- Attachments:
attached_to - Card links:
linked_document_ref - Document comments:
document_ref - Documents:
parent_ref - Folders:
parent_ref - Spaces:
parent_ref - Tree entity roles:
tree_entity_ref
Documents
Show on the entity map
Example
A record of this entity:
{
"external_id": "d-north-star",
"parent_ref": {
"resource": "folders",
"external_id": "f-definitions"
},
"title": "North Star metrics",
"data": {
"format": "markdown",
"text": "# North Star metrics\n\nMeridian tracks three company-level numbers."
},
"sort_order": 1,
"author_ref": "u-ava",
"updated_by_ref": "u-liam",
"created_at": "2026-01-08T10:00:00Z",
"updated_at": "2026-02-01T12:00:00Z"
}Rules
- parent_ref builds one tree together with Documents, Folders, Spaces; no record can be its own ancestor.
Related entities
Attachments, Document comments, Folders, Spaces
Check after the import
After the import, the records of this entity can be checked on Documents › Retrieve document.
JSON Schema
documents.json
