Getting started: update media's metadatas
Context
Metadatas are informations that describe the media.
Each media has an associated media sheet, each media sheet contains sheet fields that describe the media.
Sheet fields are also called metadatas.
Sheet fields have types listed below.
⚠️ Types have different names in the Back-office application and in the API.
| Name in Back-office | Name in API |
| Checkbox | CHECK_BOX |
| Date | DATE |
| Date and time | DATETIME |
| Dropdown list | SIMPLE_LIST |
| Fields with suggestions | MULTIPLE_LIST |
| Formatted text | HTML |
| Geographical information | GEO |
| Long text | TEXT_AREA |
| Number | NUMBER |
| Short text | TEXT |
| Thesaurus | THESAURUS |
| Url | URL |
Get metadatas of a media
To get the media's metadata, use GET request on this path:
/api/dam/medias/{{mediaId}}/metadatas
You can find this path in the media representation (/api/dam/medias/{{mediaId}}) on kpk:metadatas link:
curl --request GET \
--url https://{{KeepeekInstance}}/api/dam/medias/{{mediaId}}/metadatas \
--header 'authorization: Basic baseEncodedLoginPassword'
You should receive a response that looks like:
{
"_links": {
"self": {
"href": "https://keepeekInstance/api/dam/medias/8857/metadatas?page=1&size=40"
},
"curies": [
{
"name": "kpk",
"href": "https://keepeekInstance/api/doc/rels/{rel}",
"templated": true
}
]
},
"_embedded": {
"metadata": [
{
"id": "title",
"name": "Title",
"permission": "WRITE",
"value": "Media-test",
"_links": {
"self": {
"href": "https://keepeekInstance/api/dam/medias/8857/metadatas/title"
},
"kpk:field": {
"href": "https://keepeekInstance/api/dam/forms/1/fields/2"
}
}
},
{
"id": "shot_date",
"name": "Shoot date",
"permission": "WRITE",
"value": "2025-02-05T23:00:00.000Z",
"_links": {
"self": {
"href": "https://keepeekInstance/api/dam/medias/8857/metadatas/shot_date"
},
"kpk:field": {
"href": "https://keepeekInstance/api/dam/forms/1/fields/5"
}
}
},
{
"id": "legend",
"name": "Legend",
"permission": "WRITE",
"value": "Media-test.tif",
"_links": {
"self": {
"href": "https://keepeekInstance/api/dam/medias/8857/metadatas/legend"
},
"kpk:field": {
"href": "https://keepeekInstance/api/dam/forms/1/fields/147"
}
}
},
{
"id": "location",
"name": "Location",
"permission": "WRITE",
"value": "Maroc",
"_links": {
"self": {
"href": "https://keepeekInstance/api/dam/medias/8857/metadatas/location"
},
"kpk:field": {
"href": "https://keepeekInstance/api/dam/forms/1/fields/149"
}
}
}
...
]
},
"totalCount": 39
}
You can also see the metadata field representation by doing a GET request to kpk:field link.
Update a metadata of a media
To update a metadata, use the PUT request on the path:
/api/dam/media/{{mediaId}}/metadatas/{{metadataID}}
with the value you want to insert.
If you want to update the title of the media, send a PUT request on the URL with new title: https://keepeekInstance/api/dam/medias/8857/metadatas/title
(it is the self link of the metadata).
curl --request PUT \
--url https://{{KeepeekInstance}}/api/dam/medias/8857/metadatas/title \
--header 'authorization: Basic baseEncodedLoginPassword' \
--header 'content-type: application/json' \
--data
'{
"value": "my new title"
}'
⚠️ Some fields can have different values in different language, for example, a title can be different value in french and english. This language list is fixed and depend on your instance. If you want to modify the language list, please contact Keepeek support.
There are 2 types of multilingual fields :
- fields like short text. You can write values in different language.
Ex: Dropdown list, Email, Formatted text, Geographical information, Long text, Short text, Url
- fields like thesaurus where you have to choose values that have different translation depending of the language
Ex: Fields with suggestions, Thesaurus
To set the language, you can use the header Content-Language with the value we want to use, such as en, fr, etc.
⚠️ You can use only 1 language at a time.
If no Content-Language header is set, we use the default value of the user used, or the default value of the Keepeek instance.
Some fields have a specific format like:
- Checkbox: true or false
- Date: yyyy-mm-dd
- Date and time: yyyy-mm-ddThh:mm(+hh:mm)?
- Email: A valid email address with less than 500 characters
- Number: A valid Integer
- Url: A valid URL with less than 2000 characters
- Short text: Text with less than 2000 characters
- Long text: Text with less than 20000 characters
- Dropdown list: Text with a value that exists in the list
- Fields with suggestion: values separated by comma
- Thesaurus: An array of the form below where thesaurus values can be retrieved on the thesaurus-tree resource
{
"value": [
{
"id": 920,
"title": "beige"
},
{
"id": 940,
"title": "orange"
}
]
}
If you want to add a thesaurus value that does not exist and the thesaurus field accept candidate:
{
"value": [
{
"title": "newcolor"
}
]
}
Examples
Let's illustrate with 3 different examples !
First Example - Update 1 metadata of a media
You want to update the metadata field couleur of a media.
To know the type of the field, send a GET request on its kpk:field link.
curl --request GET \
--url https://{{KeepeekInstance}}/api/dam/forms/1/fields/200?forceArrays=true \
--header 'authorization: Basic baseEncodedLoginPassword'
Response is:
{
"id": "couleur",
"title": "Colors",
"type": "THESAURUS",
"mandatory": false,
"indexed": true,
"indexSuggest": true,
"forceSelection": true,
"summary": false,
"publicDisplay": true,
"portalDisplay": true,
"visible": true,
"editable": true,
"_links": {
"self": {
"href": "https://{{KeepeekInstance}}/api/dam/forms/1/fields/200"
},
"curies": [
{
"name": "kpk",
"href": "https://{{KeepeekInstance}}/api/doc/rels/{rel}",
"templated": true
}
],
"kpk:thesaurus": {
"href": "https://{{KeepeekInstance}}/api/dam/thesauruses/916"
}
}
}
With the response, we see that the field is of type thesaurus.
Lets follow the link kpk:thesaurus to get the kpk:thesaurus-tree link.
curl --request GET \
--url 'https://{{KeepeekInstance}}/api/dam/thesaurus-tree/916?forceArrays=true' \
--header 'authorization: Basic baseEncodedLoginPassword' \
We obtain the response:
{
"id": 916,
"title": "couleur",
"_links": {
"self": {
"href": "https://{{KeepeekInstance}}/api/dam/thesaurus-tree/916"
},
"curies": [
{
"name": "kpk",
"href": "https://{{KeepeekInstance}}api/doc/rels/{rel}",
"templated": true
}
],
"kpk:thesaurus": {
"href": "https://{{KeepeekInstance}}/api/dam/thesauruses/916"
}
},
"_embedded": {
"child": [
{
"id": 920,
"title": "beige",
"_links": {
"self": {
"href": "https://{{KeepeekInstance}}/api/dam/thesaurus-tree/916/children/920"
},
"kpk:thesaurus": {
"href": "https://{{KeepeekInstance}}/api/dam/thesauruses/920"
}
}
},
{
"id": 938,
"title": "black",
"_links": {
"self": {
"href": "https://{{KeepeekInstance}}/api/dam/thesaurus-tree/916/children/938"
},
"kpk:thesaurus": {
"href": "https://{{KeepeekInstance}}/api/dam/thesauruses/938"
}
}
},
{
"id": 922,
"title": "blue",
"_links": {
"self": {
"href": "https://{{KeepeekInstance}}/api/dam/thesaurus-tree/916/children/922"
},
"kpk:thesaurus": {
"href": "https://{{KeepeekInstance}}/api/dam/thesauruses/922"
}
}
}
...
]
},
"childrenCount": 15
}
We can now pick the values we want to update the media.
Let's say we want to set the values "black" and "blue" for the media.
Send a PUT request on the metadatas "couleur" of the media with the ids of the thesaurus we want to use:
curl --request PUT \
--url https://{{KeepeekInstance}}/api/dam/medias/8857/metadatas/couleur \
--header 'authorization: Basic baseEncodedLoginPassword' \
--data '{
"value": [
{
"id": 938
},
{
"id": 922
}
]
}'
If we get the media again, we can check than the metadata couleur has been updated.
Second example - Update 1 medatadata field in a specific language
I want to update the field fields_with_suggestions of my media in english.
To know the type of my field, send a GET request on its kpk:field link.
curl --request GET \
--url https://{{KeepeekInstance}}/api/dam/forms/1/fields/391 \
--header 'authorization: Basic baseEncodedLoginPassword'
I receive:
{
"id": "fields_with_suggestions",
"title": "Fields with suggestions",
"description": "",
"type": "MULTIPLE_LIST",
"mandatory": false,
"indexed": true,
"indexSuggest": true,
"forceSelection": false,
"summary": false,
"publicDisplay": true,
"portalDisplay": true,
"visible": true,
"editable": true,
"_links": {
"self": {
"href": "https://{{KeepeekInstance}}/api/dam/forms/1/fields/391"
},
"curies": [
{
"name": "kpk",
"href": "https://{{KeepeekInstance}}/api/doc/rels/{rel}",
"templated": true
}
]
}
}
With the result, we detect that the type is MULTIPLE_LIST (aka field with suggestions).
Let's say I want to put the values "surf", "boat" and "sea". I would need to send the PUT request:
curl --request PUT \
--url https://{{KeepeekInstance}}/api/dam/medias/8857/metadatas/fields_with_suggestions \
--header 'authorization: Basic baseEncodedLoginPassword' \
--header 'content-language: en' \
--header 'content-type: application/json' \
--data '
{
"value": "surf,boat,sea"
}'
⚠️ The values inserted are only available in English because I used the header content-language with the value "en".
Third example - Update 1 medatadata field with constraint values in a different language
I want to update the field dropdown_list on my media with a french value.
To know the type of my field, I do a GET request on its kpk:field link.
curl --request GET \
--url https://{{KeepeekInstance}}/api/dam/forms/1/fields/388 \
--header 'authorization: Basic baseEncodedLoginPassword'
I receive:
{
"id": "dropdown_list",
"title": "Dropdown list",
"description": "",
"type": "SIMPLE_LIST",
"mandatory": false,
"indexed": true,
"indexSuggest": true,
"forceSelection": false,
"summary": false,
"publicDisplay": true,
"portalDisplay": true,
"visible": true,
"editable": true,
"_links": {
"self": {
"href": "https://{{KeepeekInstance}}/api/dam/forms/1/fields/388"
},
"curies": [
{
"name": "kpk",
"href": "https://{{KeepeekInstance}}/api/doc/rels/{rel}",
"templated": true
}
],
"kpk:lookup": {
"href": "https://{{KeepeekInstance}}/api/dam/forms/lookups/22"
}
}
}
Here, I can see two importants informations, first, it's a type SIMPLE_LIST (aka Dropdown list), second, we have a link to find the available values for that list, the kpk:lookup link.
Let's do a GET request on this link with an accept-language header set to FR to get the french values:
curl --request GET \
--url https://{{KeepeekInstance}}/api/dam/forms/lookups/22 \
--header 'accept-language: FR' \
--header 'authorization: Basic baseEncodedLoginPassword'
We receive:
{
"id": 22,
"title": "default_name.lookup",
"updatable": true,
"_links": {
"self": {
"href": "https://{{KeepeekInstance}}/api/dam/forms/lookups/22"
},
"curies": [
{
"name": "kpk",
"href": "https://{{KeepeekInstance}}/api/doc/rels/{rel}",
"templated": true
}
]
},
"_embedded": {
"value": [
{
"value": "1",
"label": "Valeur sélectionnée"
},
{
"value": "2",
"label": "Valeur 1"
},
{
"value": "3",
"label": "Valeur 2"
},
{
"value": "4",
"label": "Valeur 3"
}
]
}
}
We find out that we can use the values "Valeur sélectionnée", "Valeur 1", "Valeur 2", "Valeur 3".
(Valeur sélectionnée means Selected value in English)
To update the value on my media, send PUT request (note the content-language header):
curl --request PUT \
--url hhttps://{{KeepeekInstance}}/api/dam/medias/8857/metadatas/dropdown_list \
--header 'authorization: Basic baseEncodedLoginPassword' \
--header 'content-language: fr' \
--header 'content-type: application/json' \
--data '
{
"value": "Valeur 3"
}
'