REST API

A conversation, with two HTTP calls. A direct application integration: your app owns the chat experience and the conversation ID, and Work IQ generates the grounded reply.

When to choose it

Choose REST when your application owns the chat experience and needs grounded answers from Work IQ, and nothing more: two HTTP calls, with the sources and, when present, the sensitivity label in each reply. No model of yours is involved.

Request path

POST /rest/conversations  > {}
POST /rest/conversations/{id}/chat
Body  > message + locationHint

Who does the reasoning?

Work IQ generates the grounded reply; no model of yours is involved. The MCP routes show the harness pattern for when your application needs its own orchestration.

On the wire

1. Create a conversation

POST /rest/conversations HTTP/1.1
Host: workiq.svc.cloud.microsoft
Authorization: Bearer <delegated token>
Content-Type: application/json

{}

The reply’s id is the conversation ID.

2. Ask a question in it

POST /rest/conversations/{id}/chat HTTP/1.1
Host: workiq.svc.cloud.microsoft
Authorization: Bearer <delegated token>
Content-Type: application/json

{
  "message": { "text": "What did Sarah say about the launch date?" },
  "locationHint": { "timeZone": "Europe/Berlin" }
}

The reply’s messages array ends with the answer. It carries the text, the sources in attributions, each with a providerDisplayName and a seeMoreWebUrl, and, when present, sensitivityLabel.displayName. Follow-up questions go to the same conversation; New chat in the app starts a new one.

Authentication

Your approved public-client app, with delegated WorkIQAgent.Ask consent. No client secret, and no application-only authentication. See Authentication.

What it costs

The app calls no model of yours on this route, so it adds no model charge; a harness that adds its own model pays for that model separately. Work IQ is billed in Copilot Credits. Each chat call is a Work IQ Chat call, with variable credits: Copilot reasons in the background and returns the answer. The app counts no credits for creating a conversation. See Copilot Credits.

Keep in mind

These are the stable /rest routes, not /rest/beta or the older Graph Chat API. The app shows source attributions and sensitivity information when the reply includes them.

Try it in the app

1. Open the REST API tab and click Connect.
2. Enter the Directory (tenant) ID and Application (client) ID of your app registration.
3. Click Connect and finish the sign-in in your browser.
4. Ask a question. Flow shows both calls and their payloads.

The code

src/workiq/rest.js makes both calls, and src/workiq/http.js adds the token and refuses any other host.

Work IQ REST API overview Conversations, chat and the reply format.