Skip to main content

​
Create file metadata

POST /api/v1/meta
Creates a new metadata record for an uploaded file.

​
Request body

​
filenameEnc
string
required
Encrypted filename - a 32-bit encoded string.
​
size
number
required
File size in bytes.
​
user
string
required
ID of the user who uploaded the file.
​
mimeType
string
required
MIME type of the file (e.g., image/png, application/pdf).
​
dekEnc
string
required
32-bit encrypted Data Encryption Key (DEK), wrapped by the master key.
​
thumb
boolean
required
Whether a thumbnail should be generated for this file.
{
  "filenameEnc": "a1b2c3d4e5f6a1b2c3d4e5f6a1b2c3d4",
  "size": 204800,
  "user": "usr_9f8e7d6c",
  "mimeType": "image/png",
  "dekEnc": "enc_k3y_wr4pp3d_by_m4st3r_k3y_00",
  "thumb": true
}

​
Response 200

Returns the created metadata record with a generated id and uploadedDate. 
{
  "id": "file_abc123",
  "filenameEnc": "a1b2c3d4e5f6a1b2c3d4e5f6a1b2c3d4",
  "size": 204800,
  "user": "usr_9f8e7d6c",
  "mimeType": "image/png",
  "dekEnc": "enc_k3y_wr4pp3d_by_m4st3r_k3y_00",
  "uploadedDate": "2026-06-05T14:30:00Z"
}

​
Get file metadata

GET /api/v1/meta/{fileId}
Retrieves the full metadata for a single file, including thumbnail availability and the encrypted DEK.

​
Path parameters

​
fileId
string
required
The unique file identifier.

​
Response 200

{
  "id": "file_abc123",
  "filenameEnc": "a1b2c3d4e5f6a1b2c3d4e5f6a1b2c3d4",
  "size": 204800,
  "mimeType": "image/png",
  "dekEnc": "enc_k3y_wr4pp3d_by_m4st3r_k3y_00",
  "thumbs": {
    "mobile": true,
    "web": true,
    "webPre": false
  },
  "uploadedDate": "2026-06-05T14:30:00Z"
}

​
Response 404

Returned when the file does not exist. 
{
  "error": "not_found"
}

​
List user files

GET /api/v1/meta?userId=
Retrieves a list of all file metadata for a specific user.
The dekEnc field is intentionally excluded from list responses. There is no reason to return the encrypted DEK for every file in a bulk listing.

​
Query parameters

​
userId
string
required
The user ID to filter files by.

​
Response 200

{
  "files": [
    {
      "id": "file_abc123",
      "filenameEnc": "a1b2c3d4e5f6a1b2c3d4e5f6a1b2c3d4",
      "size": 204800,
      "mimeType": "image/png",
      "thumb": true,
      "uploadedDate": "2026-06-05T14:30:00Z"
    },
    {
      "id": "file_def456",
      "filenameEnc": "f6e5d4c3b2a1f6e5d4c3b2a1f6e5d4c3",
      "size": 1048576,
      "mimeType": "application/pdf",
      "thumb": false,
      "uploadedDate": "2026-06-04T09:15:00Z"
    }
  ]
}

​
Delete file metadata

DELETE /api/v1/meta/{fileId}
Permanently deletes the metadata record for a file.

​
Path parameters

​
fileId
string
required
The unique file identifier.

​
Response 200

{
  "deleted": "file_abc123"
}

​
Response 404

Returned when the file does not exist. 
{
  "error": "not_found"
}