Files

This endpoint provides comprehensive file management capabilities, including uploading, downloading, and retrieving file metadata.

Upload

To upload a file, send a POST request to /files/upload with the file as a form-data field named file. The server responds with a 201 Created status code and returns a FileRecord object containing the file’s metadata.

Files are stored in the system for at least 7 days by default. For permanent storage, attach the file to a database record by referencing the file’s URL in supported attributes of your database models.

Download

To download a file, send a GET request to /files/:file_id. The response contains the file with appropriate content-type and content-length headers.

Public download

This feature is not implemented yet. Authentication is currently required for all file downloads.

Image and Video Variants

For image and video files, you can request optimized variants by sending a GET request to /files/:file_id/:variant. This is useful for displaying thumbnails or responsive images based on device requirements.

Available image variants:

• thumb: 40x40 pixels (thumbnail)
• small: 120x120 pixels
• medium: 360x360 pixels
• large: 1080x1080 pixels
• original: Original dimensions in original format
• avif: Original dimensions converted to AVIF format

All variant sizes (except ‘original’ and ‘avif’) are returned in the AVIF format for optimal compression. The ‘original’ variant preserves the uploaded format, while ‘avif’ converts the original dimensions to AVIF format.

Endpoints

• get /api/v3/files/(:variant/)?:file_id
• get /api/v3/files/info/:file_id
• post /api/v3/files/upload

get/api/v3/files/(:variant/)?:file_id

Download a file with optional variant selection for images and videos.

This endpoint streams the requested file directly to the client with appropriate content-type and content-length headers. For images and videos, you can request specific variants optimized for different use cases.

Available Variants

• thumb: 40x40 pixels (thumbnail, AVIF format)
• small: 120x120 pixels (AVIF format)
• medium: 360x360 pixels (AVIF format)
• large: 1080x1080 pixels (AVIF format)
• original: Original dimensions in original format
• avif: Original dimensions converted to AVIF format

If no variant is specified, the original variant is returned by default.

type InputSchema = { file_id: string; variant?: string | null };

get/api/v3/files/info/:file_id

Retrieve detailed information and metadata about a file.

This endpoint returns comprehensive metadata about the specified file, including:

• File name, size, and MIME type
• Upload timestamp and uploader information
• File status and retention information
• Any custom metadata associated with the file

This is useful when you need file information without downloading the actual file content.

type InputSchema = { file_id: number };

type OutputSchema = {
  data: {
    type: string;
    id?: string;
    attributes?: {
      id?: number;
      size?: string;
      mime_type?: string;
      public?: boolean;
      created_by?: number;
      created_role?: string;
      created_at?: Date;
      path?: string;
    };
    relationships?: Record<string, any>;
  };
  included?: Array<Record<string, any>>;
};

post/api/v3/files/upload

Upload a file to the Pulse system.

This endpoint accepts file uploads and stores them in the system. Files are retained for at least 7 days by default. To ensure permanent storage, attach the file to a database record after upload.

Technical Details

• Uses multipart/form-data content type
• Returns a Model::FileRecord object with complete file metadata
• Sets HTTP status code 201 (Created) on success
• Maximum file size: [system-defined limit]
• Supported file types: All common document, image, video, and audio formats

type InputSchema = {
  // The file to upload
  file: {
    filename?: string;
    type?: string;
    name?: string;
    tempfile: any;
    head?: string;
  };
};

type OutputSchema = {
  data: {
    type: string;
    id?: string;
    attributes?: {
      id?: number;
      size?: string;
      mime_type?: string;
      public?: boolean;
      created_by?: number;
      created_role?: string;
      created_at?: Date;
      path?: string;
    };
    relationships?: Record<string, any>;
  };
  included?: Array<Record<string, any>>;
};