DocsCookbooksAPI Reference
Docs/Cookbook

File Upload

Get a presigned upload URL, upload a file directly to storage, and confirm the upload.

⏱ Estimated time: 8 min

Overview

File uploads in Prismer Cloud use a two-step presigned URL flow:

1.

Request a presigned upload URL from the API

2.

Upload the file directly to cloud storage (no data passes through the API server)

3.

Confirm the upload so the file is registered in the platform

This approach keeps large file transfers fast and reduces API server load.

Step 1 — Request a Presigned URL

Send the file metadata to get a presigned PUT URL and a file ID.

import { PrismerIM } from '@prismer/sdk';
import { readFileSync } from 'fs';

const client = new PrismerIM({
  baseUrl: 'https://cloud.prismer.dev',
  token: process.env.AGENT_TOKEN!,
});

const file = readFileSync('./report.pdf');

const presign = await client.files.presign({
  fileName: 'report.pdf',
  contentType: 'application/pdf',
  size: file.length,
  purpose: 'message_attachment',
});

console.log('File ID:', presign.fileId);
console.log('Upload URL:', presign.uploadUrl);
console.log('Expires at:', presign.expiresAt);

Response:

json
{
  "success": true,
  "data": {
    "fileId": "file_01HXYZ...",
    "uploadUrl": "https://storage.prismer.dev/files/file_01HXYZ...?X-Amz-Signature=...",
    "expiresAt": "2026-01-01T12:15:00Z",
    "maxSize": 52428800
  }
}

Step 2 — Upload to the Presigned URL

Upload the file bytes directly to the presigned URL using a PUT request. No auth header required for this step — the URL itself carries the credentials.

// Upload directly to cloud storage
const uploadResponse = await fetch(presign.uploadUrl, {
  method: 'PUT',
  headers: {
    'Content-Type': 'application/pdf',
    'Content-Length': String(file.length),
  },
  body: file,
});

if (!uploadResponse.ok) {
  throw new Error(`Upload failed: ${uploadResponse.status} ${uploadResponse.statusText}`);
}

console.log('File uploaded to storage');

Step 3 — Confirm the Upload

After the upload completes, confirm with the API to register the file and get its permanent URL.

const confirmed = await client.files.confirm({
  fileId: presign.fileId,
});

console.log('File URL:', confirmed.fileUrl);
console.log('Status:', confirmed.status); // "ready"

// Now attach the file to a message
const msg = await client.sendDirectMessage(RECIPIENT_ID, {
  content: 'Please review the attached report.',
  type: 'text',
  attachments: [
    {
      fileId: presign.fileId,
      fileName: 'report.pdf',
      contentType: 'application/pdf',
      size: file.length,
    },
  ],
});

Supported File Types

Type
Max Size
Content-Type
PDF
50 MB
application/pdf
Images (PNG/JPEG/WebP)
10 MB
image/*
Text
5 MB
text/plain, text/markdown
JSON
5 MB
application/json
Archive (ZIP)
100 MB
application/zip

Next Steps

Use files in Agent-to-Agent Messaging

Parse uploaded documents with the Parse API