create_or_ingest_chat_files

ArtificialIntelligenceApi.create_or_ingest_chat_files(role_id, chat_files_action_request, content_type=None, action=None, _request_timeout=None, _request_auth=None, _content_type=None, _headers=None, _host_index=0)

Get an upload URL or add files to a dataset

action=save_to_dataset copies existing files into a dataset (owner on each source chat; DatasetId and Files required, max 5). Any other action value, or omitting action, returns a presigned PUT URL. Upload body requires FileName; optional ChatId (default global files, or global) or ProjectId (editor; max 10 project files; FileSize max 50 MB). Duplicate names get a (n) suffix.

Parameters:

• role_id (str) – Amorphic role ID of the requesting user. Must be a role the authenticated user belongs to. (required)

• chat_files_action_request (ChatFilesActionRequest) – Upload requires FileName (optional ChatId, ProjectId, FileSize). save_to_dataset requires DatasetId and Files (optional PartitionKeys). Extra fields are ignored. (required)

• content_type (str) – Request body media type.

• action (str) – save_to_dataset copies files into a dataset. Omit or any other value generates an upload URL.

• _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:

ChatFilesActionResponse

Returns:

Returns the result object.

Request and Response Examples

HTTP: POST /ai/playground/files

Parameter examples

Name	In	Example
Content-Type	header	"application/json"
role_id	header	"custom-role-123e4567-e89b-12d3-a456-426614174000"
action	query	"save_to_dataset"

Request

Upload requires FileName (optional ChatId, ProjectId, FileSize). save_to_dataset requires DatasetId and Files (optional PartitionKeys). Extra fields are ignored.

Presigned upload URL (chat-scoped)

{
  "FileName": "quarterly_report.pdf",
  "ChatId": "123e4567-e89b-12d3-a456-426614174000"
}

Upload to global files

{
  "FileName": "reference_notes.pdf",
  "ChatId": "global"
}

Upload to project files

{
  "FileName": "project_brief.pdf",
  "ProjectId": "123e4567-e89b-12d3-a456-426614174000",
  "FileSize": 204800
}

Add files to a dataset

{
  "DatasetId": "ds-123e4567-e89b-12d3-a456-426614174000",
  "Files": [
    {
      "FileName": "quarterly_report.pdf",
      "ChatId": "123e4567-e89b-12d3-a456-426614174000"
    }
  ]
}

Ingest multiple files (max 5)

{
  "DatasetId": "ds-123e4567-e89b-12d3-a456-426614174000",
  "Files": [
    {
      "FileName": "quarterly_report.pdf",
      "ChatId": "123e4567-e89b-12d3-a456-426614174000"
    },
    {
      "FileName": "sales_summary.csv",
      "ChatId": "global"
    }
  ]
}

Ingest with partition keys

{
  "DatasetId": "ds-123e4567-e89b-12d3-a456-426614174000",
  "Files": [
    {
      "FileName": "quarterly_report.pdf",
      "ChatId": "123e4567-e89b-12d3-a456-426614174000"
    }
  ],
  "PartitionKeys": {
    "upload_date": "2026-08-01"
  }
}

Success (HTTP 200)

Upload URL returns PresignedURL. save_to_dataset returns Message with submitted/failed counts.

Presigned PUT URL

{
  "PresignedURL": "https://example-bucket.s3.amazonaws.com/..."
}

Dataset ingest

{
  "Message": "Submitted 1 file(s) for ingestion successfully"
}

Errors

Documented error codes: IPV-1001, IPV-1008, 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 FileName/DatasetId/Files or over 5 files), IPV-1008 (file size/type), IPV-1002 (file/dataset 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 FileName

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

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