Telemetry — MANDATORY. Every

api.fabric.microsoft.com

call must carry

x-ms-fabric-skill: powerbi-report-management

(

az rest

:

--headers "x-ms-fabric-skill=powerbi-report-management"

), including every LRO poll,

fabric_lro

and retry. Snippets omit it — add it anyway.

CRITICAL NOTES

1. To find the workspace details (including its ID) from workspace name: list all workspaces and, then, use JMESPath filtering
2. To find the item details (including its ID) from workspace ID, item type, and item name: list all items of that type in that workspace and, then, use JMESPath filtering

az rest

Scope: Report item CRUD and definition management only. For report layout authoring (pages, visuals, filters, formatting), use

powerbi-report-authoring

.

Boundary: This skill transports PBIR definitions to and from Fabric. PBIR content authoring remains owned by

powerbi-report-authoring

.

az

az rest

az login

jq

base64

[Convert]::ToBase64String()

FromBase64String()

Agent check — verify before first operation:

bash

az version 2>/dev/null || echo "INSTALL: https://learn.microsoft.com/cli/azure/install-azure-cli"

Shared patterns — workspace and item resolution, pagination, and LRO polling are documented in the common skill library. Read COMMON-CLI.md § Finding Workspaces and Items in Fabric before using the CRUD operations below.

• Permissions: Viewer workspace role
• Scopes:

  Workspace.Read.All

  or

  Workspace.ReadWrite.All

az rest --method get \
  --resource "https://api.fabric.microsoft.com" \
  --url "https://api.fabric.microsoft.com/v1/workspaces/$WS_ID/reports" \
  --query "value[].{name:displayName, id:id, description:description}" \
  --output table

continuationToken

• Permissions: Read permissions on the report
• Scopes:

  Report.Read.All

  or

  Report.ReadWrite.All

az rest --method get \
  --resource "https://api.fabric.microsoft.com" \
  --url "https://api.fabric.microsoft.com/v1/workspaces/$WS_ID/reports/$REPORT_ID"

• Permissions: Read and write permissions on the report
• Scopes:

  Report.ReadWrite.All

  or

  Item.ReadWrite.All

• Limitation: Blocked for reports with encrypted sensitivity labels

format=PBIR

report.json

RESPONSE=$(az rest --method post \
  --resource "https://api.fabric.microsoft.com" \
  --url "https://api.fabric.microsoft.com/v1/workspaces/$WS_ID/reports/$REPORT_ID/getDefinition?format=PBIR" \
  --verbose 2>&1)

Note:

getDefinition

often returns

202 Accepted

(LRO). Check the Long-Running Operations section to extract the operation ID and poll for the result before decoding.

undefined

• Permissions: Contributor workspace role
• Scopes:

  Report.ReadWrite.All

  or

  Item.ReadWrite.All

undefined

create-report.json

> **PowerShell** — use `Get-ChildItem -Recurse -File` to walk the directory and
> `[Convert]::ToBase64String([System.IO.File]::ReadAllBytes($_.FullName))` to
> encode each file (instead of `base64 | tr -d '\n'`).

> **Important**: `definition.pbir` is always required. The directory walk above
> includes every file under `./report-definition/` automatically — make sure
> your local directory mirrors the full PBIR layout (top-level files, plus all
> `pages/<page>/page.json` and `pages/<page>/visuals/<visual>/visual.json`
> files) before encoding.

• Permissions: Read and write permissions on the report
• Scopes:

  Report.ReadWrite.All

  or

  Item.ReadWrite.All

undefined

update-definition.json

> **Critical**: `updateDefinition` replaces the **entire** definition. Include
> ALL parts — modified and unmodified. Omitting parts deletes them.

Optional query parameter `?updateMetadata=true` updates item metadata from
`.platform` file if included.

• Permissions: Read and write permissions on the report
• Scopes:

  Report.ReadWrite.All

  or

  Item.ReadWrite.All

cat > update-report.json << 'EOF'
{
  "displayName": "Renamed Report",
  "description": "Updated description"
}
EOF

az rest --method patch \
  --resource "https://api.fabric.microsoft.com" \
  --url "https://api.fabric.microsoft.com/v1/workspaces/$WS_ID/reports/$REPORT_ID" \
  --headers "Content-Type=application/json" \
  --body @update-report.json

• Permissions: Write permissions on the report
• Scopes:

  Report.ReadWrite.All

  or

  Item.ReadWrite.All

undefined

Create Report

Get Report Definition

Update Report Definition

202 Accepted

x-ms-operation-id

⚠️ Never retry a create POST after receiving 202. A

202 Accepted

response means the operation was accepted and is likely being processed server-side. Retrying the POST risks creating duplicates.

