Metadata

The Metadata API allows you to define custom metadata fields and apply them to files, file versions, and folders in your Egnyte domain. Metadata fields (keys) are organized into namespaces, which control visibility and modification permissions.

Namespaces and Scope

Namespaces can have one of three scope levels:

• Private: Only visible to the application that created it (same OAuth client ID). Other applications and the Web UI cannot see or modify private namespaces.
• Protected: Visible to all applications and the Web UI, but only the creating application can modify or delete it.
• Public: Visible to all applications and the Web UI. Any application or user can modify or delete public namespaces.

Metadata Scope Types

Namespaces can be scoped in three ways:

• GLOBAL: Applies to all files and folders in the domain.
• FOLDER_SCOPE: Applies only to files and folders within specified folders.
• DOCUMENT_TYPE: Applies only to files matching specified document type categories (e.g., PDF, DOCUMENT, SPREADSHEET).

Base URL

https://{domain}.egnyte.com/pubapi/v1/properties

Authentication

All requests require an OAuth 2.0 Bearer token in the Authorization header:

Authorization: Bearer {access_token}

See Authentication for details on obtaining a token.

Supported Data Types

Metadata keys support the following data types:

Timezone-Independent Date Fields

DATE fields support an optional timezoneIndependent flag that controls how date values are stored and displayed:

• timezoneIndependent: true — The value is treated as a plain calendar date with no timezone context. Values must be milliseconds at exactly UTC midnight (divisible by 86400000), for example 1725753600000 for 2024-09-08. The value is displayed as-is without any timezone adjustment.
• timezoneIndependent: false — The value is timezone-dependent and may be adjusted based on the viewer's timezone settings (legacy behavior).

Get All Namespaces

Retrieves all custom metadata namespaces in the domain.

Request

GET /pubapi/v1/properties/namespace

Query Parameters

Example Request

curl -i -X GET "https://{domain}.egnyte.com/pubapi/v1/properties/namespace?includeFolderAssociations=true" \
     -H "Authorization: Bearer YOUR_ACCESS_TOKEN"

Response

200 OK

For each key object within keys, the following fields may be present:

Example Response

[
  {
    "name": "public-global-all-data-types",
    "displayName": "public-global-all-data-types",
    "priority": 0,
    "keys": {
      "date-key": {
        "displayName": "date-key",
        "helpText": "Enter a date value for this field",
        "priority": 6,
        "type": "date",
        "timezoneIndependent": true
      },
      "string-key": {
        "displayName": "string-key",
        "helpText": "Enter a text value for this field",
        "priority": 5,
        "type": "string"
      },
      "decimal-key": {
        "displayName": "decimal-key",
        "helpText": "Enter a decimal number for this field",
        "priority": 4,
        "type": "decimal"
      },
      "int-key": {
        "displayName": "int-key",
        "helpText": "Enter a whole number for this field",
        "priority": 3,
        "type": "integer"
      },
      "enum-key": {
        "data": ["male", "female"],
        "displayName": "enum-key",
        "helpText": "Select a gender value",
        "priority": 2,
        "type": "enum"
      },
      "labels-key": {
        "data": ["green", "red"],
        "displayName": "labels-key",
        "helpText": "Select one or more color labels",
        "priority": 1,
        "type": "labels"
      },
      "multi-value-enum-key": {
        "data": ["clinical", "healthcare", "shipping"],
        "displayName": "multi-value-enum-key",
        "helpText": "Select one or more industry categories",
        "priority": 0,
        "type": "multi_value_enum"
      }
    },
    "scope": "public",
    "schemaSystemGenerated": false,
    "inheritable": false,
    "metadataScopeType": "GLOBAL"
  }
]

Create Namespace

Creates a new namespace with custom metadata fields.

Request

POST /pubapi/v1/properties/namespace

Request Body

Available Document Types

