Files — Upload, download, and manage IPFS-pinned files

Files are the core resource in Blockchain Drive. Each file is pinned to IPFS and receives a content identifier (CID). Optionally, the file can be anchored on Ethereum for tamper-proof provenance. Files may be encrypted client-side before upload; the encryption metadata travels alongside the CID. All file endpoints require an authenticated session. A 401 is returned when the session cookie is absent or expired.

POST /upload

Uploads a file to IPFS and records it in the database. The request must be multipart/form-data. Maximum file size is 500 MB.

file

binary

required

The raw file bytes. Use the field name file.

filename

string

Override the file’s display name. Defaults to the original filename from the multipart upload.

description

string

Free-text description stored alongside the file record.

encryption

string

JSON-encoded encryption metadata produced by the client before upload (algorithm, IV, encrypted key, etc.). See /api/encryption/encrypt for the shape.

driveId

number

Numeric ID of a collaborative drive to associate this file with. The caller must have at least editor role on that drive.

folderId

number

Numeric ID of a folder within the drive. Ignored when driveId is absent.

curl -X POST https://api.blockchaindrive.io/upload \
  --cookie "connect.sid=..." \
  -F "file=@report.pdf" \
  -F "filename=Q3 Report" \
  -F "driveId=7"

success

boolean

required

Always true on success.

cid

string

required

IPFS content identifier for the uploaded file.

customHash

string | null

required

Application-level hash used for integrity verification, or null if not computed.

{
  "success": true,
  "cid": "bafybeigdyrzt5sfp7udm...",
  "customHash": "sha256:e3b0c44298fc..."
}

Errors

Status	Error code	Condition
`403`	`QUOTA_EXCEEDED`	The file would exceed the user’s personal storage quota
`403`	`DRIVE_QUOTA_EXCEEDED`	The file would exceed the target drive’s quota
`403`	`ROLE_FORBIDDEN`	The user’s drive role does not permit uploads

GET /files

Lists files owned by the authenticated user, or files within a specific drive or folder.

driveId

number

Filter to files in this collaborative drive. The caller must have at least viewer role.

folderId

number

Further filter to a specific folder within the drive.

curl "https://api.blockchaindrive.io/files?driveId=7" \
  --cookie "connect.sid=..."

Returns an array of file objects:

number

required

Unique file ID.

filename

string

required

Display name of the file.

cid

string

required

IPFS content identifier.

size_bytes

number

required

File size in bytes.

custom_hash

string | null

Application-level integrity hash.

tx_hash

string | null

Ethereum transaction hash if the file has been anchored on-chain.

encryption

object | null

Encryption metadata, or null for unencrypted files.

drive_id

number | null

Drive this file belongs to, or null for personal storage.

folder_id

number | null

Folder this file belongs to, or null for the drive root.

POST /delete/:id

Permanently removes a file record. Only the file owner can delete.

number

required

Numeric ID of the file to delete.

curl -X POST "https://api.blockchaindrive.io/delete/123" \
  --cookie "connect.sid=..."

{ "success": true }

GET /files/:id/content

Streams the raw file bytes from IPFS. The response sets Content-Type and Content-Disposition: inline headers based on the stored file name.

number

required

Numeric ID of the file.

curl -OJ "https://api.blockchaindrive.io/files/123/content" \
  --cookie "connect.sid=..."

Errors: 403 ACCESS_DENIED, 404 NOT_FOUND, 502 IPFS_FETCH_FAILED.

GET /files/:id/crypto

Returns the encryption metadata needed to decrypt a file client-side. The encryptedKey field is scoped to the caller: owners receive the owner-encrypted key; shared users receive the key that was encrypted specifically for them when the file was shared.

number

required

Numeric ID of the file.

isEncrypted

boolean

required

Whether the file was encrypted before upload.

algorithm

string | null

Encryption algorithm, e.g. AES-256.

string | null

Base64-encoded initialization vector.

encryptedKey

string | null

The file encryption key, encrypted with the caller’s public key.

cid

string | null

IPFS CID of the (encrypted) file bytes.

originalName

string

Original file name before encryption.

originalMimeType

string

MIME type of the plaintext file.

{
  "isEncrypted": true,
  "algorithm": "AES-256",
  "iv": "aGVsbG8gd29ybGQ=",
  "encryptedKey": "AAAA...base64...",
  "cid": "bafybeigdyrzt...",
  "originalName": "report.pdf",
  "originalMimeType": "application/pdf"
}

Returns 403 when the file is encrypted but no key exists for the requesting user. This happens if the file was shared without re-encrypting the key for the recipient.

