File metadata create, retrieve, and delete endpoints

Create file metadata

POST /api/v1/meta

Creates a new metadata record for an uploaded file.

Request body

string

required

Encrypted filename - a 32-bit encoded string.

number

required

File size in bytes.

string

required

ID of the user who uploaded the file.

string

required

MIME type of the file (e.g., image/png, application/pdf).

string

required

32-bit encrypted Data Encryption Key (DEK), wrapped by the master key.

boolean

required

Whether a thumbnail should be generated for this file.

Example request

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

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

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

string

required

The unique file identifier.

Response `200`

{
  "deleted": "file_abc123"
}

Response `404`

Returned when the file does not exist.

{
  "error": "not_found"
}

Core

Experimental

File metadata create, retrieve, and delete endpoints

Create file metadata

Request body

Response `200`

Get file metadata

Path parameters

Response `200`

Response `404`

List user files

Query parameters

Response `200`

Delete file metadata

Path parameters

Response `200`

Response `404`

​Create file metadata

​Request body

​Response 200

​Get file metadata

​Path parameters

​Response 200

​Response 404

​List user files

​Query parameters

​Response 200

​Delete file metadata

​Path parameters

​Response 200

​Response 404

Create file metadata

Request body

Response `200`

Get file metadata

Path parameters

Response `200`

Response `404`

List user files

Query parameters

Response `200`

Delete file metadata

Path parameters

Response `200`

Response `404`