File Management

ProductFlo provides a comprehensive file management system that supports version control, metadata extraction, contextual markup, and fine-grained access control. This guide explains how to work with files in the ProductFlo API.

Storage Architecture

ProductFlo uses a layered storage architecture:

S3 Storage
Local Cache
Database

Primary storage for all files using S3-compatible object storage systems

File Upload

POST /files/upload

Upload one or more files to ProductFlo

The upload process follows these steps:

Get a pre-signed upload URL (optional for large files)
Upload the file to the URL
Register the file with metadata
Process the file for indexing and preview generation

// Using FormData
const formData = new FormData();
formData.append('file', fileObject);
formData.append('product_id', 'product-123');

const response = await fetch('https://api.productflo.io/files/upload', {
  method: 'POST',
  headers: {
    'Authorization': 'Bearer YOUR_TOKEN',
    'X-Tenant-ID': 'tenant-123'
  },
  body: formData
});

const data = await response.json();

const formData = new FormData();

// Add multiple files
for (const file of fileList) {
  formData.append('files', file);
}

formData.append('product_id', 'product-123');
formData.append('folder_path', '/designs/2023/');

const response = await fetch('https://api.productflo.io/files/multiple-upload', {
  method: 'POST',
  headers: {
    'Authorization': 'Bearer YOUR_TOKEN',
    'X-Tenant-ID': 'tenant-123'
  },
  body: formData
});

const data = await response.json();

Upload Parameters

string

The ID of the product to associate the file with

string

Virtual folder path for organizing files

string

Optional description of the file

array

Optional array of tags for categorizing the file

boolean

default:false

Whether the file should be publicly accessible

boolean

default:false

Whether to replace any existing file with the same name

File Download

GET /files/{file_id}/download

Download a file

// Direct download (browser will handle the file)
window.location.href = `https://api.productflo.io/files/${fileId}/download?token=${accessToken}`;

const response = await fetch(`https://api.productflo.io/files/${fileId}/download`, {
  headers: {
    'Authorization': 'Bearer YOUR_TOKEN',
    'X-Tenant-ID': 'tenant-123'
  }
});

const blob = await response.blob();
const url = window.URL.createObjectURL(blob);

// Create a download link
const a = document.createElement('a');
a.href = url;
a.download = 'filename.ext'; // Use the actual filename
document.body.appendChild(a);
a.click();
window.URL.revokeObjectURL(url);

File Revisions

ProductFlo automatically maintains file revisions when files are updated. You can access previous versions of a file using the revision endpoints.

GET /files/{file_id}/revisions

List all revisions of a file

GET /files/{file_id}/revisions/{revision_id}

Get a specific revision of a file

POST /files/{file_id}/revert/{revision_id}

Revert to a previous revision

File Metadata

Files in ProductFlo have rich metadata that includes:

Basic properties (name, size, type, creation date)
Custom properties (user-defined metadata)
Extracted metadata (from file contents)
Relationships (products, conversations, etc.)
Access control information

{
  "id": "file-123",
  "name": "assembly-v2.step",
  "size": 2456789,
  "type": "model/step",
  "mime_type": "application/step",
  "created_at": "2023-05-01T12:34:56.789Z",
  "updated_at": "2023-05-15T09:22:33.456Z",
  "created_by": "user-456",
  "current_revision_id": "rev-789",
  "revision_count": 3,
  "path": "/designs/2023/assembly-v2.step",
  "url": "https://api.productflo.io/files/file-123/download",
  "preview_url": "https://api.productflo.io/files/file-123/preview",
  "thumbnail_url": "https://api.productflo.io/files/file-123/thumbnail",
  "product_id": "product-789",
  "description": "Final assembly design for the prototype",
  "tags": ["assembly", "prototype", "final"],
  "metadata": {
    "dimensions": {
      "width": 120.5,
      "height": 85.3,
      "depth": 45.2,
      "units": "mm"
    },
    "components": 37,
    "software": "Fusion 360 v2023.1",
    "custom_properties": {
      "material": "Aluminum 6061",
      "finish": "Anodized",
      "color": "Black"
    }
  },
  "permissions": {
    "view": ["team-123", "user-456", "user-789"],
    "edit": ["team-123"],
    "delete": ["user-456"]
  }
}