GET /files/:id/view-url

Returns a signed in-app viewer URL that can be embedded in an iframe or opened in the Blockchain Drive viewer.

number

required

Numeric ID of the file.

url

string

required

Absolute URL to the in-app file viewer.

{ "url": "https://app.blockchaindrive.io/view/bafybei..." }

POST /files/:id/anchor

Submits an Ethereum transaction to anchor the file’s CID on-chain, creating a tamper-proof provenance record.

number

required

Numeric ID of the file to anchor.

curl -X POST "https://api.blockchaindrive.io/files/123/anchor" \
  --cookie "connect.sid=..."

success

boolean

required

Always true.

txHash

string

required

Ethereum transaction hash of the anchor transaction.

{ "success": true, "txHash": "0xabc123..." }

Anchoring costs gas. The transaction is submitted from the server-side signing key configured via environment variables. The txHash is stored against the file record and returned in GET /files as tx_hash.

POST /files/:id/link

Creates a time-limited, publicly accessible link to a file. The link resolves via the IPFS gateway without requiring authentication.

number

required

Numeric ID of the file.

expiresInMinutes

number

required

Positive integer. How long the link remains valid. Defaults to 60 if omitted or 0.

url

string

required

The shareable link URL.

expiresAt

string

required

ISO 8601 timestamp when the link expires.

{
  "url": "https://api.blockchaindrive.io/l/eyJh...",
  "expiresAt": "2025-06-01T12:00:00.000Z"
}

GET /l/:token

Resolves an expiring link token and redirects to the IPFS gateway. No authentication required — this endpoint is designed for public sharing.

token

string

required

The opaque token from a POST /files/:id/link response.

Status	Condition
`302`	Token valid — redirects to `{IPFS_GATEWAY_URL}/ipfs/{cid}`
`404`	Token not found
`410`	Token has expired

GET /files/:id/comments

Lists all comments left on a file. The caller must have at least viewer access.

number

required

Numeric ID of the file.

Returns an array of comment objects ordered by creation time.

POST /files/:id/comments

Adds a comment to a file. The caller must have at least viewer access.

number

required

Numeric ID of the file.

text

string

required

Comment content. Must be non-empty.

{ "success": true }

GET /me

Returns profile and storage quota information for the authenticated user.

number

required

Internal user ID.

username

string | null

required

Display username.

role

string

required

Account role: admin, uploader, or commenter.

quotaBytes

number

required

Total allocated storage in bytes.

usedBytes

number

required

Storage consumed across all files in bytes.

remainingBytes

number

required

Remaining quota in bytes.

{
  "id": 42,
  "username": "alice_eth",
  "role": "editor",
  "quotaBytes": 10737418240,
  "usedBytes": 1073741824,
  "remainingBytes": 9663676416
}

Looks up another user by username or wallet address. Use this before sharing a file to retrieve the recipient’s encryption public key.

identifier

string

required

A username or Ethereum wallet address.

number

required

Internal user ID of the target.

walletAddress

string

required

Ethereum wallet address.

encryptionPublicKey

string | null

required

MetaMask encryption public key, if the user has registered one.

username

string | null

required

Display username.

{
  "id": 99,
  "walletAddress": "0xdef789...",
  "encryptionPublicKey": "AAAA...base64...",
  "username": "bob_eth"
}

If encryptionPublicKey is null, the recipient has not registered a key via POST /auth/encryption-key and cannot receive end-to-end encrypted file shares.

Authentication

Files & Drives

Encryption

Admin

Files — Upload, download, and manage IPFS-pinned files

POST /upload

GET /files

POST /delete/:id

GET /files/:id/content

GET /files/:id/crypto

GET /files/:id/view-url

POST /files/:id/anchor

POST /files/:id/link

GET /l/:token

GET /files/:id/comments

POST /files/:id/comments

GET /me

Build docs developers (and LLMs) love

Authentication

Files & Drives

Encryption

Admin

Documentation Index

​POST /upload

​GET /files

​POST /delete/:id

​GET /files/:id/content

​GET /files/:id/crypto

​GET /files/:id/view-url

​POST /files/:id/anchor

​POST /files/:id/link

​GET /l/:token

​GET /files/:id/comments

​POST /files/:id/comments

​GET /me

​GET /share-target

Build docs developers (and LLMs) love

POST /upload

GET /files

POST /delete/:id

GET /files/:id/content

GET /files/:id/crypto

GET /files/:id/view-url

POST /files/:id/anchor

POST /files/:id/link

GET /l/:token

GET /files/:id/comments

POST /files/:id/comments

GET /me

GET /share-target