Metadata API

The Metadata API allows you to define custom metadata fields and then use those fields to set values on files, file versions, and folders. Metadata fields (keys) are grouped together in namespaces.

Namespaces can be either private or public. Private namespaces are only visible to the application that created them (i.e. only when accessing with the same Public API key). Public namespaces are visible to any application and are also visible within the Web UI.

Note: This API is in beta and is subject to change.

Common HTTP Headers

Header Description Value
Content-Type Specifies the format of the request body application/json
Authorization Requires the OAuth token you obtained through the OAuth flow Bearer {OAuth token}
Error Description
200 Successful operation
403 User is not authorized
404 Item not found

Get All Namespaces

This endpoint is used to list all custom metadata namespaces in the domain.

GET/pubapi/v1/properties/namespace

Create Namespace

This endpoint is used to create a namespace of custom metadata fields for a domain.

POST/pubapi/v1/properties/namespace

Request Parameters

Parameter Description Required Possible Values
name What you call the namespace Yes string
displayName The name to identify the namespace in the UI No string
scope Who can see and modify the namespace Yes public, private
keys The custom metadata key(s) you are creating Yes JSON object (see create metadata key endpoint for fields)
type Specifies the data type for a key. Yes integer, string, decimal, date, enum
data For a key of enum type, specifies the enumerated values. Only required for enum E.g. ["red", "green", "blue"]
helpText Instructional text that is displayed when a user is adding/editing a property to give context as to the property's purpose No string

Sample Request Body

{
  "name": "namespace1",
  "scope": "public",
  "displayName": "my first namespace",
  "keys": {
    "int-key": {
      "type": "integer",
      "displayName": "my key"
    },
    "decimal-key": {
      "type": "decimal"
    },
    "string-key": {
      "type": "string"
    },
    "enum-key": {
      "type": "enum",
      "data": ["val1", "val2"]
    },
    "date-key": {
      "type": "string"
    }    
  }
}

Update Namespace Values

This endpoint is used to update the namespace scope or name of a custom metadata for a domain.

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

Request Parameters

Parameter Description Required Possible Values
displayName The name to identify the namespace in the UI No string
scope Who can see and modify the namespace No public, private

Sample Request Body

{
  "scope": "public",
  "displayName": "a namespace with a new name"
}

Update Namespace Keys

This endpoint is used to update the key definitions of a namespace of custom metadata fields for a domain.

PATCH/pubapi/v1/properties/namespace/{namespace name}/keys/{key name}

Request Parameters

Parameter Description Required Possible Values
displayName Specifies the name displayed for the key No string
type Specifies the data type for a key. Can only allow a change to a broader type:
  • decimal -> string
  • integer -> string, decimal
  • date -> string, decimal, integer
  • enum -> string (in this case the 'data' parameter will be automatically set to null)
No integer, string, decimal, date, enum
data For a key of enum type, specifies the enumerated values. Only new values are allowed Only required for enum E.g. ["red", "green", "blue"]
helpText Instructional text that is displayed when a user is adding/editing a property to give context as to the property's purpose No string

Sample Request Body

{
  "displayName": "My new display name",
  "helpText": "Use this key",
  "data": ["red", "green", "blue", "new color"],
  "type": "enum"
}

Get Namespace

This endpoint is used to list all custom metadata keys that have been created in a given namespace.

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

Delete Namespace

This endpoint is used to delete a specified namespace. This is only possible if the namespace is not in use.

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

Create Metadata Key

This endpoint is used to add a metadata key to an existing namespace.

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

Request Parameters

Parameter Description Required Possible Values
key The name of the key you are creating Yes string
type Specifies the data type for a key. Yes integer, string, decimal, date, enum
displayName The name to identify the field in the UI. No string
helpText A tooltip description for the metadata field. No string
data For a key of enum type, specifies the enumerated values. Only required for enum E.g. ["red", "green", "blue"]

Sample Request Body

{
  "key": "new-enum-key",
  "type": "enum",
  "data": ["red", "green", "blue"],
  "displayName": "My new key for values",
  "helpText": "Use this key to tag files with these values"
}

Delete Metadata Key

This endpoint is used to delete a metadata key from an existing namespace. This is only possible if the namespace is not in use.

DELETE/pubapi/v1/properties/namespace/{namespace name}/keys/{key name}

Set Values for a Namespace

This endpoint is used to set a metadata values for a given namespace for a file, file version, or folder. This endpoint allows multiple key/value pairs to be set at once. If the key already has a value, the old value will be overriden by the new value. If the value for a key is set to null, the existing value will be removed. For more information on interacting with files, specific file versions, or folders, please refer to the File System API documentation.

To set a metadata value for a file, use the group ID of the file. To set a metadata value for a specific file version, use the entry ID of the file version. To set a metadata value for a folder, use the folder ID.

PUT/pubapi/v1/fs/ids/file/{group_id or entry_id}/properties/{namespace name}
PUT/pubapi/v1/fs/ids/folder/{folder_id}/properties/{namespace name}

Sample Request Body

{
  "string-key": "abc",
  "int-key": "10",
  "date-key": "1465413843995"
}

Get Values for a Namespace

This endpoint is used to get the metadata values for a given namespace for a file, file version, or folder. For more information on interacting with files, specific file versions, or folders, please refer to the File System API documentation.

GET/pubapi/v1/fs/ids/file/{group_id or entry_id}/properties/{namespace name}
GET/pubapi/v1/fs/ids/folder/{folder_id}/properties/{namespace name}

Sample Respose Body

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

Search Metadata

This endpoint is used to find items that have a specific metadata field or to find items that have a field that contains a specific value.

POST /pubapi/v1/search

Request Parameters

Parameter Description Required Possible Values
type Which item types should be searched No ALL, FOLDER, FILE
has_key Allows for finding items that have a specific key. If multiple objects are included in the array, any item matching one or more of the conditions will be returned. No An array of objects with keys "namespace" and "key", e.g. [{"namespace": "namespace1", key: "string-key"}]
key_with_value Allows for finding items that contain a specific string within a metadata value for a specified field. Note that this is not an exact match, but rather looks for any string that contains the search term. If multiple objects are included in the array, any item matching one or more of the conditions will be returned. No An array of objects with keys "namespace", "key", and "value", e.g. [{"namespace": "namespace1", key: "string-key", "value": "abc"}]

Sample Request Body

{
  "type": "ALL",
  "key_with_value": [
    {
      "namespace": "namespace1",
      "key": "string-key",
      "value": "abc"
    }
  ]
}