> ## Documentation Index
> Fetch the complete documentation index at: https://docs.productflo.io/llms.txt
> Use this file to discover all available pages before exploring further.

# File Management

> Managing files and assets in ProductFlo

# 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:

<Tabs>
  <Tab title="S3 Storage">
    Primary storage for all files using S3-compatible object storage systems
  </Tab>

  <Tab title="Local Cache">
    Temporary storage for files being processed or used in active sessions
  </Tab>

  <Tab title="Database">
    Stores file metadata, permissions, and relationships to other entities
  </Tab>
</Tabs>

## File Upload

<Card title="POST /files/upload" icon="upload" iconType="duotone">
  Upload one or more files to ProductFlo
</Card>

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

<CodeGroup>
  ```javascript Single File Upload theme={null}
  // 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();
  ```

  ```javascript Multiple Files Upload theme={null}
  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();
  ```
</CodeGroup>

### Upload Parameters

<ParamField query="product_id" type="string">
  The ID of the product to associate the file with
</ParamField>

<ParamField query="folder_path" type="string">
  Virtual folder path for organizing files
</ParamField>

<ParamField query="description" type="string">
  Optional description of the file
</ParamField>

<ParamField query="tags" type="array">
  Optional array of tags for categorizing the file
</ParamField>

<ParamField query="public" type="boolean" default={false}>
  Whether the file should be publicly accessible
</ParamField>

<ParamField query="replace_if_exists" type="boolean" default={false}>
  Whether to replace any existing file with the same name
</ParamField>

## File Download

<Card title="GET /files/{file_id}/download" icon="download" iconType="duotone">
  Download a file
</Card>

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

  ```javascript Programmatic Download theme={null}
  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);
  ```
</CodeGroup>

## File Revisions

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

<Card title="GET /files/{file_id}/revisions" icon="clock-rotate-left" iconType="duotone">
  List all revisions of a file
</Card>

<Card title="GET /files/{file_id}/revisions/{revision_id}" icon="file-circle-check" iconType="duotone">
  Get a specific revision of a file
</Card>

<Card title="POST /files/{file_id}/revert/{revision_id}" icon="rotate-left" iconType="duotone">
  Revert to a previous revision
</Card>

## 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

<CodeGroup>
  ```json File Metadata Example theme={null}
  {
    "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"]
    }
  }
  ```
</CodeGroup>

## 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

<Card title="GET /files/{file_id}/cad-metadata" icon="ruler-combined" iconType="duotone">
  Get detailed CAD-specific metadata
</Card>

## File Annotations and Markup

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

<Card title="POST /files/{file_id}/annotations" icon="comment-dots" iconType="duotone">
  Add an annotation to a file
</Card>

<Card title="GET /files/{file_id}/annotations" icon="comments" iconType="duotone">
  Get all annotations for a file
</Card>

### Annotation Data Structure

```json theme={null}
{
  "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

<Card title="PUT /files/{file_id}/permissions" icon="lock" iconType="duotone">
  Update file permissions
</Card>

<Card title="GET /files/{file_id}/access-token" icon="key" iconType="duotone">
  Generate a temporary access token
</Card>

## 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.