fabric-rest-api
Skill1 starsChanged 34 days agoMITView on GitHub
Use when calling the Microsoft Fabric or Power BI REST APIs, authenticating to them or running the Fabric CLI `fab` — tokens and audiences, `az login` and `az rest`, a service principal's tenant settings and workspace roles, workspaces and items, item IDs, definitions, long-running operations, pagination, jobs and schedules, Git integration, throttling, capacity — and when troubleshooting any Fabric error: its index maps an error code or symptom, from a REST call, a Git sync, a deploy, a notebook, a warehouse or a report publish, to the reference or skill that owns the fix.
In this repository38 other files it gives its agents.
- claude/CLAUDE.mdCLAUDE.md
- CLAUDE.mdCLAUDE.md
- author-skillSkill
- drift-auditSkill
- drift-handoffSkill
- drift-updateSkill
- test-skillSkill
- triageSkill
- fabric-iqSkill
- fabric-catalog-governanceSkill
- fabric-deploySkill
- fabric-securitySkill
- fabric-variable-librarySkill
- fabric-databaseSkill
- fabric-dataflowSkill
- fabric-data-pipelineSkill
- fabric-sparkSkill
- fabric-warehouse-monitoringSkill
- fabric-warehouseSkill
- fabric-activatorSkill
- fabric-eventhouseSkill
- fabric-event-schema-setSkill
- fabric-eventstreamSkill
- fabric-realtime-dashboardSkill
- learnSkill
- fabric-semantic-model-auditSkill
- fabric-tmdlSkill
- pbip-project-structureSkill
- pbir-report-workflowSkill
- linkedin-highlightsSkill
- msix-packagingSkill
- code-reviewSkill
- commitSkill
- find-sessionSkill
- landSkill
- prune-branchesSkill
- recreate-repoSkill
- run-briefsSkill
The file
We split this skill into the rules it gives an agent
4 rules. About 0 are common, 1 is distinctive, and 3 are very specific to this project.
≈0
Common · estimate
Many files like this have a rule of this kind.
≈1
Distinctive · estimate
This author's own choices. Worth a look.
3
Very specific
Tied to their project's names, files or tools. Probably skip.
- Common
- Distinctive
- Very specific
- Very specific: line 54
Every Fabric item has two GUIDs, and they are NOT interchangeable.
- Distinctive: line 67
Rule of thumb: if the value ends up in a payload the Fabric engine reads (pipeline definition, Variable Library value, REST body), use the …
- Very specific: line 335
After assignment, verify GET /v1/workspaces/{wsId} shows capacityAssignmentProgress: "Completed" before creating capacity-dependent items.
- Very specific: line 339
All list APIs use continuation-token pagination.
≈ “Common” is an estimate: at least 1 in 5 of the 364,980 skill files we read have a rule of the same kind, not the same words. “Very specific” is our guess from the words: it names a file, a command, a setting or the project itself.
Files
Fabric REST API patterns
Base URL: https://api.fabric.microsoft.com/v1
Three jobs have a reference of their own: read it before answering one. The rest of this file is the REST API itself.
| The job | Read first |
A token or its audience, az login or az rest, a TDS connection, or what authorizes a service principal | auth.md |
The Fabric CLI, fab: paths, commands, fab auth, fab api | cli.md |
| An error code, error text or symptom, from any Fabric surface | gotchas.md, whose index names the reference or skill that owns the fix |
Finding Workspaces and Items
- List workspaces:
GET /v1/workspaces→ paginate withcontinuationToken - Find by name: iterate results until
displayNamematches - List items in workspace:
GET /v1/workspaces/{wsId}/items?type={ItemType} - Type-specific endpoints return extra
properties(connection strings, etc.):GET /v1/workspaces/{wsId}/{lakehouses|warehouses|notebooks|semanticModels|...} - Cross-workspace discovery (no
wsIdin path):POST /v1/catalog/searchwith{ "search": "Sales Revenue", "pageSize": 50, "filter": "Type eq 'Lakehouse'" }→ permission-trimmed items (each withidGUID +workspaceId) across your whole accessible estate, by catalog metadata (name/description/workspace name). OneLake Catalog Search API (Preview, March 2026); same capability as thefab findCLI verb (cli.md) and the Fabric Core MCP server'ssearch_catalogtool.
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:
{
"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; logicalId on Get Item / List Items, null when none is assigned | Git integration / source-control tooling | .platform payloads, PBIP + the 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 bydisplayName, returnid fabCLI:fab get "Workspace.Workspace/Item.ItemType" -q id- Offline, from a committed
.platform— reverse thelogicalId, no credential needed. Portal-created items only; verify once against any of the three above before relying on it in a script.
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'To fetch the logicalId, read it from the API before deriving it:
GET /v1/workspaces/{wsId}/items[/{itemId}] returns it beside id
(Get Item),
and so does fab get <item> -q logicalId. One workspace's List Items
carried it for every Git-supported item and for no SQLEndpoint or
AppBackend, matching each committed .platform (2026-10-01).
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), only where the operation has one. Learn: "Not all long running operations have a result", and a completed operation'sLocationpoints at its result where there is one.commitToGitandupdateFromGitanswer400OperationHasNoResultthere (2026-10-12): success, with no body. - Honor
Retry-Afterheader. 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:
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_idThe 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.
az rest cannot tell a 202 from a 200. It prints the body and
nothing else, and has no option of its own to show headers (Azure CLI
2.90.0, 2026-10-01), so a 202 comes back as empty output and exit 0,
Location and x-ms-operation-id unseen. On getDefinition a session
took that for an item with no definition (2026-09-24). Where a call may
answer 202, as getDefinition, a definition update or a create can,
use fab api --show_headers, which prints status_code, an empty body
as "(Empty)", and the headers, though like az rest it does not poll
(fab 1.7.0 source, 2026-10-01).
Definition APIs
Item types with content (Notebook, SemanticModel, Report, DataPipeline) accept a definition object containing format, parts, and base64-encoded payloads.
POST /v1/workspaces/{wsId}/items/{itemId}/updateDefinition[?updateMetadata=true]?updateMetadata=truecontrols whether.platformis honored. Without it, any.platformpart indefinition.partsis silently ignored —displayName/descriptionwon't update.- Conversely, setting
?updateMetadata=truerequires a.platformpart. The flag without.platformreturns 400. - For content-only updates (typical), omit the flag.
- Notebook-specific alternative:
POST /v1/workspaces/{wsId}/notebooks/{id}/updateDefinition— same body shape. getDefinitionis a POST with empty body ('{}') — bare POST returns HTTP 411 Length Required. Result is fetched via the LRO's{Location}/resultURL (note the/resultsuffix).- Per-item-type specifics live in
fabric-tmdl(semantic models, in itsreferences/definition-api.md),fabric-spark(notebooks, SparkJobDefinition, Environment, Lakehouse shortcuts),fabric-eventhouse(Eventhouse, KQLDatabase),fabric-variable-library(VariableLibrary), andpbir-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 |
definition.pbir byConnection for single-item calls: the single-item create and update-definition endpoints accept only byConnection semantic-model references in PBIR. The byPath form (used locally with the pbir CLI) is not accepted there — switch to byConnection before deploying one report. Learn's Bulk Import example, by contrast, sends a report whose definition.pbir holds "byPath": { "path": "../../MyDataset.SemanticModel" } beside that model in the same request; that path is a documentation example, unmeasured here.
getDefinition is not the Git serialization. Where Git holds a
logicalId or a relative path, a live definition can hold a runtime id or
a connection: a report's datasetReference is byConnection live and
byPath in Git, .platform's logicalId is all zeros live, and a KQL
database's parentEventhouseItemId is the eventhouse's runtime id live
and its logicalId in Git (each seen once, 2026-10-12; a dashboard's data
source differs the same way, per fabric-realtime-dashboard). Normalize
those before diffing a live item against its folder.
Git Integration APIs
A Git-connected workspace is synced to one commit while its branch may be
at another, and
Get Status,
GET /v1/workspaces/{wsId}/git/status, returns both: workspaceHead, the
commit the workspace is synced to, remoteCommitHash, the branch head, and
changes[], each carrying workspaceChange, remoteChange and
conflictType. Heads that differ, with no remoteChange on any entry,
are the normal state after a push that changes no item folder, and the
workspace still commits (observed 2026-10-01). A workspace stranded on
Git_HeadNotSynced shows differing heads too:
gotchas.md's row for that error holds its
likelier cause, how sure that is, and the missing button.
Update From Git,
POST …/git/updateFromGit, updates only the items the incoming commits
changed. It requires remoteCommitHash; workspaceHead is checked
against the service's own head, failing WorkspaceHeadMismatch, and may
be null only right after Initialize Connection. It will not start with
items in conflict and no conflictResolution, nor with incoming items
present and options.allowOverrideItems not true. So the two hashes
from git/status, and nothing else, are the safe body: it applies or it
refuses, and never overwrites. Add either field on purpose, after reading
changes[].
{ "workspaceHead": "<git/status workspaceHead>", "remoteCommitHash": "<git/status remoteCommitHash>" }- Both calls need the caller's Git credentials.
GET …/git/myGitCredentialsanswerssource:Automatic,ConfiguredConnection(with aconnectionId) orNone; onNone, set them with Update My Git Credentials first. - Both are long-running:
200, or202withLocation,x-ms-operation-idandRetry-After, polled as Long-Running Operations (LRO) says, and invisible throughaz rest, as it also says. Learn says not to call Get Status while an update runs. One update, observed 2026-09-30, answered202withRetry-After: 20and finished in under a second; itsLocationnamed a regional cluster host, notapi.fabric.microsoft.com, and polling/v1/operations/{x-ms-operation-id}on the base URL worked. Polling thatLocationitself works too, with the same bearer, and/resultappended to it fetches the result (four operations, 2026-10-12).
Commit To Git,
POST …/git/commitToGit (scope Workspace.GitCommit.All), commits by
mode: All; Selective, with items, each a logicalId or objectId;
or FileLevelSelective (preview), with itemsWithFileSelection, each
item plus selectedFiles — paths relative to the item root, forward
slashes, no wildcards, an empty list meaning every file. Pass
workspaceHead from git/status. It needs the same Git credentials and is
long-running like the two calls above. Committing only some of an item's
files can leave its definition incomplete (Learn, 2026-10-06).
Re-read git/status after Update From Git, and commit Selective.
One update of six items left two reading workspaceChange: Modified
that nobody had edited: a KQL database whose DatabaseSchema.kql held
the branch's lines in another order, and a report whose .platform
description the update had not applied (2026-10-12, cause unknown). A
mode: All commit would have written both back over the branch.
A branch move is a reconnect. Connect refuses a connected workspace
(WorkspaceAlreadyConnectedToGit) and does not sync. So push a branch
cut at git/status's workspaceHead; keep myGitCredentials'
connectionId and the old gitProviderDetails; call git/disconnect,
a POST with no body, then git/connect with those, the new branchName
and myGitCredentials (required for GitHub), then
git/initializeConnection with PreferWorkspace. On one GitHub run that
kept uncommitted work uncommitted and answered
requiredAction: CommitToGit (2026-10-12): commit Selective, as above.
Connect and Disconnect take workspace Admin, and nothing is connected
between them: script the rollback first. Connect also sets
connectionSettings.additionalRolesAuthorizedToChangeBranch to None,
admins only, unless the body passes it, and Get Connection does not
return it: pass it on every connect where non-admins switch branch.
git/status types items outside its documented enum. One call
(2026-09-30, one tenant) typed a semantic model, a Plan and a SQL
database as dataset, Planning and SQLDbNative, where Learn's
ItemType lists SemanticModel, Plan and SQLDatabase, and none of
the three (re-read 2026-10-01). Two calls on 2026-10-01 added a User
Data Functions item as FunctionSet and a report as report
(UserDataFunction, Report on Learn), and repeated dataset and
SQLDbNative. Four on 2026-10-12 added a KQL database, a notebook and a
variable library as KustoDatabase, SynapseNotebook and Variables
(KQLDatabase, Notebook, VariableLibrary). A script filtering
changes[] on documented type names
skips those items without a word, case-insensitively too. Match on
itemMetadata.itemIdentifier instead: logicalId where present, else
objectId. Learn requires one of the two, and its example of an item
added in the workspace carries only objectId; one such item on
2026-10-12 carried both, and a Selective commit took both.
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}/schedulesURL path is /jobs/{jobType}/schedules — NOT /jobs/instances/schedules. Body:
{
"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 errorCodes: 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. Filterstate == "Active".POST /v1/workspaces/{wsId}/assignToCapacitywith{ "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}showscapacityAssignmentProgress: "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
- Microsoft Learn: Long-running operations
- Microsoft Learn: Throttling
- Comprehensive MS Learn link bundle (concept / CRUD / LRO / pagination / throttling / jobs / item-specific / workspace / Git+CI/CD / MCP): references/REFERENCE.md
Does it work?
Reviews from people and from AI agents that ran it: what they used it for, and whether it worked.
No reviews yet
People and AI agents can review whether this works in practice. Say what you used it for, and whether it worked.
- It worked
- Partly
- It didn't
Using an agent? It can post a review for you after it has run the file: the MCP tool registry_write, action report. How to connect one.
Your trail
Files you open will collect here, so you can find them again.
Open two or more, and you can remix the rules you like from each into one list. Kept in this browser only.
Now do this for your own.
Bring your CLAUDE.md, AGENTS.md or skills. agentleFS shows which of your rules are common, which are yours and which only fit one project, and keeps one version your agents read everywhere.

