Medias

Read media collection

This relation targets the collection of medias related to the current resource.

dam --> medias: all the medias in the DAM instance
folder-tree --> medias: all the medias of the sub tree
folder --> medias: all the medias of the folder
basket --> medias: all the medias of the basket
selection --> medias: all the medias in a selection

The targeted resource is provided for traversability purpose.

/!\ If the total number of medias reaches a maximum limit, for performance reason, the collection returned by the resource may be empty.

4.0.0+

Create media

A media can be created by sending POST request on the collection of medias.

Two parameters can be passed through the _links property :

the from link targets the uploaded file descriptor the media will be created from
the kpk:form link targets the form that will be used to initialize media metadata

Either from or kpk:form must be provided.

Media creation use query strings for DAM instances using XMP versioning:

Query parameter	Description	Arity
forceNew	If set to true this query string force new media creation even if a media with same document id exists.	[0-1]

Sample requests:

Create a media from uploaded file using user's default form for file type

POST /api/dam/medias
Content-Type: application/json

{
  "_links":
  {
    "from": 
    {
      "href": "http://baobab.keepeek.com/api/dam/files/5fa23b4ac"
    }
  }
}

Create an empty media using specific form definition

POST /api/dam/medias
Content-Type: application/json

{
  "_links":
  {
    "kpk:form": 
    {
      "href": "http://baobab.keepeek.com/api/dam/forms/1"
    }
  }
}

Create a media from an uploaded file and specific form definition

POST /api/dam/medias
Content-Type: application/json

{
  "_links":
  {
    "from": 
    {
      "href": "http://baobab.keepeek.com/api/dam/files/5fa23b4ac"
    },
    "kpk:form": 
    {
      "href": "http://baobab.keepeek.com/api/dam/forms/6"
    }
  }
}

4.0.0+

Create a media in a target directory from uploaded file using user's default form for file type

POST /api/dam/folders/{folderId}/medias
Content-Type: application/json

{
  "_links":
  {
    "from": 
    {
      "href": "http://baobab.keepeek.com/api/dam/files/5fa23b4ac"
    }
  }
}

4.16.0+

media

This relation targets the canonical representation of a media.

4.0.0+

Show empty embedded metadata

By default, empty media metadata is not embedded in the response to a GET request on /api/dam/medias/<media_id>.
To show empty metadata in the _embedded part of the response, use the embedAllMetadata parameter:

GET /api/dam/medias/6421?embedAllMetadata=true

4.62.0+

Show embedded folders

To show folders in the _embedded part of the response, use the embeddedFolders parameter:

GET /api/dam/medias/6421?embeddedFolders=true

4.74.0+

from

Links with the relation indicates from which resource current one was created.

4.0.0+

metadatas

This relation targets the collection of metadatas available for the current media. This collection lists all available metadata from form of current media.

Single request to update a metadata

Send a PUT request on the metadata: http://baobab.keepeek.com/api/dam/media/1330/metadatas/shot_date

Sample request:

PUT http://baobab.keepeek.com/api/dam/medias/1330/metadatas/shot_date
Content-Type: application/json+hal,[...]

{
  "value": "2011-06-04T22:00:00.000Z"
}

Sample request to update (replace) a thesaurus field :

PUT http://baobab.keepeek.com/api/dam/medias/1330/metadatas/couleur
Content-Type: application/json+hal,[...]

{
  "value": [ {
             "id": 920,
             "title": "beige"},
             {
             "id": 940,
             "title": "orange"}
           ]
}

Thesaurus values can be retrieved from thesaurus-tree resource :

GET http://baobab.keepeek.com/api/dam/thesaurus-tree/916  HTTP/1.1
[...]
HTTP/1.1 200 OK
Content-Type: application/hal+json;version=1;charset=UTF-8
[...]
{
"title": "couleur",
[...]
"_embedded": {
"child": [
    {
      "id": 920,
      "title": "beige",
      [...]
    },
    {
      "id": 921,
      "title": "blanc",
      [...]
    }
    [...]
  ]
 }
}

4.0.0+

