Metadata Service quickstart

This guide walks you through making your first requests to the Flux Metadata Service. By the end, you’ll have created a file metadata record, wrapped a DEK, and retrieved the metadata back.

The Metadata Service is internal only. All endpoints are accessible exclusively through the internal network. You must be connected to a Flux VPS or have direct internal network access - these endpoints are not exposed to the public internet.

Prerequisites

Before you begin, make sure you have:

Direct access to the Flux internal network (VPS connectivity)
A valid user ID for the target environment
curl or any HTTP client installed
The Metadata Service internal base URL (e.g., http://meta.internal:8080)

Make your first API calls

Wrap a DEK

Before creating file metadata, you need a wrapped DEK. Send a plain Data Encryption Key to the wrap endpoint - the service encrypts it with the master key and returns the wrapped version.

curl -X POST http://meta.internal:8080/api/v1/dek/wrap \
  -H "Content-Type: application/json" \
  -d '{
    "dek": "pl41n_d3k_k3y_32b1ts_0000000000"
  }'

You should receive a response like:

{
  "dekEnc": "enc_k3y_wr4pp3d_by_m4st3r_k3y_00"
}

Save the dekEnc value - you’ll use it in the next step.

Create file metadata

Use the wrapped DEK to create a metadata record for your file.

curl -X POST http://meta.internal:8080/api/v1/meta \
  -H "Content-Type: application/json" \
  -d '{
    "filenameEnc": "a1b2c3d4e5f6a1b2c3d4e5f6a1b2c3d4",
    "size": 204800,
    "user": "usr_9f8e7d6c",
    "mimeType": "image/png",
    "dekEnc": "enc_k3y_wr4pp3d_by_m4st3r_k3y_00",
    "thumb": true
  }'

The response includes the 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"
}

Retrieve the metadata

Fetch the metadata back using the file ID from the previous response.

curl http://meta.internal:8080/api/v1/meta/file_abc123

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

Check platform stats

Verify that your file was counted in the aggregate statistics.

curl http://meta.internal:8080/api/v1/stats

{
  "totalFiles": 1,
  "totalSizeBytes": 204800
}

Next steps

Now that you’ve made your first API calls, explore the full API reference:

File metadata

Full CRUD operations for metadata records.

DEK management

Wrap and unwrap encryption keys.

Statistics

Aggregate file and storage metrics.

Experimental

Cache sync, prefetch, and invalidation.

Need help? Reach out at support@fluxorg.pl.

Getting Started

Resources

Prerequisites

Make your first API calls

Next steps

File metadata

DEK management

Statistics

Experimental

​Prerequisites

​Make your first API calls

​Next steps

File metadata

DEK management

Statistics

Experimental

Prerequisites

Make your first API calls

Next steps