Support: Knowledge Base

Articles in this section

See more

Follow DF Studio Enterprise Asset API

The DF Studio Enterprise Asset API provides programmatic access to Assets (images) in the system. With this API an Enterprise customer can query Assets, read information regarding Edits and Approvals, download Files, and update Custom Metadata. This API follows the standard REST API conventions used in DF Studio’s Upload API, and can be inspected by visiting example_company.dfstudio.com/api/v1/session.html.

Documentation Conventions

Throughout this document, observe the following placeholder values:

  • [BASE]: example_company.dfstudio.com
  • [SID]: replace with the session ID
  • [AID]: replace with an asset’s ID
  • [DFSID]: replace with an asset’s globally unique ID (DFS ID)
  • [FIELD]: dfstudio.keywords or custom.myCustomField
  • [SHARELINK]: the DF Studio Share Link of a Project, asset, or folder

All URLs will end in js, however xml is supported along with easy to explore html

Authentication

Use of this API is restricted to Enterprise and Unlimited accounts. The API requires authentication and uses session URLs. Once authenticated, the client must use the URL returned for all future requests.

Configure API Credentials for each application that requires access to the API.

To authenticate, POST the following HTTP parameters to the session URL:

  • account (the DF Studio account shortname)
  • username (from API Credentials)
  • password (from API Credentials)
POST [BASE]/api/v1/session.js
//POST BODY:

{
  "account": "ACCOUNT_SHORT_NAME",
  "username": "USERNAME",
  "password": "PASSWORD"
}

//RESPONSE:

[BASE]/api/v1/session/[SID].js

Users with the “Asset API Access” privilege can also be used for authentication, substituting the user’s username and password for the API Credentials referenced above.

Review important guidelines for maximizing the security of DF Studio accounts with API-enabled users: Secure an API User.

Assets

Assets within the DF Studio Library can be listed based on their location in Projects, or searched by name. New assets can be created by specifying a valid Project location.

List Assets

GET [BASE]/api/v1/session/[SID]/assets.js
//RESPONSE:

{
  "info": {
    "count": 1999,
    "limit": 100,
    "offset": 0,
    "order": "id"
  },

  "returned": [
    {
      "id": "[AID]",
      "dfsid": "[DFSID]",
      "isStoredActive": true,
      "isStoredCold": false,
      "location": "/Folder/Series/Season1/Ep1",
      "name": "img0001",
      "rest.resourceName": "asset",
      "rest.resources": {
        "asset": "[BASE]/api/v1/session/[SID]/asset/[DFSID].js",
        "file": "[BASE]/api/v1/session/[SID]/asset/[DFSID]/file.js",
        "metadata": "[BASE]/api/v1/session/[SID]/asset/[DFSID]/metadata.js",
        "rest.self": "[BASE]/api/v1/session/[SID]/asset/[DFSID].js"
      },
      "setup": "No Setup",
      "shareLink": "[SHARELINK]"
    },

    …

   ]
}

Assets can be filtered by appending parameters to the GET request, these parameters can be combined:

  • "path=/Folder/Series/Season1/Ep1": in the Project “Ep1”
  • "folder=/Folder/Series/Season1": located within the Library folder “/Folder/Series/Season1”
  • "projectDfsid=[DFS_PROJECTID]": by globally unique Project identifier (see Projects, below)
  • "name=ExampleAsset": with the name “ExampleAsset”
  • "custom.myField=1": custom metadata field myField having the value of 1
  • "file.fileType=iiq": with associated files of type iiq
  • "file.isStoredActive=true": with files stored in Active Storage
  • "file.isStoredCold=true": with files stored in Cold Storage
  • "limit=100": sets the maximum number of assets to return
  • "offset=100": skips ahead 100 assets
  • "order=id": options [ id, displayName, createdDate, addedDate ]

Special Characters in Parameters

Within folder names, the slash character (/) is replaced with ~~. If the path or folder parameter references a folder name containing a slash, use ~~ instead. (See Folders, below.)

