fabric-rest-api

# Fabric REST API patterns Base URL: `https://api.fabric.microsoft.com/v1` ## Finding Workspaces and Items 1. List workspaces: `GET /v1/workspaces` → paginate with `continuationToken` 2. Find by name: iterate results until `displayName` matches 3. List items in workspace: `GET /v1/workspaces/{wsId}/items?type={ItemType}` 4. Type-specific endpoints return extra `properties` (connection strings, etc.): `GET /v1/workspaces/{wsId}/{lakehouses|warehouses|notebooks|semanticModels|...}` 5. Cross-workspace discovery (no `wsId` in path): `POST /v1/catalog/search` with `{ "search": "Sales Revenue", "pageSize": 50, "filter": "Type eq 'Lakehouse'" }` → permission-trimmed items (each with `id` GUID + `workspaceId`) across your whole accessible estate, by catalog metadata (name/description/workspace name). OneLake Catalog Search API (Preview, March 2026); same capability as the `fab find` CLI verb (fabric-cli skill) and the Fabric Core MCP server's `search_catalog` tool. ## Sensitivity Labels on Item Responses As of March 2026 GA, `List Items` / `Get Item` / `Update Item` responses include a `sensitivityLabel` property on the `Item` object when the item has a Purview information-protection label applied: ```json { "id": "34fa05fc-e7ba-435a-b1ab-63534b6aa4f9", "displayName": "PDF_Env", "type": "Environment", "workspaceId": "2ae4b0b9-895b-4676-bfcd-125b1f20e34d", "sensitivityLabel": { "sensitivityLabelId": "4922deb9-fe99-4f4f-971c-9bdf556ec6a9" } } ``` **Field name gotcha — spec vs runtime drift.** The MS Learn `Item` definition page documents this inner field as `id`, but the live API returns `sensitivityLabelId`. Verified across 233 labeled items in 7 workspaces (May 2026) on both `GET /v1/workspaces/{wsId}/items` and `GET /v1/workspaces/{wsId}/items/{itemId}` — 233/233 use `sensitivityLabelId`. Trust the runtime, not the schema page. The `sensitivityLabel` object carries **only the label GUID** — there is no `displayName` / `name` on the response. Resolving the GUID to a human-readable label name requires a separate call (Microsoft Graph `/security/informationProtection/sensitivityLabels` or Purview). The `sensitivityLabel` field is omitted entirely on unlabeled items. **Read-only on these endpoints.** The `Update Item` PATCH body schema (`UpdateItemRequest`) accepts only `displayName` and `description` — it does NOT accept a `sensitivityLabel` field. To apply, change, or remove labels programmatically, call the admin APIs `POST /v1/admin/items/bulkSetLabels` / `bulkRemoveLabels` — the path is under `items` even though Learn files the reference under Labels (verified 2026-09-12). They require `Tenant.ReadWrite.All` + Fabric admin role, are **`User` only** (service principals and managed identities are rejected), cap at ≤ 25 req/hour, ≤ 2000 items/request, and report status per item rather than all-or-nothing. Coverage audits and the write gate: fabric-catalog-governance skill. ## Item IDs: Runtime vs logicalId Every Fabric item has **two** GUIDs, and they are NOT interchangeable. Using the wrong one is a leading cause of `PowerBIEntityNotFound` / `EntityNotFound` errors when referencing items by ID from a pipeline, notebook parameter, REST call, or Variable Library variable. | Identifier | Source | Resolved by | Use for | |---|---|---|---| | **Runtime item ID** | Fabric portal URL (`…/items/{guid}`); `GET /v1/workspaces/{wsId}/items` response `id` | The Fabric engine at execution time | Pipeline activity `notebookId` / `pipelineId`, Variable Library values consumed at runtime, REST `/items/{id}` calls, `notebookutils.runtime.context` lookups | | **logicalId** | `.platform` file → `config.logicalId` | Git integration / source-control tooling | `.platform` payloads, PBIP + pbir-cli + `fab import` source-control operations | **The relationship is exact, not a resemblance: for a portal-created item, `logicalId` is the runtime item ID with its 16 bytes reversed.** Confirmed 2026-09-03 against `GET /v1/workspaces/{wsId}/items` over 19 workspaces — 21 of 21 resolvable reversals hit a real item with the same `displayName` and `type`, none hit a different item, and no raw `logicalId` was itself an item ID. Reversal is an involution, so it round-trips. This is also why a `logicalId` so often has a version nibble that is not `4`: a reversed v4 GUID does not look like a v4 GUID (79 reversals, zero failures, across two private repos and ~20 public ones spanning tenants). **The precondition is load-bearing.** It holds for items **created in the portal**. An item authored *git-first* — committed as files, then synced into the workspace — carries a fresh client-side v4 that encodes nothing, and reversing it yields a GUID that is not an item ID. Classifying items by whether their oldest commit is a Fabric portal sync (`Committing N items from workspace …`) separated the two forms 76 of 76 with no cross-cases. Knowing the derivation does **not** make the values interchangeable — Fabric will NOT silently fall back from one to the other at runtime. It means you can *derive* one offline instead of calling the API for it. **Rule of thumb:** if the value ends up in a payload the Fabric engine reads (pipeline definition, Variable Library value, REST body), use the **runtime item ID**. If it ends up in a file the Git integration layer reads (`.platform`, PBIP manifest), use the **logicalId**. To fetch the runtime ID: - Portal: open the item, copy the trailing GUID from the URL - REST: `GET /v1/workspaces/{wsId}/items` → find by `displayName`, return `id` - `fab` CLI: `fab get "Workspace.Workspace/Item.ItemType" -q id` - **Offline, from a committed `.platform`** — reverse the `logicalId`, no credential needed. Portal-created items only; verify once against any of the three above before relying on it in a script. ```python import uuid rev = lambda g: str(uuid.UUID(bytes_le=uuid.UUID(g).bytes_le[::-1])) rev("7c4d1e88-93af-4b02-9d61-2fa50c7e3b14") # synthetic # -> '0c7e3b14-2fa5-9d61-4b02-93af7c4d1e88' ``` **Variable Library specifically:** variable string values are passed **verbatim** to consumers — they are NOT resolved against `.platform` logicalIds. Always store the runtime item ID. ## Long-Running Operations (LRO) Many mutating calls return `202 Accepted` with `Location` and `x-ms-operation-id` headers. - Poll: `GET /v1/operations/{operationId}` → `status: Running|Succeeded|Failed` - Get result: `GET /v1/operations/{operationId}/result` (after Succeeded) - Honor `Retry-After` header. Use exponential backoff if absent. **Item creation is 201-OR-202, not "always sync" or "always LRO"** — the same endpoint can return either depending on current provisioning load. Always branch on status code; never assume sync. A function that only inspects the body on 2xx will silently return before the item is queryable whenever Fabric picks the LRO path, racing any immediately-downstream call that expects the new item to exist. Canonical `create_*` pattern for Fabric item creation: ```python def create_item(access_token: str, item_name: str, ...) -> str: """Return the newly-created item's GUID. Handles 201 and 202.""" workspace_id = notebookutils.runtime.context["currentWorkspaceId"] endpoint = f"https://api.fabric.microsoft.com/v1/workspaces/{workspace_id}/<items_path>" headers = { "Authorization": f"Bearer {access_token}", "Content-Type": "application/json", } body = {"displayName": item_name} response = requests.post(endpoint, headers=headers, json=body) if response.status_code == 201: # Synchronous creation — the body is the created item item_id = response.json()["id"] elif response.status_code == 202: # LRO — poll to completion, then fetch /result for the item body result_response = poll_lro(response, headers, return_result=True) item_id = result_response.json()["id"] else: response.raise_for_status() return item_id ``` The `poll_lro` helper honors `Retry-After`, polls `Location` until the operation reaches `Succeeded`, and (with `return_result=True`) fetches `/result` to return the actual created-item body. ## Definition APIs Item types with content (Notebook, SemanticModel, Report, DataPipeline) accept a `definition` object containing `format`, `parts`, and base64-encoded payloads. ``` PATCH /v1/workspaces/{wsId}/items/{itemId}/definition[?updateMetadata=true] ``` - **`?updateMetadata=true` controls whether `.platform` is honored.** Without it, any `.platform` part in `definition.parts` is silently ignored — `displayName`/`description` won't update. - Conversely, setting `?updateMetadata=true` *requires* a `.platform` part. The flag without `.platform` returns 400. - For content-only updates (typical), omit the flag. - Notebook-specific alternative: `POST /v1/workspaces/{wsId}/notebooks/{id}/updateDefinition` — same body shape. - `getDefinition` is a POST with empty body (`'{}'`) — bare POST returns HTTP 411 Length Required. Result is fetched via the LRO's `{Location}/result` URL (note the `/result` suffix). - Per-item-type specifics live in `fabric-tmdl-api` (semantic models), `fabric-spark` (notebooks, SparkJobDefinition, Environment, Lakehouse shortcuts), `fabric-eventhouse` (Eventhouse, KQLDatabase), `fabric-variable-library` (VariableLibrary), and pbir-cli/pbir-report-workflow (Report). ### Support matrix | Item Type | Formats | Main parts | |---|---|---| | Notebook | `ipynb` (default), `FabricGitSource` | `notebook-content.ipynb` or `.py`/`.sql`/`.scala`/`.r` | | DataPipeline | *(default)* | `pipeline-content.json` | | SemanticModel | `TMSL`, `TMDL` (prefer) | `definition/database.tmdl`, `model.tmdl`, `tables/*.tmdl`, `definition.pbism` | | Report | `PBIR-Legacy`, `PBIR` (prefer) | `definition/report.json`, `version.json`, `pages/*`, `definition.pbir` | | Lakehouse | `LakehouseDefinitionV1` | `lakehouse.metadata.json` (+ optional `shortcuts.metadata.json`) | | SparkJobDefinition | `SparkJobDefinitionV1`, `SparkJobDefinitionV2` | `SparkJobDefinitionV1.json` (+ `Main/`, `Libs/` for V2) | | Environment | *(default — set `null`)* | `Libraries/PublicLibraries/environment.yml`, `Setting/Sparkcompute.yml` | | VariableLibrary | **omit `format` entirely** | `variables.json`, `settings.json`, `valueSets/<name>.json` | | Eventhouse | `JSON` | `EventhouseProperties.json` | | KQLDatabase | `JSON` | `DatabaseProperties.json` (+ optional `DatabaseSchema.kql`) | | Other (KQLDashboard, CopyJob, Dataflow, Eventstream, MirroredDatabase, GraphQLApi, etc.) | varies | see [MS schema index](https://github.com/microsoft/json-schemas/tree/main/fabric/item) | **`definition.pbir` `byConnection` only**: Fabric REST API supports only `byConnection` semantic-model references in PBIR. The `byPath` form (used locally with pbir-cli) is not accepted by the Fabric REST endpoints — switch to `byConnection` before deploying. ## Job Execution ``` POST /v1/workspaces/{wsId}/items/{itemId}/jobs/instances?jobType={jobType} ``` | Item Type | jobType | |---|---| | Notebook | `RunNotebook` | | DataPipeline | `Pipeline` | | SparkJobDefinition | `SparkJob` | | SemanticModel | `Refresh` | **Gotcha**: `DefaultJob` does NOT work for most item types. Use the type-specific value above. ## Job Scheduling ``` POST /v1/workspaces/{wsId}/items/{itemId}/jobs/{jobType}/schedules ``` URL path is `/jobs/{jobType}/schedules` — NOT `/jobs/instances/schedules`. Body: ```json { "enabled": true, "configuration": { "startDateTime": "2026-01-01T06:00:00.000Z", "endDateTime": "2027-01-01T06:00:00.000Z", "type": "Daily", "interval": 1, "localTimeZoneId": "UTC", "times": ["06:00"] } } ``` `enabled`, `configuration.startDateTime`, `configuration.endDateTime`, and `configuration.type` are all required. Omitting `endDateTime` returns 400. `type` ∈ `Daily | Weekly | Monthly`; `Weekly` also requires `weekDays` (array of day names). List with `GET .../schedules`; delete with `DELETE .../schedules/{scheduleId}`. ## Rate Limiting `429 Too Many Requests` includes a `Retry-After` header (seconds). Honor it; never tight-loop. Use exponential backoff with jitter when `Retry-After` is absent. | Category | Approximate limit | |---|---| | Admin APIs | Varies by endpoint — 200/hour (List Items, List Workspaces, activity events), 25/min (domains, tenant settings, role assignments), 25/hour (bulk labels). Check the endpoint's own Throttling section | | OneLake (ADLS) | Standard Azure Storage throttling, per workspace | | Warehouse TDS | ~128 concurrent connections (varies by SKU) | **Two limits apply to every call.** A per-identity **unified quota** of 200 calls/min is evaluated *and* the endpoint's own limit — most restrictive wins. Platform, Job Scheduler and Long-Running Operations APIs get separate 200/min buckets, and the 60-second window refills all at once, so bursting at the start leaves you throttled for the rest of it. A `429` carries one of two `errorCode`s: `RequestBlocked` (your request rate — honour `Retry-After`) or `CapacityLimitExceeded` (the tenant's capacity is overloaded — retrying immediately will not help). (Verified 2026-09-12.) Watch `x-ms-ratelimit-remaining-*` response headers to back off before hitting the limit. ## Capacity - `GET /v1/capacities` — list available capacities. Filter `state == "Active"`. - `POST /v1/workspaces/{wsId}/assignToCapacity` with `{ "capacityId": "..." }` — assigns workspace to capacity. - Lakehouse, Warehouse, Notebook execution, and Spark Job Definitions all require workspace capacity. Without it, item creation returns `FeatureNotAvailable`. - After assignment, verify `GET /v1/workspaces/{wsId}` shows `capacityAssignmentProgress: "Completed"` before creating capacity-dependent items. ## Pagination All list APIs use continuation-token pagination. Keep calling with `?continuationToken={value}` until the token is null. The response also includes `continuationUri` — the fully-formed next-page URL — which you can call directly without re-constructing the query string. The token itself is opaque; never modify it. ## Reference - Microsoft Learn: [Item management overview](https://learn.microsoft.com/rest/api/fabric/articles/item-management/item-management-overview) - Microsoft Learn: [Long-running operations](https://learn.microsoft.com/rest/api/fabric/articles/long-running-operation) - Microsoft Learn: [Throttling](https://learn.microsoft.com/rest/api/fabric/articles/throttling)