> This page is for API Reference & Tools.

> For clean Markdown of any page, append .md to the page URL.
> For a complete documentation index, see https://docs.moveworks.com/llms.txt.
> For AI client integration (Claude Code, Cursor, etc.), connect to the MCP server at https://docs.moveworks.com/_mcp/server.

# Create response (streaming)

POST https://api.moveworks.ai/assistant/v1/conversations/{conversation_id}/responses/stream
Content-Type: application/json

Creates a response and streams updates in real-time via Server-Sent Events (SSE). This provides a real-time alternative to creating a response and polling the GetResponse endpoint.

Reference: https://docs.moveworks.com/api-reference/conversations-api/deprecated-conversations-api/responses/create-response-stream

## Authentication

- `Authorization` header (bearer token, required) — JWT bearer token authentication. Obtain an access token from the Moveworks auth endpoint and include it in the Authorization header as 'Bearer \<token>'.

## Request

### Path parameters

- `conversation_id` (string, required) — A base-62 identifier prefixed by a short resource type

### Headers

- `Assistant-Name` (string, required) — The Moveworks assistant identifier that was configured for your organization.
- `Accept` (enum, required) — Must be set to `text/event-stream` to receive Server-Sent Events
  - Allowed values: `text/event-stream`

### Body (application/json)

This endpoint expects a CreateResponseStreamRequest.

- `input` (UserInput, required) — User input message

## Response

### 200

Server-Sent Events stream of response updates

- Streaming response of `ResponseStreamEvent`.
- `event` (enum, required) — Response streaming event type
  - Allowed values: `RESPONSE_CREATED`, `RESPONSE_IN_PROGRESS`, `RESPONSE_OUTPUT_DELTA`, `RESPONSE_COMPLETED`, `RESPONSE_FAILED`, `ERROR`
- `data` (ResponseStreamData, required) — Event data payload (structure depends on event type)

## Errors

### 400 Bad Request Error

Bad request - Invalid input parameters

- `error` (InputRequiredErrorResponseError, required)

### 401 Unauthorized Error

Unauthorized - Invalid or missing authentication

- `error` (UnauthorizedErrorResponseError, required)

### 403 Forbidden Error

Forbidden - Invalid assistant

- `error` (ForbiddenErrorResponseError, required)

### 404 Not Found Error

Not found - Resource does not exist

- `error` (NotFoundErrorResponseError, required)

### 429 Too Many Requests Error

Rate limit exceeded

- `error` (RateLimitExceededErrorResponseError, required)

### 500 Internal Server Error

Internal server error

- `error` (InternalErrorResponseError, required)

## Types

### UserInput

User input for a response. Exactly one of `text` or `callback_id` must be provided.

- Text: Text
- Callback: Callback

### ResponseStreamData

Event data payload (structure depends on event type)

- Response Created Event: ResponseCreatedData
- Response In Progress Event: ResponseInProgressData
- Response Output Delta Event: ResponseOutputDeltaData
- Response Completed Event: ResponseCompletedData
- Response Failed Event: ResponseFailedData
- Streaming Error Event: StreamingErrorData

### InputRequiredErrorResponseError

- `code` (enum, required)
  - Allowed values: `INVALID_INPUT`
- `message` (string, required)

### UnauthorizedErrorResponseError

- `code` (enum, required)
  - Allowed values: `UNAUTHORIZED`
- `message` (string, required)

### ForbiddenErrorResponseError

- `code` (enum, required)
  - Allowed values: `FORBIDDEN`
- `message` (string, required)

### NotFoundErrorResponseError

- `code` (enum, required)
  - Allowed values: `NOT_FOUND`
- `message` (string, required)

### RateLimitExceededErrorResponseError

- `code` (enum, required)
  - Allowed values: `RATE_LIMIT_EXCEEDED`
- `message` (string, required)

### InternalErrorResponseError

- `code` (enum, required)
  - Allowed values: `INTERNAL_ERROR`
- `message` (string, required)

### Text

- `text` (string, required) — User message text

### Callback

- `callback_id` (string, required) — Opaque callback id for an action the user triggered (e.g. clicking a button rendered in a prior assistant message).

### ResponseCreatedData

