> 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.

# List conversation messages

GET https://api.moveworks.ai/assistant/v1/conversations/{conversation_id}/messages

Retrieves all messages (both user and assistant) in a conversation in descending order by creation time (most recent first).

Reference: https://docs.moveworks.com/api-reference/conversations-api/deprecated-conversations-api/messages/list-conversation-messages

## 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

### Query parameters

- `cursor` (string, optional) — Opaque cursor for pagination
- `limit` (integer, optional, default: 20) — Maximum number of messages to return (1-100)

### Headers

- `Assistant-Name` (string, required) — The Moveworks assistant identifier that was configured for your organization.

## Response

### 200

List of messages

- `messages` (list of Message, required) — Array of messages
- `metadata` (Metadata, optional) — Metadata (pagination)

## Errors

### 400 Bad Request Error

Bad request - Invalid input parameters

- `error` (InvalidCursorErrorResponseError, 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

### 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.

### Metadata

- `next_cursor` (string, optional, nullable) — Opaque cursor for next page (null if no more results)

### InvalidCursorErrorResponseError

- `code` (enum, required)
  - Allowed values: `INVALID_CURSOR`
- `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)

### 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

**Response**

```json
{
  "messages": [
    {
      "message_id": "msg_32bt8vagXAoRwRLIdI2Oj",
      "conversation_id": "conv_32bt7BMLhLyVzTUjfi35N",
      "response_id": "resp_32bt7rXXugeJjvE3pQzOk",
      "actor": "ASSISTANT",
      "content": {
        "type": "COMMONMARK_TEXT",
        "commonmark_text": {
          "text": "John Doe reports to Jane Smith in the Engineering department."
        }
      },
      "created_at": "2025-01-20T10:00:01Z",
      "citations": [
        {
          "citation_id": "cite_32bt9xYZabcDEFghijk",
          "url": "https://company.com/users/123",
          "display": {
            "title": {
              "type": "COMMONMARK_TEXT",
              "commonmark_text": {
                "text": "John Doe"
              }
            },
            "body": {
              "type": "COMMONMARK_TEXT",
              "commonmark_text": {
                "text": "John Doe reports to Jane Smith in the Engineering department."
              }
            },
            "attributes": [
              {
                "key": "EMAIL",
                "value": "johndoe@company.com"
              },
              {
                "key": "MANAGER",
                "value": "Jane Smith"
              }
            ]
          }
        }
      ],
      "content_references": [
        {
          "citation_id": "cite_32bt9xYZabcDEFghijk",
          "offset": 0
        },
        {
          "citation_id": "cite_32bt9xYZabcDEFghijk",
          "offset": 20
        }
      ],
      "feedback": {
        "helpful": {
          "callback_id": "eyJhY3Rpb24iOiJoZWxwZnVsIi4uLn0"
        },
        "unhelpful": {
          "callback_id": "eyJhY3Rpb24iOiJ1bmhlbHBmdWwiLi4ufQ"
        }
      }
    },
    {
      "message_id": "msg_32bt8vagXAoRwRLIdI2Oj",
      "conversation_id": "conv_32bt7BMLhLyVzTUjfi35N",
      "response_id": "resp_32bt7rXXugeJjvE3pQzOk",
      "actor": "USER",
      "content": {
        "type": "PLAIN_TEXT",
        "plain_text": {
          "text": "Who does John Doe report to?"
        }
      },
      "created_at": "2025-01-20T10:00:00Z"
    },
    {
      "message_id": "msg_55bt8vagXAoRwRLIdI2Oj",
      "conversation_id": "conv_32bt7BMLhLyVzTUjfi35N",
      "response_id": "resp_32bt7rXXugeJjvE3pQzOk",
      "actor": "ASSISTANT",
      "content": {
        "type": "COMMONMARK_TEXT",
        "commonmark_text": {
          "text": "You report to John Doe"
        }
      },
      "created_at": "2025-01-20T09:00:01Z"
    },
    {
      "message_id": "msg_32bt8vagXAoRwRLIdI2Oj",
      "conversation_id": "conv_32bt7BMLhLyVzTUjfi35N",
      "response_id": "resp_77bt7rXXugeJjvE3pQz77",
      "actor": "USER",
      "content": {
        "type": "PLAIN_TEXT",
        "plain_text": {
          "text": "Who is my manager"
        }
      },
      "created_at": "2025-01-20T09:00:00Z"
    }
  ],
  "metadata": {
    "next_cursor": "eyJvZmZzZXQiOjIwfQ=="
  }
}
```

**SDK Code**

```python Messages_listConversationMessages_example
import requests

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

headers = {
    "Assistant-Name": "acmecorp-conversations-rest-api",
    "Authorization": "Bearer <token>"
}

response = requests.get(url, headers=headers)

print(response.json())
```

```javascript Messages_listConversationMessages_example
const url = 'https://api.moveworks.ai/assistant/v1/conversations/conv_32bt7BMLhLyVzTUjfi35N/messages';
const options = {
  method: 'GET',
  headers: {
    'Assistant-Name': 'acmecorp-conversations-rest-api',
    Authorization: 'Bearer <token>'
  }
};

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

```go Messages_listConversationMessages_example
package main

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

func main() {

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

	req, _ := http.NewRequest("GET", url, nil)

	req.Header.Add("Assistant-Name", "acmecorp-conversations-rest-api")
	req.Header.Add("Authorization", "Bearer <token>")

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

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

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

}
```

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

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

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

request = Net::HTTP::Get.new(url)
request["Assistant-Name"] = 'acmecorp-conversations-rest-api'
request["Authorization"] = 'Bearer <token>'

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

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

HttpResponse<String> response = Unirest.get("https://api.moveworks.ai/assistant/v1/conversations/conv_32bt7BMLhLyVzTUjfi35N/messages")
  .header("Assistant-Name", "acmecorp-conversations-rest-api")
  .header("Authorization", "Bearer <token>")
  .asString();
```

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

$client = new \GuzzleHttp\Client();

$response = $client->request('GET', 'https://api.moveworks.ai/assistant/v1/conversations/conv_32bt7BMLhLyVzTUjfi35N/messages', [
  'headers' => [
    'Assistant-Name' => 'acmecorp-conversations-rest-api',
    'Authorization' => 'Bearer <token>',
  ],
]);

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

```csharp Messages_listConversationMessages_example
using RestSharp;

var client = new RestClient("https://api.moveworks.ai/assistant/v1/conversations/conv_32bt7BMLhLyVzTUjfi35N/messages");
var request = new RestRequest(Method.GET);
request.AddHeader("Assistant-Name", "acmecorp-conversations-rest-api");
request.AddHeader("Authorization", "Bearer <token>");
IRestResponse response = client.Execute(request);
```

```swift Messages_listConversationMessages_example
import Foundation

let headers = [
  "Assistant-Name": "acmecorp-conversations-rest-api",
  "Authorization": "Bearer <token>"
]

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

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()
```