Any ampersand characters (&) in the location path must be URL encoded in order to return a valid match. For example, a Project named “This & That” would be specified as path=/This %26 That

Create an Asset

Create a new asset in the system by specifying its name and the Project in which it should be stored (see Projects, below). Optionally, specify the name of a Setup for the asset. (Default is “No Setup”.)

PUT [BASE]/api/v1/session/[SID]/asset.js
//PUT BODY:

{
  "projectDfsid":"[DFS_PROJECTID]",
  "name":"New Asset_001",
  "setup":"Setup 101"
}

//RESPONSE:

{
  "dfsid": "[DFSID]",
  "id": "[AID]",
  "name": "New Asset_001",
  "projectDfsid": "[DFS_PROJECTID]",

  …

}

Asset Resource

A variety of information is available regarding each asset in the system.

In the following example request, [DFSID] and [AID] may be used interchangeably.

GET [BASE]/api/v1/session/[SID]/asset/[DFSID].js

It is also possible to retrieve an asset based on its DF Studio Share Link. In this example, the Share Link URL may be used interchangeably with the asset's [DFSID].

GET [BASE]/api/v1/session/[SID]/asset.js?rest.id=[DFSID]

Either of the example requests above will yield the same response:

//RESPONSE:

{
  "addedToStudio": "2015-10-21 16:29"
  "approvalState": "Approved",
  "folder": "/",
  "id": "[AID]",
  "dfsid": "[DFSID]", 
  "isStoredActive": true,
  "isStoredCold": false,
  "location": "/Folder/Series/Season1/Ep1",
  "name": "img0001",
  "project": "Ep1",
  "rest.resourceName": "asset",
  "rest.resources": {
    "asset": "[BASE]/api/v1/session/[SID]/asset/[DFSID].js",
    "edits": "[BASE]/api/v1/session/[SID]/asset/[DFSID]/edits.js",
    "file": "[BASE]/api/v1/session/[SID]/asset/[DFSID]/file.js",
    "metadata": "[BASE]/api/v1/session/[SID]/asset/[DFSID]/metadata.js",
    "rest.self": "[BASE]/api/v1/session/[SID]/asset/[DFSID].js"
  },
  "setup": "No Setup",
  "shareLink": "[SHARELINK]"
 }

Edits Property

The edits property lists Edits that users have made on the asset in a Project, Collection, or Messenger. These Edits come in three types:

  1. USER edits are created by a user in DF Studio.
  2. MESSENGER edits are created by the recipient of a Messenger in that Messenger.
  3. MESSENGER_AS_SENT edits are snapshots of the Edit information from the sender of a Messenger at the point in time at which the Messenger was sent. 

The submitDate field records the time that the select level was set, and will only appear when the selectLevel value is not UNSELECTED, even if the select level has been changed from UNSELECTED to another value and subsequently changed back.

Key/value pairs will be omitted from the response whenever the value is null.

Also note that an Edit on an asset will only exist if a user has interacted with the select level of the asset.

GET [BASE]/api/v1/session/[SID]/asset/[DFSID]/edits.js
//RESPONSE:

[
  {
    "container": "/Folder/Series/Season1/Ep1",
    "editorEmail": "alice@example.com",
    "editorName": "Alice Example",
    "messenger": {
      "messengerId": "100",
      "name": "Example Messenger",
      "sendDate": "2015-10-21T16:29:01-800"
    },
    "name": "As Sent",
    "selectLevel": "UNSELECTED",
    "type": "MESSENGER_AS_SENT"
  },
  {
    "container": "/Folder/Series/Season1/Ep1",
    "editorEmail": "bob@example.com",
    "editorName": "Bob Example",
    "messenger": {
      "messengerId": "100",
      "name": "Example Messenger",
      "sendDate": "2015-10-21T16:29:01-800"
    },
    "name": "bob@example.com",
    "selectLevel": "SECOND_SELECT”,
    "submitDate": "2015-10-21T16:29:01-800",
    "type": "MESSENGER"
  },
  {
    "container": "/Folder/Series/Season1/Ep1",
    "editorEmail": "alice@example.com",
    "editorName": "Alice Example",
    "name": "Main Edit",
    "selectLevel": "FIRST_SELECT",
    "submitDate": "2015-10-21T16:29:01-800", 
    "type": "USER"
  }
]