• PDF
• DOCUMENT
• SPREADSHEET
• PRESENTATION
• IMAGE
• AUDIO_VIDEO
• TEXT_SOURCE_CODE
• GOOGLE_FILE
• EMAIL
• CAD
• ARCHIVE

Example Request

curl -i -X POST "https://{domain}.egnyte.com/pubapi/v1/properties/namespace" \
     -H "Content-Type: application/json" \
     -H "Authorization: Bearer YOUR_ACCESS_TOKEN" \
     -d '{
  "name": "public-global-all-data-types",
  "displayName": "all-data-types-example",
  "scope": "public",
  "inheritable": false,
  "metadataScopeType": "GLOBAL",
  "keys": {
    "labels-key": {
      "type": "labels",
      "data": [
        "red",
        "green"
      ],
      "helpText": "Select one or more color labels"
    },
    "multi-value-enum-key": {
      "type": "multi_value_enum",
      "data": [
        "shipping",
        "healthcare",
        "clinical"
      ],
      "helpText": "Select one or more industry categories"
    },
    "enum-key": {
      "type": "enum",
      "data": [
        "male",
        "female"
      ],
      "helpText": "Select a gender value"
    },
    "int-key": {
      "type": "integer",
      "priority": 1,
      "helpText": "Enter a whole number for this field"
    },
    "decimal-key": {
      "type": "decimal",
      "priority": 2,
      "displayName": "decimal-key",
      "helpText": "Enter a decimal number for this field"
    },
    "string-key": {
      "type": "string",
      "priority": 3,
      "displayName": "string-key",
      "helpText": "Enter a text value for this field"
    },
    "date-key": {
      "type": "date",
      "priority": 4,
      "displayName": "date-key",
      "helpText": "Enter a date value for this field",
      "timezoneIndependent": true
    }
  }
}'

Response

204 No Content

The namespace was created successfully.

Get Namespace

Retrieves all custom metadata keys within a specific namespace.

Request

GET /pubapi/v1/properties/namespace/{namespace_name}

Path Parameters

Example Request

curl -i -X GET "https://{domain}.egnyte.com/pubapi/v1/properties/namespace/public-global-all-data-types" \
     -H "Authorization: Bearer YOUR_ACCESS_TOKEN"

Response

200 OK

Example Response

{
  "name": "public-global-all-data-types",
  "scope": "public",
  "keys": {
    "date-key": {
      "type": "date",
      "displayName": "date-key",
      "priority": 4,
      "timezoneIndependent": true
    },
    "string-key": {
      "type": "string",
      "displayName": "string-key",
      "priority": 3
    },
    "decimal-key": {
      "type": "decimal",
      "displayName": "decimal-key",
      "priority": 2
    },
    "int-key": {
      "type": "integer",
      "priority": 1
    },
    "enum-key": {
      "type": "enum",
      "data": ["male", "female"],
      "priority": 0
    },
    "labels-key": {
      "type": "labels",
      "data": ["green", "red"],
      "priority": 0
    },
    "multi-value-enum-key": {
      "type": "multi_value_enum",
      "data": ["clinical", "healthcare", "shipping"],
      "priority": 0
    }
  },
  "displayName": "all-data-types-example",
  "priority": 0,
  "inheritable": false,
  "schemaSystemGenerated": false,
  "metadataScopeType": "GLOBAL"
}

Update Namespace Attributes

Updates the display name, key priorities, folder associations, or document type associations of a namespace.

Request

PATCH /pubapi/v1/properties/namespace/{namespace_name}

Path Parameters

Request Body

Example Request

curl -i -X PATCH "https://{domain}.egnyte.com/pubapi/v1/properties/namespace/metadata" \
     -H "Content-Type: application/json" \
     -H "Authorization: Bearer YOUR_ACCESS_TOKEN" \
     -d '{
  "displayName": "scope-metadata",
  "priorities": {
    "first_name": 5,
    "last_name": 3,
    "role": 0
  },
  "folderAssociation": {
    "associateFolderIds": [
      "{folderId}"
    ],
    "dissociateFolderIds": [
      "{folderId}"
    ]
  }
}'

