# Bundle import

> Import a JSON bundle (agents, automations, projects, templates, apps) into a workspace. The bundle is validated against the SpaceBundleData v1 schema and all items are installed into the target workspace. Media items are not supported — use the ZIP import or upload media separately via the media endpoints after import.

- Source: https://www.taskade.com/docs/rest/bundle-import
- Section: REST API
- Endpoint: `POST /bundles/{workspaceId}/import` (API v1)
- Index of all pages: https://www.taskade.com/docs/llms.txt

## POST `/bundles/{workspaceId}/import`

Import a JSON bundle (agents, automations, projects, templates, apps) into a workspace. The bundle is validated against the SpaceBundleData v1 schema and all items are installed into the target workspace. Media items are not supported — use the ZIP import or upload media separately via the media endpoints after import.

Base URL: `https://www.taskade.com/api/v1`

### Authentication

Send a personal access token or an OAuth 2.0 access token as a bearer token. Create a personal access token at [taskade.com/settings/api](https://www.taskade.com/settings/api).

```http
Authorization: Bearer tskdp_your_token_here
```

### Parameters

| Name | In | Type | Required | Description |
| --- | --- | --- | --- | --- |
| `workspaceId` | path | `string` | Yes | The target workspace ID to import the bundle into. |

### Request body

`application/json`

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `bundleData` | `object` | Yes | The Workspace DNA bundle to import (SpaceBundleData v1). |
| `bundleData.version` | `string` | Yes | Bundle format version. Allowed values: `1`. |
| `bundleData.items` | `object` | Yes | Map of bundle items keyed by ID. Each item has a `type` field: space-bundle-flow-item, space-bundle-project-item, space-bundle-agent-item, space-bundle-template-item, space-bundle-media-item, space-bundle-app-item, space-bundle-agent-team-item. Agent-team items name their members by SOURCE agent id in `agentIds`; the importer remaps them and drops any member whose agent is not also in the bundle. |

A nested field marked Yes is required whenever its parent object is present.

### Example request

```bash
curl -X POST "https://www.taskade.com/api/v1/bundles/<workspaceId>/import" \
  -H "Authorization: Bearer $TASKADE_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"bundleData":{"version":"1","items":{}}}'
```

### Responses

#### `200` — Bundle imported

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `ok` | `boolean` | Yes | — |
| `item` | `object` | Yes | — |
| `item.id` | `string` | Yes | Unique identifier for the bundle installation. |
| `item.projectCount` | `number` | Yes | Number of projects installed. |
| `item.flowCount` | `number` | Yes | Number of automations installed. |
| `item.agentCount` | `number` | Yes | Number of agents installed. |
| `item.templateCount` | `number` | Yes | Number of templates installed. |
| `item.mediaCount` | `number` | Yes | Number of media files installed. |
| `item.appCount` | `number` | Yes | Number of apps installed. |

#### `4XX` — Error description

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `ok` | `boolean` | Yes | — |
| `message` | `string` | Yes | — |
| `code` | `string` | Yes | — |
| `statusMessage` | `string` | Yes | — |
| `featureId` | `string` | No | The plan entitlement the request needs, set on some PAYMENT_REQUIRED errors. |

### Errors

Errors return an `ok: false` envelope. Rate limiting returns `429` with `x-rate-limit-limit`, `x-rate-limit-remaining` and `x-rate-limit-reset` headers. `x-rate-limit-reset` is the number of seconds until the window reopens. `Retry-After` is not sent, so schedule retries from `x-rate-limit-reset`; retrying sooner will fail again.

```json
{ "ok": false, "message": "Unauthorized", "code": "UNAUTHORIZED" }
```

Rate limits for this version: enforced per endpoint; ceilings are not published and can change without notice. A `429` response carries `x-rate-limit-limit`, `x-rate-limit-remaining`, and `x-rate-limit-reset` (seconds until the window reopens). Back off from those headers rather than hardcoding numbers. Bundle import and export run under tighter limits than regular reads and writes, so schedule bulk transfers accordingly. See [Rate limits](https://www.taskade.com/docs/getting-started/rest-api-guide#rate-limits).