add-ai-webapi

> **Plugin check**: Run `node "${CLAUDE_PLUGIN_ROOT}/scripts/check-version.js"` — if it outputs a message, show it to the user before proceeding.

# Add AI Web API

> **Note**
>
> AI summarization APIs are a preview feature. Preview features aren't meant for production use and may have restricted functionality. These features are available before an official release so that customers can get early access and provide feedback.

**Surface this note to the user verbatim** during Phase 1 and again in the Phase 8 summary —
copy the exact `**Note**` block above (including its wording about "available before an official
release so that customers can get early access and provide feedback"). Do not paraphrase it into
your own "Preview-feature note: ..." sentence; the wording matches the Microsoft Learn preview
disclaimer and rephrasing it loses that fidelity.

Integrate Power Pages generative-AI summarization APIs into a SPA site. This skill focuses on the AI layer (Layer 3): the summarization service code and the `Summarization/*` site settings. The underlying Web API prerequisites — `Webapi/<table>/enabled`, `Webapi/<table>/fields`, table permissions, and web roles — are **delegated** to `/integrate-webapi` and `/create-webroles` so there is a single source of truth for every layer.

## The two APIs covered

| # | API | URL | Body | Response |
|---|-----|-----|------|----------|
| 1 | **Search Summary** | `POST /_api/search/v1.0/summary` | `{ userQuery }` | `{ Summary, Citations }` |
| 2 | **Data Summarization** | `POST /_api/summarization/data/v1.0/<entitySet>(<id>)?$select=...&$expand=...` | `{ InstructionIdentifier }` or `{ RecommendationConfig }` | `{ Summary, Recommendations }` |

> **Example: Microsoft-shipped Copilot summary on a support-case page.** Data Summarization can be
> called with any combination of entity set, columns, and prompt — but Microsoft documents and
> ships one specific configuration for the standard `incident` table:
> `POST /_api/summarization/data/v1.0/incidents(<caseId>)?$select=description,title&$expand=incident_adx_portalcomments($select=description)`
> with body `{ "InstructionIdentifier": "Summarization/prompt/case_summary" }`. This is sometimes
> called the "Case-page Copilot preset" in Microsoft Learn. Treat it as one possible Data
> Summarization recipe — useful when the user explicitly wants to mirror the Microsoft sample —
> not as an automatic recommendation. A custom case-like table (`cr363_servicerequest`,
> `adx_case`), or the standard incident table summarised on different facets (priority, owner,
> SLA timer), is just a regular Data Summarization call with maker-defined values.

> Reference: `${CLAUDE_PLUGIN_ROOT}/skills/add-ai-webapi/references/ai-api-reference.md` — canonical
> API shapes, required headers, site-setting names, error codes, and the documented support-case
> example. Read this at the start of the workflow; fetch the Microsoft Learn source pages with
> `mcp__plugin_power-pages_microsoft-learn__microsoft_docs_fetch` if the user asks for the latest.

> **Admin governance hierarchy**: both APIs are gated by a **three-level admin
> hierarchy** — tenant PowerShell setting (`enableGenerativeAIFeaturesForSiteUsers`), Copilot Hub
> environment/site governance, and the site-level maker toggle (for Search Summary: Set up
> workspace → Copilot → Site search (preview) → Enable Site search with generative AI (preview)).
> **Each level overrides the one below it**, so "the maker toggle is on but the API still says
> disabled" is a real scenario — admin-level governance wins.
>
> The two endpoints surface disablement differently:
>
> - **Search Summary** → HTTP **200** with an embedded envelope `{ Code: 400, Message: "Gen AI
>   Search is disabled." }`. The generated `fetchSearchSummary` detects this and throws
>   `SearchSummaryApiError`; the UI renders a remediation card.
> - **Data Summarization** → HTTP **400** with `error.code = 90041001` (admin-level disabled) or
>   `90041003` (per-site `Summarization/Data/Enable=false`).
>
> Full troubleshooting checklist (tenant → environment → site, plus runtime version, Bing
> dependency, and cross-region data movement) lives in
> `references/ai-api-reference.md` §1 "Troubleshooting: AI feature appears disabled (admin
> hierarchy)" — point users there when either disablement shape surfaces. Mention this governance
> hierarchy explicitly to the user before Phase 7, and again in the Phase 8 summary.

> **Built-in search control vs. custom code path**: if the site uses the Microsoft-shipped Power
> Pages search **control** and only wants AI-summarised search results on that page, they don't
> need this skill — just the Copilot workspace toggle and the `Search/Summary/Title` content
> snippet. This skill is for sites that build their own search UI or need to call
> `/_api/search/v1.0/summary` from custom code. Confirm which path the user is on in Phase 1.

## Core principles

- **Layer 3 only, delegate the rest.** Web API site settings, table permissions, and web roles all belong to `/integrate-webapi` and `/create-webroles`. This skill creates the summarization service code and the `Summarization/*` site settings — nothing else.
- **Sequential agent spawning.** Per `plugins/power-pages/AGENTS.md`, spawn the `ai-webapi-integration` agent sequentially per target (never in parallel). The first call establishes the shared summarization service file and CSRF helper; subsequent calls extend it. `ai-webapi-settings-architect` runs alone, after all code integrations land.
- **Raw `fetch` + CSRF.** Every summarization request attaches `__RequestVerificationToken` (from `/_layout/tokenhtml`) and `X-Requested-With: XMLHttpRequest`. Never route through an OData wrapper.
- **Skip `/integrate-webapi` when it's not needed.** If every confirmed target is Search Summary (which has no per-table Web API prerequisites), or every Layer 1/2 prerequisite already exists on disk, the skill goes straight from Phase 3 to Phase 5.
-