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 the asset id
  • [DFSID]: replace with the asset globally unique id (DFS ID)
  • [FIELD]: dfstudio.keywords or custom.myCustomField

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.

List Assets

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

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

  "returned": [
    {
      "id": "1",
      "dfsid": "dfsa-a40fsd91ex-0001",
      "isStoredActive": true,
      "isStoredCold": false,
      "location": "/Folder/Series/Season1/Ep1",
      "name": "img0001",
      "rest.resourceName": "asset",
      "rest.resources": {
        "asset": "[BASE]/api/v1/session/[SID]/asset/1.html",
        "file": "[BASE]/api/v1/session/[SID]/asset/1/file.html",
        "metadata": "[BASE]/api/v1/session/[SID]/asset/1/metadata.html",
        "rest.self": "[BASE]/api/v1/session/[SID]/asset/1.html"
      }
    },

    ...

   ]
}

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

  • "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 ]
  • "location=/Folder/Series/Season1/Ep1": in the Project “Ep1”

Note that 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 location=/This %26 That

Asset Resource

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

GET [BASE]/api/v1/session/[SID]/asset/[AID].js
//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/[AID].js",
    "edits": "[BASE]/api/v1/session/[SID]/asset/[AID]/edits.js",
    "file": "[BASE]/api/v1/session/[SID]/asset/[AID]/file.js",
    "metadata": "[BASE]/api/v1/session/[SID]/asset/[AID]/metadata.js",
    "rest.self": "[BASE]/api/v1/session/[SID]/asset/[AID].js"
  },
  "setup": "No Setup",
  "shareLink": "[BASE]/link/a:100-example/img/8765/[AID]"
 }

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/[AID]/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/[AID]/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/[AID]/metadata.js
//RESPONSE

{
  "composite:ImageSize": "1400x1800",
  "custom.myField": "1",
  "dfstudio.caption": "Example Photo",
  "dfstudio.captionWriter": "Bob Example",
  "dfstudio.captureDate": "2015-10-21",
  "dfstudio.copyright": "2018, 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": "2018, Example Company",
  "iptc:By-line": "",
  "iptc:Caption-Abstract": "",
  "iptc:CopyrightNotice": "2018, 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/[AID]/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": "2018, 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": "2018, Example Company",
  "iptc:By-line": "",
  "iptc:Caption-Abstract": "",
  "iptc:CopyrightNotice": "2018, Example Company"
  "xmp:Location": "A Place, City, State ZIP"
}

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/[AID]/files.js
//RESPONSE

[
  {
    "id": "jpg",
    "fileType": "jpg",
    "fileUrl": null,
    "isStoredActive": true,
    "isStoredCold": false,
    "size": "42118 bytes",
    "stored": "active"
    "rest.resourceName": "file",
    "rest.resources": {
      "file": "[BASE]/api/v1/session/[SID]/asset/1/file/jpg.js",
      ...
    }
  }
]

Get the fileURL of a File

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

{
  "id": "jpg",
  "fileUrl": [URL],
  ...
}

With this information, a client can download the file within 1 hour.

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