Skip to main content

​
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

Public Files

  • 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

Private Files

  • File Storage: IPFS only (private access)
  • Metadata: JSON stored on IPFS
  • Access: Restricted to authorized users
  • JSON Contains: FileHash only (no FileLinkS3)

​
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

POST /projects/{projectId}/files

Upload a new public file to a project

​
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

{
  "message": "File uploaded successfully",
  "fileId": "file-uuid-here"
}

​
Example

curl -X POST https://api.labtrace.io/projects/PROJECT_ID/files \
  -H "Authorization: Bearer YOUR_JWT_TOKEN" \
  -F "[email protected]" \
  -F "type=primary" \
  -F "label=research,data" \
  -F "uploaded=2024-01-15T10:30:00Z"

​
Get Project Files

GET /projects/{projectId}/files

Get all public files in a project

​
Parameters

  • projectId (path): Project ID

​
Response

{
  "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

GET /projects/{projectId}/files/{fileId}

Get information about a specific file

​
Parameters

  • projectId (path): Project ID
  • fileId (path): File ID

​
Response

{
  "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

GET /projects/{projectId}/files/{fileId}/download

Get a pre-signed URL to download a file

​
Parameters

  • projectId (path): Project ID
  • fileId (path): File ID

​
Response

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

​
Delete File

PATCH /projects/{projectId}/file/{fileId}/delete

Mark a file as deleted

​
Parameters

  • projectId (path): Project ID
  • fileId (path): File ID

​
Request Body

{
  "userId": "user-uuid",
  "reason": "User requested deletion"
}

​
Response

{
  "message": "File has been successfully deleted."
}

​
Get File Certificate

GET /projects/{projectId}/files/{fileId}/download/certificate

Download a blockchain certificate for a file

​
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

GET /projects/{projectId}/files/{fileId}/ipfs

Get the IPFS content metadata for a file

​
Parameters

  • projectId (path): Project ID
  • fileId (path): File ID

​
Response

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

​
Private Files

​
Upload Private File

POST /private-files/project/{projectId}

Upload a new private file to a project

​
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

{
  "message": "File uploaded successfully",
  "fileId": "file-uuid-here"
}

​
Get Private Project Files

GET /private-files/project/{projectId}

Get all private files in a project

​
Parameters

  • projectId (path): Project ID

​
Response

{
  "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

PATCH /private-files/project/{projectId}/file/{fileId}/delete

Mark a private file as deleted

​
Parameters

  • projectId (path): Project ID
  • fileId (path): File ID

​
Request Body

{
  "userId": "user-uuid",
  "reason": "User requested deletion"
}

​
Response

{
  "message": "File has been successfully deleted."
}

​
Get Private File Certificate

GET /private-files/project/{projectId}/files/{fileId}/download/certificate

Download a blockchain certificate for a private file

​
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

GET /private-files/project/{projectId}/files/{fileId}/ipfs

Get the IPFS content metadata for a private file

​
Parameters

  • projectId (path): Project ID
  • fileId (path): File ID

​
Response

{
  "FileHash": "sha256-hash-of-file-content",
  "JsonCid": "ipfs-hash-of-metadata"
}

​
File Verification

​
Verify File Existence

POST /projects/files/verify

Check if a file with the same content already exists in the platform

​
Request Body (multipart/form-data)

file: [File] - The file to verify

​
Response

{
  "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

{
  "error": {
    "statusCode": 400,
    "message": "Invalid file format or missing required fields"
  }
}

​
401 Unauthorized

{
  "error": {
    "statusCode": 401,
    "message": "Authentication required"
  }
}

​
403 Forbidden

{
  "error": {
    "statusCode": 403,
    "message": "Insufficient permissions to access this file"
  }
}

​
404 Not Found

{
  "error": {
    "statusCode": 404,
    "message": "File not found"
  }
}

​
413 Payload Too Large

{
  "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