Microsoft Work IQ API — Complete Developer Guide

What Is the Microsoft Work IQ API?

Before Work IQ, building an enterprise AI agent that could reason over your organization’s actual work — who is working on what, what was decided in last Tuesday’s meeting, what the latest version of a document says — required a significant custom engineering effort. Teams had to extract data from SharePoint and Teams via the Microsoft Graph API, compute vector embeddings, store them in external vector databases, implement access control lists to prevent sensitive data exposure, and keep the whole pipeline synchronized as data changed.

The Work IQ API eliminates that stack. It exposes a continuously updated, permission-trimmed semantic model of how work actually happens in your organization — built from emails, calendar patterns, Teams chats, SharePoint documents, meeting transcripts, people connections, and line-of-business systems — directly to any agent through standard protocols.

Agents call the Work IQ API. Work IQ assembles the grounding context internally, enforces the invoking user’s Entra ID permissions automatically, and returns agent-ready intelligence. No custom vector pipeline. No external database. No separate governance layer to build.

The Microsoft IQ Stack — Where Work IQ Fits

Work IQ is one component of the broader Microsoft IQ umbrella announced at Build 2026 — an enterprise intelligence architecture that grounds AI agents in both organizational knowledge and the live web. Understanding the full stack clarifies what Work IQ is responsible for and what the other layers handle.

For data engineering teams already using Microsoft Fabric, the connection between Work IQ and Fabric IQ is important: Work IQ grounds agents in collaboration signals (who talked to whom, what was decided), while Fabric IQ grounds them in structured business data (what the numbers say). Foundry IQ orchestrates retrieval across both. See Microsoft Fabric IQ — The Intelligence Layer Explained for the Fabric IQ deep-dive.

Work IQ Architecture — How It Builds Organizational Context

Work IQ does not work by indexing documents at query time. It continuously processes signals from across Microsoft 365 and connected external systems, building and maintaining a live semantic model of how work happens in the organization. When an agent queries the API, it draws from this pre-built model rather than running a fresh retrieval pipeline on every request.

The Three Internal Layers

The Four Work IQ API Domains

The Work IQ API is organized around four domains that map to how agents actually work — from conversational intelligence to persistent state management. Each domain has a distinct purpose and a distinct cost model.

1. Chat — Copilot-Quality Conversational Intelligence

The Chat API returns the response Microsoft 365 Copilot would give a signed-in user for a given prompt, including citations. It provides programmatic access to the full Copilot reasoning and grounding stack — without requiring users to interact with the Copilot interface directly.

Use Chat when your agent needs a synthesized, human-readable answer grounded in organizational context. The response includes source citations so agents can surface provenance to users. This is the most straightforward integration path for developers who want Copilot-quality responses in a custom application.

2. Context — Agent-Ready Grounding Data

The Context API returns the raw grounding data Copilot would use to answer a query — but instead of synthesizing it into a response, it packages that context in a machine-consumable format designed for agent ingestion. The agent then decides what to do with the context rather than receiving a pre-formed answer.

Use Context when your agent needs the underlying signals rather than a synthesized response — for example, when feeding context into your own model with a specialized system prompt, or when combining Work IQ context with data from other sources before generating a response.

3. Tools — Actions Inside Microsoft 365

The Tools domain provides a stable set of action verbs that agents can execute within Microsoft 365 — send email, schedule meeting, upload document, create task, search Teams. The key design principle is that the action vocabulary stays stable even as the underlying Microsoft 365 surface evolves. Agents call a documented Tool, not a raw Graph endpoint.

Tools carry a fixed Copilot Credit charge per invocation — the cost is predictable regardless of the complexity of the underlying operation.

4. Workspaces — Persistent Agent State

Workspaces are secure, tenant-contained containers where long-running agents store intermediate state, files, and memory across complex multi-step tasks. Microsoft Scout and Copilot Cowork use Workspaces for exactly this purpose — storing task progress, intermediate files, and working memory that persists across sessions and agent handoffs in multi-agent systems.

Without Workspaces, agents must either store state in external systems (introducing governance risk) or lose state between sessions (requiring users to repeat context). Workspaces solve both problems by keeping persistent agent memory inside the Microsoft 365 tenant boundary.

Work IQ API Protocols — A2A, MCP, and REST

Work IQ supports three protocols at GA, each targeting a different agent architecture. Your choice of protocol depends on where your agent runs and how it communicates with other systems.

Authentication & Security Model

Delegated Authentication Only — No Application-Only Access

The Work IQ API enforces Microsoft Entra ID delegated authentication for all requests. Every API call must execute in the context of a signed-in user. Application-only authentication — where an application authenticates as itself without a user context — is not supported.

This is an architectural security decision, not a limitation to work around. Because Work IQ grants access to personal email, meeting content, and collaboration history, running queries without a user context would mean an application could access organizational intelligence without any individual being accountable. The delegated model ensures that every Work IQ query is traceable to a specific user, and that the response is permission-trimmed to exactly what that user can see.