Data for RESPONSE_CREATED event - response initially created

- `event_type` (enum, required) — Response streaming event type
  - Allowed values: `RESPONSE_CREATED`, `RESPONSE_IN_PROGRESS`, `RESPONSE_OUTPUT_DELTA`, `RESPONSE_COMPLETED`, `RESPONSE_FAILED`, `ERROR`
- `sequence_number` (integer, required) — Sequential event number in stream. Monotonically increasing counter starting at 1.
- `response` (Response, required) — Newly created response object with CREATED status

### ResponseInProgressData

Data for RESPONSE_IN_PROGRESS event - response processing update

- `event_type` (enum, required) — Response streaming event type
  - Allowed values: `RESPONSE_CREATED`, `RESPONSE_IN_PROGRESS`, `RESPONSE_OUTPUT_DELTA`, `RESPONSE_COMPLETED`, `RESPONSE_FAILED`, `ERROR`
- `sequence_number` (integer, required) — Sequential event number in stream. Monotonically increasing counter starting at 1.
- `response` (Response, required) — Response object with IN_PROGRESS status

### ResponseOutputDeltaData

Data for RESPONSE_OUTPUT_DELTA event - new output item generated

- `event_type` (enum, required) — Response streaming event type
  - Allowed values: `RESPONSE_CREATED`, `RESPONSE_IN_PROGRESS`, `RESPONSE_OUTPUT_DELTA`, `RESPONSE_COMPLETED`, `RESPONSE_FAILED`, `ERROR`
- `sequence_number` (integer, required) — Sequential event number in stream. Monotonically increasing counter starting at 1.
- `output` (OutputItem, required) — Output item delta (message or reasoning message)

### ResponseCompletedData

Data for RESPONSE_COMPLETED event - response successfully completed

- `event_type` (enum, required) — Response streaming event type
  - Allowed values: `RESPONSE_CREATED`, `RESPONSE_IN_PROGRESS`, `RESPONSE_OUTPUT_DELTA`, `RESPONSE_COMPLETED`, `RESPONSE_FAILED`, `ERROR`
- `sequence_number` (integer, required) — Sequential event number in stream. Monotonically increasing counter starting at 1.
- `response` (Response, required) — Final response object with COMPLETED status and all outputs

### ResponseFailedData

Data for RESPONSE_FAILED event - response processing failed

- `event_type` (enum, required) — Response streaming event type
  - Allowed values: `RESPONSE_CREATED`, `RESPONSE_IN_PROGRESS`, `RESPONSE_OUTPUT_DELTA`, `RESPONSE_COMPLETED`, `RESPONSE_FAILED`, `ERROR`
- `sequence_number` (integer, required) — Sequential event number in stream. Monotonically increasing counter starting at 1.
- `response` (Response, required) — Response object with FAILED status and error details

### StreamingErrorData

Data for ERROR event - error that occurs mid-stream

- `error` (Error, required) — Error details

### Response

- `response_id` (string, required) — A base-62 identifier prefixed by a short resource type
- `conversation_id` (string, required) — A base-62 identifier prefixed by a short resource type
- `status` (enum, required) — Response processing status
  - Allowed values: `CREATED`, `IN_PROGRESS`, `COMPLETED`, `FAILED`
- `created_at` (datetime, required) — Creation timestamp (ISO 8601)
- `completed_at` (datetime, optional, nullable) — Completion timestamp (ISO 8601), null if not completed
- `outputs` (list of OutputItem, optional) — Output items

### OutputItem

Output item wrapper with type discriminator

- `type`: `MESSAGE` (MESSAGE)
  - `message` (Message, required)
- `type`: `REASONING_MESSAGE` (REASONING_MESSAGE)
  - `reasoning_message` (ReasoningMessage, required)

### Error

- `code` (string, required) — Machine-readable error code
- `message` (string, required) — Human-readable error message

### Message

- `message_id` (string, required) — A base-62 identifier prefixed by a short resource type
- `conversation_id` (string, required) — A base-62 identifier prefixed by a short resource type
- `response_id` (string, required) — A base-62 identifier prefixed by a short resource type
- `actor` (enum, required) — Message actor type
  - Allowed values: `USER`, `ASSISTANT`