Approvals Property

The approvals property lists the approval state of an asset, as set by the recipient of an Approvals Messenger. It also includes information about the Messenger in which the approvals were set, and the time at which the approval was last updated (unless the approval state is Pending).

approvalState can have a value of Approved, Killed, or Pending.

GET [BASE]/api/v1/session/[SID]/asset/[DFSID]/approvals.js
//RESPONSE:

[
  {
    "approvalState": "Approved",
    "messengerId": "100",
    "messengerName": "Example Messenger",
    "messengerSentDate": "2015-10-21T16:29:01-800",
    "recipientEmail": "frank@example.com”,
    "recipientName": "Frank Example", 
    "senderEmail": "alice@example.com", 
    "senderName": "Alice Example", 
    "submitDate": "2015-10-21T16:29:01-800"
  },
  {
    "approvalState": "Killed",
    "messengerId": "200",
    "messengerName": "Example Approval Messenger",
    "messengerSentDate": "2015-10-21T16:29:01-800",
    "recipientEmail": "bob@example.com”,
    "recipientName": "Bob Example", 
    "senderEmail": "alice@example.com", 
    "senderName": "Alice Example", 
    "submitDate": "2015-10-21T16:29:01-800"
  },
  {
    "approvalState": "Pending",
    "messengerId": "200",
    "messengerName": "Example Approval Messenger",
    "messengerSentDate": "2015-10-21T16:29:01-800",
    "recipientEmail": "carol@example.com”,
    "recipientName": "Carol Example", 
    "senderEmail": "alice@example.com", 
    "senderName": "Alice Example" 
  }
]

Asset Metadata

An asset’s metadata can be fetched by submitting a GET request for the metadata property of the asset.

GET [BASE]/api/v1/session/[SID]/asset/[DFSID]/metadata.js
//RESPONSE:

{
  "composite:ImageSize": "1400x1800",
  "custom.myField": "1",
  "dfstudio.caption": "Example Photo",
  "dfstudio.captionWriter": "Bob Example",
  "dfstudio.captureDate": "2015-10-21",
  "dfstudio.copyright": "2015, Example Company",
  "dfstudio.credit": "Bob Example",
  "dfstudio.headline": "Sample Headline",
  "dfstudio.instructions": "Not to be copied",
  "dfstudio.keywords": "example, keywords",
  "dfstudio.location": "A Place, City, State ZIP",
  "dfstudio.photographer": "Photographers, LLC",
  "dfstudio.specialInstructions": "",
  "dfstudio.writer": "",
  "exif:Copyright": "2015, Example Company",
  "iptc:By-line": "",
  "iptc:Caption-Abstract": "",
  "iptc:CopyrightNotice": "2015, Example Company"
  "xmp:Location": "A Place, City, State ZIP"
}

An asset’s metadata can be updated by POSTing the subset of values to change to the same metadata property.

POST [BASE]/api/v1/session/[SID]/asset/[DFSID]/metadata.js
//POST BODY:

{
  "custom.myField":"2"
}

//RESPONSE:

{
  "composite:ImageSize": "1400x1800",
  "custom.myField": "2",
  "dfstudio.caption": "Example Photo",
  "dfstudio.captionWriter": "Bob Example",
  "dfstudio.captureDate": "2015-10-21",
  "dfstudio.copyright": "2015, Example Company",
  "dfstudio.credit": "Bob Example",
  "dfstudio.headline": "Sample Headline",
  "dfstudio.instructions": "Not to be copied",
  "dfstudio.keywords": "example, keywords",
  "dfstudio.location": "A Place, City, State ZIP",
  "dfstudio.photographer": "Photographers, LLC",
  "dfstudio.specialInstructions": "",
  "dfstudio.writer": "",
  "exif:Copyright": "2015, Example Company",
  "iptc:By-line": "",
  "iptc:Caption-Abstract": "",
  "iptc:CopyrightNotice": "2015, Example Company"
  "xmp:Location": "A Place, City, State ZIP"
}

