Bundles & App Kits

What Are Bundles?

A bundle is a portable snapshot of workspace components. It can contain projects, agents, automations, templates, media, and Taskade Genesis app source.

You can move bundles between workspaces, accounts, and environments. Bundles support app sharing, backups, and community App Kits.

Bundles come in two flavors:

Bundle endpoints are part of the Action API v2. Authenticate with a personal access token.

Export requires bundle permission for the space. Import limits depend on your plan. See Plan Limits.

What's Included in a Bundle

API Reference

Export a Bundle (JSON) — v1

See the generated API reference for this endpoint’s parameters and response schema.

Export a Bundle (ZIP / .tsk) — v1

See the generated API reference for this endpoint’s parameters and response schema.

A successful response streams the binary file. Errors return the standard JSON error object.

Import a Bundle (JSON) — v1

See the generated API reference for this endpoint’s parameters and response schema.

Import a Bundle (ZIP / .tsk) — v1

See the generated API reference for this endpoint’s parameters and response schema.

Export a bundle (JSON) — Action API v2

POST /api/v2/exportBundle returns the full SpaceBundleData object (no binary media).

curl -X POST https://www.taskade.com/api/v2/exportBundle \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{ "spaceId": "SPACE_ID" }'

const res = await fetch("https://www.taskade.com/api/v2/exportBundle", {
  method: "POST",
  headers: {
    Authorization: `Bearer ${process.env.TASKADE_TOKEN}`,
    "Content-Type": "application/json",
  },
  body: JSON.stringify({ spaceId: "SPACE_ID" }),
});
const { item: bundleData } = await res.json();

Response:

{
  "ok": true,
  "item": {
    "version": "1",
    "name": "Sales CRM",
    "description": "Pipeline + outreach agent",
    "items": {
      "proj_abc": { "type": "space-bundle-project-item", "projectId": "proj_abc", "root": { } },
      "agent_xyz": { "type": "space-bundle-agent-item", "agentId": "agent_xyz", "template": { } }
    }
  }
}

Import a bundle (JSON)

POST /api/v2/importBundle installs a SpaceBundleData object into a target workspace.

curl -X POST https://www.taskade.com/api/v2/importBundle \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{ "workspaceId": "WORKSPACE_ID", "bundleData": { "version": "1", "items": { } } }'

Response reports what was created:

{
  "ok": true,
  "item": {
    "id": "WORKSPACE_ID",
    "projectCount": 3,
    "flowCount": 1,
    "agentCount": 2,
    "templateCount": 0,
    "mediaCount": 0,
    "appCount": 1
  }
}

The JSON import skips media items. Use ZIP or .tsk to transfer media.

Import always creates new resources. It never overwrites existing projects or agents.

Export / import as ZIP (.tsk)

For full-fidelity transfer including media, use the binary endpoints:

# Export as a binary archive. format is "zip" (default) or "tsk".
curl -X GET "https://www.taskade.com/api/v2/bundles/SPACE_ID/export/zip?format=tsk" \
  -H "Authorization: Bearer YOUR_TOKEN" \
  --output workspace.tsk

# Import a .tsk / .zip archive (raw binary body, max 50 MB)
# Content-Type: application/zip, application/octet-stream, or application/x-tsk
curl -X POST "https://www.taskade.com/api/v2/importBundleZip?workspaceId=WORKSPACE_ID" \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -H "Content-Type: application/zip" \
  --data-binary @workspace.tsk

The SpaceBundleData Schema

The JSON bundle is a flat map of items keyed by id:

interface SpaceBundleData {
  version: "1";
  name?: string;
  description?: string;
  items: Record<string, SpaceBundleDataItem>;
}

// Every item carries these two base fields.
interface SpaceBundleDataItemBase {
  rank: string;
  dependsOn?: string[];
}

type SpaceBundleDataItem = SpaceBundleDataItemBase & (
  | { type: "space-bundle-project-item";    projectId: string; root: object; preferences?: object; pinnedAt?: string }
  | { type: "space-bundle-template-item";   projectId: string; root: object; preferences?: object; pinnedAt?: string }
  | { type: "space-bundle-agent-item";      agentId: string;   template: object }
  | { type: "space-bundle-agent-team-item"; agentTeamId: string; name: string; data?: object; agentIds: string[] }
  | { type: "space-bundle-flow-item";       flowId: string;    template: object }
  | { type: "space-bundle-app-item";        appId: string;     files: object; branding?: object }
  | { type: "space-bundle-media-item";      mediaId: string }
);

Agent team items

agentIds on an agent-team item holds source agent ids. The installer remaps every id through the same id map it uses for the other items.

The installer drops a member whose agent did not come along in the bundle. As a result, a partial bundle yields a smaller team, not a dangling membership.

Export an agent team together with every agent it names.

The .tsk Format

A .tsk file is a ZIP archive with a manifest and type-based directories:

manifest.json          # { version, exportedAt, spaceId, spaceMetadata, name?, description? }
projects/{id}.json
templates/{id}.json
agents/{id}.json
automations/{id}.json
apps/{id}/…             # Genesis app source as a real directory tree
media/{mediaId}/metadata.json
media/{mediaId}/{originalFilename}

Two manifest versions exist. Version 1.0 stores app source as one JSON object.

Version 1.1, the current export version, stores app source as a directory tree. Import accepts both versions.

Agent-team items travel only in the JSON bundle body. The .tsk archive writer has no directory for them yet: it writes projects, templates, agents, automations, apps, and media. An archive import therefore rebuilds every agent but not the team that groups them.

Plan Limits

Imports are checked per item type against your plan:

There is no separate "bundle import" entitlement. The importer checks each item type it finds. As a result, a bundle of only projects, templates, and media imports on any plan.

An over-limit import returns 402 with code: "PAYMENT_REQUIRED" and a message naming the limit.

The public ZIP import is limited to 50 MB per archive.

Rate limits differ by API version. The v1 /api/v1/bundles/* routes carry a tighter budget than ordinary reads and writes, counted per IP address. The v2 bundle operations shown above carry no bundle-specific budget. They use the shared public-API budget, counted per IP address.

Use Cases

• Share apps across workspaces — export from one workspace, import into another.
• Back up before big changes — snapshot a workspace and restore later.
• Distribute through the community — publish a .tsk so others import a working app in seconds.
• Template creation — build once, export, and reimport for fresh copies.

Next Steps

• Action API v2 Reference — the full v2 operation set
• Authentication — get your API token
• Outbound MCP — call a remote MCP server's tools from an automation in your imported app