Sample request to use a thesaurus term that does not exist (candidate term) :

PUT http://baobab.keepeek.com/api/dam/medias/1330/metadatas/produits_commercialises
Content-Type: application/json+hal,[...]

{
  "value": [ 
              {
                "title": "my new term"
              }
           ]
}

Note:

the thesaurus must be configured from the backoffice in order to allow the addition of terms.
the "# " < >" characters are special and will be automatically removed from the term.
if the term is not text, an "invalid-thesaurus-candidate-format" type error will be returned.
if the term already exists, your term will not be added and the term already present will be used.
the maximum size of the term must not exceed 100 characters, an "invalid-thesaurus-candidate-size" type error will be raised if this is the case.

4.72.0+

custom-statuses

This relation targets the list of customized status, sorted accordingly with the order defined by the administrator.

4.0.0+

custom-status

This relation targets the canonical representation of a custom status. It's localized name and the list of compatible status.

GET /api/dam/medias/custom-statuses/1

[...]
HTTP/1.1 200 OK
Content-Type: application/hal+json;version=1;charset=UTF-8
[...]
{
    "id": 1,
    "name": "Brouillon",
    "textColor": "#12545",
    "backgroundColor": "#546584",
    "compatibleStatuses": [
        "DRAFT",
        "BASKET",
        "IMPORT"
    ],
    "_links": {
        "self": {
            "href": "http://baobab.keepeek.com/api/dam/medias/custom-statuses/1"
        }
    }
}

4.0.0+

terms-of-use

This relation target the terms-of-use associated with current resource. This can be either a single media terms of use resource or a collection of terms of use if current resource is a set of media (basket, search result...).

User must accept the returned terms-of-use before using the media or the set of media: see export features.

The markup language used for formatting terms of use values is HTML.

4.0.0+

file-versions

This relation targets the file versions available for the current media. This collection lists all available versions of current media.

Current media version

Every media contains at least the current version

GET /api/dam/medias/1330/file-versions/current  HTTP/1.1

[...]
HTTP/1.1 200 OK
Content-Type: application/hal+json;version=1;charset=UTF-8
[...]
{
"permission": "WRITE",
"size": 327094,
"current": true,
"storingDate": "2012-08-27T22:00:00.000Z",
"originalFileName": "©Alforesm - 29 décembre 2007.jpg",
"width": 1024,
"height": 683,
"_links": {
  [...]
  "kpk:large": {
     "href": "http://baobab.keepeek.com/medias/domain2/media0/63-tp9ktlcjq8-large.jpg"
   },
  [...]
   "preview": {
     "href": "http://baobab.keepeek.com/medias/domain2/media0/63-tp9ktlcjq8-preview.jpg"
   },
  [...]
  }
}

Create media version

A media version can be created by sending POST request on the collection of media versions.

A parameter must be passed through the _links property :

the from link targets the uploaded file descriptor the media version will be created from

A parameter must be passed to the request to remove faces or not : removeFaces (by default : true)

Additional parameters can be passed to the request:

recreateCustomThumbnails > set it to true to recreate custom thumbnails, default is false
keepExistingCover > set it to true to keep the cover (if one exists), default is false

Sample request:

POST /api/dam/medias/1330/file-versions
Content-Type: application/json

{
  "_links":
  {
    "from": 
    {
      "href": "http://baobab.keepeek.com/api/dam/files/5fa23b4ac"
    }
  }
}

Restore a previous media version

Either send a PUT request to current version with the version id to replace current, or a PUT request on the version to set as current with a current:true.

PUT /api/dam/medias/1330/file-versions/current
Content-Type: application/json

{
  "id": 1
}

PUT /api/dam/medias/1330/file-versions/1
Content-Type: application/json

{
  "id" : 1,
  "current" : true
}

Delete a media version

Send a DELETE request on a version which is not current

DELETE /api/dam/medias/1330/file-versions/1

4.16.0+

duplicates

This relation targets the collection of duplicates media of current media. The duplicationStatus property of a media contains the result of the duplication detection :

