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

# Files

> File management endpoints for uploading, downloading, and managing both public and private files

# Files

LabTrace supports two types of files: **public files** (stored in AWS S3) and **private files** (stored only on IPFS). Both types have their metadata stored on IPFS and operations recorded on the blockchain.

## File Storage Overview

<CardGroup cols={2}>
  <Card title="Public Files" icon="globe">
    * **File Storage**: AWS S3 (publicly accessible)
    * **Metadata**: JSON stored on IPFS
    * **Access**: Can be accessed via web interface or SDK
    * **JSON Contains**: `FileHash` and `FileLinkS3`
  </Card>

  <Card title="Private Files" icon="lock">
    * **File Storage**: IPFS only (private access)
    * **Metadata**: JSON stored on IPFS
    * **Access**: Restricted to authorized users
    * **JSON Contains**: `FileHash` only (no `FileLinkS3`)
  </Card>
</CardGroup>

## File Status

Files can have the following statuses:

* **Available**: File is successfully uploaded and available
* **Pending**: File is being processed
* **PendingDeletion**: File deletion is being processed
* **NotarizationError**: Error occurred during blockchain recording
* **Deleted**: File has been marked as deleted

## Public Files

### Upload Public File

<Card title="POST /projects/{projectId}/files" icon="upload">
  Upload a new public file to a project
</Card>

### Parameters

* `projectId` (path): Project ID to upload the file to

### Request Body (multipart/form-data)

```
file: [File] - The file to upload
type: string - File type (primary/secondary)
label: string - Comma-separated labels/tags
uploaded: string - Upload timestamp (ISO format)
procedureDescription: string - Optional procedure description (for secondary files)
linkToProcedure: string - Optional comma-separated file IDs (for secondary files)
primaryData: string - Optional comma-separated primary data file IDs (for secondary files)
```

### Response

```json theme={null}
{
  "message": "File uploaded successfully",
  "fileId": "file-uuid-here"
}
```

### Example

```bash theme={null}
curl -X POST https://api.labtrace.io/projects/PROJECT_ID/files \
  -H "Authorization: Bearer YOUR_JWT_TOKEN" \
  -F "file=@document.pdf" \
  -F "type=primary" \
  -F "label=research,data" \
  -F "uploaded=2024-01-15T10:30:00Z"
```

### Get Project Files

<Card title="GET /projects/{projectId}/files" icon="list">
  Get all public files in a project
</Card>

### Parameters

* `projectId` (path): Project ID

### Response

```json theme={null}
{
  "records": [
    {
      "id": "file-uuid",
      "name": "research-data.pdf",
      "ownerId": "user-uuid",
      "ownerName": "John",
      "ownerLastName": "Doe",
      "label": "research,data",
      "type": "primary",
      "fileFormat": "application/pdf",
      "linkToProcedure": null,
      "procedureDescription": null,
      "primaryData": null,
      "downloadStatistic": 5,
      "uploaded": "2024-01-15T10:30:00Z",
      "status": "Available"
    }
  ],
  "start": 0,
  "limit": 50,
  "totalRecords": 1
}
```

### Get Single File

<Card title="GET /projects/{projectId}/files/{fileId}" icon="file">
  Get information about a specific file
</Card>

### Parameters

* `projectId` (path): Project ID
* `fileId` (path): File ID

### Response

```json theme={null}
{
  "id": "file-uuid",
  "name": "research-data.pdf",
  "ownerId": "user-uuid",
  "ownerName": "John",
  "ownerLastName": "Doe",
  "label": "research,data",
  "type": "primary",
  "fileFormat": "application/pdf",
  "linkToProcedure": null,
  "procedureDescription": null,
  "primaryData": null,
  "downloadStatistic": 5,
  "uploaded": "2024-01-15T10:30:00Z",
  "status": "Available"
}
```

### Download File

<Card title="GET /projects/{projectId}/files/{fileId}/download" icon="download">
  Get a pre-signed URL to download a file
</Card>

### Parameters

* `projectId` (path): Project ID
* `fileId` (path): File ID

### Response

```json theme={null}
{
  "s3Url": "https://s3.amazonaws.com/bucket/file-path?signature=..."
}
```

### Delete File

<Card title="PATCH /projects/{projectId}/file/{fileId}/delete" icon="trash">
  Mark a file as deleted
</Card>

### Parameters

* `projectId` (path): Project ID
* `fileId` (path): File ID

### Request Body

```json theme={null}
{
  "userId": "user-uuid",
  "reason": "User requested deletion"
}
```

### Response

```json theme={null}
{
  "message": "File has been successfully deleted."
}
```

### Get File Certificate

<Card title="GET /projects/{projectId}/files/{fileId}/download/certificate" icon="certificate">
  Download a blockchain certificate for a file
</Card>

### Parameters

* `projectId` (path): Project ID
* `fileId` (path): File ID
* `raw` (query): Set to `true` to get raw JSON data instead of PDF

### Response

Returns a PDF certificate or JSON data if `raw=true`

### Get File IPFS Content

<Card title="GET /projects/{projectId}/files/{fileId}/ipfs" icon="globe">
  Get the IPFS content metadata for a file
</Card>

### Parameters

