What Data Is Included When Exporting a Paperclip Organization: Complete 2024 Guide

Exporting a Paperclip organization creates a portable "Agent Company" bundle containing all declarative data including agents, projects, skills, issues, labels, documents, attachments, approvals, cost events, activity logs, and monitors—enabling full fidelity restoration in another instance.

Paperclip serves as the control-plane for AI-agent companies, and its export feature packages every structural and operational artifact into a self-contained zip folder. This article breaks down exactly what data gets exported, where the logic lives in the source code, and how to work with the resulting bundle.

Core Entities Exported from a Paperclip Organization

Agents and Organizational Structure

Every agent belonging to your company is exported with complete metadata. According to the generateOrgChartMermaid function in server/src/services/company-export-readme.ts (lines 22-44), each agent record includes:

• Name and slug (URL-friendly identifier)
• Role definition
• Hierarchical relationship via reportsToSlug (reporting structure)

The export preserves the complete organizational chart, enabling the Mermaid diagram generation in the bundled README.md.

Projects, Skills, and Operational Definitions

The manifest—built in the shared portability package @paperclipai/shared—captures:

Entity	Fields Exported
Projects	name, description, custom fields
Skills	name, description, source locator, source type

These definitions establish the operational blueprint your agents use to execute work.

Issues (Tasks) and Their Complete State

Issues represent the core work items in Paperclip. The collectExportFidelityCounts function in server/src/services/export-fidelity.ts (lines 22-55) retrieves comprehensive issue data:

• Full issue objects and their labels
• Attachments and documents
• Work-product references
• Blocker relationships
• Monitoring settings

This ensures no task state is lost during migration.

Relational Data and Advanced Entity Types

The same fidelity function captures interconnected data that preserves operational context:

• Labels — definitions and every issueLabelReferences mapping
• Issue Relations — "blocks" relationships between issues (issueBlockerRelations)
• Documents & Attachments — issueDocuments and issueAttachmentCount
• Approvals — approvalCount for gated workflows
• Cost Events — costEventCount for tracking compute and operational spend
• Activity Log — activityLogEntries for audit history
• Issue Monitors — issueMonitors with scheduled check configuration and nextCheckAt timestamps

The Export Bundle Structure

When you trigger an export, Paperclip assembles a zip folder containing:

paperclip-export.zip
├── manifest.json           # CompanyPortabilityManifest (all entities as JSON)

├── README.md               # Human-readable overview with Mermaid org chart

├── images/
│   └── org-chart.png       # Rendered organization hierarchy

└── assets/                 # Optional folders

    ├── documents/          # Raw files referenced by issues

    └── attachments/        # Uploaded file attachments

The fidelity report (ExportFidelityReport) is embedded in the manifest, recording exact counts of each entity type and flagging any warnings about missing or inconsistent data. The report schema lives in @paperclipai/shared/portability-fidelity and is constructed by buildExportFidelityReport in server/src/services/export-fidelity.ts (lines 71-78).

How to Export and Inspect Organization Data

Trigger an Export via REST API

curl -X POST \
  -H "Authorization: Bearer <YOUR_AGENT_API_KEY>" \
  https://localhost:3100/api/companies/<COMPANY_ID>/export \
  -o paperclip-export.zip

Replace <YOUR_AGENT_API_KEY> and <COMPANY_ID> with your credentials. The endpoint streams the complete zip bundle.

Inspect the Manifest Locally

unzip -p paperclip-export.zip manifest.json | jq .

The JSON structure follows this shape:

{
  "companyId": "c_12345",
  "agents": [],
  "projects": [],
  "skills": [],
  "issues": [],
  "labels": [],
  "relations": [],
  "documents": [],
  "attachments": [],
  "approvals": [],
  "costEvents": [],
  "activityLog": [],
  "monitors": []
}

Import into Another Paperclip Instance

pnpm exec paperclipai company import /path/to/paperclip-export.zip

The CLI command in cli/src/commands/company-import.ts reads manifest.json, recreates all entities, and writes accompanying assets to the target database.

Source Code Architecture for Exports

File	Responsibility
server/src/services/export-fidelity.ts	collectExportFidelityCounts gathers entity counts; buildExportFidelityReport constructs the validation report
server/src/services/company-export-readme.ts	generateOrgChartMermaid builds hierarchy diagrams; generateReadme produces human-readable documentation (lines 71-72)
packages/shared/portability-fidelity.ts	Schema definitions for ExportFidelityReport and warning logic
server/src/routes/company.ts	HTTP endpoint handling for the export stream
cli/src/commands/company-import.ts	Consumes exported zips and restores organizations with full fidelity

This architecture ensures all relational data—not just primary entities—is captured, allowing downstream Paperclip instances to recreate companies with preserved task state, permissions, and historical activity.

Summary

• Primary entities: Agents, projects, skills, and issues form the structural core of every Paperclip export
• Relational completeness: Labels, blocker relations, monitors, and references maintain operational context
• Audit and cost data: Activity logs, approvals, and cost events preserve governance and spend tracking
• Asset portability: Documents and attachments are bundled for complete restoration
• Validation built-in: The ExportFidelityReport validates data completeness and flags inconsistencies
• Full round-trip: Exports from server/src/services/ and imports via cli/src/commands/company-import.ts enable zero-loss migration

Frequently Asked Questions

Does a Paperclip export include private agent configurations?

Yes. The export captures all agent metadata including role definitions and reporting hierarchies as implemented in generateOrgChartMermaid at server/src/services/company-export-readme.ts. However, external API keys or runtime secrets are typically excluded from declarative exports—check your specific deployment's secret management configuration.

Can I export a single project instead of the entire organization?

The current export implementation targets full-company portability through the /api/companies/<COMPANY_ID>/export endpoint. For project-level extraction, you would need to filter the resulting manifest.json manually or request a feature extension through the Paperclip maintainers.

How does the fidelity report detect missing data?

The buildExportFidelityReport function in server/src/services/export-fidelity.ts (lines 71-78) compares actual counts against expected relationships—flagging, for example, issues referencing non-existent labels or agents with broken reportsToSlug links. Warnings are embedded in the ExportFidelityReport schema defined in @paperclipai/shared/portability-fidelity.

What happens to issue monitors during import?

Issue monitors export with full configuration including scheduled check intervals and nextCheckAt timestamps. The cli/src/commands/company-import.ts restoration process recreates these monitors in the target instance, preserving automated monitoring behavior.

{
  "mcpServers": {
    "instagit": {
      "command": "npx",
      "args": ["-y", "instagit@latest"]
    }
  }
}