Bundle format

A package is a set of files. All paths are relative to the root of the package, which can be a folder or a .zip archive.

my-package/
├── meta-data.json            the manifest: which file holds which entity
├── resources/
│   ├── boards.json           a JSON array of records
│   ├── cards-0001.json       an entity can be split into any number of files
│   ├── cards-0002.json
│   └── users.json
└── files/
    └── report.txt            the bytes of an attachment

• meta-data.json is the manifest. It lists every JSON file of the package together with the entity the file holds.
• The JSON files hold the records, one entity per file. Their names and folders are up to you; the manifest tells what each holds. What you can import lists the entities, and the page of each describes its records.
• files/ holds the bytes of attachments. The folder may be absent when the package has no files. Files in it that no record names are not imported.

Each entity has a name, such as cards or card_members. It is the name used in the manifest, in the resource property of every entry of resource_files, and in the references between records.

meta-data.json names the format and lists the files of the package. It is encoded as UTF-8, and all properties are required.

An example:

{
  "profile": {
    "name": "external"
  },
  "package_id": "b6cde3fd-5d39-4fbf-85b8-c57c09e42ff6",
  "source": {
    "system": "custom",
    "namespace": "acme:tracker",
    "exported_at": "2026-10-07T09:00:00Z"
  },
  "timeline_mode": "current_state_only",
  "resource_files": [
    {
      "resource": "cards",
      "path": "resources/cards-0001.json"
    },
    {
      "resource": "cards",
      "path": "resources/cards-0002.json"
    }
  ],
  "binary_files": {
    "base_path": "files/"
  }
}

timeline_mode is one for the whole package:

Entities that you do not use are not listed. A property that the manifest does not define is refused. package_id identifies the snapshot you exported: a new export gets a new UUID. It does not make a second import update the first one.

• A file is a JSON array of records, encoded as UTF-8. Records may span several lines. A file with one JSON value per line is not accepted. A JSON file outside files/ that the manifest does not list is an error; other files outside files/ are ignored.
• An entity can have any number of files, for example cards-0001.json and cards-0002.json. List every file in the manifest. You do not split data into pages, sort it or compute service values.
• Records of different files and entities can be in any order, and a record may refer to one that comes later.
• Small values live inside a record: a text, a date, a size, the place of a card. Comments, tags, checklist items, history and links are records of their own, so a card stays small however much belongs to it.
• An empty array means no records. An entity that is absent from the package changes nothing in the target. Deleting and updating existing objects are not supported: an import only adds.

• external_id is a string of 1 to 512 characters. It is unique within its entity across all of its files, case matters, and the value is used as it is. A number is written as a string: "42". A repeated value is an error, not an update.
• A reference is the external_id of a record of another entity. The entity is fixed by the field: card_ref refers to a card. The field table of every entity tells the target.
• A reference that may point to one of several entities is an object with the name of the entity and the identifier. The prefix of an identifier, such as space:, says nothing about its entity.
• Every reference must resolve inside the package. References to identifiers of the target company are not allowed. People are matched to the members of the target company by email, and the others are invited to the target space when the import runs.
• A field that the entity does not define is refused. A field you leave out gets its documented default; null is accepted only where the field says so.

{
  "card_ref": "card:42"
}

{
  "parent_ref": {
    "resource": "spaces",
    "external_id": "space:delivery"
  }
}

Rich text and dates are objects:

{
  "format": "markdown",
  "text": "Write the **release notes**."
}

[
  {
    "precision": "date",
    "value": "2026-10-08"
  },
  {
    "precision": "date_time",
    "value": "2026-10-08T18:00:00Z"
  }
]

Formats of rich text can be mixed in one package; the product keeps them in a single format. Numbers are finite, and integers stay within the range that JavaScript represents exactly. A type followed by a question mark accepts null.

An attachment is a record of Attachments plus the bytes of the file, without base64, or a link to a file in the cloud given by url. The record names the file with file_path, a path inside files/, and declares size and, optionally, sha256. Convertinator compares them with the bytes. A path is never a URL, an absolute path or a path outside the folder: segments such as .., backslashes and links are refused. A path also cannot start with emails/ or index/, cannot be exactly undefined, and cannot contain % followed by two hexadecimal digits or a ~ segment, because the target keeps or changes those names. Case matters. Several records can refer to the same bytes.

