Get metadata

File Metadata contains, all information related to files or folders state on Filecoin and retrievability.

Requirement #

To access file or folder metadata, you need the fileId. The fileId is a unique identifier provided by Nextcloud when interacting with its WebDAV server. There are 3 ways to fetch the metadata:

Option 1: Nextcloud WebApp #

When browsing your Files, you can extract the fileId from the URL

Option 2: Fetching File Metadata Using HTTP Headers #

When you copy, create, or move a file in Nextcloud, the OC-FileId is sent in the response headers.

Example: #

curl -siu ‘<YOUR_NEXTCLOUD_USERNAME>:<YOUR_NEXTCLOUD_PASSWORD>’ \
-T <PATH_OF_LOCAL_FILE_TO_UPLOAD> \
"https://nextcloud.twinquasar.io/remote.php/dav/files/<YOUR_NEXTCLOUD_USERNAME>/Public%20Filecoin/"

The headers returned will include something like:

OC-FileId: 1234567890

Option 3: Fetching File Metadata Using a WebDAV PROPFIND Query #

You can make a WebDAV query with a curl request to fetch the fileId.

Example Curl Command: #

curl -su '<YOUR_NEXTCLOUD_USERNAME>:<YOUR_NEXTCLOUD_PASSWORD>’ \
-X PROPFIND \
-H "Depth: 0" \
-d '<?xml version="1.0"?><d:propfind xmlns:d="DAV:" xmlns:oc="http://owncloud.org/ns"><d:prop><oc:fileid/></d:prop></d:propfind>' \
"https://nextcloud.twinquasar.io/remote.php/dav/files/<YOUR_NEXTCLOUD_USERNAME>/Public%20Filecoin/<FILE_PATH>“

The response contains the fileId “oc:fileid”

Hint : you can use the command xmllint to extract that value

xmllint --xpath "//*[local-name()='fileid']/text()" -

get-file-metadata API call #

The main information are :

• file.cid
• file.details.state
• file.details.retrievableCopies

When pulling metadata from a folder, the returned information aggregates all subfolders and files within that folder. This means that querying the top-level folder provides a comprehensive view of the entire dataset, including all contained subfolders and their respective files.

Deals provide resilience by distributing file storage across multiple providers, with redundancy ensuring data availability.

Request Format #

You can track the status of a file or folder tree in real-time using the following request:

curl -u '<YOUR_NEXTCLOUD_USERNAME>:<YOUR_NEXTCLOUD_PASSWORD>' \
-X GET "https://nextcloud.twinquasar.io/ocs/v2.php/apps/cidgravity_gateway/get-file-metadata?fileId=<FILE_ID>"

Response Format #

Top-level Fields #

Metadata - (Inside metadata) #

File Details - (Inside metadata.file.details) #

Deal Details (Inside metadata.file.details.groups[].deals) #

File states Overview #

Response Example #

The API returns a detailed response containing file metadata.

{
  "success": true,
  "metadata": {
    "file": {
      "cid": "QmYLX2WS5Yb2SsUe8iL53osM9Wgx5xFpTrtr4QiN5nouxH",
      "details": {
        "groups": [
          {
            "pieceCid": "baga6ea4seaqlne54hvmeopx2yh335nay2oyae4crwpqqyosscwdz5tw7lix32pa",
            "deals": [
              {
                "provider": "f010479",
                "endEpoch": 5968776,
                "dealId": 97326078,
                "isRetrievable": true,
                "state": "active"
              },
              {
                "provider": "f0717969",
                "endEpoch": 5968776,
                "dealId": 97529013,
                "isRetrievable": true,
                "state": "active"
              }
            ],
            "state": "offloaded",
            "retrievableCopies": 8
          }
        ],
        "state": "offloaded",
        "retrievableCopies": 8,
        "expirationEpoch": 5971777,
        "expirationTimestamp": 1777459710
      }
    }
  }
}