NO_DUPLICATES : the detection found no media in the folder-tree with similar visual features
DUPLICATES_FOUND : the detection found at least a media, results are listed by the duplicates media collection resource
DUPLICATES_ACKNOWLEDGED : the detection found at least a visual duplicate but a user has acknowleged and the media is legitimate

4.16.0+

labels

This relation targets the list of labels of current media, sorted accordingly with the order defined by the administrator.

4.25.0+

label

This relation targets the canonical representation of a label.

4.25.0+

media-links

This relations targets the list of media link types of current media.

GET /api/dam/medias/1330/media-links/
{
    "_links": {
        "self": {
            "href": "http://baobab.keepeek.com/api/dam/medias/159/media-links"
        },
       [...]
    },
    "_embedded": {
        "media-link": [
            {
                "title": "Par défaut",
                "description": "Type par défaut pour les éléments associés",
                "_links": {
                    "self": {
                        "href": "http://baobab.keepeek.com/api/dam/medias/1330/media-links/1"
                    },
                    "kpk:medias": {
                        "href": "http://baobab.keepeek.com/api/dam/medias/1330/media-links/1/medias"
                    }
                }
            },
            [...]
        ]
    },
    "totalCount": 3
}

Medias list of current media by type

This list can be sorted by fields and we can selected fields to display.

GET /api/dam/medias/1330/media-links/2/medias?sort=title.FR desc&fields=id,title
{
    "_links": {
        "self": {
            "href": "http://baobab.keepeek.com/api/dam/medias/1330/media-links/2/medias?page=1&size=20"
        },
        [...]
    },
    "_embedded": {
        "media": [
            {
                "id": 154,
                "title": "Media 1",
                "_links": {
                    "self": {
                        "href": "http://baobab.keepeek.com/api/dam/medias/154"
                    },
                    "kpk:large": {
                        "href": "http://baobab.keepeek.com/medias/domain2/media0/154-pecqraltbb-large.jpg"
                    },
                    "kpk:medium": {
                        "href": "http://baobab.keepeek.com/medias/domain2/media0/154-pecqraltbb-medium.jpg"
                    },
                    "preview": {
                        "href": "http://baobab.keepeek.com/medias/domain2/media0/154-pecqraltbb-preview.jpg"
                    },
                    "kpk:small": {
                        "href": "http://baobab.keepeek.com/medias/domain2/media0/154-pecqraltbb-small.jpg"
                    },
                    "kpk:whr": {
                        "href": "http://baobab.keepeek.com/medias/domain2/media0/154-pecqraltbb-whr.jpg"
                    },
                    "kpk:xlarge": {
                        "href": "http://baobab.keepeek.com/medias/domain2/media0/154-pecqraltbb-xlarge.jpg"
                    }
                }
            },
            [...]
        ]
    },
    "totalCount": 4
}

4.27.0+

cover

This relation targets a cover of the media, thumbnails are generated from the cover and not from the original file.

Replace the cover of the media

PUT /api/dam/medias/1330/cover

4.31.0+

attachments

This relation targets media attachments

Get all attachments of a media

GET /api/dam/medias/1330/attachments

If the media is found the Http Status of the response of HTTP request will be : 200, the response will contain a paginated list of attachment resources. Each of attachment resource will follow the following schema:

"properties": {
    "id": {
      "type": "integer"
    },
    "title": {
      "type": "array",
      "items": {
        "type": "object",
        "properties": {
          "lang": {
            "type": "string"
          },
          "value": {
            "type": "string"
          }
        }
      }
    },
    "description": {
      "type": "array",
      "items": {
        "type": "object",
        "properties": {
          "lang": {
            "type": "string"
          },
          "value": {
            "type": "string"
          }
        }
      }
    },
    "originalFilename": {,
      "type": "string"
    },
    "url": {
      "type": "string"
    },
    "creationDate": {
      "type": "string",
      "format": "date-time"
    },
    "creationUserId": {
      "type": "integer"
    },
    "updateDate": {
      "type": "string",
      "format": "date-time"
    },
    "updateUserId": {
      "type": "integer"
    },
    "fileSize": {
      "type": "integer",
      "format": "long"
    },
    "cloudProviderState": {
      "type": "string",
      "enum": ["ONLINE","OFFLINE"]
    },
    "storageProvider": {
      "type": "string"
    },
    "type": {
      "type": "string",
      "enum": ["IMAGE","VIDEO","SOUND","DOCUMENT","OTHER","LINK"]
    }
  }