File Processing

When files are uploaded, ProductFlo performs several processing steps:

Virus scanning: Checks files for malware
Metadata extraction: Pulls out technical information from the file
Preview generation: Creates images or 3D previews depending on file type
Indexing: Makes the file content searchable
Classification: Automatically categorizes files

CAD File Support

ProductFlo has specialized support for CAD files:

Format support: STEP, IGES, STL, OBJ, SLDPRT, DWG, DXF, and more
3D preview: Web-based 3D viewing without specialized software
Measurement tools: Measure dimensions directly in the preview
Metadata extraction: Extracts dimensions, components, materials, etc.
Markup support: Add annotations and comments to specific parts

GET /files/{file_id}/cad-metadata

Get detailed CAD-specific metadata

File Annotations and Markup

ProductFlo allows you to add contextual annotations to files, which are especially useful for technical documentation and design reviews.

POST /files/{file_id}/annotations

Add an annotation to a file

GET /files/{file_id}/annotations

Get all annotations for a file

Annotation Data Structure

{
  "id": "annotation-123",
  "file_id": "file-456",
  "user_id": "user-789",
  "created_at": "2023-06-01T10:20:30.456Z",
  "text": "We need to reinforce this connection point",
  "position": {
    "x": 120.5,
    "y": 85.3,
    "z": 45.2
  },
  "target": {
    "type": "point", // or "area", "component"
    "component_id": "component-123" // if targeting a specific component
  },
  "color": "#FF5733",
  "status": "open", // or "resolved", "in-progress"
  "replies": [
    {
      "id": "reply-123",
      "user_id": "user-456",
      "created_at": "2023-06-01T11:22:33.789Z",
      "text": "I'll add a gusset plate here"
    }
  ]
}

File Access Control

ProductFlo provides fine-grained access control for files:

User-level permissions: Control which users can view, edit, or delete files
Team-level permissions: Grant access to entire teams
Role-based access: Define access based on user roles
Public/private files: Make files publicly accessible when needed
Temporary access: Generate time-limited access tokens

PUT /files/{file_id}/permissions

Update file permissions

GET /files/{file_id}/access-token

Generate a temporary access token

Best Practices

When working with files in ProductFlo, follow these best practices:

Chunk large uploads: For files larger than 100MB, use chunked uploads to improve reliability.
Include metadata: Always provide as much metadata as possible during upload for better searchability.
Use revisions: Instead of creating new files, update existing ones to maintain revision history.
Optimize file size: Compress files when possible before uploading, especially images and CAD files.
Use appropriate permissions: Restrict file access to only those who need it.
Add context: Use annotations and comments to provide context for files.
Organize with folders: Use folder paths to maintain a logical structure.
Use tags: Tag files consistently for easier filtering and searching.

Get Started

Core Concepts

File Management

File Management

Storage Architecture

File Upload

POST /files/upload

Upload Parameters

File Download

GET /files/{file_id}/download

File Revisions

GET /files/{file_id}/revisions

GET /files/{file_id}/revisions/{revision_id}

POST /files/{file_id}/revert/{revision_id}

File Metadata

File Processing

CAD File Support

GET /files/{file_id}/cad-metadata

File Annotations and Markup

POST /files/{file_id}/annotations

GET /files/{file_id}/annotations

Annotation Data Structure

File Access Control

PUT /files/{file_id}/permissions

GET /files/{file_id}/access-token

Best Practices

​File Management

​Storage Architecture

​File Upload

POST /files/upload

​Upload Parameters

​File Download

GET /files/{file_id}/download

​File Revisions

GET /files/{file_id}/revisions

GET /files/{file_id}/revisions/{revision_id}

POST /files/{file_id}/revert/{revision_id}

​File Metadata

​File Processing

​CAD File Support

GET /files/{file_id}/cad-metadata

​File Annotations and Markup

POST /files/{file_id}/annotations

GET /files/{file_id}/annotations

​Annotation Data Structure

​File Access Control

PUT /files/{file_id}/permissions

GET /files/{file_id}/access-token

​Best Practices

File Management

Storage Architecture

File Upload

Upload Parameters

File Download

File Revisions

File Metadata

File Processing

CAD File Support

File Annotations and Markup

Annotation Data Structure

File Access Control

Best Practices