Files & Media

Upload and manage files from your app code. Every file gets a permanent public URL.

Proyecta provides a Files API via the SDK for programmatic file management from your app code.

Chat attachments

The chat input accepts images directly — paste a screenshot or drag an image file onto the input. Supported formats: PNG, JPEG, WebP, GIF, AVIF. Maximum size: 10 MB per image.

Chat attachments are part of the message, not your file library. For persistent storage, use the SDK.

The Files API (SDK)

Every published Proyecta app has access to a file storage API through the Proyecta SDK. The SDK supports listing, fetching, and uploading files. Uploaded files get a permanent public URL that you can reference from your app.

import Proyecta from '@proyecta-ai/sdk';

const proyecta = new Proyecta({ apiKey: process.env.PROYECTA_API_KEY });

// List files (supports limit and starting_after for pagination)
const files = await proyecta.files.list();

// Fetch a single file by ID
const file = await proyecta.files.get('1234567890123456789');
console.log(file.url); // permanent public URL

// Upload a file (two-step)
// Step 1: create a placeholder and get a signed upload URL
const { id: fileId, upload_url } = await proyecta.files.create({
    filename: 'avatar.png',
    mime_type: 'image/png',
});

// Step 2: PUT the file bytes directly to the signed URL
await fetch(upload_url, {
    method: 'PUT',
    body: fileBytes,
    headers: { 'Content-Type': 'image/png' },
});

// Step 3: finalize to get the permanent file record
const uploaded = await proyecta.files.finalize({ fileId });
console.log(uploaded.url); // permanent public URL, now populated

Each file carries:

Field	Description
id	Unique identifier (numeric snowflake string)
url	Permanent public URL (populated after the finalize step)
filename	Original filename at upload
mime_type	image/jpeg, application/pdf, etc.
size	Size in bytes
path	Optional folder path (e.g. /images/blog)
content_hash	SHA-256 of file contents
metadata	Arbitrary key/value metadata
created	ISO 8601 creation timestamp
updated	ISO 8601 last-updated timestamp

How do files get uploaded to my app?

File uploads are handled through the AI builder. Ask the AI to build the upload flow for you:

• "Let users upload a profile photo and store it in Proyecta Files"
• "Add an image gallery where signed-in users can upload and view their photos"
• "Let me attach PDF invoices to orders"

The AI wires up the upload in your app code using the SDK’s two-step upload API and references the returned public URL. You can also call files.create() / files.finalize() directly from your own app code.

FAQ

Are the file URLs public?

Yes. Any file returned by the Files API has a permanent public URL. Don’t upload anything you don’t want exposed.

How big can a file be?

Per-file limits depend on your plan. Chat attachments are capped at 10 MB per image.

Can I resize or crop images at the URL?

On-the-fly image transforms (resize, crop, format conversion) are on the roadmap.

Coming soon

• Image transformations via URL parameters (resize, crop, format conversion)
• Folder organization — create and manage folder paths in the panel
• “Add to Chat” from a file row, so library assets can be dropped into the AI conversation