- `content` (Content, required) — Message content with type discriminator
- `created_at` (datetime, required) — Creation timestamp (ISO 8601)
- `citations` (list of Citation, optional, nullable) — Unique citation references in the assistant message. Use `content_references` to determine where in the message text each citation is referenced.
- `content_references` (list of CitationContentReference, optional, nullable) — Ordered positions in the message text where citations appear (ascending by offset). Each entry references a `Citation` via `citation_id`. Only populated on assistant messages.
- `feedback` (MessageFeedback, optional, nullable) — Feedback options for this message. Present only on final assistant messages that support feedback. Use the callback IDs to submit a rating via the feedback endpoint.
- `actions` (list of Action, optional) — Actions a user can take in response to this message (e.g. buttons or links). Absent on messages with no actions.

### ReasoningMessage

- `reasoning_message_id` (string, required) — A base-62 identifier prefixed by a short resource type
- `conversation_id` (string, required) — A base-62 identifier prefixed by a short resource type
- `response_id` (string, required) — A base-62 identifier prefixed by a short resource type
- `content` (Content, required) — Message content with type discriminator
- `created_at` (datetime, required) — Creation timestamp (ISO 8601)

### Content

Message content with type discriminator

- `type`: `PLAIN_TEXT` (PLAIN_TEXT)
  - `plain_text` (PlainTextContent, required)
- `type`: `COMMONMARK_TEXT` (COMMONMARK_TEXT)
  - `commonmark_text` (CommonmarkTextContent, required)
- `type`: `MARKDOWN_TEXT` (MARKDOWN_TEXT)
  - `markdown_text` (MarkdownTextContent, required)
- `type`: `CALLBACK_ACTION_CONTENT` (CALLBACK_ACTION_CONTENT)
  - `callback_action` (CallbackActionContent, required)

### Citation

- `citation_id` (string, optional) — Unique citation identifier (format: `cite_<base62>`). Use this to join with `content_references` on the Message object.
- `url` (string, optional) — URL to the entity
- `display` (Display, optional)

### CitationContentReference

- `citation_id` (string, required) — References `Citation.citation_id` to link this position to a citation entity.
- `offset` (integer, required) — Zero-based character position in the assistant message where the citation appears.

### MessageFeedback

Feedback options available on an assistant message. When present, this message supports feedback and the callback IDs can be used to submit a rating.

- `helpful` (FeedbackOption, optional) — Positive feedback option. Use this callback_id to rate the response as helpful.
- `unhelpful` (FeedbackOption, optional) — Negative feedback option. Use this callback_id to rate the response as unhelpful.

### Action

An action a user can take in response to a message. The `type` field determines which action payload is present.

- `type`: `CALLBACK_ACTION` (CALLBACK_ACTION)
  - `callback_action` (CallbackAction, required)
  - `label` (string, required) — Label associated with the action (e.g., button text).
- `type`: `URL_ACTION` (URL_ACTION)
  - `label` (string, required) — Label associated with the action (e.g., link text).
  - `url_action` (URLAction, required)

### PlainTextContent

- `text` (string, required) — Plain text content

### CommonmarkTextContent

- `text` (string, required) — Commonmark-formatted text content

### MarkdownTextContent

- `text` (string, required) — Raw markdown text content. Used when Minerva's chat response `is_commonmark` is not set.

### CallbackActionContent

- `callback_id` (string, required) — Opaque callback id for the action the user triggered. Submit this via `input.callback_id` on the create response endpoint to trigger the action.

### Display

- `title` (Content, optional) — Primary heading/identifier with type discriminator
- `body` (Content, optional) — Body/description content with type discriminator
- `attributes` (list of Attribute, optional) — Opaque key-value metadata for citation display. These attributes contain implementation-specific rendering hints and should be treated as a black-box by clients. The structure and values may vary between citations and should not be relied upon for business logic.

### FeedbackOption

- `callback_id` (string, required) — Opaque callback identifier. Pass this value to the feedback endpoint to submit this rating.

### CallbackAction

- `callback_id` (string, required) — Opaque callback identifier for the action. Submit this via `input.callback_id` on the create response endpoint to trigger the action.

### URLAction

