Skip to main content
Version: v5.3

File attachments

Overview​

Platform version 5.3 introduced a new feature which allows you to attach files to conversations with AI teams or agents. Previously, conversations were strictly based on text prompts and responses. Now you can attach files such as a PDF documents, Microsoft Word files, or a graphic file, and ask the AI Service to analyze the content of the file to assist with the conversation.

Note: The main file types currently supported are PDF documents and graphics files. OpenAI will also support Word, Excel, text, CSV, Markdown, and JSON files. For more information see, File attachment usage and size limits.

How the file attachment feature works​

File attachments are loaded via the File Service, using the new optional _attachments list array.

This list can be added to a conversation API request, using either the existing REST API or Javascript API.

Adding file attachments using the REST API​

To use the REST API, the base URL is:

/aisvc/api/v1

Use the following command, which now accepts optional _attachments as an argument:

POST /conversations?sync=true

Code examples​

See example code below.

{
"_teamId": "team-id",
"_input": {
"message": "Summarise this attachment."
},
"_attachments": [
{
"_fileId": "e4115f51-...",
"_fileVersionId": "c932f909-..."
}
]
}

To add a message to an existing conversation, include its _id, as shown below.

{
"_id": "conversation-id",
"_teamId": "team-id",
"_input": {
"message": "Explain invoice.pdf again."
}
}

Description of fields​

FieldTypeRequiredDescription
_idUUIDNoExisting conversation ID. Omit to create a new conversation.
_teamIdUUIDYesTeam executing the request.
_input.messageStringYesCurrent user prompt.
_attachmentsArrayNoExact File Service versions added in the current message.
_attachments[]._fileIdStringYes per itemFile Service file ID.
_attachments[]._fileVersionIdStringYes per itemImmutable File Service version ID.

Note: Filename and file version metadata are resolved by the AI Service from the File Service and are not trusted from the request payload.

Error behavior​

ConditionBehavior
_attachments is not an array or an item is malformedControlled 400 validation error.
Explicit current-message version returns File Service 404/410Request fails with the corresponding status and identifies the unavailable attachment.
Other File Service metadata failureControlled error using the downstream status when available.
File is neither image not PDFControlled 400 unsupported-type error.
Historical attachment is deleted before later selectionTool marks it as unavailable. The worker agent must state that it is missing or may have been deleted.
Provider upload rejects the fileProvider status is retained when available - network errors use 502.
Provider rejects file during model useError passes through the LLM error mapper. Recognized auth/rate-limit/outage/timeout errors are controlled; an unrecognized provider 400 may appear as Bad Request.
Required provider API key is missingControlled 400 configuration error.

Note: The AI Service validates the platform-level contract (image or PDF). However, the exact rules for image-format, size, and token policies remain governed by the LLM provider. For example, File Service metadata identifying a TIFF file as an image will pass the AI Service classification but a LLM provider may reject it when the file is uploaded or used.

Adding file attachments using the Javascript API​

To use the Javascript API, use the existing API call IafAISvc.createConversation() and ensure it contains an _attachments list.

Javascript code example​

