Conversations API overview

The Conversations API is a REST interface for creating and interacting with Moveworks Assistant conversations from your own application. Your service sends a user’s message, the assistant plans and executes actions against connected systems, and you receive the assistant’s response back, either by polling or over a streaming connection.

Every request runs on behalf of a specific user, so responses reflect that user’s roster identity, permissions, connected content, and conversation history.

What you can build with it

The API is intentionally general-purpose. Two common patterns:

• Custom user-facing chat surfaces. Embed the assistant in a product you already own, such as a customer portal, an internal web app, a mobile app, or a voice or messaging surface. Users sign in with your identity provider, and your application exchanges their token for a Moveworks bearer that scopes each request to the signed-in user.
• Backend and workflow integrations. Trigger assistant conversations from a service that already knows which user each action is on behalf of. Examples include ambient monitoring, batch processing, ticket-driven automation, or systems that need to consume assistant output programmatically. Authentication is handled by a backend credential rather than an interactive sign-in.

Before you start

Two things have to be in place before any request will succeed:

1. Your account team enables the Conversations API for your org. Requests return 404 until they have.
2. You create the Conversations API chatbot in Moveworks Setup. This produces the Bot Name you send in the Assistant-Name header on every request, and it is an input to each authentication guide below.

Choosing an authentication path

Every conversation runs as a specific user. How your application obtains a token that identifies that user depends on how your integration is architected.

All three paths land at the same Moveworks token endpoint (POST /oauth/v1/token) and produce a bearer token you use on every Conversations API request.

Interaction patterns

Once authenticated, every conversation follows the same shape:

1. Create a conversation with POST /conversations. You get back a conversation_id that scopes all subsequent activity.
2. Send a message with POST /conversations/{conversation_id}/responses (for polling) or POST /conversations/{conversation_id}/responses/stream (for streaming).
3. Read the response by polling until the status is COMPLETED, or by consuming Server-Sent Events on the streaming endpoint.
4. Continue the conversation by sending more messages on the same conversation_id. Conversation history is preserved server-side.

Streaming is recommended for user-facing surfaces where perceived latency matters. Polling is simpler to implement and appropriate for backend integrations where progressive rendering is not needed. Both patterns are documented alongside their endpoints in the API reference.

Sample code

The Conversations API starter is Python sample code for this API. It includes a client library, a runnable example for each authentication path, and a reference chat app.

The Conversations API demo app is a styled chat app built on the starter.

Next steps

• Create the Conversations API chatbot and record its Bot Name.
• Pick the authentication path that matches your integration and follow its setup guide.
• Once you have a bearer, walk the API reference to see every endpoint, request shape, and response schema.
• Confirm the smoke-test flow at the end of each auth guide works end to end before wiring the API into production traffic.
• If your integration needs to receive messages the assistant initiates, such as approval requests or async action outcomes, read Proactive notifications. Routing behavior there is the most commonly misunderstood part of the API.