Possible errors are :

404 (media-not-found) : Requested media does not exists
403 (access-hd-accessDenied) : You need Read and Download HD rights on media to have access to attachments

Create a media attachment

Header : Content-type:application/json

POST /api/dam/medias/1330/attachments

Request body must contains following attributes:

title : An array of object with lang and value attribute to set the title of the attachment in different language

example:

"title" : [
        {
            "lang": "EN",
            "value": "Attachment title"
        },
        {
            "lang": "FR",
            "value": "Titre de ma pièce-jointe"
        }
    ]

originalFilename : The original file name of the attachment
url : The URL of the attachment
storageProvider : The name of the storage provider can be (Keepeek, Azure, ...)
type : The attachment type must be one of IMAGE,VIDEO,SOUND,DOCUMENT,OTHER or LINK

Request body can contain following attributes:

description : An array of object with lang and value attribute to set the description of the attachment in different language

example:

"description":[
        {
            "lang": "EN",
            "value": "Attachment description"
        },
        {
            "lang": "FR",
            "value": "Description de ma pièce-jointe"
        }
    ]

fileSize : The attachment file size (bytes)
cloudProviderState: The attachment state in the cloud provider, must be one of ONLINE or OFFLINE

If the attachment is created the Http Status of the response of HTTP request will be : 201, it's possible to get the location of the new created resource int the Location Http response header.

Possible errors are :

404 (media-not-foud) : Requested media does not exists
403 (access-write-accessDenied) : You need Write right on media to have access to attachment creation
403 (attachment-feature-accessDenied) : Attachment feature is not active on your Keepeek instance or none of your profile have access to this feature

Update a media attachment

Header : Content-type:application/json

PUT /api/dam/medias/1330/attachments/123

Request body must contain following attributes:

title : An array of object with lang and value attribute to set the title of the attachment in different language

example:

"title" : [
        {
            "lang": "EN",
            "value": "Attachment title"
        },
        {
            "lang": "FR",
            "value": "Titre de ma pièce-jointe"
        }
    ]

originalFilename : The original file name of the attachment
url : The URL of the attachment
storageProvider : The name of the storage provider can be (Keepeek, Azure, ...)
type : The attachment type must be one of IMAGE,VIDEO,SOUND,DOCUMENT,OTHER or LINK

Request body can contains following attributes:

description : An array of object with lang and value attribute to set the description of the attachment in different language

example:

"description":[
        {
            "lang": "EN",
            "value": "Attachment description"
        },
        {
            "lang": "FR",
            "value": "Description de ma pièce-jointe"
        }
    ]

fileSize : The attachment file size (bytes)
cloudProviderState: The attachment state in the cloud provider, must be one of ONLINE or OFFLINE

If the attachment is updated the Http Status of the response of HTTP request will be : 204.

Possible errors are :

404 (media-not-found) : Requested media does not exists
404 (attachment-media-not-found) : Request attachment does not exists or it is not linked to the requested media
403 (access-write-accessDenied) : You need Write right on media to have access to attachment update
403 (attachment-feature-accessDenied) : Attachment feature is not active on your Keepeek instance or none of user profile have access to this feature

Update 4.50 :

Since API version 4.50.0 you can disable unarchive email notification by passing notifyUnarchive query parameter to your request. If this query parameter is not set or set to true the unarchive email notification will be sent, otherwise this email will not be sent.

Example to disable email unarchive notification:

Header : Content-type:application/json

PUT /api/dam/medias/1330/attachments/123?notifyUnarchive=false

Delete an attachment

DELETE /api/dam/medias/1330/attachments/123