What Entra ID Enforces Automatically

Work IQ API Pricing — Copilot Credits

From GA on June 16, 2026, the Work IQ API uses a consumption-based pricing model billed in Copilot Credits — the same unified currency used by Copilot Studio and other Microsoft AI services. There is no separate Work IQ API subscription, SKU, or per-user license.

Copilot Credits — How They Work

Copilot Credits are the shared consumption currency across Copilot Studio, Work IQ API, and other Microsoft AI services. Organisations can acquire credits through two mechanisms: pay-as-you-go (credits billed as consumed, no commitment) or Copilot Credit prepurchase plans (bulk purchase at a committed rate).

New Cost Management Dashboard

Microsoft launched a new cost management dashboard in the Microsoft 365 admin center alongside Work IQ GA. IT admins can review AI credit usage, configure Copilot Credit billing (prepaid or pay-as-you-go), set spending limits for tenants, groups, and individual users, and monitor credit requests across agents and services. Work IQ is the first product managed through this dashboard — additional Copilot Credit-consuming products will follow.

Developer Setup — Registering and Calling the Work IQ API

1. Register an application in Microsoft EntraNavigate to the Microsoft Entra admin center (entra.microsoft.com). Create a new App Registration. Set the redirect URI appropriate for your application type (web, SPA, or mobile/desktop).
2. Add the Work IQ delegated permissionIn the App Registration, go to API permissions → Add a permission → Microsoft APIs → Work IQ. Add the delegated permission WorkIQAgent.Ask. This is the scope required for all Work IQ API calls.
3. Grant tenant-wide admin consentA Global Administrator must grant admin consent for the WorkIQAgent.Ask permission at the tenant level. Without this, individual users will be prompted to consent on first use — or blocked entirely if user consent is disabled by tenant policy.
4. Configure Copilot Credits billingIn the Microsoft 365 admin center, enable consumptive billing for Work IQ API. Configure whether to use pay-as-you-go or a prepurchase Copilot Credit plan. Set spending limits if required.
5. Obtain a delegated access tokenUse MSAL (Microsoft Authentication Library) to acquire a delegated access token for the signed-in user with the WorkIQAgent.Ask scope. The token must represent a real user — application-only tokens are rejected.
6. Call the Work IQ APIMake REST, A2A, or MCP calls using the token. For REST, include the bearer token in the Authorization header. For A2A, include it in the JSON-RPC security envelope. For MCP, configure the server with the token via the Foundry Toolkit or local CLI.

// Example: REST call to Work IQ Context API
const response = await fetch(
  'https://api.work-iq.microsoft.com/v1/context',
  {
    method: 'POST',
    headers: {
      'Authorization': `Bearer ${delegatedAccessToken}`,
      'Content-Type': 'application/json',
    },
    body: JSON.stringify({
      query: 'What are the open blockers on the Q3 launch?',
      sources: ['email', 'teams', 'sharepoint'],
    }),
  }
);

const context = await response.json();
// context.items contains agent-ready grounding data
// Each item includes source, content, and permission metadata

Work IQ MCP Server — Context for AI Coding Assistants

The redesigned Work IQ remote MCP server, released at GA, exposes Microsoft 365 work context as tools for any MCP-compatible AI assistant — GitHub Copilot in VS Code, coding agents, IDE extensions, and local CLI agents. This means a developer’s coding assistant can answer questions grounded in organizational context without leaving the development environment.

The Work IQ CLI can be configured as a local MCP server by adding it to the MCP configuration file of your assistant:

// MCP server configuration (e.g., .vscode/mcp.json)
{
  "workiq": {
    "type": "stdio",
    "command": "workiq",
    "args": ["mcp"]
  }
}

// Example agent interaction via MCP
// User: "Summarize recent discussions about project risks"
{
  "tool": "workiq.search",
  "arguments": {
    "query": "project risks",
    "source": "teams"
  }
}

// Work IQ response
{
  "results": [
    {
      "summary": "Recent discussions highlighted timeline risks in the Q3 feature branch and dependency risks with the authentication service refactor.",
      "sources": ["Teams channel: Engineering #q3-planning", "Meeting: Architecture review 2026-06-08"]
    }
  ]
}

Work IQ API Use Cases

What Work IQ Is Built For

When Work IQ Is Not the Right Choice

Work IQ is optimised for Microsoft 365 collaboration context. It is not a general-purpose database query interface or a replacement for the Microsoft Graph API when you need raw structured data. If your agent needs to query calendar entries in a structured way, enumerate SharePoint list items programmatically, or access Microsoft 365 admin data, the Graph API is the right tool. Work IQ is for agents that need to understand organizational context and act on it — not for applications that need to enumerate raw data resources.

FAQ — Microsoft Work IQ API

Official Resources — Microsoft Work IQ Documentation