- `url` (string, required) — URL to open when the action is triggered.

### Attribute

Key-value pair for citation display metadata. This is an opaque structure that contains rendering hints specific to each citation. Clients should not make assumptions about the keys or values present, as they may vary based on citation type and context.

- `key` (string, required) — Attribute name
- `value` (string, required) — Attribute value

## Examples

**Request**

```json
{
  "body": {
    "input": {
      "text": "Who does John Doe report to?"
    }
  }
}
```

**Response**

```json
[
  {
    "event_type": "RESPONSE_CREATED",
    "response": {
      "conversation_id": "conv_32bt7BMLhLyVzTUjfi35N",
      "created_at": "2025-01-20T10:00:00Z",
      "outputs": [],
      "response_id": "resp_32bt7rXXugeJjvE3pQzOk",
      "status": "CREATED"
    },
    "sequence_number": 1
  },
  {
    "event_type": "RESPONSE_IN_PROGRESS",
    "response": {
      "conversation_id": "conv_32bt7BMLhLyVzTUjfi35N",
      "created_at": "2025-01-20T10:00:00Z",
      "outputs": [],
      "response_id": "resp_32bt7rXXugeJjvE3pQzOk",
      "status": "IN_PROGRESS"
    },
    "sequence_number": 2
  },
  {
    "event_type": "RESPONSE_OUTPUT_DELTA",
    "output": {
      "reasoning_message": {
        "content": {
          "commonmark_text": {
            "text": "Looking up John Doe..."
          },
          "type": "COMMONMARK_TEXT"
        },
        "conversation_id": "conv_32bt7BMLhLyVzTUjfi35N",
        "created_at": "2025-01-20T10:00:01Z",
        "reasoning_message_id": "rs_32bt8IqHzbv0FLmtGssa3",
        "response_id": "resp_32bt7rXXugeJjvE3pQzOk"
      },
      "type": "REASONING_MESSAGE"
    },
    "sequence_number": 3
  },
  {
    "event_type": "RESPONSE_OUTPUT_DELTA",
    "output": {
      "message": {
        "actor": "ASSISTANT",
        "content": {
          "commonmark_text": {
            "text": "John Doe reports to Jane Smith in the Engineering department."
          },
          "type": "COMMONMARK_TEXT"
        },
        "conversation_id": "conv_32bt7BMLhLyVzTUjfi35N",
        "created_at": "2025-01-20T10:00:01Z",
        "feedback": {
          "helpful": {
            "callback_id": "eyJhY3Rpb24iOiJoZWxwZnVsIi4uLn0"
          },
          "unhelpful": {
            "callback_id": "eyJhY3Rpb24iOiJ1bmhlbHBmdWwiLi4ufQ"
          }
        },
        "message_id": "msg_32bt8vagXAoRwRLIdI2Oj",
        "response_id": "resp_32bt7rXXugeJjvE3pQzOk"
      },
      "type": "MESSAGE"
    },
    "sequence_number": 4
  },
  {
    "event_type": "RESPONSE_COMPLETED",
    "response": {
      "completed_at": "2025-01-20T10:00:15Z",
      "conversation_id": "conv_32bt7BMLhLyVzTUjfi35N",
      "created_at": "2025-01-20T10:00:00Z",
      "outputs": [],
      "response_id": "resp_32bt7rXXugeJjvE3pQzOk",
      "status": "COMPLETED"
    },
    "sequence_number": 5
  }
]
```

**SDK Code**

```python
import requests

url = "https://api.moveworks.ai/assistant/v1/conversations/conv_32bt7BMLhLyVzTUjfi35N/responses/stream"

payload = { "body": { "input": { "text": "Who does John Doe report to?" } } }
headers = {
    "Authorization": "Bearer <token>",
    "Content-Type": "application/json"
}

response = requests.post(url, json=payload, headers=headers)

print(response.json())
```

```javascript
const url = 'https://api.moveworks.ai/assistant/v1/conversations/conv_32bt7BMLhLyVzTUjfi35N/responses/stream';
const options = {
  method: 'POST',
  headers: {Authorization: 'Bearer <token>', 'Content-Type': 'application/json'},
  body: '{"body":{"input":{"text":"Who does John Doe report to?"}}}'
};

try {
  const response = await fetch(url, options);
  const data = await response.json();
  console.log(data);
} catch (error) {
  console.error(error);
}
```

