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
| Field | Type | Required | Description |
|---|---|---|---|
_id | UUID | No | Existing conversation ID. Omit to create a new conversation. |
_teamId | UUID | Yes | Team executing the request. |
_input.message | String | Yes | Current user prompt. |
_attachments | Array | No | Exact File Service versions added in the current message. |
_attachments[]._fileId | String | Yes per item | File Service file ID. |
_attachments[]._fileVersionId | String | Yes per item | Immutable 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
| Condition | Behavior |
|---|---|
_attachments is not an array or an item is malformed | Controlled 400 validation error. |
| Explicit current-message version returns File Service 404/410 | Request fails with the corresponding status and identifies the unavailable attachment. |
| Other File Service metadata failure | Controlled error using the downstream status when available. |
| File is neither image not PDF | Controlled 400 unsupported-type error. |
| Historical attachment is deleted before later selection | Tool marks it as unavailable. The worker agent must state that it is missing or may have been deleted. |
| Provider upload rejects the file | Provider status is retained when available - network errors use 502. |
| Provider rejects file during model use | Error 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 missing | Controlled 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);
Recommended usage for streaming conversations
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.
| Event | What it means | Useful data |
|---|---|---|
conversation | Gives you the conversation ID | id |
attachment-status | What happened to a file | ref, name, status, reason |
agent-message | A small piece of the answer | delta |
summary | The 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-done | Progress updates. Showing them is optional. You can simply ignore them. | |
token-usage | How many tokens used during the turn. | |
complete | The answer is finished. | _id, _turnId, _output |
error | Something went wrong. | message |
close | The 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_iddoes 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
| Issue | OpenAI | Anthropic |
|---|---|---|
| Files API upload cap | 512 MB per file; very large uploads can time out. | 500 MB per file; request_too_large if exceeded. |
| Effective use-time limit | Approximately 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 formats | PNG, JPEG, WebP, non-animated GIF | JPEG, PNG, GIF, WebP |
| Documents (any non image file) | PDF, Word, Excel, CSV, text, Markdown, JSON, RTF, and code. (OpenAI decides by file extension | PDF, and plain text (text, Markdown, code). Word, Excel, CSV and JSON are refused with Anthropic's own message. |
| Agent client requirement | Responses API | files-api-2025-04-14 beta |
| AI Service provider retention | OpenAI uploads expire after two days | Anthropic provider lifecycle applies. |