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.

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 in the API documentation for the endpoint. For response fields, follow the Response Format 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 <your 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.

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

{
  "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 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, 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

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.

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, 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 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-<number> or page-<number> (- 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/

{"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/

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