Upload File

  • Is able to store the (binary) content of a file in a File or FileList property.

  • Required security permission - MODIFY.

  • HTTP methods supported: POST

Description

Some properties of an object may be allowed to store files. The files themselves are stored in a MongoDB GridFS bucket. The files can be stored or updated using this endpoint with name as the key plus additional metadata. The metadata specification (a table schema) is documented together with the property in question.

If a file already exists in the property with the given file name, it is replaced with the new one and the metadata is replaced or merged depending on mode.

If a file with the given name does not already exist, it is added as a new file if the property can hold multiple files (i.e., the property is of type FileList) or completely replaced otherwise (independent of the mode parameter).

Depending on the actual property the file is attached to, some meta-data is added automatically.

On success, this endpoint returns the metadata of the stored file.

Parameters

Name Type Optional Description

pathspec

string

yes

Path or id specification of the property where the file is to be stored. Required when the request body contains binary file data.

name

string

Maybe

The name of the file. This name has to be used for retrieval. Required when the request body contains binary data. the name can be omitted for properties of type File.

custom

string

yes

Additional metadata for the file. Has to be a Base64 encoded JSON (dictionary).

mode

string

yes

Indicates whether the existing metadata needs to be completely replaced (mode = 'replace') or merged with the provided metadata (mode = 'merge'). By default 'replace'.

base64

string

yes

Can be used to provide the file content as a Base64 encoded string.

scope_comment

string

yes

Audit trail comment.

insights

boolean

yes

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

Examples

Storing a file by providing binary file data

HTTP POST

Request URL

  • /api/v2/uploadfile?pathspec=/Enterprise.Attachments&name=example.svg

Request Body

  • Must contains the binary file data.

Storing a file by providing file data as a base64 encoded string.

HTTP POST

Request URL

  • /api/v2/uploadfile

