agentleFS
wardawgmalviciouswardawgmalvicious/agent-config/skills/fabric-core/fabric-rest-api/SKILL.md

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.

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
  1. Very specific:

    Every Fabric item has two GUIDs, and they are NOT interchangeable.

    line 54
  2. Distinctive:

    Rule of thumb: if the value ends up in a payload the Fabric engine reads (pipeline definition, Variable Library value, REST body), use the …

    line 67
  3. Very specific:

    After assignment, verify GET /v1/workspaces/{wsId} shows capacityAssignmentProgress: "Completed" before creating capacity-dependent items.

    line 335
  4. Very specific:

    All list APIs use continuation-token pagination.

    line 339

≈ “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.

Keep what fits and drop the rest. Your version, ready for your agents.
Files
SKILL.md

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 jobRead first
A token or its audience, az login or az rest, a TDS connection, or what authorizes a service principalauth.md
The Fabric CLI, fab: paths, commands, fab auth, fab apicli.md
An error code, error text or symptom, from any Fabric surfacegotchas.md, whose index names the reference or skill that owns the fix

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 (cli.md) 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:

{
  "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.

IdentifierSourceResolved byUse for
Runtime item IDFabric portal URL (…/items/{guid}); GET /v1/workspaces/{wsId}/items response idThe Fabric engine at execution timePipeline 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 assignedGit 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 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.
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's Location points at its result where there is one. commitToGit and updateFromGit answer 400 OperationHasNoResult there (2026-10-12): success, with no body.
  • 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:

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.

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=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 (semantic models, in its references/definition-api.md), fabric-spark (notebooks, SparkJobDefinition, Environment, Lakehouse shortcuts), fabric-eventhouse (Eventhouse, KQLDatabase), fabric-variable-library (VariableLibrary), and pbir-report-workflow (Report).

Support matrix

Item TypeFormatsMain parts
Notebookipynb (default), FabricGitSourcenotebook-content.ipynb or .py/.sql/.scala/.r
DataPipeline(default)pipeline-content.json
SemanticModelTMSL, TMDL (prefer)definition/database.tmdl, model.tmdl, tables/*.tmdl, definition.pbism
ReportPBIR-Legacy, PBIR (prefer)definition/report.json, version.json, pages/*, definition.pbir
LakehouseLakehouseDefinitionV1lakehouse.metadata.json (+ optional shortcuts.metadata.json)
SparkJobDefinitionSparkJobDefinitionV1, SparkJobDefinitionV2SparkJobDefinitionV1.json (+ Main/, Libs/ for V2)
Environment(default — set null)Libraries/PublicLibraries/environment.yml, Setting/Sparkcompute.yml
VariableLibraryomit format entirelyvariables.json, settings.json, valueSets/<name>.json
EventhouseJSONEventhouseProperties.json
KQLDatabaseJSONDatabaseProperties.json (+ optional DatabaseSchema.kql)
Other (KQLDashboard, CopyJob, Dataflow, Eventstream, MirroredDatabase, GraphQLApi, etc.)variessee 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/myGitCredentials answers source: Automatic, ConfiguredConnection (with a connectionId) or None; on None, set them with Update My Git Credentials first.
  • Both are long-running: 200, or 202 with Location, x-ms-operation-id and Retry-After, polled as Long-Running Operations (LRO) says, and invisible through az rest, as it also says. Learn says not to call Get Status while an update runs. One update, observed 2026-09-30, answered 202 with Retry-After: 20 and finished in under a second; its Location named a regional cluster host, not api.fabric.microsoft.com, and polling /v1/operations/{x-ms-operation-id} on the base URL worked. Polling that Location itself works too, with the same bearer, and /result appended 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 TypejobType
NotebookRunNotebook
DataPipelinePipeline
SparkJobDefinitionSparkJob
SemanticModelRefresh

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:

{
  "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.

CategoryApproximate limit
Admin APIsVaries 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. 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

Download now (ZIP)

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
What did you use it for? e.g. Reviewing pull requests in a Rails app

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.