Response

200 OK

Example Response

{
  "name": "metadata",
  "displayName": "scope-metadata",
  "priority": 0,
  "keys": {
    "first_name": {
      "displayName": "first_name",
      "helpText": "Enter the person's first name",
      "priority": 5,
      "type": "string"
    },
    "role": {
      "displayName": "role",
      "helpText": "Enter the numeric role identifier",
      "priority": 0,
      "type": "integer"
    },
    "last_name": {
      "displayName": "last_name",
      "helpText": "Enter the person's last name",
      "priority": 3,
      "type": "string"
    }
  },
  "scope": "public",
  "schemaSystemGenerated": false,
  "metadataScopeType": "FOLDER_SCOPE",
  "folderAssociations": [
    {
      "folderId": "d21a238a-b72e-46b2-9998-8571bdca3085",
      "path": "/Shared/video"
    }
  ],
  "hasAccessToAllAssociations": true
}

Example Response with documentTypes and documentExtensions

{
  "name": "metadata",
  "displayName": "scope-metadata",
  "priority": 0,
  "keys": {
    "first_name": {
      "displayName": "first_name",
      "helpText": "Enter the person's first name",
      "priority": 5,
      "type": "string"
    },
    "role": {
      "displayName": "role",
      "helpText": "Enter the numeric role identifier",
      "priority": 0,
      "type": "integer"
    },
    "last_name": {
      "displayName": "last_name",
      "helpText": "Enter the person's last name",
      "priority": 3,
      "type": "string"
    }
  },
  "scope": "public",
  "schemaSystemGenerated": false,
  "metadataScopeType": "GLOBAL/FOLDER_SCOPE/DOCUMENT_TYPE",
  "folderAssociations": [
    {
      "folderId": "d21a238a-b72e-46b2-9998-8571bdca3085",
      "path": "/Shared/video"
    }
  ],
  "hasAccessToAllAssociations": true,
  "documentTypes": [
    "PDF"
  ],
  "documentExtensions": [
    "pdf"
  ]
}

Update Namespace Keys

Updates the definition of a specific metadata key within a namespace.

Request

PATCH /pubapi/v1/properties/namespace/{namespace_name}/keys/{key_name}

Path Parameters

Request Body

Allowed Type Changes

You can only change a key's type to a broader type:

• date → string, decimal, integer
• integer → string, decimal
• decimal → string
• enum → string (the data field will be automatically set to null)

Data Field Behavior

• enum: New values replace existing values. Existing values on files/folders will be deleted.
• multi_value_enum: New values are appended to existing values.
• labels: New values are appended to existing values.

Example Request

curl -i -X PATCH "https://{domain}.egnyte.com/pubapi/v1/properties/namespace/my-namespace/keys/color-key" \
     -H "Content-Type: application/json" \
     -H "Authorization: Bearer YOUR_ACCESS_TOKEN" \
     -d '{
  "displayName": "My new display name",
  "helpText": "Use this key to describe the field",
  "data": [
    "red",
    "green",
    "blue",
    "new color"
  ],
  "priority": 21,
  "type": "enum"
}'

Response

204 No Content

The key was updated successfully.

Delete Namespace

Deletes a namespace and all its metadata keys.

Request

DELETE /pubapi/v1/properties/namespace/{namespace_name}

Path Parameters

Headers

Example Request

curl -i -X DELETE "https://{domain}.egnyte.com/pubapi/v1/properties/namespace/my-namespace" \
     -H "X-Egnyte-Force-Delete: Yes" \
     -H "Authorization: Bearer YOUR_ACCESS_TOKEN"

Response

204 No Content

The namespace was deleted successfully.

Create Metadata Key

Adds a new metadata key to an existing namespace.

Request

POST /pubapi/v1/properties/namespace/{namespace_name}/keys

