Matilda
Contact
Client SDK · State and data

Files.

Upload one file or many, then attach the IDs to a chat request.

files.upload(file, options?)

Uploads a single file. Files at or above the server's chunked threshold use the parallel multipart protocol; smaller files use single-shot upload.

TypeScript
const file = new File(['Hello, world!'], 'hello.txt', { type: 'text/plain' });
const result = await client.files.upload(file, {
  onProgress: (pct) => console.log(`Upload: ${pct}%`),
});
console.log(`File ID: ${result.fileId}, Status: ${result.status}`);

FileUploadOptions

Extends MatildaRequestOptions:

Fieldtypedescription
onProgress(pct: number) => voidProgress callback (0–100).
fingerprintstring | nullDevice fingerprint.
accessTokenstring | nullOverride access token.
signalAbortSignalAbort the upload.

Returns Promise<FileCompleteResponse>:

TypeScript
interface FileCompleteResponse {
  fileId: string;
  status: FileAttachmentStatus;
  failureReason?: FileFailureReason;
}

type FileAttachmentStatus = 'pending' | 'scanning' | 'processing' | 'ready' | 'failed' | 'rejected';

files.uploadMany(files, options?)

Uploads multiple files in parallel. One file's failure does not abort the others. Inspect each PromiseSettledResult for per-file outcomes.

TypeScript
const files = [
  new File(['doc 1'], 'doc1.txt', { type: 'text/plain' }),
  new File(['doc 2'], 'doc2.txt', { type: 'text/plain' }),
];

const results = await client.files.uploadMany(files);
for (let i = 0; i < results.length; i++) {
  const result = results[i];
  if (result.status === 'fulfilled') {
    console.log(`File ${i}: ${result.value.fileId} (${result.value.status})`);
  } else {
    console.error(`File ${i} failed:`, result.reason);
  }
}

Returns Promise<PromiseSettledResult<FileCompleteResponse>[]>.

files.retrieve(fileId, options?)

Retrieves metadata for a previously uploaded file.

TypeScript
const file = await client.files.retrieve('file-abc123');
console.log(`${file.filename} — ${file.status} (${file.sizeBytes} bytes)`);
if (file.extractedText) {
  console.log(`Extracted: ${file.extractedText.slice(0, 100)}...`);
}

Returns Promise<FileAttachment>:

TypeScript
interface FileAttachment {
  id: string;
  filename: string;
  contentType: string;
  sizeBytes: number;
  status: FileAttachmentStatus;
  extractedText?: string;
  thumbnailUrl?: string;
  localUri?: string;
  failureReason?: FileFailureReason;
  createdAt: string;
}

interface FileFailureReason {
  code: string;
  message: string;
  retryable: boolean;
}

Using files in chat

Upload a file, then reference its fileId in a chat message:

TypeScript
const fileResult = await client.files.upload(
  new File(['Quarterly report content...'], 'report.txt', { type: 'text/plain' }),
);

const response = await client.chat.create({
  input: 'Summarise this report.',
  fileIds: [fileResult.fileId],
});
console.log(response.outputText);