Request Body
{
  "pathspec": "/Enterprise.Attachments",
  "name": "example.svg",
  "base64": "PD94bWwgdmVyc2lvbj0iMS4wIiBlbmNvZGluZz0iVVRGLTgiIHN0YW5kYWxvbmU9Im5vIj8+CjwhLS0gQ3JlYXRlZCB3aXRoIElua3NjYXBlIChodHRwOi8vd3d3Lmlua3NjYXBlLm9yZy8pIC0tPgoKPHN2ZwogICB4bWxuczpkYz0iaHR0cDovL3B1cmwub3JnL2RjL2VsZW1lbnRzLzEuMS8iCiAgIHhtbG5zOmNjPSJodHRwOi8vY3JlYXRpdmVjb21tb25zLm9yZy9ucyMiCiAgIHhtbG5zOnJkZj0iaHR0cDovL3d3dy53My5vcmcvMTk5OS8wMi8yMi1yZGYtc3ludGF4LW5zIyIKICAgeG1sbnM6c3ZnPSJodHRwOi8vd3d3LnczLm9yZy8yMDAwL3N2ZyIKICAgeG1sbnM9Imh0dHA6Ly93d3cudzMub3JnLzIwMDAvc3ZnIgogICB2ZXJzaW9uPSIxLjEiCiAgIHdpZHRoPSI2MDAiCiAgIGhlaWdodD0iNjAwIgogICB2aWV3Qm94PSIwIDAgNjAwIDYwMCIKICAgaWQ9IkxheWVyXzEiCiAgIHhtbDpzcGFjZT0icHJlc2VydmUiCiAgIHN0eWxlPSJvdmVyZmxvdzp2aXNpYmxlIj48bWV0YWRhdGEKICAgICBpZD0ibWV0YWRhdGEyMCI+PHJkZjpSREY+PGNjOldvcmsKICAgICAgICAgcmRmOmFib3V0PSIiPjxkYzpmb3JtYXQ+aW1hZ2Uvc3ZnK3htbDwvZGM6Zm9ybWF0PjxkYzp0eXBlCiAgICAgICAgICAgcmRmOnJlc291cmNlPSJodHRwOi8vcHVybC5vcmcvZGMvZGNtaXR5cGUvU3RpbGxJbWFnZSIgLz48ZGM6dGl0bGU+PC9kYzp0aXRsZT48L2NjOldvcms+PC9yZGY6UkRGPjwvbWV0YWRhdGE+PGRlZnMKICAgICBpZD0iZGVmczE4IiAvPjxwYXRoCiAgICAgZD0iTSAzMDAsMzAwIgogICAgIGlkPSJwYXRoNyIgLz48cGF0aAogICAgIGQ9Im0gMzAwLDEwLjAwMjkzIGMgMjMuNTY0NDUsMjAuMDc1MTk1IDU0LjExNzE5LDMyLjE5MTQwNiA4Ny41LDMyLjE5MTQwNiAzMy4zODI4MSwwIDYzLjkzNTU1LC0xMi4xMTkxNDEgODcuNSwtMzIuMTk0MzM2IGwgMTE1LDExNSBjIC0yMS4xNjIxMSwzMC4wODEwNSAtMzMuNTg3ODksNjYuNzUzOTEgLTMzLjU4Nzg5LDEwNi4zMjYxNyAwLDI4LjQ2Mzg3IDYuNDI2NzYsNTUuNDI0ODEgMTcuOTEwMTYsNzkuNTEyNyBDIDU4NC4yNDQxNCwzMzEuNjY0MDYgNTkwLDM1NS4zOTQ1MyA1OTAsMzgwIDU5MCw0NjguMzY3MTkgNTE4LjM2NzE5LDU0MCA0MzAsNTQwIEggNDA0Ljg4NjcyIEMgMzYyLjU0MTk5LDU0MCAzMjQuNzUwOTgsNTU5LjQ5NTEyIDMwMCw1OTAgMjc1LjI0ODU0LDU1OS40OTUxMiAyMzcuNDU4MDEsNTQwIDE5NS4xMTMyOCw1NDAgSCAxNjkuOTk5NTEgQyA4MS42MzI4MTMsNTQwIDkuOTk5NTExNyw0NjguMzY3MTkgOS45OTk1MTE3LDM4MCBjIDAsLTI0LjYwNTQ3IDUuNzU2MzQ3MywtNDguMzM1OTQgMTUuNjc4NzExMywtNjkuMTYxMTMgMTEuNDgyNDIyLC0yNC4wODc4OSAxNy45MTAxNTYsLTUxLjA0ODgzIDE3LjkxMDE1NiwtNzkuNTEyNyBDIDQzLjU4ODM3OSwxOTEuNzUzOTEgMzEuMTYxNjIxLDE1NS4wODEwNSAxMCwxMjUgTCAxMjUsMTAgYyAyMy41NjQ0NSwyMC4wNzUxOTUgNTQuMTE2NywzMi4xOTQzMzYgODcuNSwzMi4xOTQzMzYgMzMuMzgyODEsMCA2My45MzU1NSwtMTIuMTE2MjExIDg3LjUsLTMyLjE5MTQwNiB6IgogICAgIGlkPSJwYXRoMTEiCiAgICAgc3R5bGU9ImZpbGw6I2ZmZmZmZjtmaWxsLW9wYWNpdHk6MTtmaWxsLXJ1bGU6ZXZlbm9kZCIgLz48ZwogICAgIGlkPSJnMzg4NiI+PHBhdGgKICAgICAgIGQ9Ik0gMCw1MCBDIDAsMjIuMzg1NzQyIDIyLjM4NTI1NCwwIDUwLDAgaCA1MDAgYyAyNy42MTQyNiwwIDUwLDIyLjM4NTc0MiA1MCw1MCB2IDUwMCBjIDAsMjcuNjE1MjMgLTIyLjM4NTc0LDUwIC01MCw1MCBIIDUwIEMgMjIuMzg1MjU0LDYwMCAwLDU3Ny42MTUyMyAwLDU1MCBWIDUwIGwgMCwwIHoiCiAgICAgICBpZD0icGF0aDUiIC8+PHBhdGgKICAgICAgIGQ9Im0gMzAwLDEwLjAwMjkzIGMgMjMuNTY0NDUsMjAuMDc1MTk1IDU0LjExNzE5LDMyLjE5MTQwNiA4Ny41LDMyLjE5MTQwNiAzMy4zODI4MSwwIDYzLjkzNTU1LC0xMi4xMTkxNDEgODcuNSwtMzIuMTk0MzM2IGwgMTE1LDExNSBjIC0yMS4xNjIxMSwzMC4wODEwNSAtMzMuNTg3ODksNjYuNzUzOTEgLTMzLjU4Nzg5LDEwNi4zMjYxNyAwLDI4LjQ2Mzg3IDYuNDI2NzYsNTUuNDI0ODEgMTcuOTEwMTYsNzkuNTEyNyBDIDU4NC4yNDQxNCwzMzEuNjY0MDYgNTkwLDM1NS4zOTQ1MyA1OTAsMzgwIDU5MCw0NjguMzY3MTkgNTE4LjM2NzE5LDU0MCA0MzAsNTQwIEggNDA0Ljg4NjcyIEMgMzYyLjU0MTk5LDU0MCAzMjQuNzUwOTgsNTU5LjQ5NTEyIDMwMCw1OTAgMjc1LjI0ODU0LDU1OS40OTUxMiAyMzcuNDU4MDEsNTQwIDE5NS4xMTMyOCw1NDAgSCAxNjkuOTk5NTEgQyA4MS42MzI4MTMsNTQwIDkuOTk5NTExNyw0NjguMzY3MTkgOS45OTk1MTE3LDM4MCBjIDAsLTI0LjYwNTQ3IDUuNzU2MzQ3MywtNDguMzM1OTQgMTUuNjc4NzExMywtNjkuMTYxMTMgMTEuNDgyNDIyLC0yNC4wODc4OSAxNy45MTAxNTYsLTUxLjA0ODgzIDE3LjkxMDE1NiwtNzkuNTEyNyBDIDQzLjU4ODM3OSwxOTEuNzUzOTEgMzEuMTYxNjIxLDE1NS4wODEwNSAxMCwxMjUgTCAxMjUsMTAgYyAyMy41NjQ0NSwyMC4wNzUxOTUgNTQuMTE2NywzMi4xOTQzMzYgODcuNSwzMi4xOTQzMzYgMzMuMzgyODEsMCA2My45MzU1NSwtMTIuMTE2MjExIDg3LjUsLTMyLjE5MTQwNiB6IgogICAgICAgaWQ9InBhdGgxMyIKICAgICAgIHN0eWxlPSJmaWxsOiNmZmZmZmY7ZmlsbC1vcGFjaXR5OjE7ZmlsbC1ydWxlOmV2ZW5vZGQ7c3Ryb2tlOiMwMDAwMDA7c3Ryb2tlLWxpbmVjYXA6cm91bmQ7c3Ryb2tlLWxpbmVqb2luOnJvdW5kO3N0cm9rZS1taXRlcmxpbWl0OjMuODYzNjkzIiAvPjwvZz48ZwogICAgIGlkPSJ0ZXh0MTM0MyIKICAgICBzdHlsZT0iZm9udC1zaXplOjQ0Ny43NjExOTk5NXB4O2ZvbnQtc3R5bGU6bm9ybWFsO2ZvbnQtdmFyaWFudDpub3JtYWw7Zm9udC13ZWlnaHQ6bm9ybWFsO2ZvbnQtc3RyZXRjaDpub3JtYWw7dGV4dC1hbGlnbjpjZW50ZXI7bGluZS1oZWlnaHQ6MTI1JTt3cml0aW5nLW1vZGU6bHItdGI7dGV4dC1hbmNob3I6bWlkZGxlO2ZvbnQtZmFtaWx5OlJvYWRnZWVrIDIwMDUgU2VyaWVzIEQiPjxwYXRoCiAgICAgICBkPSJtIDI2OC42MzIyMiwzNTEuMDgyMDkgYyAtMi4zZS00LDEyLjgzNTg5IC0yLjY4NjgsMjQuOTI1NDMgLTguMDU5NywzNi4yNjg2NiAtNS4wNzQ4NSwxMS4wNDQ4MSAtMTIuMjM5MDIsMjAuNzQ2MjkgLTIxLjQ5MjU0LDI5LjEwNDQ3IC04Ljk1NTQyLDguMDU5NzIgLTE5LjcwMTY4LDE0LjQ3NzYyIC0zMi4yMzg4MSwxOS4yNTM3NCAtMTIuNTM3NDcsNC43NzYxMSAtMjUuOTcwMjksNy4xNjQxNyAtNDAuMjk4NSw3LjE2NDE3IC0xNC4zMjg0OCwwIC0yNy43NjEzLC0yLjM4ODA2IC00MC4yOTg1MSwtNy4xNjQxNyAtMTIuNTM3MzksLTUuMDc0NjIgLTIzLjQzMjkxLC0xMS45NDAyOSAtMzIuNjg2NTcsLTIwLjU5NzAyIC04Ljk1NTI3MywtOC42NTY2OSAtMTYuMTE5NDQ1LC0xOC44MDU5MyAtMjEuNDkyNTM3LC0zMC40NDc3NiAtNS4wNzQ2NTksLTExLjY0MTczIC03LjYxMTk3LC0yNC4xNzkwMyAtNy42MTE5NDEsLTM3LjYxMTk0IC0yLjllLTUsLTIwLjg5NTQxIDIuNjg2NTM1LC00MS42NDE2NiA4LjA1OTcwMiwtNjIuMjM4ODEgNS42NzE1OTksLTIwLjU5Njg0IDEzLjU4MjAzOCwtNDAuMjk4MzEgMjMuNzMxMzQ0LC01OS4xMDQ0OCAxMC4xNDkxODIsLTE4LjgwNTc0IDIyLjIzODcyMiwtMzYuMTE5MTUgMzYuMjY4NjUyLC01MS45NDAzIDE0LjMyODI1LC0xNi4xMTkxMiAzMC4xNDkxMywtMjkuOTk5NyA0Ny40NjI2OSwtNDEuNjQxNzkgbCAyNC4xNzkxMSw0MC4yOTg1MSBjIC05LjI1Mzg5LDcuMTY0NDQgLTE3LjQ2Mjg0LDE0LjE3OTM2IC0yNC42MjY4NywyMS4wNDQ3OCAtNi44NjU4MSw2LjU2NzQgLTEzLjI4MzcxLDEzLjQzMzA2IC0xOS4yNTM3MywyMC41OTcwMSAtNS42NzE3Niw3LjE2NDQgLTEwLjg5NTY0LDE0Ljc3NjMzIC0xNS42NzE2NCwyMi44MzU4MiAtNC43NzYyMyw3Ljc2MTM5IC05LjQwMzA5LDE2LjQxODEgLTEzLjg4MDYsMjUuOTcwMTUgOC42NTY2MSwtMS40OTIzNiAxNS4yMjM3NywtMi4zODc4OCAxOS43MDE0OSwtMi42ODY1NyA0Ljc3NiwtMC4yOTgzMyAxMC4xNDkxMywtMC40NDc1OCAxNi4xMTk0MSwtMC40NDc3NiAxMy43MzExOSwxLjhlLTQgMjYuNzE2MjYsMi4zODgyNCAzOC45NTUyMiw3LjE2NDE4IDEyLjUzNzEzLDQuNzc2MjkgMjMuNDMyNjQsMTEuMzQzNDUgMzIuNjg2NTcsMTkuNzAxNSA5LjU1MjAyLDguMDU5ODQgMTcuMDE0NywxNy43NjEzMiAyMi4zODgwNiwyOS4xMDQ0NyA1LjM3MjksMTEuMDQ0ODkgOC4wNTk0NywyMi44MzU5MiA4LjA1OTcsMzUuMzczMTQgbSAtNDcuNDYyNjksLTAuODk1NTIgYyAtMS44ZS00LC01LjY3MTU1IC0xLjQ5MjcyLC0xMS4xOTM5NCAtNC40Nzc2MSwtMTYuNTY3MTcgLTIuNjg2NzUsLTUuMzczMDIgLTYuNTY3MzQsLTkuOTk5ODggLTExLjY0MTc5LC0xMy44ODA2IC00Ljc3NjI5LC0zLjg4MDQ3IC0xMC41OTcxOCwtNy4wMTQ4IC0xNy40NjI2OSwtOS40MDI5OCAtNi41NjczMSwtMi4zODc5MyAtMTMuNTgyMjMsLTMuNTgxOTYgLTIxLjA0NDc3LC0zLjU4MjA5IC03LjQ2MjgxLDEuM2UtNCAtMTQuNDc3NzMsMS4xOTQxNiAtMjEuMDQ0NzgsMy41ODIwOSAtNi4yNjg3NiwyLjM4ODE4IC0xMS45NDA0LDUuNTIyNTEgLTE3LjAxNDkzLDkuNDAyOTggLTQuNzc2MiwzLjg4MDcyIC04LjY1NjgsOC41MDc1OCAtMTEuNjQxNzksMTMuODgwNiAtMi42ODY2NCw1LjM3MzIzIC00LjAyOTkzLDEwLjg5NTYyIC00LjAyOTg1LDE2LjU2NzE3IC04ZS01LDUuOTcwMjMgMS4zNDMyMSwxMS42NDE4NiA0LjAyOTg1LDE3LjAxNDkyIDIuOTg0OTksNS4zNzMyIDYuODY1NTksMTAuMTQ5MzIgMTEuNjQxNzksMTQuMzI4MzYgNS4wNzQ1MywzLjg4MDY1IDEwLjc0NjE3LDcuMDE0OTcgMTcuMDE0OTMsOS40MDI5OSA2LjU2NzA1LDIuMzg4MSAxMy41ODE5NywzLjU4MjEzIDIxLjA0NDc4LDMuNTgyMDggNy40NjI1NCw1ZS01IDE0LjQ3NzQ2LC0xLjE5Mzk4IDIxLjA0NDc3LC0zLjU4MjA4IDYuNTY3MDEsLTIuMzg4MDIgMTIuMjM4NjQsLTUuNTIyMzQgMTcuMDE0OTMsLTkuNDAyOTkgNS4wNzQ0NSwtNC4xNzkwNCA5LjEwNDMsLTguOTU1MTYgMTIuMDg5NTUsLTE0LjMyODM2IDIuOTg0ODksLTUuMzczMDYgNC40Nzc0MywtMTEuMDQ0NjkgNC40Nzc2MSwtMTcuMDE0OTIiCiAgICAgICBpZD0icGF0aDQ1NjQiIC8+PHBhdGgKICAgICAgIGQ9Im0gNTAwLjA3NTc5LDM2Mi43MjM4OCAwLDc0Ljc3NjEyIC00Ny4wMTQ5MiwwIDAsLTc0Ljc3NjEyIC0xNDguNjU2NzIsMCAwLC0yOC4yMDg5NiBMIDQ1My4wNjA4NywxMzcuNSBsIDQ3LjAxNDkyLDAgMCwxODIuMjM4OCAyOC42NTY3MiwwIDAsNDIuOTg1MDggLTI4LjY1NjcyLDAgbSAtNDcuMDE0OTIsLTE1NS44MjA5IC04NS41MjIzOSwxMTIuODM1ODIgODUuNTIyMzksMCAwLC0xMTIuODM1ODIiCiAgICAgICBpZD0icGF0aDQ1NjYiIC8+PC9nPjwvc3ZnPg==",
  "custom": {
    "lorum": "ipsum"
  },
  "mode": "replace"
}
Response body
{
    "data": {
        "metadata": {
            "_dbref": "8b18c8da9355e38daf6c935b4921d2ad8b2ef1cac4c2fbeebfd8af9946a91574",
            "custom": {
                "lorum": "ipsum"
            },
            "dateuploaded": 1622758226545,
            "extension": "svg",
            "name": "example.svg",
            "size": 2149
        }
    }
}