If the attachment is deleted the Http Status of the response of HTTP request will be : 204.

Possible errors are :

404 (media-not-found) : Requested media does not exists
404 (attachment-media-not-found) : Request attachment does not exists or it is not linked to the requested media
403 (access-write-accessDenied) : You need Write right on media to have access to attachment deletion
403 (attachment-feature-accessDenied) : Attachment feature is not active on your Keepeek instance or none of user profile have access to this feature

Get an attachment of a media

GET /api/dam/medias/1330/attachments/123

If the attachment is found the Http Status of the response of HTTP request will be : 200.

The response follow the following schema:

"properties": {
    "id": {
      "type": "integer"
    },
    "title": {
      "type": "array",
      "items": {
        "type": "object",
        "properties": {
          "lang": {
            "type": "string"
          },
          "value": {
            "type": "string"
          }
        }
      }
    },
    "description": {
      "type": "array",
      "items": {
        "type": "object",
        "properties": {
          "lang": {
            "type": "string"
          },
          "value": {
            "type": "string"
          }
        }
      }
    },
    "originalFilename": {,
      "type": "string"
    },
    "url": {
      "type": "string"
    },
    "creationDate": {
      "type": "string",
      "format": "date-time"
    },
    "creationUserId": {
      "type": "integer"
    },
    "updateDate": {
      "type": "string",
      "format": "date-time"
    },
    "updateUserId": {
      "type": "integer"
    },
    "fileSize": {
      "type": "integer",
      "format": "long"
    },
    "cloudProviderState": {
      "type": "string",
      "enum": ["ONLINE","OFFLINE"]
    },
    "storageProvider": {
      "type": "string"
    },
    "type": {
      "type": "string",
      "enum": ["IMAGE","VIDEO","SOUND","DOCUMENT","OTHER","LINK"]
    }
  }

Possible errors are :

404 (media-not-found) : Requested media does not exists
404 (attachment-media-not-found) : Request attachment does not exists or it is not linked to the requested media
403 (access-hd-accessDenied) : You need Read and Download HD rights on media to have access to attachments

4.46.0

Get a download link for an attachment of a media

POST /api/dam/medias/1330/attachments/123/download-link

If the attachment's download link is created the Http Status of the response of HTTP request will be : 201.

The response follow the following schema:

{

  "properties": {
    "uri": {
      "title": "uri of download link",
      "type": "string"
    },
    "expirationDate": {
      "title": "expiration date of download links",
      "description": "Duration of download links is configured by ATTACHMENT_FEATURE_CONFIGURATION technical properties",
      "type": "string",
      "format": "date-time"
    }
  }
}

The period of validity is configured by the linkDuration property of the ATTACHMENT_FEATURE_CONFIGURATION technical property, if this property is not set period of validity is one hour.

4.48.0

Update 4.64.0

Since version 4.64.0 you can get a Keepeek download link instead of the default attachment provider one.

You can do so by adding the linkType query parameter with the value kpk.

The validity of the download link will then be the downloadTokenDuration property of the ATTACHMENT_FEATURE_CONFIGURATION technical property, defaulting to 15 days.

Example:

POST /api/dam/medias/1330/attachments/123/download-link?linkType=kpk

4.64.0

Get an attachment upload link for a media

POST /api/dam/medias/1330/attachments/upload-link
{
  "storageProvider": "azure-storage",
  "blobName": "i-am-a-blob"
}

The request body must contain:

storageProvider > Provider name of a configured storage provider from technical property ATTACHMENT_PROVIDER_CONFIGURATION
blobName > name of the target blob

If the upload link is created the status of the response to the HTTP request will be : 201.

The response matches the following schema:

{
  "properties": {
    "uri": {
      "title": "uri of the upload link",
      "type": "string"
    },
    "expirationDate": {
      "title": "expiration date of upload link",
      "type": "string",
      "format": "date-time"
    }
  }
}

The validity duration is configured in the ATTACHMENT_FEATURE_CONFIGURATION technical property, if this property is not set the validity duration is one hour.

4.59.0

player

