Assets API

Upload and manage files, images, and media for your AI assistant.

POST /api/sdk/assets/upload

Get a pre-signed URL for uploading files directly to our CDN.

Request Body

{
  filename: string;       // Original filename
  contentType: string;    // MIME type
  folder?: string;        // Optional folder path
}

Example Request

curl -X POST https://app.fig1.ai/api/sdk/assets/upload \
  -H "Content-Type: application/json" \
  -H "X-Fig1-API-Key: fig1_sdk_abc123" \
  -d '{
    "filename": "product-image.jpg",
    "contentType": "image/jpeg",
    "folder": "products"
  }'

Response

{
  "success": true,
  "data": {
    "uploadUrl": "https://storage.fig1.ai/upload/...",
    "cdnUrl": "https://cdn.fig1.ai/sites/abc/products/product-image.jpg",
    "key": "sites/abc123/products/product-image.jpg",
    "expiresIn": 3600
  }
}

Two-Step Upload Process

Step 1: Get Upload URL

const response = await fetch('https://app.fig1.ai/api/sdk/assets/upload', {
  method: 'POST',
  headers: {
    'Content-Type': 'application/json',
    'X-Fig1-API-Key': 'fig1_sdk_abc123'
  },
  body: JSON.stringify({
    filename: file.name,
    contentType: file.type,
    folder: 'uploads'
  })
});

const { data } = await response.json();

Step 2: Upload File

await fetch(data.uploadUrl, {
  method: 'PUT',
  body: file,
  headers: {
    'Content-Type': file.type
  }
});

// File is now available at data.cdnUrl
console.log('Uploaded to:', data.cdnUrl);

Complete Upload Example

TypeScript/JavaScript

async function uploadFile(file: File, folder?: string): Promise<string> {
  // 1. Get upload URL
  const response = await fetch('https://app.fig1.ai/api/sdk/assets/upload', {
    method: 'POST',
    headers: {
      'Content-Type': 'application/json',
      'X-Fig1-API-Key': process.env.FIG1_API_KEY!
    },
    body: JSON.stringify({
      filename: file.name,
      contentType: file.type,
      folder
    })
  });

  const { data } = await response.json();

  // 2. Upload to pre-signed URL
  await fetch(data.uploadUrl, {
    method: 'PUT',
    body: file,
    headers: { 'Content-Type': file.type }
  });

  // 3. Return CDN URL
  return data.cdnUrl;
}

// Usage
const imageUrl = await uploadFile(imageFile, 'products');

React Component

function FileUpload({ onUpload }: { onUpload: (url: string) => void }) {
  const [uploading, setUploading] = useState(false);

  const handleChange = async (e: React.ChangeEvent<HTMLInputElement>) => {
    const file = e.target.files?.[0];
    if (!file) return;

    setUploading(true);
    try {
      const cdnUrl = await uploadFile(file);
      onUpload(cdnUrl);
    } finally {
      setUploading(false);
    }
  };

  return (
    <input
      type="file"
      onChange={handleChange}
      disabled={uploading}
    />
  );
}

GET /api/sdk/assets/folders

List asset folders.

curl -X GET "https://app.fig1.ai/api/sdk/assets/folders" \
  -H "X-Fig1-API-Key: fig1_sdk_abc123"

Response:

{
  "success": true,
  "data": [
    {
      "_id": "folder_abc123",
      "name": "products",
      "path": "/products",
      "createdAt": "2024-01-15T10:00:00Z"
    },
    {
      "_id": "folder_def456",
      "name": "blog",
      "path": "/blog",
      "createdAt": "2024-01-16T10:00:00Z"
    }
  ]
}

POST /api/sdk/assets/folders

Create a new folder.

curl -X POST https://app.fig1.ai/api/sdk/assets/folders \
  -H "Content-Type: application/json" \
  -H "X-Fig1-API-Key: fig1_sdk_abc123" \
  -d '{
    "name": "marketing",
    "parentId": "folder_abc123"
  }'

Supported File Types

Images

• JPEG, PNG, GIF, WebP, SVG
• Max size: 10MB

Documents

• PDF, DOCX, TXT, MD
• Max size: 50MB
• Auto-indexed for RAG search

Media

• MP4, MP3, WebM
• Max size: 500MB

CDN Features

All uploaded files are served through our global CDN with:

• Automatic optimization - Images are resized and compressed
• Global edge caching - Fast delivery worldwide
• HTTPS - All URLs are secure
• Permanent URLs - URLs don't expire after upload

Image Transformations

Add query parameters to CDN URLs for on-the-fly transformations:

https://cdn.fig1.ai/sites/abc/image.jpg?w=400&h=300&fit=cover

| Parameter | Description | Example | |-----------|-------------|---------| | w | Width in pixels | w=400 | | h | Height in pixels | h=300 | | fit | Resize mode | fit=cover, fit=contain | | q | Quality (1-100) | q=80 | | f | Format | f=webp, f=avif |

Error Handling

File Too Large (413)

{
  "success": false,
  "error": "File exceeds maximum size of 10MB"
}

Invalid File Type (400)

{
  "success": false,
  "error": "File type not supported"
}

Upload URL Expired (400)

{
  "success": false,
  "error": "Upload URL has expired. Request a new one."
}