Path Parameters

Request Body

Example Request

curl -i -X POST "https://{domain}.egnyte.com/pubapi/v1/properties/namespace/my-namespace/keys" \
     -H "Content-Type: application/json" \
     -H "Authorization: Bearer YOUR_ACCESS_TOKEN" \
     -d '{
  "key": "new-enum-key",
  "type": "enum",
  "data": [
    "active",
    "completed",
    "archived"
  ],
  "displayName": "Project Status",
  "priority": 5,
  "helpText": "Select the current status of the project"
}'

Response

204 No Content

The key was created successfully.

Delete Metadata Key

Deletes a metadata key from a namespace.

Request

DELETE /pubapi/v1/properties/namespace/{namespace_name}/keys/{key_name}

Path Parameters

Headers

Example Request

curl -i -X DELETE "https://{domain}.egnyte.com/pubapi/v1/properties/namespace/my-namespace/keys/old-key" \
     -H "X-Egnyte-Force-Delete: Yes" \
     -H "Authorization: Bearer YOUR_ACCESS_TOKEN"

Response

204 No Content

The key was deleted successfully.

Set Values for a Namespace

Sets metadata values for a file, file version, or folder. Multiple key/value pairs can be set at once. Existing values are overwritten. Setting a value to null removes the existing value.

Request

For Files:

PUT /pubapi/v1/fs/ids/file/{group_id_or_entry_id}/properties/{namespace_name}

For Folders:

PUT /pubapi/v1/fs/ids/folder/{folder_id}/properties/{namespace_name}

Path Parameters

Request Body

Provide a JSON object with key/value pairs matching the keys defined in the namespace.

Value Behavior by Type:

• enum: Overwrites the existing value
• labels: Appends to existing values
• multi_value_enum: Appends to existing values

Example Request (File)

curl -i -X PUT "https://{domain}.egnyte.com/pubapi/v1/fs/ids/file/a1b2c3d4-e5f6-7890-abcd-ef{id}90/properties/my-namespace" \
     -H "Content-Type: application/json" \
     -H "Authorization: Bearer YOUR_ACCESS_TOKEN" \
     -d '{
  "enum-key": "abc",
  "multi-value-enum-key": [
    "value-1"
  ],
  "labels-key": [
    "egnyte"
  ],
  "int-key": 1,
  "decimal-key": 2.2,
  "date-key": "1465413843995",
  "string-key": "egnyte"
}'

Example Request (Folder)

curl -i -X PUT "https://{domain}.egnyte.com/pubapi/v1/fs/ids/folder/f1g2h3i4-j5k6-7890-lmno-pq{id}90/properties/my-namespace" \
     -H "Content-Type: application/json" \
     -H "Authorization: Bearer YOUR_ACCESS_TOKEN" \
     -d '{
  "string-key": "Marketing Campaign",
  "int-key": 42
}'

Response

204 No Content

The metadata values were set successfully.

Get Values for a Namespace

Retrieves metadata values for a file, file version, or folder within a specific namespace.

Request

For Files:

GET /pubapi/v1/fs/ids/file/{group_id_or_entry_id}/properties/{namespace_name}

For Folders:

GET /pubapi/v1/fs/ids/folder/{folder_id}/properties/{namespace_name}

Path Parameters

Example Request (File)

curl -i -X GET "https://{domain}.egnyte.com/pubapi/v1/fs/ids/file/a1b2c3d4-e5f6-7890-abcd-ef{id}90/properties/my-namespace" \
     -H "Authorization: Bearer YOUR_ACCESS_TOKEN"

Example Request (Folder)

curl -i -X GET "https://{domain}.egnyte.com/pubapi/v1/fs/ids/folder/f1g2h3i4-j5k6-7890-lmno-pq{id}90/properties/my-namespace" \
     -H "Authorization: Bearer YOUR_ACCESS_TOKEN"

Response

200 OK

Example Response

