Help Center

Menu

Using the File Store API

The API reference documentation describes the available operations that are possible with the File Store API.

This section describes some common operations you would perform with the API to manage the lifecycle of a digital asset.

Before you start

  • The source property requires a trailing slash (/) when querying with the GET /api/v2/file and GET `/api/v2/directory endpoint methods.

  • A trailing slash is not required for POST /api/v2/directory and PATCH /api/v2/directory/{directoryId} because these endpoint methods infer a directory based on context.

  • All other endpoints use the directoryId to infer the directory location.

  • The API does not offer a caching layer so do not use it to allow direct file download access. Read Download a file hosted in File Store for best practice recommendations.

How to get a list of files uploaded to the service

cUrl

Replace the values enclosed in [] with their required values. 
curl -X GET 'https://[SERVER_URL]/__dxp/service/file-storage/api/v2/file?source=/' -H "x-api-key: [API_KEY]" -H "x-dxp-tenant: [TENANT_ID]"
Requesting too many files at once can cause the request to timeout. Use the limit and cursor parameters detailed in the API Reference to paginate the results.

Javascript

async function getFiles(serverHost, apiKey, tenantId) {
    const files = [];
    let cursor;

    do {
        const url = new URL(`https://${serverHost}/__dxp/service/file-storage/api/v2/file`);
        url.searchParams.set("source", "/");
        // Add in a limit to the request to avoid requesting too many files at once
        url.searchParams.set("limit", "1000");

        // If we have a cursor, add it to the request to get the next section of paginated results
        if (cursor) {
            url.searchParams.set("cursor", cursor);
        }

        const response = await fetch(url, {
            method: "GET",
            headers: {
                "x-api-key": apiKey,
                "x-dxp-tenant": tenantId,
            }
        });
        const body = await response.json();

        if (!response.ok) {
            throw new Error(`GET file failed: ${body.message}`);
        }

        // Add the results to the files array
        files.push(...body.data);

        // Get the cursor from the response headers to continue pagination
        cursor = response.headers.get("x-filestore-cursor");
    } while (cursor);

    return files;
}

How to create a directory and add a file to the service

cUrl

Replace the values enclosed in [] with their required values. 
curl -X POST https://[SERVER_URL]/__dxp/service/file-storage/api/v2/directory -H "x-api-key: [API_KEY]" -H "x-dxp-tenant: [TENANT_ID]" -d '{"source":"test-directory","access":"public"}'
curl -X POST https://[SERVER_URL]/__dxp/service/file-storage/api/v2/file -H "x-api-key: [API_KEY]" -H "x-dxp-tenant: [TENANT_ID]" -d '{"source":"test-directory/test.json","access":"public","data":"{\"test\":\"test\"}"}'

Javascript

async function createDirectoryAndFile(serverHost, apiKey, tenantId) {
    const directoryResponse = await fetch(`https://${serverHost}/__dxp/service/file-storage/api/v2/directory`, {
        method: "POST",
        headers: {
            "x-api-key": apiKey,
            "x-dxp-tenant": tenantId,
        },
        body: JSON.stringify({
            "source": "test-directory",
            "access": "public",
        }),
    });
    const directoryBody = await directoryResponse.json();

    if (!directoryResponse.ok) {
        throw new Error(`POST directory failed: ${directoryBody.message}`);
    }

    console.log(directoryBody);

    const fileResponse = await fetch(`https://${serverUrl}/__dxp/service/file-storage/api/v2/file`, {
        method: "POST",
        headers: {
            "x-api-key": apiKey,
            "x-dxp-tenant": tenantId,
        },
        body: JSON.stringify({
            "source": "test-directory/test.json",
            "access": "public",
            "data": JSON.stringify({test:"test"})
        }),
    });
    const fileBody = await fileResponse.json();

    if (!fileResponse.ok) {
        throw new Error(`POST file failed: ${fileBody.message}`);
    }

    console.log(fileBody);
}

How to update the version of a file stored in the service

Replace the values enclosed in [] with their required values.

cUrl

curl -X POST https://[SERVER_URL]/__dxp/service/file-storage/api/v2/file/pass:[{{file-id}}] -H "x-api-key: [API_KEY]" -H "x-dxp-tenant: [TENANT_ID]" -d '{"access":"private"}'

Javascript

async function updateFileAccess(serverHost, apiKey, tenantId, fileId) {
    const response = await fetch(`https://${serverHost}/__dxp/service/file-storage/api/v2/file/${fileId}`, {
        method: "PATCH",
        headers: {
            "x-api-key": apiKey,
            "x-dxp-tenant": tenantId,
        },
        body: JSON.stringify({
            "access": "private",
        }),
    });
    const body = await response.json();

    if (!response.ok) {
        throw new Error(`PATCH file failed: ${body.message}`);
    }

    console.log(body);
}