Always write

--verbose

output to a file to reliably capture the

x-ms-operation-id

header on every attempt — this is the only reliable way to track the operation. Regex extraction from in-memory strings is fragile across shells and platforms. Once captured, poll the operation to completion just like any other LRO call.

powershell

# PowerShell — reliable operation ID capture
az rest --method post ... --verbose 2>&1 | Out-File "$env:TEMP\lro-response.txt" -Encoding utf8
$opId = (Select-String -Path "$env:TEMP\lro-response.txt" -Pattern "x-ms-operation-id.*?'([a-f0-9-]+)'" | Select-Object -First 1).Matches.Groups[1].Value

As a last resort, if the operation ID is still lost despite writing to a file, list reports in the workspace to locate the created report — but this should not be the normal path.

• ALL PBIR content MUST go through the

  powerbi-report-authoring

  skill — this is the single most important rule. Whether creating a brand-new report or modifying an existing one, every PBIR file (

  definition.pbir

  ,

  report.json

  ,

  version.json

  ,

  pages.json

  , page configs, visuals, filters, formatting, themes, expressions) must be authored using

  powerbi-report-authoring

  . Follow its guidance for correct PBIR structure, schemas, and field values. Use its CLI tools for validation. Never construct any PBIR JSON from memory or guesswork — not even "simple" files like

  definition.pbir

  or

  version.json

  . This skill is strictly for API transport (download, encode, upload) — it does not author PBIR content.
• Always pass

  --resource "https://api.fabric.microsoft.com"

  to

  az rest

  — omitting it causes silent auth failures.
• Always pass

  ?format=PBIR

  on

  getDefinition

  — without it, older reports return PBIR-Legacy format which is not supported by this skill.
• Only work with PBIR format — if a definition comes back with

  "format": "PBIR-Legacy"

  , stop and tell the user that PBIR-Legacy is not supported.
• Include ALL definition parts in

  updateDefinition

  — modified + unmodified. The API replaces the entire definition; omitting parts deletes them.
• Base64-encode all part payloads — every

  payload

  value must be base64-encoded.
• Use

  byConnection

  in

  definition.pbir

  for Fabric API —

  byPath

  is for local/Git scenarios only.
• Poll LRO to completion —

  Create

  ,

  getDefinition

  , and

  updateDefinition

  return

  202 Accepted

  . Poll until terminal state.
• Always use

  --verbose

  on LRO operations —

  az rest

  does not expose response headers by default. Without

  --verbose

  , you cannot capture the

  x-ms-operation-id

  header needed for polling, and there is no other way to retrieve it after the fact.
• Clean up temporary files — delete any local temp directories and files (decoded definitions, JSON payloads) created during the workflow once the operation completes. These can be large and accumulate on the user's machine.
• Verify semantic-model bindings after the target model is resolved — once the report's target semantic model is known (whether by a fresh deploy through an available semantic-model authoring skill or by selecting an existing workspace model), download its TMDL and compare all PBIR bindings (

  Entity

  ,

  queryRef

  ,

  nativeQueryRef

  , filter

  Source

  /

  Entity

  references) against the model's table/column/measure names. This applies to both branches: even a hand-off deploy may rename or transform the model during publish, so the diff is not optional. If names differ but models are structurally equivalent (same columns/measures), remap all table-qualified bindings via

  powerbi-report-authoring

  . If the models are not structurally equivalent, prompt the user before attempting to re-author — explain which tables/columns/measures don't match and ask whether to proceed.
• Local edits stay local by default — when a user requests changes to a local

  .pbip

  report, apply the changes to the local files only. Do not publish to Fabric unless the user explicitly asks to publish, upload, or push the report. Even if the report was previously published to Fabric, treat subsequent edits as local-only until told otherwise. When the user does request publishing a local

  .pbip

  , follow the Publishing a local .pbip workflow: (a) confirm the target workspace once up front, (b) prompt publish-the-local-model vs. connect-to-an-existing-workspace-model, (c) on the publish-model branch, check whether a semantic-model authoring skill is available in the current session and degrade gracefully if not, (d) confirm create-new vs. update-existing for the report itself.

• Soft delete over hard delete — allows recovery.

• az rest

  with JMESPath

  --query

  for filtering — built-in JSON parsing, no extra tools needed.

• Hand-writing or directly constructing PBIR JSON — whether creating new files or modifying existing ones, all PBIR content (

  definition.pbir

  ,

  report.json

  ,

  version.json

  , pages, visuals, filters, formatting, themes, expressions) must go through the

  powerbi-report-authoring

  skill. Never construct any PBIR JSON from memory or guesswork — not even "simple" structural files. No exceptions.