{
  "results": [
    {
      "workspace": {
        "string-key": "abc",
        "int-key": 10
      }
    }
  ]
}

Search Metadata

Searches for files and folders that have specific metadata fields or field values.

Request

POST /pubapi/v1/search

Request Body

Example Request

curl -i -X POST "https://{domain}.egnyte.com/pubapi/v1/search" \
     -H "Content-Type: application/json" \
     -H "Authorization: Bearer YOUR_ACCESS_TOKEN" \
     -d '{
  "type": "ALL",
  "key_with_value": [
    {
      "namespace": "namespace1",
      "key": "string-key",
      "value": "abc"
    }
  ]
}'

Response

200 OK

Returns search results matching the metadata criteria. See the Search API for response format details.

Delete Data for a Single Key

Deletes specific enumerated values from a single metadata key.

Request

PATCH /pubapi/v1/properties/namespace/{namespace_name}/keys/{key_name}/data

Path Parameters

Headers

Request Body

Provide an array of enumerated values to delete.

Example Request

curl -i -X PATCH "https://{domain}.egnyte.com/pubapi/v1/properties/namespace/my-namespace/keys/status-key/data" \
     -H "Content-Type: application/json" \
     -H "X-Egnyte-Force-Delete: Yes" \
     -H "Authorization: Bearer YOUR_ACCESS_TOKEN" \
     -d '[
  "urgent",
  "review",
  "archived"
]'

Response

204 No Content

The key data was deleted successfully.

Delete Data for Multiple Keys

Deletes specific enumerated values from multiple metadata keys in a single request.

Request

PATCH /pubapi/v1/properties/namespace/{namespace_name}/keys/data

Path Parameters

Headers

Request Body

Example Request

curl -i -X PATCH "https://{domain}.egnyte.com/pubapi/v1/properties/namespace/my-namespace/keys/data" \
     -H "Content-Type: application/json" \
     -H "X-Egnyte-Force-Delete: Yes" \
     -H "Authorization: Bearer YOUR_ACCESS_TOKEN" \
     -d '{
  "keyDataDeletions": [
    {
      "key": "status",
      "data": [
        "completed",
        "cancelled"
      ]
    },
    {
      "key": "priority",
      "data": [
        "low"
      ]
    },
    {
      "key": "tags",
      "data": [
        "archived",
        "obsolete"
      ]
    }
  ]
}'

Response

204 No Content

The key data was deleted successfully.

Error Codes

Code Examples

POST /pubapi/v1/fs/ids/file/{entryId}/properties/project-metadata

curl -i -X POST "https://{domain}.egnyte.com/pubapi/v1/fs/ids/file/{entryId}/properties/project-metadata" \
     -H "Content-Type: application/json" \
     -H "Authorization: Bearer YOUR_ACCESS_TOKEN" \
     -d '{
  "project-name": "Website Redesign",
  "project-status": "active"
}'

PUT /pubapi/v1/fs/ids/file/{entryId}/properties/project-metadata

curl -i -X PUT "https://{domain}.egnyte.com/pubapi/v1/fs/ids/file/{entryId}/properties/project-metadata" \
     -H "Content-Type: application/json" \
     -H "Authorization: Bearer YOUR_ACCESS_TOKEN" \
     -d '{
  "project-name": "Website Redesign",
  "project-status": "active"
}'

GET /pubapi/v1/fs/ids/file/{entryId}/properties/project-metadata

curl -i -X GET "https://{domain}.egnyte.com/pubapi/v1/fs/ids/file/{entryId}/properties/project-metadata" \
     -H "Content-Type: application/json" \
     -H "Authorization: Bearer YOUR_ACCESS_TOKEN"

Related Resources

• File System API — Obtain file and folder IDs for metadata operations
• Search API — Advanced search capabilities including metadata filtering
• Authentication — How to obtain and refresh OAuth tokens
• Best Practices — Rate limiting, error handling, and optimization strategies