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 access to the source workspace. Import creates resources in the target workspace.

What a Bundle Includes

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", "rank": "a0", "projectId": "proj_abc", "root": { } },
      "agent_xyz": { "type": "space-bundle-agent-item", "rank": "a1", "agentId": "agent_xyz", "template": { } }
    },
    "metaData": {
      "agentIcons": [],
      "projectIcons": [],
      "automationLogoUrls": []
    }
  }
}

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": { }, "metaData": {} } }'

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 rejects a bundle that contains media items with 400. Remove the media items first, or 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 a full-fidelity transfer that includes 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 as a raw binary body.
# 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>;
  metaData?: {
    agentIcons: string[];
    projectIcons: string[];
    automationLogoUrls: string[];
  };
}

// 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}/…             # Taskade Genesis app source as a directory tree
agent-teams/{id}.json
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.

Version 1.1 archives can include agent teams under agent-teams/{id}.json. The importer remaps their source agent IDs in the same way as JSON bundle imports.

Import Behavior

Import creates new resources. It does not overwrite matching projects, agents, automations, or apps.

The importer validates each item against the target workspace's current access and limits. If an item cannot be created, use the returned error code to select the next step. Do not parse the human-readable message.

The Action API checks the target workspace's plan before an import creates anything. A bundle that goes over a limit returns 402 with code: "PAYMENT_REQUIRED":

A bundle of only projects, templates, and media imports on every plan. A ZIP or .tsk upload can be at most 50 MB.

Export requires permission to create a bundle in the source workspace.

Read the live X-Rate-Limit-* response headers for the current request budget. See Rate Limits.

Use Cases

• Share apps across workspaces. Export from one workspace. Import into another.
• Back up before big changes. Snapshot a workspace. Restore it later.
• Distribute through the community. Publish a .tsk so others can import a working app.
• Create templates. Build once. Export the bundle. Import it for a fresh copy.

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