Metadata updates that fail metadata validation rules configured for the account will receive a MetadataValidationException response.

To exempt a specific metadata update from metadata validation, append the rest.metadataValidation=false parameter to the POST.

POST [BASE]/api/v1/session/[SID]/asset/[DFSID]/metadata.js?rest.metadataValidation=false

Asset Files

In order to download a file in the asset’s stack a client must first GET the file property for the type of file, then fetch the generated fileUrl. The fileUrl is a temporary URL and will expire 1 hour after it has been generated.

Files can be moved to active or cold storage by POSTing to the rest.self URL with the parameter isStoredActive=true or isStoredCold=true.

Fetch a List of Files

GET [BASE]/api/v1/session/[SID]/asset/[DFSID]/files.js
//RESPONSE:

[
  {
    "id": "jpg",
    "fileType": "jpg",
    "size": "42118 bytes",
    "stored": "active"
    "isStoredActive": true,
    "isStoredCold": false,
    "rest.resourceName": "file",
    "fileName": "example_001.jpg",
    "fileUrl": "[BASE]/api/v1/session/[SID]/asset/[DFSID]/fileDownload/[FILE].js",
    "rest.resources": {
      "file": "[BASE]/api/v1/session/[SID]/asset/[DFSID]/file/jpg.js",
      "rest.self": "[BASE]/api/v1/session/[SID]/asset/[DFSID]/file/jpg.js",
  
      …

    }
  }
]

Get the fileURL of a File

GET [BASE]/api/v1/session/[SID]/asset/[DFSID]/file/jpg.js
//RESPONSE:

{
  "id": "jpg",
  "fileUrl": "[BASE]/api/v1/session/[SID]/asset/[DFSID]/fileDownload/[FILE].js",
  
  …

}

This fileUrl resource will remain accessible as long as the session is active. It will redirect to a signed URL which will last for 1 hour. 

curl -i "[BASE]/api/v1/session/[SID]/asset/[DFSID]/fileDownload/[FILE].js"

//RESPONSE:

  HTTP/2 302 
  content-length: 0
  location: location: [BASE]/views/…
  …

Most HTTP clients provide an option to follow redirects automatically. For example, cURL provides this function through the --location option.

Upload Files Directly to S3

Uploading directly to S3 storage is supported. This is the preferred upload method because it reduces load on DF Studio servers and is likely to provide better direct throughput to the upload client. The steps to upload a file and submit it for ingestion are detailed below.

Request an upload URL for an existing asset (see Create an Asset, above):

GET [BASE]/api/v1/session/[SID]/asset/[DFSID]/file/[FILE_EXT]?action=uploadUrl&contentType=[MIME_TYPE]

Example file extension and MIME type:

GET [BASE]/api/v1/session/[SID]/asset/[DFSID]/file/jpg?action=uploadUrl&contentType=image/jpeg
//RESPONSE:

{
  "uploadUrl": "[SIGNED_UPLOAD_URL]",
  "uploadUrlExpires": "2015-10-21T14:00:00+0000",
  "uploadOnCompleteUrl": [ON_COMPLETE_URL],
  "rest.resourceName": "file",
  "rest.resources": {
      "file": "[BASE]/api/v1/session/[SID]/asset/[DFSID]/file/[FILE_EXT]",
      "rest.self": "[BASE]/api/v1/session/[SID]/asset/[DFSID]/file/[FILE_EXT]"
  }
}

Transmit file data to the signed upload URL ([MIME_TYPE] must match the initial request):

curl --request PUT --upload-file [FILE] -H 'Content-Type:[MIME_TYPE]' "[SIGNED_UPLOAD_URL]"

Once the file has completed transferring, signal DF Studio to begin processing:

GET [ON_COMPLETE_URL]
//RESPONSE:

{
  "dfsid": "[DFSID]",
  "status": "ingesting",
  "rest.resourceName": "pending",
  "rest.resources": {
      "pending": "[ON_COMPLETE_URL]",
      "rest.self": "[ON_COMPLETE_URL]"
  }
}

All steps must be completed prior to the URL expiration timestamp included in the uploadUrl response.

Upload Files From a URL

It is also possible to upload directly from a public or fully signed URL.

POST [BASE]/api/v1/session/[SID]/asset/[DFSID]/file/[FILE_EXT]?action=uploadSource

With the POST body containing any URL that can be read, such as a signed S3 URL.

The file will be imported from the provided URL and ingestion will begin immediately once the transfer completes. If the URL cannot be accessed, an error will be returned.

Upload Files Asynchronously From a URL

With larger file transfers (approximately 1GB and up), the uploadSource method will time out before the transfer has completed. In these cases, the uploadSourceAsync method is preferred. This will process the transfer as a background task and return a statusUrl which can be inspected to track progress.

POST [BASE]/api/v1/session/[SID]/asset/[DFSID]/file/[FILE_EXT]?action=uploadSourceAsync

With the POST body containing any URL that can be read, such as a signed S3 URL.

//RESPONSE:

{
  "rest.resourceName": "file",
  "rest.resources": {
    "file": "[BASE]/api/v1/session/[SID]/asset/[DFSID]/file/[FILE_EXT]",
    "rest.self": "[BASE]/api/v1/session/[SID]/asset/[DFSID]/file/[FILE_EXT]"
  },
  "statusUrl": "[STATUS_URL]"
}

Fetch the statusUrl to track the file’s progress through transfer and ingestion. When the status returned matches ingested, the file is available for access within DF Studio.

//RESPONSE:

{
  "pending": "[ID]",
  "dfsid": "[DFSID]",
  "status": "copying",
  "rest.resourceName": "pending",
  "rest.resources": {
    "pending": "[STATUS_URL]",
    "rest.self": "[STATUS_URL]"
  }
}

Stream Data to a File

Streaming data to a file is also supported.

POST [BASE]/api/v1/session/[SID]/asset/[DFSID]/file/[FILE_EXT]?action=uploadStream

With the POST body containing a file to stream.

Ingestion will begin immediately once the transfer completes.

Projects

Projects can be located by name, path in the folder hierarchy, or custom metadata value. New Projects can be created by specifying the desired destination folder.

List Projects

Results will not include metadata.

GET [BASE]/api/v1/session/[SID]/projects.js
//RESPONSE:

[
  {
    "dfsid": "[DFS_PROJECTID]",
    "name": "Example Project",
    "path": "/Folder/Series/Season1,
    "rest.resourceName": "project",
    "rest.resources": {
      "project": "[BASE]/api/v1/session/[SID]/project/[DFS_PROJECTID].js",
      "rest.self": "[BASE]/api/v1/session/[SID]/project/[DFS_PROJECTID].js"
    },
    "shareLink": "[SHARELINK]"
  },

  …

]

Projects can be filtered by appending parameters to the GET request, these parameters can be combined:

  • "path=/Folder/Series/Season1": located within the Library folder “/Folder/Series/Season1”
  • "name=Example Project": with a name beginning with “Example Project”
  • "custom.myField=1": custom metadata field myField having the value of 1 (only one metadata field is allowed per query; null/empty search is not supported)
  • "folderId=[SHARELINK]": contained within the DF Studio folder identified by the Share Link (A folder’s ID, e.g., f_1001, can be used interchangeably.)

Note that within folder names, the slash character (/) is replaced with ~~. If the path parameter references a folder name containing a slash, use ~~ instead.

Create a Project

Add a new Project to the account by submitting the entirety of the path to the desired folder in which it should be stored. Any folders within the path that do not already exist will be created.

Optionally, custom metadata values for the Project can be specified by including a JSON Object in the metadata property.

PUT [BASE]/api/v1/session/[SID]/project.js
//PUT BODY:

{
  "name":"BTS - Selects",
  "path":"/Folder/Series/Season 2/BTS"
}

//RESPONSE:

