Read File Metadata

  • Retrieves metadata of files stored in one or different File or FileList properties.

  • Required security permission - READ.

  • HTTP methods supported: GET, POST.

Description

Some properties of an object can be used to store files. The files themselves are stored in a MongoDB GridFS bucket. The metadata of existing files can be retrieved using this endpoint.

This endpoint is used to read metadata of files which are stored in one or different File or FileList properties of a single or different objects.

HTTP GET

Parameters

Name Type Optional Description

identifier

string

no

The path or ID of the file property to be queried for file metadata.

filter

string

yes

A filter specification to lookup a file which is stored in a File or FileList property. Must be a string containing the name or a Base64 encoded JSON dictionary. See the getfilemetadata Lua function for details.

prev

number or string

yes

A filter can have an optional start value 'prev' which is typically the metatable obtained from a previous call to continue iterating over all matching entries. It may also be an integral row index (negative values are relative to the last row, i.e. specifying -2 returns the last table row if it matches). Must be a number or a Base64 encoded JSON dictionary.

insights

boolean

yes

Indicates application insights should be included in the response, by default false.

Examples

The example below use a HTTP GET call to read the metadata of one or more files in the system.

  1. Read file metadata by FileName

    This example shows a readfilemetadata request for a single file. The filter parameter is used to specify which file to return data for.

    Request URL: /api/v2/readfilemetadata?identifier=/System/Core/GenericItem.Attachments&filter=example1.png

    Response Body:

    {
    "data": {
        "items": [
            {
                "i": 281474986082351,
                "metadata": {
                    "_dbref": "cfd3dfbc1c3c186a94f3a2d8ef8c3f2efbdc38e00bd2349dcac1af6c4f56e760",
                    "custom": {
                        "lorem": "ipsum"
                    },
                    "dateuploaded": 1754485770303,
                    "extension": "png",
                    "name": "example1.png",
                    "size": 894
                },
                "p": "/System/Core/GenericItem.Attachments"
            }
        ]
    }
}

HTTP POST

Parameters

Name Type Optional Description

body

body

no

Read File Metadata RPC data

Name Description

items

An array of objects which contain the path or id of file property to be queried for file metadata.

filter

Defines the filter condition used when looking up metadata for the provided items.

insights

boolean

yes

Indicates application insights should be included in the response, by default false.

Examples

In the examples below, a HTTP POST call is used to read the metadata of one or more files in the system.

  1. Read file metadata

    In this example, the readfilemetadata endpoint is used to retrieve file metadata from the FileList property of two objects in the system.

    Request URL: /api/v2/readfilemetadata

    Request Body:

    {
    "items": [
        {
            "p": "/System/Core/GenItem.Attachments"
        },
        {
            "p": "/System/Core/GenItem2.Attachments"
        }
    ]
}

    Response Body:

    {
    "data": {
        "items": [
            {
                "i": 281475020423215,
                "metadata": {
                    "_dbref": "cbb2d50bd9c870e0f098b9230d66d2f74d55544f2e57f1aabe3830443a040eb6",
                    "custom": {
                        "path": "C:\\Users\\Admin\\Documents\\test-file-2.txt"
                    },
                    "dateuploaded": 1760007340759,
                    "extension": "txt",
                    "name": "test-file-2.txt",
                    "size": 17
                },
                "p": "/System/Core/GenItem.Attachments"
            },
            {
                "i": 281475020619823,
                "metadata": {
                    "_dbref": "76fc1c80b77fc11d54abb5b973ceb4ca4c945ca591fe8199309bc5bd1e797c41",
                    "custom": {
                        "path": "C:\\Users\\Admin\\Downloads\\test-image.png"
                    },
                    "dateuploaded": 1760010593551,
                    "extension": "png",
                    "name": "test-image.png",
                    "size": 444
                },
                "p": "/System/Core/GenItem2.Attachments"
            }
        ]
    }
}

  2. Read file metadata with filter parameter

    This example shows a readfilemetadata request using the filter parameter to return the metadata for files with the '.txt' file extension. The second item in the response contains a error message as the object specified does not contain any files matching the filter condition.

    Request URL: /api/v2/readfilemetadata

    Request Body:

    {
    "items": [
        {
            "p": "/System/Core/GenItem.Attachments"
        },
        {
            "p": "/System/Core/GenItem2.Attachments"
        }
    ],
    "filter": {
        "extension": "txt"
    }
}

    Response Body:

    {
    "data": {
        "items": [
            {
                "i": 281475020423215,
                "metadata": {
                    "_dbref": "cbb2d50bd9c870e0f098b9230d66d2f74d55544f2e57f1aabe3830443a040eb6",
                    "custom": {
                        "path": "C:\\Users\\Admin\\Documents\\test-file-2.txt"
                    },
                    "dateuploaded": 1760007340759,
                    "extension": "txt",
                    "name": "test-file-2.txt",
                    "size": 17
                },
                "p": "/System/Core/GenItem.Attachments"
            },
            {
                "error": {
                    "msg": "The filter didn't match any entry."
                },
                "p": "/System/Core/GenItem2.Attachments"
            }
        ]
    }
}

Filtering

In the body of a POST request, the filter and prev parameters can be defined on root level to specify a global filter for the provided items. For each item, the global filter and or prev parameter can be overruled.

Global filter applied to every item

{
    "filter": {
        "extension" : "pdf"
    },
    "items": [
        {
            "p": "/Enterprise.Attachments"
        },
        {
            "p": "/Enterprise/Site01.Attachments"
        }
    ]
}

Global filter applied to the first to items and overruled by the third item

{
    "filter": {
        "extension" : "pdf"
    },
    "items": [
        {
            "p": "/Enterprise.Attachments"
        },
        {
            "p": "/Enterprise/SiteNL.Attachments"
        },
        {
            "p": "/Enterprise/SiteNL/Area01.Attachments",
            "filter": {
                "extension" : "svg"
            },
        }
    ]
}