Public APIs - bulk import and export items definition (Preview)

[evaAlroy]

If you haven’t already, check out Arun Ulag’s hero blog “FabCon and SQLCon 2026: Unifying databases and Fabric on a single, complete platform” for a complete look at all of our FabCon and SQLCon announcements across both Fabric and our database offerings. 

---

What are bulk import and export APIs?

Every Fabric item—whether a Notebook, Report, Semantic Model, Pipeline, or KQL Dashboard—has an underlying item definition: a portable, structured payload containing the item’s full configuration and content encoded in Base64. Bulk Import & Export APIs enables:

• Export item definitions individually or in bulk from any workspace.
• Import (create) new items from definitions into a target workspace.
• Update existing item definitions in place for continuous deployment.
• List and paginate through all items in a workspace for batch processing.

These APIs surface through the standard Fabric REST API, use Microsoft Entra ID (Azure AD) authentication, and support both delegated (user) and service principal (app-only) access modes. The result is a first-class programmatic interface for managing Fabric content at enterprise scale.

Why APIs matter

Previously, moving Fabric items between workspaces, backing up analytics content, or building repeatable deployment pipelines required a combination of manual UI steps, workarounds, and non-standard scripting. Bulk Import & Export APIs change that fundamentally.

Before: friction at every step

• Workspace migration required manual recreation of items one by one.
• No supported backup mechanism for Fabric items definition.
• CI/CD pipelines lacked a reliable way to deploy Fabric content programmatically.
• Metadata scanning required individual API calls per item—slow and unscalable.
• Template-based provisioning was impossible without manual intervention.

After: programmable, scalable, repeatable

• Export a full workspace manifest with a single paginated API.
• Import hundreds of items into a new workspace in one automated flow.
• Drive Dev → Test → Prod promotion from your existing DevOps pipeline.
• Back up items definition on a schedule and restore.
• Scan items definition in bulk for lineage, governance, and audit purposes.

Key Scenarios

Workspace migration

Moving items across workspaces, tenants is one of the most requested Fabric capabilities. Bulk Export APIs let you serialize an entire workspace into a portable JSON manifest, then import it into any target workspace. This is valuable for:

• Migrating to workspaces during organizational restructuring or mergers
• Replicating environments across tenants for partner or subsidiary scenarios
• Cloning a production workspace to create an isolated test environment

Because item definitions are standard JSON, the manifest can be stored, versioned, inspected, and transformed before re-import—giving you full control over what lands in the target workspace.

CI/CD and DevOps integration

Integrate Fabric item management into your existing DevOps pipelines. Export items definition to a Git repository, apply changes through pull requests, and deploy to staging or production workspaces on merge. The Update Definition API enables a true sync pattern—create items that don’t exist and update those that do—without deleting and recreating.

A typical CI/CD flow:

1. Developer commits notebook / report change to Git

2. PR review + automated validation pipeline runs

3. On merge: CI pipeline calls POST /items (create) or POST /updateDefinition (update)

4. Staging workspace is updated automatically

5. After QA approval: same pipeline promotes to Production

Metadata backup and recovery

Schedule periodic bulk items definition exports to capture the full state of your workspace as versioned JSON manifests. Store them in Azure Blob Storage, a Git repository, or any durable storage system. If a workspace is accidentally modified or deleted, re-import the latest manifest to restore all items definition to a known-good state.

• Zero additional tooling required—pure REST API calls
• Definitions are human-readable and diff-friendly JSON
• Bulk import creates all items in a single automated pass

Environment promotion (Dev → Test → Prod)

Promote Fabric items through multiple stages with confidence. Export from Dev, transform parameterized values such as connection strings, workspace references, or data source bindings, and import into Test or Prod. The batch APIs give you full control over what gets deployed and when.

Metadata scanning and lineage analysis

One of the most compelling scenarios is at-scale scanning. Tools that analyze report definitions to discover data lineage—such as which Semantic Model columns are used in each report—can now extract hundreds of definitions in bulk instead of one at a time, dramatically reducing scan time and enabling real-time governance dashboards.