{
  "dfsid": "[DFS_PROJECTID]",
  "metadata": {},
  "name": "BTS - Selects",
  "path": "/Folder/Series/Season 2/BTS",
  "rest.resourceName": "project",
  "rest.resources": {
      "project": "[BASE]/api/v1/session/[SID]/project/[DFS_PROJECTID].js",
      "rest.self": "[BASE]/api/v1/session/[SID]/project/[DFS_PROJECTID].js"
  },
  "shareLink": "[SHARELINK]"
}

Folders within the path are delimited using the slash character (/). If a slash is desired within a folder name, substitute ~~ and this will be displayed as a slash when the folder appears in DF Studio.

Project Resource

An individual Project can be accessed using its DFS ID or its Share Link from within DF Studio. In the following example, the Share Link URL may be used interchangeably with the Project’s [DFS_PROJECTID]

GET [BASE]/api/v1/session/[SID]/project.js?rest.id=[DFS_PROJECTID]
//RESPONSE:

{
  "dfsid": "[DFS_PROJECTID]",
  "metadata": {},
  "name": "Example Project",
  "path": "/Folder/Series/Season1,
  "rest.resourceName": "project",
  "rest.resources": {
    "project": "[BASE]/api/v1/session/[SID]/project/[DFS_PROJECTID].js",
    "rest.self": "[BASE]/api/v1/session/[SID]/project/[DFS_PROJECTID].js"
  },
  "shareLink": "[SHARELINK]"
}

Project Metadata

Custom metadata fields defined for a Project are returned in the metadata property of the response, as illustrated above. (This includes all fields with keys matching custom.*). These values can be modified by including a JSON Object in the metadata property of a PUT request.

PUT [BASE]/api/v1/session/[SID]/project/[DFS_PROJECTID].js
//PUT BODY:

{
  "metadata":{"custom.titleid": "1234"}
}

//RESPONSE:

{
  "dfsid": "[DFS_PROJECTID]",
  "metadata": {
  
    …

      "custom.titleid": "1234"  
  },
  
  …

}

Any keys not present in the Project’s custom metadata configuration will not be updated.

Folders

Library folders within the DF Studio account can be listed based on their path in the folder hierarchy, or searched by name. New folders or sub-folders can be created by specifying any valid path.

List Folders

GET [BASE]/api/v1/session/[SID]/folders.js
//RESPONSE:

[
  {
    "fullPath": "/Folder/Series/Season1/Ep1",
    "rest.resourceName": "folder"
  },
  
  …

]

Folders can be filtered by appending parameters to the GET request, these parameters can be combined:

  • "path=/Folder/Series": contained within the folder at /Folder/Series
  • "name=Example": with name containing the string Example

Note that within folder names, the slash character (/) is replaced with ~~. If the path or name parameter references a folder name containing a slash, use ~~ instead.

Create a Folder

Add a folder to the account by submitting the entirety of its desired path. Any folders within the path that do not already exist will be created.

PUT [BASE]/api/v1/session/[SID]/folder.js
//PUT BODY:

{
  "fullPath":"/Folder/Series/Season 2"
}

//RESPONSE:

{
  "fullPath": "/Folder/Series/Season 2",
  "rest.resourceName": "folder"
}

Folders within the path are delimited using the slash character (/). If a slash is desired within a folder name, substitute ~~ and this will be displayed as a slash when the folder appears in DF Studio.

PUT [BASE]/api/v1/session/[SID]/folder.js
//PUT BODY:

{
  "fullPath":"/Folder/Series/Season 2/Reshoots ~~ Retouching"
}

//RESPONSE:

{
  "fullPath": "/Folder/Series/Season 2/Reshoots ~~ Retouching",
  "rest.resourceName": "folder"
}

Folder name in DF Studio: “Reshoots / Retouching”.

Lookup Domains