• PBIR-Legacy format — do not create, read, or update PBIR-Legacy definitions. Only modern PBIR format is supported.
• Sending only modified parts in

  updateDefinition

  — the API replaces the full definition; missing parts are deleted.
• Using

  byPath

  in

  definition.pbir

  for API payloads — only works for local/Git scenarios.
• Hardcoded workspace/report IDs — resolve dynamically via the List APIs.
• Skipping LRO polling — definition operations may be async; always check for 202 responses.
• Omitting

  ?format=PBIR

  on

  getDefinition

  — may return unusable PBIR-Legacy format.
• Retrying a create POST after receiving 202 — risks creating duplicates. See the LRO section for the correct recovery pattern.

.pbip

.SemanticModel

.pbip

• A

  <Name>.pbip

  file in or above the working directory.
• A

  <Name>.Report

  folder with a sibling

  <Name>.SemanticModel

  folder.
• The report's

  definition.pbir

  uses

  byPath

  (local/Git form) rather than

  byConnection

  (API form).
• Presence of a

  .pbi/

  cache folder.

.pbip

.Report

byConnection

definition.pbir

"Do you want me to publish the local semantic model to this workspace too, or connect this report to an existing semantic model already in the workspace?"

• Check whether a semantic-model authoring skill is available in the current session.
  • Available → hand off to that workflow to create or update the semantic model. Pass: target workspace ID, the local

    .SemanticModel

    folder path (TMDL source), and the desired model display name. Wait for that skill's workflow to reach terminal success before proceeding.
  • Not available → tell the user a semantic-model authoring skill is not loaded in this session and that publishing the local model is not possible without it. Then degrade to branch 4b (connect-to-existing) and re-prompt for which workspace model to bind the report to.

• List semantic models in the target workspace and confirm the target model with the user. Resolve

  semanticModelId

  by name.

semanticModelId

• After 4a: list semantic models in the target workspace and find the model just deployed by name (the model skill verifies by listing workspace items but does not return an ID).
• After 4b: this was already done.

powerbi-report-authoring

definition.pbir

byPath

byConnection

powerbi-report-authoring

"datasetReference": {
  "byConnection": {
    "connectionString": "semanticmodelid=<resolved-id>"
  }
}

byPath

displayName

.pbip

SalesDashboard.pbip

"SalesDashboard"

• List reports in the target workspace and look up the chosen

  displayName

  .
  • Not found → create. Follow Create Report (with Definition).
  • Found → confirm with the user: overwrite the existing report (

    updateDefinition

    ), publish under a different name, or cancel. Follow Update Report Definition on overwrite.

parts

x-ms-operation-id

--verbose

Note on report-side verification: there is no reliable programmatic way to confirm a report renders correctly post-publish — the report lives at a Fabric Service URL and visual rendering requires a browser session. Surface the workspace/report URL so the user can verify in the browser.

1. Authenticate → see COMMON-CLI.md § Authentication Recipes
2. Find workspace → Resolve workspace ID by name
3. List/find report → Resolve report ID by name
4. Download definition →

   getDefinition?format=PBIR

   → poll LRO → decode parts to local files
5. Author PBIR content → Use the

   powerbi-report-authoring

   skill for ALL changes. This covers every file:

   definition.pbir

   ,

   report.json

   ,

   version.json

   ,

   pages.json

   , page configs, visuals, filters, formatting, themes, and expressions. Follow its guidance for correct structure, schemas, and field values. Use its CLI tools to validate. Never construct any PBIR JSON from memory or guesswork.
6. Upload changes → Re-encode all local files to base64 →

   updateDefinition

   with ALL parts (modified + unmodified)
7. Clean up → Delete all temporary local files and directories created during the workflow

1. Authenticate → see COMMON-CLI.md § Authentication Recipes
2. Find workspace → Resolve workspace ID by name
3. Resolve semantic model → Find the semantic model ID and workspace name for the

   definition.pbir

   connection string
4. Verify semantic-model bindings → Download the target semantic model definition (TMDL) and compare all PBIR

   Entity

   ,

   queryRef

   ,

   nativeQueryRef

   , and filter references against the target table/column names. If names differ but structure matches, remap all table-qualified bindings. If models are structurally different, prompt the user before proceeding — explain what doesn't match and ask whether to re-author the affected bindings
5. Author PBIR content → Use the

   powerbi-report-authoring

   skill to generate the complete PBIR definition from scratch —

   definition.pbir

   ,

   report.json

   ,

   version.json

   ,

   pages.json

   , page configs, and all visuals. Never construct any PBIR JSON from memory or guesswork.
6. Upload → Encode all files to base64 →

   POST /reports

   with

   displayName

   and all definition parts
7. Clean up → Delete temporary local files