​
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:
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:
  1. Get a pre-signed upload URL (optional for large files)
  2. Upload the file to the URL
  3. Register the file with metadata
  4. 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();

​
Upload Parameters

​
product_id
string
The ID of the product to associate the file with
​
folder_path
string
Virtual folder path for organizing files
​
description
string
Optional description of the file
​
tags
array
Optional array of tags for categorizing the file
​
public
boolean
default:false
Whether the file should be publicly accessible
​
replace_if_exists
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}`;

​
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:
  1. Virus scanning: Checks files for malware
  2. Metadata extraction: Pulls out technical information from the file
  3. Preview generation: Creates images or 3D previews depending on file type
  4. Indexing: Makes the file content searchable
  5. 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:
  1. Chunk large uploads: For files larger than 100MB, use chunked uploads to improve reliability.
  2. Include metadata: Always provide as much metadata as possible during upload for better searchability.
  3. Use revisions: Instead of creating new files, update existing ones to maintain revision history.
  4. Optimize file size: Compress files when possible before uploading, especially images and CAD files.
  5. Use appropriate permissions: Restrict file access to only those who need it.
  6. Add context: Use annotations and comments to provide context for files.
  7. Organize with folders: Use folder paths to maintain a logical structure.
  8. Use tags: Tag files consistently for easier filtering and searching.