Template libraries and self-service provisioning

Maintain a catalog of reusable item definitions: standardized notebooks, reports, pipelines, or KQL dashboards that teams can quickly instantiate into new workspaces.

• Governance team maintains approved, validated item templates.
• New projects request a workspace; automation provisions it fully configured.
• All items are traceable to source templates via definition provenance.

API endpoints overview

All endpoints use the Fabric REST API base URL: Fabric API reference

Export (Read) Operations

Method	Endpoint	Description
POST	/workspaces/{workspaceId}/items/bulkExportDefinitions?beta=true	Export an item’s full definition as Base64-encoded parts. May return 202 for LRO.

Import (Write) Operations

Method	Endpoint	Description
POST	/workspaces/{workspaceId}/items/bulkImportDefinitions?beta=true	Create/Update an existing item’s definition in-place. Ideal for CI/CD sync.

Required permissions

• Import:
  1. The caller must have a contributor or higher role for the workspace.
  2. The caller must have read and write permissions for each item being updated.
• Export"
  1. The caller must have a contributor or higher role for the workspace.
  2. When exporting all items in a workspace: Only the Items that the caller has both read and write permissions for are exported.

How it works: The LRO pattern

Operations on large or complex items—Items with heavy content or Reports with many pages—may not complete synchronously. The Fabric REST API uses a Long-Running Operation (LRO) pattern for these cases, returning HTTP 202 Accepted with an operation ID to poll.

# Step 1: Request the definition

POST /workspaces/{workspaceId}/items/bulkImportDefinitions?beta={beta}

-> HTTP 202 Accepted

-> Location: /operations/{operationId}

# Step 2: Poll until complete

GET /operations/{operationId}

-> { "status": "Running" } ... retry after

-> { "status": "Succeeded" } -> proceed

# Step 3: Retrieve result

GET /operations/{operationId}/result

-> { "definition": { "parts": [...] } }

Each definition part is a Base64-encoded file. Parts are identified by path (e.g., notebook-content.py, report.json) and payloadType (InlineBase64). Decoding the parts gives you the raw content file, which you can inspect, transform, or version in Git.

Limitations

As with all Preview features, there are limitations to be aware of. The team is actively working to address these before being made Generally Available.

Limitation	Details
Rate Limiting	The API enforces rate limits. Include 0.5–1s delays between requests and handle 429 responses with exponential backoff.
Payload	Maximum request size is 128 MB
Bulk Export/Import Items definition	Only items supported by both Fabric Git Integration and single item definitions APIs are applicable
Bulk Export/Import Items definition	Semantic model V1 is not supported
Cross-Tenant References	Items may contain tenant-specific references (connection strings, data source bindings) that must be manually updated after cross-tenant import.
Display Name Uniqueness	Item display names must be unique within a workspace per item type. Duplicates will fail with DuplicateDisplayNameAndType
Breaking Changes Possible	The API surface is stable for evaluation but may undergo minor changes before GA. Monitor the Fabric REST API release notes.

Prerequisites

Requirement	Details
Microsoft Entra ID App	Registered app with Item.ReadWrite.All and Workspace.Read.All permissions.
Fabric Workspace	At least one workspace with items to export, and a target workspace for import.
Workspace Role	Contributor or higher on both source and target workspaces.

Resources

• Fabric Items API Reference—Fabric Items CORE APIs
• Item Definition Reference—Item Definition
• Long-Running Operations Guide—Long running operation
• Microsoft Entra ID Documentation—Microsoft Entra ID

Share your feedback!

Your feedback is essential in guiding future improvements. Please share your experience with the engineering team:

• What scenarios are you using the Bulk APIs for?
• What additional item types do you need support for?
• What limitations are most impactful for your workflow?

Share feedback through the Fabric Ideas Portal at Ideas Portal or through your Microsoft account representative.