list_ai_chat_files¶

ArtificialIntelligenceApi.list_ai_chat_files(role_id, action=None, chat_id=None, project_id=None, file_name=None, limit=None, offset=None, sortby=None, sortorder=None, filter_expression=None, projection_expression=None, _request_timeout=None, _request_auth=None, _content_type=None, _headers=None, _host_index=0)¶

List, download, or preview files

Omit action (or any value other than download/preview) to list files. List with chat_id returns that chat’s files plus global files (chat_id is used as-is; pass project-files-{project_id} to list a project’s files). List without chat_id returns accessible chat, project, and global files. Default offset 1, limit 5000 (max 5000), sortby UploadTime, sortorder desc. action=download or preview requires file_name; chat_id defaults to the user’s global files (use global). project_id (not N/A) targets project files. Preview of csv/tsv/txt/json/sql returns {data}; otherwise {PresignedURL}. No request body.

Parameters:

role_id (str) – Amorphic role ID of the requesting user. Must be a role the authenticated user belongs to. (required)
action (str) – download or preview a file. Omit or any other value lists files.
chat_id (str) – For list, scopes to that chat id as stored (global files are still appended). For download/preview, defaults to global-files-{user_id}; use global for the same.
project_id (str) – Used with download/preview only. When set and not N/A, reads from project files. Ignored for list.
file_name (str) – Required for download/preview. Ignored for list.
limit (int) – List only. Page size. Default 5000, maximum 5000.
offset (int) – List only. 1-based page offset. Default 1. Values below 1 are treated as page 1.
sortby (str) – List only. Field to sort by. Default UploadTime. The field must exist on every file item.
sortorder (str) – List only. Sort direction. Default desc. Any value other than desc is treated as ascending.
filter_expression (str) – List only. Comma-separated field:value filters (format key:value). FileName supports wildcard matching.
projection_expression (str) – List only. Comma-separated file attributes to include. When omitted, all returned fields are included.
_request_timeout (int, tuple(int, int), optional) – timeout setting for this request. If one number provided, it will be total request timeout. It can also be a pair (tuple) of (connection, read) timeouts.
_request_auth (dict, optional) – set to override the auth_settings for an a single request; this effectively ignores the authentication in the spec for a single request.
_content_type (str, Optional) – force content-type for the request.
_headers (dict, optional) – set to override the headers for a single request; this effectively ignores the headers in the spec for a single request.
_host_index (int, optional) – set to override the host_index for a single request; this effectively ignores the host_index in the spec for a single request.

Return type:

ListAiChatFiles200Response

Returns:

Returns the result object.

Request and Response Examples¶

HTTP: GET /ai/playground/files

Parameter examples¶

Name	In	Example
`role_id`	header	`"custom-role-123e4567-e89b-12d3-a456-426614174000"`
`action`	query	`"download"`
`chat_id`	query	`"123e4567-e89b-12d3-a456-426614174000"`
`project_id`	query	`"123e4567-e89b-12d3-a456-426614174000"`
`file_name`	query	`"quarterly_report.pdf"`
`filterExpression`	query	`"FileName:report*"`
`projectionExpression`	query	`"FileName,UploadTime,Source,ChatId"`

Success (HTTP 200)¶

List returns paginated files. download/preview returns PresignedURL, except preview of csv/tsv/txt/json/sql which returns data.

List files

{
  "files": [
    {
      "FileName": "quarterly_report.pdf",
      "UploadTime": "2026-08-19 10:02:00",
      "UploadedBy": "jdoe",
      "FileType": "pdf",
      "FileSize": 204800,
      "ChatId": "123e4567-e89b-12d3-a456-426614174000",
      "ProjectId": "N/A",
      "Source": "Chats"
    }
  ],
  "next_available": "no",
  "count": 1,
  "total_count": 1
}

Presigned download URL

{
  "PresignedURL": "https://example-bucket.s3.amazonaws.com/ai-chats/.../quarterly_report.pdf"
}

Preview text/csv file content

{
  "data": "col1,col2\n1,2"
}

Errors¶

Documented error codes: IPV-1001, IPV-1050, IPV-1002, AUTH-1001, AUTH-1011, GE-1008, DB-1002.

HTTP 400

Input validation or authorization failure. Body is {“Message”: “<CODE> - <text>”}. Codes: IPV-1001 (missing file_name for download/preview), IPV-1050 (limit over maximum), IPV-1002 (file/chat not found), AUTH-1001 (missing role_id), AUTH-1011 (caller not authorized).

Missing role_id header

{
  "Message": "AUTH-1001 - Missing role information in event header"
}

Caller not authorized

{
  "Message": "AUTH-1011 - User does not have sufficient permission to perform this action"
}

Missing file_name for download/preview

{
  "Message": "IPV-1001 - Missing mandatory parameter(s) 'file_name'"
}

HTTP 500

Backend failure. Body is {“Message”: “<CODE> - <text>”}. Codes: GE-1008 (unexpected backend failure), DB-1002 (persistence failure).

Unexpected backend failure

{
  "Message": "GE-1008 - Could not complete the request. Please try again."
}