Status: Public Preview — behaviour may change.

What it does

A natural-language question-answering API, separate from the Web API and from Dataverse Search. You define a semantic model naming the tables relevant to a scenario, then POST a plain-English question against it at /api/iq/v1.0/ask; the response comes back as matching rows, an AI-written summary, source citation links and a paging token. It's the API surface behind the "Business Applications in Work IQ" capability Microsoft announced alongside Work IQ.

Key facts

• Not OData. There's no $metadata, no $select/$filter/$expand, no SDK for .NET or Python — plain HTTPS with a bearer token and JSON bodies only.
• Must be turned on per environment first: Business Applications in Work IQ in the Power Platform admin center. It's off by default.
• Creating a semantic model triggers Dataverse Search indexing of the selected tables, which consumes database storage — visible under the DataverseSearch table (the renamed RelevanceSearch) and counted on the environment's Summary/Dataverse storage tabs.
• Managing semantic models (create/delete) needs a role with that specific privilege: Dataverse Search Role, Environment Maker, System Administrator or System Customizer — a narrower list than "anyone who can read the tables".
• Asking a question only ever uses data the calling identity can already read — record ownership, business units, sharing and column security all apply, same as everywhere else in Dataverse.
• Rate limit is tighter than the general Dataverse service protection limits: 30 requests per user per organization per minute, with 429 plus a Retry-After header on breach.
• searchMode (Auto / QuickResponse / ThinkDeeper) trades latency for depth — ThinkDeeper can take noticeably longer, so a caller needs its own timeout and progress UI rather than assuming Web-API-like response times.

When to use / skip

Use it where the caller is genuinely a natural-language question, not a query you could write yourself — an internal chat surface, an agent skill, a support tool where "show me what's happening with this account" beats teaching every user OData syntax. Skip it as a replacement for the Web API in anything that needs deterministic, precise results: exact filters, joins, or anything a workflow or integration depends on getting byte-for-byte right. The response shape (rawResult as loosely-typed JSON) is explicitly not meant to be deserialized into a fixed model.

Configuration decisions

• Which tables go in a semantic model, and how many models you need. A model scoped to "sales pipeline" is easier to reason about and cheaper to index than one spanning the whole schema.
• Who gets the semantic-model-management privilege versus who only calls Ask — these are different risk profiles and the built-in roles conflate them more than some clients will want.
• Retry and backoff behaviour client-side: the API's own guidance is exponential backoff with jitter, capped retries, and re-listing models before retrying a Create or Delete rather than assuming the first call failed.
• Storage budget: indexing cost isn't free, so semantic model scope is a capacity-planning conversation, not just a security one.

Gotchas

• Enabling the environment feature and creating a model are two separate steps in two different places (admin center, then a Dataverse operation) — miss the first and every Ask call 400s with a message about a required capability not being enabled.
• The 30-requests-per-minute cap is per user per org, not per app registration — a shared service identity fronting many end users will hit it far sooner than a naive read of "30/minute" suggests.
• rawResult shape depends on the question asked; code that assumes a fixed column set from testing will break the day someone asks a differently-shaped question.
• Don't hand-construct or edit pagingToken values — they're opaque, and the API gives no guarantee they'll keep the same format across versions.

Consultant notes

• This is the concrete developer-facing half of Work IQ — when a client asks what Work IQ actually gives them to build with, this API (plus the separate business-skills layer) is the honest answer, not the marketing framing.
• Flag the storage-consumption line item early. "Turn on AI grounding" sounds free; Dataverse Search indexing on a large table set is not, and it lands on someone's capacity bill.
• Because the security-role list for model management is short and specific, audit who actually has Dataverse Search Role / Environment Maker before assuming least-privilege is already in place — it's an easy one to inherit broadly by accident.
• Preview means the request/response contract can still move. Anything built against this now wants a thin adapter layer, not calls scattered through the codebase, so a contract change is a one-file fix.

---

Worth revisiting at GA, and once Microsoft SDK support (if any) lands for a non-preview version.