> For the complete documentation index, see [llms.txt](https://docs.maiagent.ai/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.maiagent.ai/tech/en/api-integration/endpoint-behaviors/conversation-outputs-api.md).
# Conversation Output List API
Retrieve a list of documents, images, videos, and presentations generated by AI in a conversation.
The Conversation Outputs API lists files generated by AI in a conversation, such as documents, images, videos, and HTML presentations. When the organization has enabled the file library, the list is read from the file library; otherwise, it is read from the conversation's code execution workspace. Your integration can use this API to show which files were produced in a conversation.
API response field names use camelCase. For authentication and common request conventions, see [Quickstart](/tech/en/api-integration/quickstart.md).
## Endpoints
```
GET /api/conversations/{conversationId}/outputs/
GET /api/v1/conversations/{conversationId}/outputs/
```
Both prefixes are registered and behave identically. `conversationId` must be a UUID; an invalid format returns HTTP 400. See [List Conversation Output Files](https://docs.maiagent.ai/api/api-reference/dui-hua-he-xun-xi#conversations-outputs-retrieve) in the API documentation for the endpoint. For response fields, follow the [Response Format](#response) on this page.
## Authentication and Conversation Visibility
This API requires authentication. Requests without valid credentials are rejected. When integrating with an API Key, include:
```
Authorization: Api-Key
```
An API Key is bound to a member, and the service determines access based on that member's organization. When calling with a login token, also include `X-Organization-Id` to specify the organization. Otherwise, the service cannot identify the member and returns HTTP 404.
Read access depends on conversation visibility, using the same rules as retrieving conversation details:
* Organization owners can read conversations within their organization.
* Regular members can read conversations visible to their groups, as well as conversations assigned to them, conversations in which they are the contact, or conversations they initiated.
* Members with the `maigpt_access` permission can also read all conversations on the organization's MaiGPT platform without a group assignment.
For an overview of conversation visibility, see [Conversation Visibility and Real-Time Events](/tech/en/api-integration/endpoint-behaviors/conversation-visibility-events.md).
All of the following return HTTP 404 with `{"detail": "..."}`, without revealing whether the conversation exists: the conversation does not exist or has been deleted, the conversation belongs to another organization, or the caller cannot view the conversation.
## Response Format
```json
{
"count": 2,
"source": "file_library",
"results": [
{
"id": "3f2b7c1e-8a4d-4e21-9c55-1d2e3f4a5b6c",
"name": "quarterly-report.xlsx",
"fileType": "xlsx",
"size": 48213,
"createdAt": "1790000000000",
"canOpenInLibrary": true,
"libraryFolderId": "9a8b7c6d-5e4f-4a3b-8c2d-1e0f9a8b7c6d",
"source": "file_library"
},
{
"id": null,
"name": "chart.png",
"fileType": "image/png",
"size": 10240,
"createdAt": "1789990000000",
"canOpenInLibrary": false,
"libraryFolderId": null,
"source": "container"
}
]
}
```
The list returns all items at once, without pagination.
| Field | Description |
| ---------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| `count` | Number of items in `results` |
| `source` (top level) | `file_library` means the list primarily uses the file library; `container` means it uses the legacy workspace retrieval method. See [Behavior When the File Library Is Not Enabled](#library-disabled) for the conditions |
| `results[].id` | UUID of a file library file; `null` for a workspace file |
| `results[].name` | File name |
| `results[].fileType` | File extension for file library files (without the dot, such as `pdf`); MIME type inferred from the file name for workspace files, or `application/octet-stream` if it cannot be inferred |
| `results[].size` | File size in bytes |
| `results[].createdAt` | Creation time as a Unix epoch millisecond string; `null` for workspace files without a modification time |
| `results[].canOpenInLibrary` | Whether the user can be directed to open the file in the file library. This is `true` only for file library items when the top-level `source` is `file_library` and the caller is the user in this conversation. Workspace items, and videos and images merged in [when the file library is not enabled](#library-disabled), always have `false` |
| `results[].libraryFolderId` | UUID of the folder containing the file in the file library; provided under the same conditions that make `canOpenInLibrary` `true`, otherwise `null` |
| `results[].source` | Source of an individual item: `file_library` or `container` |
{% hint style="info" %}
The format of `fileType` varies by source: file library items use a file extension, while workspace items use a MIME type. Check `results[].source` first when determining the file type in your integration.
{% endhint %}
## Ordering
Ordering depends on the retrieval path:
* Top-level `source` is `file_library`: file library items are ordered by creation time from newest to oldest. For [legacy conversations](#legacy-conversations), after merging with workspace files, the list is reordered by creation time from newest to oldest, with items without a creation time placed last.
* Top-level `source` is `container`, with [videos or images previously saved to the file library](#library-disabled) merged in: the list is also reordered by creation time from newest to oldest, with items without a creation time placed last.
* Top-level `source` is `container`, with no file library items merged in: the list retains the workspace order rather than sorting by creation time, with folders first, then items ordered by name.
## Excluded Intermediate Files
When reading from the file library, the list includes only final outputs. The following supporting files are excluded:
* Presentation previews and thumbnails: PPTX previews, PPTX thumbnails, and HTML presentation previews, thumbnails, screenshots, and reference previews.
* Code execution outputs with the following file names (case-insensitive): `deck.pdf`, or `.jpg`/`.jpeg`/`.png` files starting with `slide-` or `page-` (`-` can also be `_`), such as `slide_3.png`.
This filter applies only to file library items. Files read from the workspace are not subject to this filter.
## File Library Conditions
When all of the following conditions are met, the list primarily uses the file library and the top-level `source` is `file_library`:
1. The conversation's organization has enabled the file library. It is disabled by default for organizations.
2. The caller's role has the `file_library_access` permission; organization owners always satisfy this condition.
3. The conversation's contact corresponds to a platform user, such as a member who initiated a conversation in MaiGPT.
### Legacy Conversations
When the conditions are met and the conversation still has a legacy code execution workspace, the list merges workspace files with file library files. If file names match, the file library version is retained.
### Behavior When the File Library Is Not Enabled
If any condition is not met, the top-level `source` is `container` and the list is read from the conversation's code execution workspace instead. If the conversation has no workspace, `results` is an empty array. If videos or images from this conversation were previously saved to the file library, for example while the organization had the file library enabled, these items are still merged into the list, with their `source` set to `file_library` and `canOpenInLibrary` set to `false`.
## Anonymous Access
This API does not accept anonymous requests. Anonymous visitors on conversation platforms such as Web Chat continue to use the existing `GET /api/code-execution-environments/{conversationId}/outputs/` endpoint. This legacy endpoint does not authenticate callers, reads files only from the workspace, and does not write files to the file library.
## Relationship to Downloads
The list does not include download URLs. For items whose `source` is `file_library`, `id` is the file library file ID. Call the file library download endpoint to obtain a URL:
```
GET /api/file-library/files/{id}/download/
```
```json
{"url": "https://storage.example.com/signed-url"}
```
This endpoint requires the organization to have the file library enabled and the caller to have at least one file library permission. It can find only files in spaces visible to the caller; if the file is not found, it returns HTTP 404. Download access depends on these file library permissions and space visibility, independently of `canOpenInLibrary`. Workspace items have `id` set to `null` and cannot be downloaded this way.
A conversation-level download endpoint is also available. It uses the same permissions as this list (anyone who can view the conversation can download) and does not require file library permissions:
```
GET /api/v1/conversations/{conversationId}/outputs/{fileId}/download/
```
```json
{"url": "https://storage.example.com/signed-url", "name": "quarterly-report.xlsx"}
```
`fileId` must be the `id` of an item generated in this conversation whose `source` is `file_library`. If the file has been deleted or a signed URL cannot be generated, the endpoint returns HTTP 404 with `{"detail": "File not found or expired"}`.
### Workspace Items and `outputs/` Paths in Messages
Items whose `source` is `container` have no `id`. Download them through the code execution workspace endpoint, specifying the file name:
```
GET /api/code-execution-environments/{conversationId}/download_output/?filename=chart.png
```
The response is the file itself (`Content-Type: application/octet-stream`, with the file name in `Content-Disposition`), rather than JSON. This endpoint does not authenticate callers, checks only the conversation ID, and applies rate limits by source IP. If the workspace container has stopped, it reads from a snapshot instead. If the file is also absent from the workspace, it then searches the file library.
Paths such as `outputs/report.docx` in AI reply text are paths relative to the workspace's `/workspace/outputs/` directory, rather than URLs you can open directly. Extract the file name (`report.docx`) and pass it as `filename` above, or first call the list endpoint on this page and use `results[].source` to choose between file library and workspace downloads. The reply's `contentPayload.items` may also contain items listing output files; your integration can use the list endpoint as the authoritative source.
---
# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.
## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation by asking a question.
Perform an HTTP GET request on the following URL with the `ask` and `goal` query parameters:
```
GET https://docs.maiagent.ai/tech/en/api-integration/endpoint-behaviors/conversation-outputs-api.md?ask=&goal=
```
`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is what the user is ultimately trying to achieve, the reason they need the answer. Sharing it helps GitBook give you a better, more relevant answer. A goal is most helpful when it describes the outcome the user wants rather than restating the question. For example, with `ask=how do I create an API token`, a goal like `automate deployments from our CI pipeline` lets GitBook tailor the answer to that use case.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.
Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.