> ## Documentation Index
> Fetch the complete documentation index at: https://meta.fluxdrop.pl/llms.txt
> Use this file to discover all available pages before exploring further.

# Metadata Service quickstart

> Set up your internal network access and make your first Flux Metadata Service calls to wrap a DEK, create a metadata record, and retrieve it.

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.

<Warning>
  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.
</Warning>

## 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

<Steps>
  <Step title="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.

    ```bash theme={null}
    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:

    ```json theme={null}
    {
      "dekEnc": "enc_k3y_wr4pp3d_by_m4st3r_k3y_00"
    }
    ```

    Save the `dekEnc` value - you'll use it in the next step.
  </Step>

  <Step title="Create file metadata">
    Use the wrapped DEK to create a metadata record for your file.

    ```bash theme={null}
    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`:

    ```json theme={null}
    {
      "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"
    }
    ```
  </Step>

  <Step title="Retrieve the metadata">
    Fetch the metadata back using the file ID from the previous response.

    ```bash theme={null}
    curl http://meta.internal:8080/api/v1/meta/file_abc123
    ```

    ```json theme={null}
    {
      "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"
    }
    ```
  </Step>

  <Step title="Check platform stats">
    Verify that your file was counted in the aggregate statistics.

    ```bash theme={null}
    curl http://meta.internal:8080/api/v1/stats
    ```

    ```json theme={null}
    {
      "totalFiles": 1,
      "totalSizeBytes": 204800
    }
    ```
  </Step>
</Steps>

## Next steps

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

<CardGroup cols={2}>
  <Card title="File metadata" icon="file" href="/api/metadata/meta">
    Full CRUD operations for metadata records.
  </Card>

  <Card title="DEK management" icon="key" href="/api/metadata/dek">
    Wrap and unwrap encryption keys.
  </Card>

  <Card title="Statistics" icon="chart-bar" href="/api/metadata/stats">
    Aggregate file and storage metrics.
  </Card>

  <Card title="Experimental" icon="flask" href="/api/metadata/experimental">
    Cache sync, prefetch, and invalidation.
  </Card>
</CardGroup>

<Tip>
  Need help? Reach out at [support@fluxorg.pl](mailto:support@fluxorg.pl).
</Tip>