Skip to main content
Everything you can ask Wren in Dialog Studio, you can ask from your own code. Send a prompt, stream the response back. This is useful for wiring Wren into your own tooling: kicking off a build from a ticket, running an analysis on a schedule of your own, or bringing agent changes into an existing review process.

Authentication

Requests authenticate with a personal access token in the x-api-key header. Workspace API keys are not accepted on this endpoint. The run acts as you, with your permissions, and the conversation appears in your Wren chats in Dialog Studio. To create a token, open your profile menu in Dialog Studio, go to Account › Personal access tokens, and select Token. If you don’t see the tab, contact your PolyAI representative. Use your region’s base URL, the same one you’d use for the rest of the platform APIs. See base URLs for the table. Tokens are region-specific: a token created in one region’s Dialog Studio is rejected with a 401 in any other region.

Send a turn

The response is a server-sent event stream. Keep the connection open and read events as they arrive; the stream carries the same activity you’d watch in the chat panel: Wren’s reasoning steps, the tools it runs, the changes it applies, and its final message.

Request body

File attachments aren’t supported over the API yet.

Modes over the API

API turns default to auto mode, which is almost always what you want: Wren runs the task start to finish, resolves its own clarifying questions and plan approvals, and finishes with a report rather than waiting on a human. Auto mode doesn’t remove every pause. A few actions always ask a person to confirm first, even in auto mode. When that happens the stream ends on a user_input_required event and the run waits for your answer, so handle that event even if you never choose interactive.
  • interactive makes Wren stop and wait at plan and question gates too, which needs something on your side able to answer them. Unless you’ve built that, stay on the default.
  • headless never waits. Anything that would need a person’s answer is recorded as a blocker in the final report instead.
The usual auto-mode limits apply: Wren won’t ask for secrets and won’t publish a dashboard. It reports those as blockers instead. Mode is set per turn, not per conversation. Send it again on each follow-up turn if you don’t want the default.

Answering a question

When the stream ends on a user_input_required event, the run is parked. Answer it with a second request to the same endpoint, and the run picks up where it stopped on a new stream:
sessionId, requestId (from the event you’re answering), context and answer are all required. answer.inputKind must match the event’s inputKind: An answer in the wrong shape is rejected with a 400 and the run stays parked, so you can send it again.

Continuing a conversation

Every run belongs to a session. Pass the sessionId from a previous turn to continue that conversation with its full history, exactly as a follow-up in the chat panel would. Disconnecting doesn’t cancel the run. If your connection drops mid-turn, Wren keeps working, but you can’t rejoin that stream. Sending another turn with the same sessionId is rejected while the run is still going, and starts a new turn once it has finished. For long runs, save events as they arrive. Only one run at a time can be in flight per session. A second turn on a busy session is rejected rather than queued. Conversations are shared with Dialog Studio. A conversation you start over the API shows up in your Wren chats, and you can continue a chat you started in Dialog Studio by passing its ID.

Using Wren from your own agents

Because a turn is a single authenticated HTTP request that streams its result back, Wren fits into agentic workflows you have already built. Wrap the endpoint as a tool or function call and your own agent can hand work to Wren the same way it would call any other service. This works with Claude, GPT, or whichever models your stack runs on, and with any framework that can call an HTTP API. A few patterns this makes possible:
  • From your issue tracker. An agent picks up a ticket describing an agent change, calls Wren to implement it on a Branch, and comments back with what changed for a human to review and publish.
  • On your own schedule. A nightly job asks Wren the same analytical question and posts the answer into Slack or a dashboard of your own.
  • Inside a larger workflow. Wren handles the Dialog Studio step while the rest of your pipeline handles everything around it, such as fetching requirements, notifying reviewers, or opening a ticket.
Two things make this practical. Auto mode is the default, so a turn runs start to finish without waiting on a human. And sessionId gives you continuity, so a follow-up turn keeps the full context of the last one rather than starting cold. The safety model is unchanged when Wren is driven this way. It still works on a Branch, it still refuses to merge or publish, and it is still bound by the permissions of the token’s owner. A human still approves what ships.

Errors

Once the stream has opened, failures arrive as an error event with a machine-readable errorCode instead of an HTTP status. Branch on the code, not the message text. The stream sends periodic keepalive comments so idle connections aren’t dropped by intermediate proxies. Runs can take many minutes, so set your client’s read timeout in minutes, not seconds.

Limits

API turns draw on the same fair-use allowance as the chat panel, and are subject to the same permissions as the token’s owner.
Wren never merges or publishes, over the API or anywhere else. Changes land on a Branch for you to review. See Deployments to publish them.

API reference

Base URLs, authentication, and the rest of the platform APIs.

Builder MCP

Build agents from your IDE or AI coding tool.

ADK

A local, Git-like workflow for Dialog Studio projects.
Last modified on November 3, 2026