A text shows a file of the package, such as a picture, by a link to its attachments record, written as attachment://<external_id>; an unknown identifier is an error. The text of a card (its description, its history and its comments) may show the files attached to the card, to its comments and to its property values. An external_id that contains a space, a quote, a parenthesis, a bracket, < or > must be written percent-encoded in the link. The file_path of a linked file cannot contain ", <, > or &. The data of a document shows the attachments owned by that document the same way, with attachment://<attachments external_id>.

The cards hold the current state, which is version N of a card. The history of a card is made of snapshots and actions, and the two must agree.

• With explicit, the package carries the actions of every card and, for a card above version 1, the snapshots of the versions 1 to N-1. The action of version V moves the card from snapshot V-1 to the state V; version 1 is a card_add action without a snapshot. It is the creation of the card; the import adds no other. Versions, times and places must agree with the neighbouring states. Nothing is guessed or repaired, and a conflict stops the import.
• With current_state_only, activities and card history are absent, and a card has no version or version 1.
• The actions are card_add, card_move, card_leave_board, card_join_board, card_assign_responsible, card_relieve_responsible, card_assign_member, card_remove_member. A move inside one board is one card_move with the same board in from and to. A change of board is a card_leave_board (sequence 1) and a card_join_board (sequence 2) with the same card version and time; a card_move between boards is not allowed. Actions about people are card_assign_responsible, card_relieve_responsible, card_assign_member and card_remove_member. They name the person in payload.user_ref, are not changes of the card, make no version and no snapshot, and show the card as it is at their time. A relieved responsible person stays a member, so a person who leaves the card is relieved and then removed. Comments are records of Comments, not actions.

The package is read one record at a time. A file can hold any number of records; what is limited is the size of a single record. Convertinator needs free disk space for the temporary files it writes while it compiles a large package.

Limits of single fields, such as the length of a title, are listed on the pages of the entities, for example Cards. A record that does not fit what the server accepts stops the import before anything is sent.

Convertinator checks the whole package on your computer before it sends anything. A package must be valid: a problem in the package itself stops the import in both error-handling modes. Every problem is reported with the entity, the file, the number of the record in it counted from 1, the identifier of the record and the field, when they apply. The properties that do not apply are null.

{
  "code": "reference_not_found",
  "resource": "comments",
  "file": "resources/comments.json",
  "record_index": 12,
  "external_id": "comment:12",
  "field": "card_ref",
  "message": "В пакете отсутствует карточка с external_id card:404"
}

The error codes:

The error-handling mode is chosen when the import is started, see Convertinator. It changes only what happens after the package has been accepted: in strict mode the import stops on the first error and removes what it had written, in non-strict mode it skips the rows the database refuses, where it can, and continues. Errors of the package itself are fatal in both modes.

JSON Schemas (draft-07) for the manifest and for the records of every entity. They are the schemas the checks above use:

• activities.json
• attachments.json
• boards.json
• card_blockers.json
• card_children.json
• card_history.json
• card_links.json
• card_members.json
• card_planned_relations.json
• card_time_logs.json
• card_types.json
• cards.json
• checklist_items.json
• checklists.json
• columns.json
• comments.json
• custom_directories.json
• custom_directory_records.json
• custom_properties.json
• document_comments.json
• documents.json
• folders.json
• iteration_cards.json
• iterations.json
• lanes.json
• manifest.json
• roles.json
• space_boards.json
• spaces.json
• tags.json
• tree_entity_roles.json
• user_groups.json
• users.json

• The format has no version number. The manifest names only the profile, external, and these pages describe the format as it is now.
• Before it compiles a package, Convertinator makes sure that the target installation describes the format exactly as Convertinator knows it. When the two differ, or the installation does not offer this format, the package is refused with a message and nothing is sent. Use a Convertinator release that supports your installation.

Kaiten

Addons terms of usePersonal data processing policy

If you have any questions or need help with integration feel free to write us at support@kaiten.ru