How to delete a file stored in the service

Before deleting any folder, manually check in the File Store interface what static mappings are associated with the folder using the Information option inside the more_horiz menu for the folder.

cUrl

Replace the values enclosed in [] with their required values. 
curl -X DELETE https://[SERVER_URL]/__dxp/service/file-storage/api/v2/file/pass:[{{file-id}}] -H "x-api-key: [API_KEY]" -H "x-dxp-tenant: [TENANT_ID]"
curl -X GET https://[SERVER_URL]/__dxp/service/file-storage/{{polling-url-from-delete-response}} -H "x-api-key: [API_KEY]" -H "x-dxp-tenant: [TENANT_ID]"

Javascript

async function deleteFile(serverHost, apiKey, tenantId, fileId) {
    const deleteResponse = await fetch(`https://${serverHost}/__dxp/service/file-storage/api/v2/file/${fileId}`, {
        method: "DELETE",
        headers: {
            "x-api-key": apiKey,
            "x-dxp-tenant": tenantId,
        }
    });
    const deleteBody = await deleteResponse.json();

    if (!deleteResponse.ok) {
        throw new Error(`DELETE file failed: ${deleteBody.message}`);
    }

    console.log(deleteBody);

    let deleteComplete = false;
    do{
        const statusResponse = await fetch(`https://${serverHost}/__dxp/service/file-storage/${body.pollingUrl}`, {
            method: "GET",
            headers: {
                "x-api-key": apiKey,
                "x-dxp-tenant": tenantId,
            }
        });

        const statusBody = await statusResponse.json();

        if (!statusResponse.ok) {
            throw new Error(`GET status failed: ${statusBody.message}`);
        }

        console.log(statusBody)

        if(statusBody.status === 'SUCCEED'){
            deleteComplete = true;
        }

    }while(!deleteComplete)
}

How to rename (patch) a file or directory stored in the service

There is no way to rename a file or directory using the File Store UI.

There is no dedicated rename endpoint, but the PATCH facility is available to rename a file or directory in File Store.

You patch the full path in the source attribute to rename the file or directory.

The name of a file or directory is not stored as a separate attribute but as one full path and must be updated as such in the API call.

cUrl

Replace the values enclosed in [] with their required values.
Rename a file
curl -X PATCH https://[SERVER_URL]/__dxp/service/file-storage/api/v2/file/pass:[{{file-id}}] -H "x-api-key: [API_KEY]" -H "x-dxp-tenant: [TENANT_ID]" -d '{"source":"path-to-file/new-file-name"}'


curl -X GET https://[SERVER_URL]/__dxp/service/file-storage/{{polling-url-from-patch-response}} -H "x-api-key: [API_KEY]" -H "x-dxp-tenant: [TENANT_ID]"
Rename a directory
curl -X PATCH https://[SERVER_URL]/__dxp/service/file-storage/api/v2/directory/pass:[{{directory-id}}] -H "x-api-key: [API_KEY]" -H "x-dxp-tenant: [TENANT_ID]" -d '{"source":"path-to-directory/new-directory-name"}'

curl -X GET https://[SERVER_URL]/__dxp/service/file-storage/{{polling-url-from-patch-response}} -H "x-api-key: [API_KEY]" -H "x-dxp-tenant: [TENANT_ID]"

Javascript

Rename a file
async function renameFile(serverHost, apiKey, tenantId, fileId, newName) {
  const headers = {
    "x-api-key": apiKey,
    "x-dxp-tenant": tenantId,
  };

  // Get the file details to get the file location
  const getFileResponse = await fetch(`https://${serverHost}/__dxp/service/file-storage/api/v2/file/${fileId}`, {
    method: "GET",
    headers: headers
  });

  if (!getFileResponse.ok) {
    throw new Error(`GET file failed: ${getFileResponse.status} ${getFileResponse.statusText}`);
  }

  const getFileBody = await getFileResponse.json();
  console.log(getFileBody);
  // Get the file location portion of the source path
  const fileLocation = getFileBody.source.split('/').slice(0, -1).join('/');
  console.log(fileLocation);

  const fileResponse = await fetch(`https://${serverHost}/__dxp/service/file-storage/api/v2/file/${fileId}`, {
      method: "PATCH",
      headers: headers,
      body: JSON.stringify({
          "source": `${fileLocation}/${newName}`
      }),
  });
  const fileBody = await fileResponse.json();

  if (!fileResponse.ok) {
      throw new Error(`POST file failed: ${fileBody.message}`);
  }

  console.log(fileBody);
}