createConversation and streamConversation take the same request. To send files, add _attachments to it. Each file requires its _fileId``` and _fileVersionId``.

See example below.

await IafAISvc.createConversation({
_teamId: 'team-id',
_input: {
message: 'Summarize this attachment.'
},
_attachments: [
{
_fileId: 'e4115f51-...',
_fileVersionId: 'c932f909-...'
}
]
}, ctx);

Call IafAISvc.streamConversation(request, onEvent, ctx, options). Users see the answer as it is written, so they do not wait for the full reply. You also get updates on each attachment. The request is the same as for createConversation, including _attachments. It returns two things: done (wait on it until the answer is finished) and abort() (stop early).

let answer = '';

const handle = IafAISvc.streamConversation(
{
_teamId: 'team-id',
_input: { message: 'Summarise this attachment.' },
_attachments: [
{ _fileId: 'e4115f51-...', _fileVersionId: 'c932f909-...' }
]
},
(event) => {
switch (event.type) {
case 'conversation':
// Save this id. You need it to send a follow-up message.
console.log('conversation id:', event.payload.id);
break;
case 'attachment-status': {
// Shows what happened to each file.
// Flow: selected -> loaded, unavailable or failed.
// 'failed' also gives a reason.
const { ref, name, status, reason } = event.payload;
console.log(`attachment ${ref} (${name}): ${status}${reason ? ' - ' + reason : ''}`);
break;
}
case 'agent-message':
// A small piece of the answer. Add the pieces together.
answer += event.payload.delta;
break;
case 'complete':
console.log('done, conversation:', event.payload._id);
break;
case 'error':
console.error('stream error:', event.payload.message);
break;
}
},
ctx
);

await handle.done; // waits until the answer is finished
// handle.abort(); // stops early, e.g. when the user leaves the page

Follow up query example​

To ask a follow-up, send the conversation ID. You do not need to attach the file again. Just use its name in your question.

IafAISvc.streamConversation(
{
_teamId: 'team-id',
_id: conversationId, // the id you saved from the 'conversation' event
_input: { message: 'What is the total in invoice.pdf?' }
},
onEvent,
ctx
);

Event types​

The onEvent function receives the events listed below.

EventWhat it meansUseful data
conversationGives you the conversation IDid
attachment-statusWhat happened to a fileref, name, status, reason
agent-messageA small piece of the answerdelta
summaryThe full answer text. It is sent once, just before complete.content
team-start, agent-invoked, agent-invocation-message, llm-analysing, tool-invoked, tool-result, process-status, team-doneProgress updates. Showing them is optional. You can simply ignore them.
token-usageHow many tokens used during the turn.
completeThe answer is finished._id, _turnId, _output
errorSomething went wrong.message
closeThe stream is over (sent by the client library).

File attachment usage and size limits​

The main file types currently supported are PDF documents and graphics files. For other file types, note the following:

  • OpenAI will also support text, Word, Excel, CSV, Markdown, and JSON files.
  • Anthropic will also support text files but will reject Word, Excel, CSV and JSON files.

File size limits​

A user can attach multiple files in a single conversation. The AI Service does not impose its own upload-size or usage limits. However, the effective limits on file size and usage are determined by whatever rules each specific LLM provider enforces under its own policy.

Consider the following:

  • Upload success does not guarantee that the file is usable - Both providers (OpenAI and Anthropic) can accept an upload and validate type, size, or token cost only when the file is used in a model request. This means that a file that exceeds size restrictions or an unsupported file could be uploaded successfully and then only fail when a worker agent uses it.

  • OpenAI is size-gated - When using an OpenAI agent, any document larger than approximately 32 MB in size will be rejected at use time. Referencing it by file_id does not bypass this restriction because OpenAI fetches the provider file server-side.

  • Anthropic is token-gated - When using an Anthropic agent, there are restrictions based on the number of tokens used in the conversation. This practical limit is related to the model context window. When using a PDF, extracted text and rendered page images will add to the request token count. A file that is near the context boundary may not fit reliably into the Anthrophic token limit.

Notes on file behavior for different LLM providers​

IssueOpenAIAnthropic
Files API upload cap512 MB per file; very large uploads can time out.500 MB per file; request_too_large if exceeded.
Effective use-time limitApproximately 32 MB per document, with provider combined-request limits also applying.Model context window, approximately 200K tokens depending on model; no fixed per-file MB limit.
Image formatsPNG, JPEG, WebP, non-animated GIFJPEG, PNG, GIF, WebP
Documents (any non image file)PDF, Word, Excel, CSV, text, Markdown, JSON, RTF, and code. (OpenAI decides by file extensionPDF, and plain text (text, Markdown, code). Word, Excel, CSV and JSON are refused with Anthropic's own message.
Agent client requirementResponses APIfiles-api-2025-04-14 beta
AI Service provider retentionOpenAI uploads expire after two daysAnthropic provider lifecycle applies.