```go
package main

import (
	"fmt"
	"strings"
	"net/http"
	"io"
)

func main() {

	url := "https://api.moveworks.ai/assistant/v1/conversations/conv_32bt7BMLhLyVzTUjfi35N/responses/stream"

	payload := strings.NewReader("{\n  \"body\": {\n    \"input\": {\n      \"text\": \"Who does John Doe report to?\"\n    }\n  }\n}")

	req, _ := http.NewRequest("POST", url, payload)

	req.Header.Add("Authorization", "Bearer <token>")
	req.Header.Add("Content-Type", "application/json")

	res, _ := http.DefaultClient.Do(req)

	defer res.Body.Close()
	body, _ := io.ReadAll(res.Body)

	fmt.Println(res)
	fmt.Println(string(body))

}
```

```ruby
require 'uri'
require 'net/http'

url = URI("https://api.moveworks.ai/assistant/v1/conversations/conv_32bt7BMLhLyVzTUjfi35N/responses/stream")

http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true

request = Net::HTTP::Post.new(url)
request["Authorization"] = 'Bearer <token>'
request["Content-Type"] = 'application/json'
request.body = "{\n  \"body\": {\n    \"input\": {\n      \"text\": \"Who does John Doe report to?\"\n    }\n  }\n}"

response = http.request(request)
puts response.read_body
```

```java
import com.mashape.unirest.http.HttpResponse;
import com.mashape.unirest.http.Unirest;

HttpResponse<String> response = Unirest.post("https://api.moveworks.ai/assistant/v1/conversations/conv_32bt7BMLhLyVzTUjfi35N/responses/stream")
  .header("Authorization", "Bearer <token>")
  .header("Content-Type", "application/json")
  .body("{\n  \"body\": {\n    \"input\": {\n      \"text\": \"Who does John Doe report to?\"\n    }\n  }\n}")
  .asString();
```

```php
<?php
require_once('vendor/autoload.php');

$client = new \GuzzleHttp\Client();

$response = $client->request('POST', 'https://api.moveworks.ai/assistant/v1/conversations/conv_32bt7BMLhLyVzTUjfi35N/responses/stream', [
  'body' => '{
  "body": {
    "input": {
      "text": "Who does John Doe report to?"
    }
  }
}',
  'headers' => [
    'Authorization' => 'Bearer <token>',
    'Content-Type' => 'application/json',
  ],
]);

echo $response->getBody();
```

```csharp
using RestSharp;

var client = new RestClient("https://api.moveworks.ai/assistant/v1/conversations/conv_32bt7BMLhLyVzTUjfi35N/responses/stream");
var request = new RestRequest(Method.POST);
request.AddHeader("Authorization", "Bearer <token>");
request.AddHeader("Content-Type", "application/json");
request.AddParameter("application/json", "{\n  \"body\": {\n    \"input\": {\n      \"text\": \"Who does John Doe report to?\"\n    }\n  }\n}", ParameterType.RequestBody);
IRestResponse response = client.Execute(request);
```

```swift
import Foundation

let headers = [
  "Authorization": "Bearer <token>",
  "Content-Type": "application/json"
]
let parameters = ["body": ["input": ["text": "Who does John Doe report to?"]]] as [String : Any]

let postData = JSONSerialization.data(withJSONObject: parameters, options: [])

let request = NSMutableURLRequest(url: NSURL(string: "https://api.moveworks.ai/assistant/v1/conversations/conv_32bt7BMLhLyVzTUjfi35N/responses/stream")! as URL,
                                        cachePolicy: .useProtocolCachePolicy,
                                    timeoutInterval: 10.0)
request.httpMethod = "POST"
request.allHTTPHeaderFields = headers
request.httpBody = postData as Data

let session = URLSession.shared
let dataTask = session.dataTask(with: request as URLRequest, completionHandler: { (data, response, error) -> Void in
  if (error != nil) {
    print(error as Any)
  } else {
    let httpResponse = response as? HTTPURLResponse
    print(httpResponse)
  }
})

dataTask.resume()
```