DF Studio supports Custom Lookup Domains - Enterprise-controlled terms a user selects from when editing a metadata field. The terms available for a field are based the path in DF Studio (path), and/or the value of another metadata field (meta). Terms or Options are associated with folders and Projects in DF Studio (path) and/or with specific values of fields on the Asset. Path-based terms can be edited from within DF Studio (or can be hidden); all terms can be edited from the Enterprise API. The Enterprise API (found at https://example_company.dfstudio.com/api/v1/session.js) has several resources which can be used to manage Lookup Domain values.

Lookup Domain Terms can also optionally have Labels associated with them. When a label is present it will be shown in the DF Studio interface and used for Search Indexing. The value will be shown in the Enterprise API. Labels are optional and only supported for Dropdowns, Radio, Checkboxes, and Selectors.

List Domains

List all Lookup Domains defined. Note the property field: Lookup Domains are identified by the field they are associated with. [FIELD] is replaced with the field name for a domain.

GET [BASE]/api/v1/session/[SID]/domains.js
//RESPONSE: 

{
  "results": [
    {
      "field": "custom.subcategory",
      "lookupRules": [ "meta_custom_category" ],
      "addTo": "meta_custom_category",
      "rest.resourceName": "domain"
    }
  ]
}

List Lookup Keys

List the lookup keys for this field, these values replaced [KEY] in the next URL.

GET [BASE]/api/v1/session/[SID]/domain/[FIELD]/meta.js
//RESPONSE:

[
  "fruit",
  "vehicles",
  "sizes"
]

List Lookup Terms

List all terms for a Lookup Domain and given lookup key. The field isAdded is true if the value was added by a user in DF Studio.

GET [BASE]/api/v1/session/[SID]/domain/[FIELD]/meta/[KEY].js
//RESPONSE:

[
  {
    "value": "apple",
    "isAdded": false
  },
  {
    "value": "banana",
    "isAdded": false
  },
  {
    "value": "orange",
    "isAdded": false
  }
]

Update Lookup Terms

Updates the terms associated with the lookup [KEY], removing any terms not contained in the set and setting all remaining values' isAdded to false.

POST [BASE]/api/v1/session/[SID]/domain/[FIELD]/meta/[KEY].js
//POST BODY:

[ 'apple','banana','carrot' ]

//RESPONSE:

{'[KEY]': 'updated' }

Update Multiple Lookup Terms Sets

Updates the terms associated with multiple lookup keys in one operation, removing any terms not contained in the set and setting all remaining values' isAdded to false.

POST [BASE]/api/v1/session/[SID]/domain/[FIELD]/meta.js
//POST BODY:

{
  'key1':[ 'apple','banana','carrot' ],
  'key2':[ 'dog','cat','horse' ]
}

//RESPONSE:

{
  'key1': 'updated',
  'key2': 'updated' 
}

List Lookup Terms Added

List all terms added by users in DF Studio.

GET [BASE]/api/v1/session/[SID]/domain-added.js
//RESPONSE:

[
  {
    "field": "custom.subcategory",
    "meta": "fruit",
    "value": "guava"
  }
]

Global Terms

Some terms or options are global to all Assets

GET [BASE]/api/v1/session/[SID]/domain/[FIELD]/path/root.js
//RESPONSE:

[
  {
    "value": "apple",
    "isAdded": false
  },
  {
    "value": "banana",
    "isAdded": false
  },
  {
    "value": "orange",
    "isAdded": false
  }
]

Update Global Terms

Updates the terms global to DF Studio, removing any values not contained in the set and setting all remaining values' isAdded to false.

POST [BASE]/api/v1/session/[SID]/domain/[FIELD]/path/root.js
//POST BODY:

[ 'apple','banana','carrot' ]

//RESPONSE:

{
  'f_root_3': 'updated'
}

Define Terms with Labels

Updates the terms with labels for multiple lookup keys at once. If no Label is set for a value, then the value is shown in DF Studio.

POST [BASE]/api/v1/session/[SID]/domain/[FIELD]/path/root.js
//POST BODY:

[ {value:'1',label:'apple'},{value:'2',label:'banana'},{value:'3',label:'carrot'} ]


//RESPONSE:

{
  'f_root_3': 'updated'
}

Related articles