Files

Files are used to store media assets like images, PDFs, and other content in Lettercast. On this page, we'll explore the different file endpoints you can use to manage files programmatically.

The file model

The file model contains all the information about the files you upload and manage in Lettercast.

Properties

Name
id
Type
string
Description
Unique identifier for the file.
Name
path
Type
string
Description
The path where the file is stored.
Name
file_type
Type
string
Description
The type of file. Must be one of the allowed file types.
Name
meta_data
Type
object
Description
Additional metadata about the file, including:
- original_filename: Original name of the uploaded file
- uploaded_by: Username of the uploader
- uploaded_at: Timestamp of upload
Name
created_at
Type
string
Description
The date and time when the file was created.

POST/v1/files

Upload a file

This endpoint allows you to upload a new file. The file content should be sent as a base64-encoded string.

Limitations

Maximum file size: 10 MB
Supported file types: POD_VIDEO_IMAGE, POD_VIDEO_LOGO

Required Parameters

Name
file
Type
string
Description
The base64-encoded file content.
Name
file_type
Type
string
Description
The type of file being uploaded. Must be one of:
- POD_VIDEO_IMAGE
- POD_VIDEO_LOGO
Name
filename
Type
string
Description
The original filename.

Optional Parameters

Name
meta_data
Type
object
Description
Additional metadata to store with the file.

Request

POST

/v1/files

// Convert file to base64
const fileToBase64 = (file) => {
  // Check file size
  if (file.size > 10 * 1024 * 1024) {
    throw new Error('File size exceeds maximum limit of 10 MB');
  }
  
  return new Promise((resolve, reject) => {
    const reader = new FileReader();
    reader.readAsDataURL(file);
    reader.onload = () => {
      let encoded = reader.result.toString().replace(/^data:(.*,)?/, '');
      resolve(encoded);
    };
    reader.onerror = error => reject(error);
  });
};

// Upload file
async function uploadFile(file) {
  try {
    const base64 = await fileToBase64(file);
    
    const response = await fetch('https://app.lettercast.ai/v1/files', {
      method: 'POST',
      headers: {
        'Authorization': `Bearer ${API_KEY}`,
        'Content-Type': 'application/json',
      },
      body: JSON.stringify({
        file: base64,
        filename: file.name,
        file_type: 'POD_VIDEO_IMAGE',
        meta_data: {
          usage: 'logo'
        }
      }),
    });

    if (!response.ok) {
      const error = await response.json();
      throw new Error(error.error || 'Upload failed');
    }

    const data = await response.json();
    return data.file_id;
  } catch (error) {
    console.error('File upload error:', error.message);
    throw error;
  }
}

Response

{
  "file_id": "123e4567-e89b-12d3-a456-426614174000"
}

GET/v1/files/:id

Get file details

This endpoint allows you to retrieve details about a specific file.

Request

GET

/v1/files/123e4567-e89b-12d3-a456-426614174000

async function getFileDetails(fileId) {
  const response = await fetch(`https://app.lettercast.ai/v1/files/${fileId}`, {
    headers: {
      'Authorization': `Bearer ${API_KEY}`,
    },
  });

  if (!response.ok) {
    throw new Error('Failed to fetch file details');
  }

  return response.json();
}

Response

{
  "id": "123e4567-e89b-12d3-a456-426614174000",
  "path": "pod_video_images/123e4567-e89b-12d3-a456-426614174000.png",
  "file_type": "POD_VIDEO_IMAGE",
  "meta_data": {
    "original_filename": "image.png",
    "uploaded_by": "user123",
    "uploaded_at": "2024-02-14T12:00:00Z",
    "usage": "logo"
  },
  "created_at": "2024-02-14T12:00:00Z"
}