> For the complete documentation index, see [llms.txt](https://docs.cogram.com/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.cogram.com/organization-administration/data-export-package-layout.md).

# Data export package layout

What's inside a Cogram Data Export zip: top-level folders, per-entity layout, file types, and naming conventions.

A Cogram [Data Export](https://docs.cogram.com/organization-administration/data-exports.md) is delivered as one or more zip files. This page documents what's inside them, so you know exactly where to find every kind of data after unpacking.

The layout is **stable and self-describing**: every entity has a predictable folder, every binary lives next to its metadata, and customer-uploaded filenames are preserved (sanitized for filesystem safety). If you script downstream processing of the package, you can rely on the paths below.

[Continuous Data Export (S3 Push)](https://docs.cogram.com/organization-administration/continuous-data-export.md) writes this same layout for your whole organization to your own S3 bucket and keeps it up to date, with changes that keep every file's key stable: folders are named by ID only, files the zip numbers by position are named by their row ID instead (for example `attachments/<attachment_KSUID>-<filename>`, `photos/<photo_KSUID>.<ext>` and `revisions/<revision_KSUID>.<ext>`), each email has its own folder `emails/<email_KSUID>/` with `email.json`, `message.eml` and its attachments, `projects/index.json` lists the projects by name, and chat messages, prompts, Agents and workflow runs get one file each. When a record is removed in Cogram, its files stay in **Archive** mode, the default, and its state file says `delete: true`. In **Mirror** mode, Cogram deletes them. See [How the bucket differs from a zip export](https://docs.cogram.com/organization-administration/continuous-data-export.md#how-the-bucket-differs-from-a-zip-export).

## Multi-part zips

Large exports are split into multiple parts so each zip stays a manageable size. Each part is delivered with a filename like:

```
Cogram_data_export_<YYYY-MM-DD_HH-MM-SS>_part_NNN_<scope>_<window>.zip
```

* `<YYYY-MM-DD_HH-MM-SS>`: when the export was requested (UTC). Different invocations of the same scope/window never overwrite each other on disk.
* `NNN`: zero-padded part index (`000`, `001`, …) so parts sort in build order.
* `<scope>`: `all_projects` for org-wide exports, your project's `customer_project_id` (falling back to the sanitized project name) for a single-project export, or `<N>_projects` when the export covers several projects.
* `<window>`: `all_time` or `YYYY-MM-DD_to_YYYY-MM-DD`.

To reconstruct the full package, **unzip every part into the same directory**. The folder structure below is shared across parts; extracting all of them merges into one coherent tree. No single entity is split across parts.

## Top-level structure

After unzipping every part into the same folder, you get:

```
organization/
projects/
workflows/               ← only present if there are workflows in scope
```

* **`organization/`**: org-level data. The reference files are always for the whole organization regardless of the export's project scope or time window: `organization.json` (the organization's own record), `users.json` (every user: `id`, `name`, `email`, `role`), and `directory/companies.json` and `directory/contacts.json` (the organization directory). Every `user_id`, `company_id` and `contact_id` anywhere in the zip resolves against these files (a contact's `linked_user_id` can point at a user of another organization on a shared project; then it is absent from `users.json`). An **org-wide export** also carries the organization's own content here, subject to the time window: `prompts.json` (the prompt library: every saved prompt with its owner, `scope`, `tags` and `content`), `agents.json` (every customer-authored Agent with its `instructions`, `skill_ids`, `knowledge_entry_ids`, sharing flags, `model` and `reasoning_effort`; a deleted Agent is not carried), and `knowledge/` (organization-wide and personal Agent knowledge entries, see [Knowledge](#knowledge)). A project-scoped export describes that project and leaves these out.
* **`projects/`**: every entity lives under here, grouped by project. Every meeting belongs to a project; a meeting that isn't filed into a shared team project lives under its owner's personal **"My Workspace"** project folder (identifiable by `is_personal: true` in that project's `project.json`).
* **`workflows/`**: workflows sit at the root, not under any single project, because a workflow can target multiple projects. Each `workflow.json` carries a `project_ids[]` field to cross-reference back.

## Per-project folder

Each project gets its own folder under `projects/`, named:

```
projects/<prj_KSUID>__<sanitized_name>__<sanitized_customer_project_id>/
```

For example:

```
projects/prj_2abc123…__Skyrise-Tower-Phase-2__SRT-002/
```

* The **leading KSUID** is the project's unique Cogram ID: your stable identifier for joining back to the API.
* The **sanitized name** and **customer project ID** are included purely for human navigation. The `customer_project_id` is *not* unique inside an org (it's a label, not an identifier), so always disambiguate via the KSUID.
* The `__` (double underscore) separator visually marks the boundary between the KSUID and the human-readable suffix.

Inside each project folder, you'll find one subfolder per entity type that has any data in scope (subfolders are omitted when empty):

```
projects/<prj-folder>/
├── project.json
├── team.json
├── folders.json
├── schedule.json            ← only when the project has a programme
├── meetings/
├── emails/
├── documents/
├── drawings/
├── drawing_sets/
├── reports/
├── observations/
├── tasks/
├── correspondence/
├── chat/
├── knowledge/
├── transmittals/
├── submittals/
├── rfis/
└── change_orders/
```

`project.json` holds the project's metadata (name, address, customer project ID, client, project type, stage, custom fields, etc.). A project with an uploaded cover image also gets that image next to it as `cover-image.<ext>`; `cover_image_filename` in `project.json` names it. `team.json` lists the companies and contacts on the project with their function there (`project_function`); their details are in `organization/directory/`. `folders.json` lists the project's document folders with their `parent_id` and full `path`, so a document's `folder_id` resolves to where it sits in the register. `schedule.json` is the project's programme: every item (phase, activity or milestone, with its WBS key, dates, duration, status, owner and `parent_item_id` for nesting, in `position` order) under `items[]`, and every predecessor-to-successor link under `dependencies[]` (`dependency_type` is FS, SS, FF or SF; `lag_days` is negative for a lead). A programme ships whole whenever it, one of its items or one of its links changed inside the export's time window.

## Report and observation renderings are optional

Every export ships the JSON metadata, `meeting.md`, `meeting.docx`, and the raw binaries. When the export also asks for rendered documents (the **Include rendered documents** checkbox in the dialog, or `document_formats: ["docx"]` on the API request), the build writes a `.docx` next to the JSON for each field report, and for every observation its report does not already show.

Rendering reports and observations makes the build slower and the zip larger, so it is opt-in. The `.json` files are written either way: an export that asks for no rendered documents is still a complete export.

Every `.docx` is best-effort. When no template is configured, or one render fails, that single file is skipped and the build continues.

## Per-entity layout

With one exception (emails), every entity gets its own folder, named:

```
<KSUID>__<sanitized_truncated_name>/
```

Inside that folder are the entity's JSON metadata file and an optional `attachments/` subfolder for binaries:

```
projects/<prj-folder>/<entity-type>/<KSUID>__<name>/
├── <entity>.json
└── attachments/
    └── …binaries…
```

`KSUID` stable IDs let you join entities back to the API or to each other (e.g. a meeting referenced from a transmittal). The trailing name suffix is truncated to \~20 characters and sanitized: slashes, NULs, and other unsafe characters are collapsed to dashes, so a customer-uploaded title can never escape its folder.

### Meetings

```
meetings/<mtg_KSUID>__<title>/
├── meeting.json            ← metadata only (no transcript)
├── transcript.json         ← only when transcripts are enabled AND present
├── insights.json           ← only when Cogram generated insights for the meeting
├── meeting.md              ← always written, human-readable rendering
├── meeting.docx            ← always written, rendered from your org template
└── attachments/
    ├── attachment-001-<original-filename>
    ├── attachment-002-<original-filename>
    ├── photo-001.jpg
    └── photo-002.jpg
```

* **`meeting.docx`** is written for every export. It uses your organization's default `.docx` template (see [Setting a meeting template before exporting](https://docs.cogram.com/organization-administration/data-exports.md#choosing-a-meeting-template-before-exporting)), and it's best-effort: when no template is configured or a single render fails, the `.docx` is skipped and the build keeps going. The `.json` and `.md` siblings are always written.
* **`transcript.json`** is a sibling of `meeting.json` rather than a section inside it, so a directory listing immediately answers "is there a transcript?" with no JSON parsing required.
* **`insights.json`** holds the insights Cogram generated for the meeting (summary, key points, action items, and any custom insight), one entry per insight with its `building_block` name and type and the generated `output` text. It is a sibling for the same reason as the transcript, and it is absent when no insights were generated.
* **`attachments/`** holds uploaded meeting attachments and in-meeting photos only. Attachments and photos are indexed (`attachment-001-…`, `photo-001.jpg`) so two files with the same original name never collide.
* **Audio recordings are not exported.** Meeting audio stays inside Cogram by policy; the exported transcript, `meeting.md`, and `meeting.docx` are the user-facing meeting payload.

A meeting that isn't filed into a shared project lives under its owner's personal **"My Workspace"** project folder (`projects/<workspace-folder>/meetings/…`), the same internal layout as any other meeting.

### Emails: flat `.eml` files

Emails are the **one exception** to the per-entity-folder rule. They ship as flat RFC-822 `.eml` files inside `emails/`, with **attachments embedded inline** in the message body:

```
emails/<YYYY-MM-DD>_<HHMMSS>_<safe-subject>_<email_KSUID>.eml
```

Each `.eml` opens in any standard mail client (Outlook, Apple Mail, Thunderbird) with all original headers, body, and attachments intact. The filename leads with the date+time so a directory listing sorts chronologically.

There is **no JSON sidecar** for emails: the `.eml` is the complete record. (This mirrors how email is universally archived elsewhere.)

### Documents

```
documents/<doc_KSUID>__<title>/
├── document.json
└── attachments/
    ├── <original-filename>    ← the current version's binary
    └── versions/
        ├── 001-<version-filename>
        └── 002-<version-filename>    ← every other version's binary
```

The current binary under `attachments/` keeps its original filename (sanitized). `document.json` lists the version history under `versions[]` (version number, revision code, note, status, size, who uploaded it); each entry's `filename` names its binary (the zip entry carries the sanitized form), and `is_current` marks the version the document shows, whose binary is the document's own file. Every other version sits under `attachments/versions/`, numbered so they sort in order, under the name it was uploaded with.

### Drawings

```
drawings/<drw_KSUID>__<title>/
├── drawing.json
└── attachments/
    ├── revision-001.pdf
    ├── revision-002.pdf
    └── revision-003.pdf
```

One file per revision, numbered so revisions sort and are unambiguous. Cogram prefers the original PDF when available, falling back to a rendered image for legacy revisions. **Thumbnails are not exported**: they're a UI optimization, not customer data.

A separate `drawing_sets/` folder lists Cogram's customer-defined drawing groupings:

```
drawing_sets/<set_KSUID>__<name>/
└── drawing_set.json
```

### Reports

```
reports/<rpt_KSUID>__<title>/
├── report.json
└── report.docx             ← only when rendered documents were requested
```

Reports have no binary attachments: the JSON is the whole record. Reports, observations and transmittals carry their assignee (`assignee`, `assignee_role`, and the `assignee_user_id`, `assignee_contact_id` or `assignee_company_id` it resolves to). Custom field values are inlined into `report.json` rather than living in a sibling folder: single-value fields under `field_report_type_field_values`, and every cell of a table field under `field_report_type_table_cells` (group by `field_report_type_field_id`, then `row_index`, to rebuild a table).

`report.docx` uses the default export template of the report's type. A report whose type has no template gets `report.json` only.

### Observations

```
observations/<obs_KSUID>__<title>/
├── observation.json
├── observation.docx        ← only when rendered documents were requested,
│                             and only when no report.docx already carries it
└── attachments/
    ├── photo-001.jpg
    ├── photo-002.jpg
    └── …
```

`observation.docx` is skipped only when the observation's field report got a `report.docx` that lays its observations out: that file already contains it. A standalone observation gets its own file, and so does one whose report shipped without a `.docx` (its type has no template) or whose report template does not show observations at all.

Photos are exported at full resolution. Indexed filenames (`photo-001.jpg`, `photo-002.jpg`, …) avoid collisions with camera-default filenames.

### Tasks

```
tasks/<pbi_KSUID>__<title>/
└── task.json
```

Project tasks (the project board). `task.json` carries the task's title, body, status, priority, due date, assignee, the meeting it came from (`source_meeting_id`), and its full change history inlined as `history[]`: one entry per change with who made it, what triggered it, every field's previous and new value, and any comment. Meeting action items that were moved to the board point here through `migrated_to_board_item_id` in `meeting.json`.

### Correspondence

```
correspondence/<corrt_KSUID>__<subject>/
├── thread.json
└── messages/
    └── <corrm_KSUID>.eml       ← only for messages Cogram archived
```

The message thread behind each RFI, submittal, transmittal and change order. `thread.json` says which item it registers (`registered_as`: type and id, resolving to that item's own folder), lists the parties (reviewers, approvers, submitters, assignees, each resolving to `organization/directory/contacts.json` through `contact_id`, with their receipt state) and the messages in send order (a draft sorts by its creation time) with their addressees and attached documents (`document_id` resolves to the project's `documents/`, `drawing_revision_id` to a revision in `drawings/`; `document_version_id` names a version of that document, which a later phase exports). A message that Cogram archived as an `.eml` names it in `eml_filename` and the file sits under `messages/`. `comments` lists your team's internal comments on the item, oldest first, with the author and mentioned users resolving to `organization/users.json`. A deleted comment is not exported.

### Chat

```
chat/<pcc_KSUID>__<channel-name>/
├── channel.json
├── messages.json
└── attachments/
    └── <pca_KSUID>-<original-filename>
```

Project chat, one folder per channel. `channel.json` is the room (`name`, and `archived_at` when it was archived; its history still ships). `messages.json` lists the channel's messages in send order: author (`author_user_id` resolves against `organization/users.json`), the markdown `body`, the editor's `rich_body` when the message was written in the rich composer, mentions, `edited_at`, the reactions (`user_id` and `reaction`) and the attachments (`filename` as uploaded, `attachment_filename` as it sits under `attachments/`, prefixed with the attachment's KSUID so two uploads of one name never collide). A deleted message is not exported. A ranged export carries the messages sent inside the window, in every channel that had one; an untouched channel with no message in the window is left out.

### Knowledge

```
knowledge/<kn_KSUID>__<title>/
├── entry.json
└── attachments/
    └── <attachment-filename>    ← only for a FILE entry
```

Agent knowledge: the notes and files the Agent reads. `entry.json` carries `scope` (`PROJECT` under the project's folder; `ORG` and `USER`, the creator's personal entries, under `organization/knowledge/`), `kind` (`NOTE`, with the markdown in `body_text`; or `FILE`, with the upload's name in `filename` and the binary under `attachments/` as `attachment_filename` (the sanitized form), plus its `mime_type`, `size_bytes`, `content_sha256` and the `extracted_content` Cogram indexed), the creator, and where the entry came from (`source`, `source_thread_id`, `source_ref`). An Agent's `knowledge_entry_ids` in `organization/agents.json` resolve against these entries.

### Transmittals

```
transmittals/<tmt_KSUID>__<subject>/
└── transmittal.json
```

Each transmittal recipient entry carries the receipt state (`acknowledged_at`, `first_viewed_at`, `first_downloaded_at`, each with a `_verified` flag that is true when a signed-in recipient did it) and its `standing_role`. Transmittals reference documents by their KSUID. The actual document binaries live under `projects/<prj-folder>/documents/`; no copies are made.

### Submittals and RFIs (Procore-synced)

When your project is connected to Procore, submittals and RFIs are included with both Cogram's wrapper metadata (workflow status, the Cogram Automatic Review, response state) and the verbatim Procore raw object:

```
submittals/<sub_KSUID>/
├── submittal.json
└── attachments/
    ├── submittal-attachment-001-<filename>
    ├── approver-<approver_KSUID>-attachment-001-<filename>
    └── external-review-<inv_KSUID>-attachment-001-<filename>

rfis/<rfi_KSUID>/
├── rfi.json
└── attachments/
    ├── question-<q_KSUID>-attachment-001-<filename>
    ├── answer-<a_KSUID>-attachment-001-<filename>
    └── external-review-<inv_KSUID>-attachment-001-<filename>
```

The filename prefix (`submittal-`, `approver-`, `question-`, `answer-`, `external-review-`) tells you exactly which part of the submittal or RFI lifecycle each binary belongs to. The owning parent's KSUID is embedded in the filename for full traceability.

Both JSON files carry the fields Cogram tracks on the item itself, next to the verbatim Procore object in `procore_data`: `title`, `number`, `due_date`, the CSI spec section (`spec_csi_division`, `spec_csi_section`), `assignee_user_id`, the AI draft response (`ai_draft_response`, `ai_draft_status`), the drawing reference (`drawing_number`), the disciplines (`disciplines`), and for submittals `revision`, `package_label` and `previous_revision_id` (the revision an emailed resubmission revises). An RFI or submittal that was created from an email rather than synced from Procore has `procore_data: null`; its identity is in `subject` and `number`, and `source_email_id` points at the `.eml` it came from. Attachment entries carry `creator_id` and the `extracted_text` Cogram indexed from the file.

Cogram only ships attachment binaries that it actually downloaded from Procore. If a Procore-only attachment was never mirrored locally, its metadata still appears in the parent JSON but no binary file is written.

### Change orders

```
change_orders/<co_KSUID>/
├── change_order.json
└── attachments/
    └── external-review-<inv_KSUID>-attachment-001-<filename>
```

One folder per change order. `change_order.json` carries:

* What it is: `type` (`pco`, `co` or `ccd`), `number`, `subject`, `contractor` and `disciplines`.
* The money and the time: `amount` and `currency`, and `schedule_impact_days`. `amount` is a decimal string such as `"12500.00"`, so no precision is lost. An unpriced change order has `null` for both `amount` and `currency`.
* Where it stands: `review_status` says whose court it is in (`received`, `with_consultants`, `with_owner`, `in_our_court` or `issued`). `outcome` says what was decided (`approved`, `revise_resubmit`, `rejected` or `void`), and is `null` until a decision is recorded. `review_status_changed_at` and `review_status_changed_by_id` say when either last changed and who changed it. `commercial_status` is `unpriced`, `estimated`, `proposed` or `agreed`. `owner_decision` holds the owner's words.
* Who has it: `assignee_user_id` and `creator_id` resolve against `organization/users.json`. `ball_in_court` is free text.
* Dates: `date_received`, `due_date` and `execution_date`.
* Execution: `signed_document_id` resolves to the project's `documents/`. A change order executed outside Cogram has `outside_cogram_attestation` instead.
* Where it came from: `source_email_id` points at the `.eml` it was filed from. It is `null` for a change order that someone entered by hand, and after the email is deleted.

`revisions[]` lists the issued revisions by `revision_number`, each with `issued_at`, `note`, `issued_by_id` and the `document_id` of the issued document. A revision has no amount of its own: the change order's `amount` is the only total.

`external_reviews[]` lists the reviewers the change order was forwarded to, with the same fields as on a submittal or RFI, plus `audience`: `owner` or `consultants`. Each review's files ship under `attachments/` with the `external-review-` prefix: the files the sender attached when forwarding, and the files the reviewer uploaded. `uploaded_by` in the review's `attachments[]` says which.

The messages and the documents sent with them are in the change order's thread under `correspondence/`. `thread_id` names that thread, and the thread's `registered_as` points back at the change order. The documents themselves ship once, under `documents/`.

A ranged export includes a change order when the change order, one of its revisions or one of its external reviews changed inside the time window.

### Workflows

```
workflows/<wf_KSUID>__<name>/
└── workflow.json
```

Workflows sit at the root because a workflow targets one or more projects via `project_ids[]`. Workflow runs are inlined into `workflow.json` rather than written as sibling files. `project_ids[]` is only authoritative when `project_selection_mode` is `MANUAL`; a role-based or event-driven workflow leaves it empty and picks its projects at run time, so a project-scoped export includes every workflow that ran for one of its projects (see `runs[].project_id`) or is owned by one (`owner_project_id`), with all of its runs.

## Identifying example / demo data

Every new Cogram organization is seeded with an **example project**, *"Example Project: Skyrise Tower"*, plus sample meetings, emails, drawings, reports, and observations, so you can explore the product before your real data lands. This example data **is included in exports**. To tell it apart from your real data (and filter it out), use the `is_dummy` flag:

* **JSON entities** carry an **`is_dummy`** boolean: `true` means Cogram-generated example data, `false` means your own data. It's present in `project.json`, `meeting.json`, `drawing.json`, `report.json`, and `observation.json`.
* **`project.json`** additionally carries **`is_personal`**: `true` for a personal workspace (e.g. your default *"My Workspace"*) as opposed to a shared team project. This is independent of `is_dummy`: a personal project can be real (`is_dummy: false`).
* **Emails** have no JSON sidecar, so the same signal rides as an RFC-822 header: every `.eml` carries **`X-Cogram-Is-Dummy: true`** or **`false`** (alongside other `X-Cogram-*` metadata headers: `X-Cogram-Email-Id`, `X-Cogram-Conversation-Id` for the mail provider's thread key when known, `X-Cogram-Mailbox-User-Id` for the user whose mailbox filed it, `X-Cogram-Filed-At`, and the filing decision headers).

To exclude all example data in one pass, drop any entity where `is_dummy` is `true` (or, for emails, where `X-Cogram-Is-Dummy` is `true`). Because example data is grouped under the example project's folder, you can also skip that project's folder wholesale, but the per-entity flag is the reliable signal.

## Filename and path safety

Cogram aggressively sanitizes customer-uploaded names before they become parts of a path:

* Anything outside `[A-Za-z0-9._-]` is collapsed to a single dash.
* Leading and trailing dots/dashes are stripped (so `../foo` and `..` can never reach a parent directory).
* The human-readable suffix on each entity folder is truncated to \~20 characters (30 for project names) so deeply nested paths stay under typical filesystem limits when extracted.

The stable **KSUID** at the start of each entity folder is the part you should rely on programmatically; the sanitized name suffix is purely for human navigation.

## Putting it together

A complete export of a single project named "Skyrise Tower" with one meeting and one drawing, requested **with** rendered documents, might look like:

```
Cogram_data_export_2026-05-20_14-32-15_part_000_SRT-002_2026-01-01_to_2026-05-20.zip
└── projects/prj_2abc…__Skyrise-Tower__SRT-002/
    ├── project.json
    ├── meetings/mtg_3def…__Weekly-OAC-2026-/
    │   ├── meeting.json
    │   ├── transcript.json
    │   ├── meeting.md
    │   ├── meeting.docx
    │   └── attachments/
    │       ├── attachment-001-agenda.pdf
    │       └── photo-001.jpg
    └── drawings/drw_4ghi…__A-101-Floor-Plan/
        ├── drawing.json
        └── attachments/
            ├── revision-001.pdf
            └── revision-002.pdf
```

Every path is deterministic from the entity's type and KSUID, so once you've unpacked a few exports the layout becomes second nature, and trivial to drive from a script.


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation by asking a question.

Perform an HTTP GET request on the following URL with the `ask` and `goal` query parameters:

```
GET https://docs.cogram.com/organization-administration/data-export-package-layout.md?ask=<question>&goal=<user_goal>
```

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is what the user is ultimately trying to achieve, the reason they need the answer. Sharing it helps GitBook give you a better, more relevant answer. A goal is most helpful when it describes the outcome the user wants rather than restating the question. For example, with `ask=how do I create an API token`, a goal like `automate deployments from our CI pipeline` lets GitBook tailor the answer to that use case.

The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.