* `projectId` (path): Project ID
* `fileId` (path): File ID

### Response

```json theme={null}
{
  "FileHash": "sha256-hash-of-file-content",
  "FileLinkS3": "https://s3.amazonaws.com/bucket/file-path",
  "JsonCid": "ipfs-hash-of-metadata"
}
```

## Private Files

### Upload Private File

<Card title="POST /private-files/project/{projectId}" icon="upload">
  Upload a new private file to a project
</Card>

### Parameters

* `projectId` (path): Project ID to upload the file to

### Request Body (multipart/form-data)

```
file: [File] - The file to upload
type: string - File type (primary/secondary)
label: string - Comma-separated labels/tags
uploaded: string - Upload timestamp (ISO format)
procedureDescription: string - Optional procedure description (for secondary files)
linkToProcedure: string - Optional comma-separated file IDs (for secondary files)
primaryData: string - Optional comma-separated primary data file IDs (for secondary files)
```

### Response

```json theme={null}
{
  "message": "File uploaded successfully",
  "fileId": "file-uuid-here"
}
```

### Get Private Project Files

<Card title="GET /private-files/project/{projectId}" icon="list">
  Get all private files in a project
</Card>

### Parameters

* `projectId` (path): Project ID

### Response

```json theme={null}
{
  "records": [
    {
      "id": "file-uuid",
      "name": "private-data.pdf",
      "ownerId": "user-uuid",
      "ownerName": "John",
      "ownerLastName": "Doe",
      "label": "sensitive,data",
      "type": "primary",
      "fileFormat": "application/pdf",
      "linkToProcedure": null,
      "procedureDescription": null,
      "primaryData": null,
      "downloadStatistic": 2,
      "uploaded": "2024-01-15T10:30:00Z",
      "status": "Available"
    }
  ],
  "start": 0,
  "limit": 50,
  "totalRecords": 1
}
```

### Delete Private File

<Card title="PATCH /private-files/project/{projectId}/file/{fileId}/delete" icon="trash">
  Mark a private file as deleted
</Card>

### Parameters

* `projectId` (path): Project ID
* `fileId` (path): File ID

### Request Body

```json theme={null}
{
  "userId": "user-uuid",
  "reason": "User requested deletion"
}
```

### Response

```json theme={null}
{
  "message": "File has been successfully deleted."
}
```

### Get Private File Certificate

<Card title="GET /private-files/project/{projectId}/files/{fileId}/download/certificate" icon="certificate">
  Download a blockchain certificate for a private file
</Card>

### Parameters

* `projectId` (path): Project ID
* `fileId` (path): File ID
* `raw` (query): Set to `true` to get raw JSON data instead of PDF

### Response

Returns a PDF certificate or JSON data if `raw=true`

### Get Private File IPFS Content

<Card title="GET /private-files/project/{projectId}/files/{fileId}/ipfs" icon="globe">
  Get the IPFS content metadata for a private file
</Card>

### Parameters

* `projectId` (path): Project ID
* `fileId` (path): File ID

### Response

```json theme={null}
{
  "FileHash": "sha256-hash-of-file-content",
  "JsonCid": "ipfs-hash-of-metadata"
}
```

## File Verification

### Verify File Existence

<Card title="POST /projects/files/verify" icon="search">
  Check if a file with the same content already exists in the platform
</Card>

### Request Body (multipart/form-data)

```
file: [File] - The file to verify
```

### Response

```json theme={null}
{
  "exists": true,
  "fileName": "existing-file.pdf",
  "project": "project-name"
}
```

## File Types

### Primary Files

Primary files are original research data or documents:

* Independent files that don't reference other files
* Can be referenced by secondary files
* Required fields: `file`, `type`, `label`, `uploaded`

### Secondary Files

Secondary files are derived from or reference primary files:

* Must reference one or more primary files
* Required additional fields: `linkToProcedure`, `procedureDescription`, `primaryData`
* Used for analysis results, reports, or derived data

## Blockchain Integration

All file operations are recorded on the Algorand blockchain:

* **Upload**: Records file hash and metadata on blockchain
* **Download**: Verifiable through blockchain transaction
* **Delete**: Marks file as deleted while preserving history
* **Certificate**: Provides cryptographic proof of file authenticity

## Error Responses

### 400 Bad Request

```json theme={null}
{
  "error": {
    "statusCode": 400,
    "message": "Invalid file format or missing required fields"
  }
}
```

### 401 Unauthorized

```json theme={null}
{
  "error": {
    "statusCode": 401,
    "message": "Authentication required"
  }
}
```

### 403 Forbidden

```json theme={null}
{
  "error": {
    "statusCode": 403,
    "message": "Insufficient permissions to access this file"
  }
}
```

### 404 Not Found

```json theme={null}
{
  "error": {
    "statusCode": 404,
    "message": "File not found"
  }
}
```

### 413 Payload Too Large

```json theme={null}
{
  "error": {
    "statusCode": 413,
    "message": "File size exceeds maximum allowed limit"
  }
}
```

## File Size Limits

* **Maximum file size**: 2.5 GB
* **Recommended size**: Under 100 MB for optimal performance
* **Supported formats**: All file types supported
* **Concurrent uploads**: Multiple files can be uploaded simultaneously