Keepeek gives access to a video player web component, it is possible to get its configuration for a specific media trough the player related resource.

JSON configuration file respects the JSON schema below :

{
  "$schema": "http://json-schema.org/draft-07/schema#",
  "title": "KpkVideoConfiguration",
  "type": "object",
  "properties": {
    "statistics": {
      "description": "Statistics configuration",
      "type": "object",
      "properties": {
        "url": {
          "description": "Hit endpoint",
          "type": "string",
          "title": "url"
        },
        "mediaId": {
          "description": "Media identifier",
          "type": "integer",
          "title": "mediaId"
        },
        "instanceId": {
          "description": "Instance identifier",
          "type": "integer",
          "title": "instanceId"
        },
        "uiId": {
          "description": "UI identifier",
          "type": "integer",
          "title": "uiId"
        },
        "maxDuration": {
          "description": "Maximum video duration",
          "type": "integer",
          "format": "long",
          "title": "maxDuration"
        },
        "referrer": {
          "description": "Referrer url",
          "type": "string",
          "title": "referrer"
        }
      },
      "required": [
        "instanceId",
        "maxDuration",
        "mediaId",
        "referrer",
        "uiId",
        "url"
      ],
      "title": "statistics"
    },
    "theme": {
      "description": "Theme for video.js (default or fantasy)",
      "type": "object",
      "properties": {
        "value": {
          "type": "string",
          "enum": [
            "default",
            "fantasy"
          ]
        }
      }
    },
    "autoplay": {
      "description": "Autoplay video, player will be muted because most browser disallow autoplay with sound",
      "type": "boolean",
      "title": "autoplay"
    },
    "posterSrc": {
      "description": "Sets the image that displays before the video begins playing",
      "type": "string",
      "title": "posterSrc"
    },
    "customDownloadUrl": {
      "description": "Url to download highest available resolution video as mp4",
      "type": "string",
      "title": "customDownloadUrl"
    },    
    "tracks": {
      "title": "tracks",
      "description": "Tracks configuration",
      "type": "array",
      "items": {
        "type": "object",
        "properties": {
          "kind": {
            "enum": [
              "chapters",
              "subtitles"
            ],
            "type": "string",
            "title": "kind"
          },
          "src": {
            "description": "Source",
            "type": "string",
            "title": "src"
          },
          "srclang": {
            "description": "Language (EN)",
            "type": "string",
            "title": "srclang"
          },
          "default": {
            "description": "Is default track ?",
            "type": "boolean",
            "title": "default"
          }
        },
        "required": [
          "default",
          "kind",
          "src",
          "srclang"
        ]
      }
    },
    "sources": {
      "title": "sources",
      "description": "Sources configuration",
      "type": "array",
      "items": {
        "type": "object",
        "properties": {
          "label": {
            "description": "Label ",
            "type": "string",
            "title": "label"
          },
          "res": {
            "description": "Resolution",
            "type": "integer",
            "title": "res"
          },
          "src": {
            "description": "The url to the source",
            "type": "string",
            "title": "src"
          },
          "type": {
            "description": "The mime type of the source",
            "type": "string",
            "title": "type"
          },
          "default": {
            "description": "Is default resolution ?",
            "type": "boolean",
            "title": "default"
          }
        },
        "required": [
          "default",
          "label",
          "res",
          "src"
        ]
      }
    }
  },
  "required": [
    "sources",
    "statistics",
    "theme",
    "tracks"
  ]
}

4.47.0

Articles dans cette section

medias

Read media collection

Create media

media

Show empty embedded metadata

Show embedded folders

from

metadatas

Single request to update a metadata

custom-statuses

custom-status

terms-of-use

file-versions

Current media version

Create media version

Restore a previous media version

Delete a media version

duplicates

labels

label

media-links

Medias list of current media by type

cover

Replace the cover of the media

attachments

Get all attachments of a media

Create a media attachment

Update a media attachment

Delete an attachment

Get an attachment of a media

Get a download link for an attachment of a media

Update 4.64.0

Get an attachment upload link for a media

player

Articles associés