Get started: Update medias

Updating the media itself

By updating the media itself, you can update 4 différents informations:

1. Status and sub status (Import, Draft, Published, etc)
2. Annotation (OK, KO, In progress, etc)
3. Orientation (Portrait, Landscape, Square)
4. Duplication status (No duplicates, Duplicate found, Duplicates Acknowledged
5. Point of interest

First, get the media by doing a HTTP GET request on the path /api/dam/medias/{{mediaId}}.

curl --request GET \
--url https://{{KeepeekInstance}}/api/dam/medias/{{mediaId}} \
--header 'authorization: Basic baseEncodedLoginPassword'

You should receive a response that looks like (information in bold are informations you can update):

{
  "id": 8857,
  "title": "882-1-147z",
  "status": "DRAFT",
  "statusUpdateDate": "2025-01-16T13:58:41.000Z",
  "permission": "ADMIN",
  "downloadLevel": "HD",
  "annotation": "NONE",
  "width": 4080,
  "height": 3060,
  "resolution": 72,
  "orientation": "LANDSCAPE",
  "mediaType": "image/jpeg",
  "fileSize": 2973754,
  "totalSize": 0,
  "fileSizeString": "3 Mo",
  "totalSizeString": "0 o",
  "originalFileName": "882-1-147z.jpg",
  "creationDate": "2025-01-16T13:58:24.000Z",
  "updateDate": "2025-01-16T13:59:03.000Z",
  "importDate": "2025-01-16T13:58:40.000Z",
  "addFolderDate": "2025-01-16T13:58:41.000Z",
  "durationInSeconds": 0,
  "colorSpace": "sRGB",
  "duplicationStatus": "NO_DUPLICATES",
  "thumbnailGenerationStatus": "GENERATED",
  "statViews": 0,
  "statDownloads": 0,
  "checkSums": {
    "md5": "b321f02d805dbcb3accf1a2e807ea224"
  },
  "attachmentCounts": {
    "online": 0,
    "offline": 0,
    "pendingToOnline": 0
  },
  "mediaLinkCount": 0,
  "formType": "PICTURE",
  "pointOfInterest": {
    "x": 65.85,
    "y": 34.93
  },
  "fileVersionCount": 1,
  "_links": {
    ...
    "kpk:custom-status": {
      "href": "https://keepeekInstance/api/dam/medias/custom-statuses/5"
    }
...
  },
  "_embedded": {
    ...
  }
}

To update the information in bold, do a HTTP PUT request on the same path (/api/dam/medias/{{mediaId}}).

The body in the PUT request should be the one you receive in the GET request with your modification.

There are two ways of doing it:

We can conclude that if you have a small amount of datas, it is ok to send the whole json (for testing purpose for example). But if you have a big amount of datas and api calls, it is preferable to send only the necessary informations (ie, the one you want to modify)

Instead of modifying the field one by one, it is more efficient to update everything at ones.

Let's say I want to modify all the available fields, I can send this body:

curl --request PUT \
--url https://keepeekInstance/api/dam/medias/8857 \
--header 'authorization: Basic baseEncodedLoginPassword' \
--header 'content-type: application/json' \
--data '
{
  "status": "PUBLISHED",
  "annotation": "OK",
  "orientation": "SQUARE",
  "duplicationStatus": "DUPLICATES_FOUND",
  "pointOfInterest": {
    "x": 0,
    "y": 50
  },
  "_links": {
    "kpk:custom-status": {
      "href": "https://keepeekInstance/api/dam/medias/custom-statuses/4"
    }
  }
}'

Let's see what we just did :

1. We update the annotation field with "OK" value. Possible annotations value are:
   • • RED
     • ORANGE
     • GREEN
     • PURPLE
     • YELLOW
     • KO
     • OK
     • IN_PROGRESS
     • ATTENTION
     • BOOKMARK
     • TO_REMOVE
     • FLAG
     • TO_RECYCLE
     • REJECTED
     • ACCEPTED
2. We update the orientation field with the value "SQUARE". Possible values for orientation field are:
   • • PORTRAIT
     • LANDSCAPE
     • SQUARE
3. We update the duplicationStatus field.Possible values for duplicationStatus field are:
   • • NO_DUPLICATES
     • DUPLICATES_FOUND
     • DUPLICATES_ACKNOWLEDGED
4. We update the pointOfInterest field.Point of interest x and y positions must be not null and between 0 and 100 (it is a percentage).
5. We update the status and custom statuses.Status and custom status of a media are dependant. Possible status are:
   
   1. • DRAFT
      • PUBLISHED
      • ARCHIVED
   Custom statuses (aka substatus) are status created by users of DAM. To consult all the available substatus, use the path /api/dam/medias/custom-statuses. The rules are:
   1. 1. If status and sub status are not present, we do not change anything
      2. If substatus only is present, we use the substatus and the status in which belong the substatus
      3. If status only is present, we use the status and the first substatus of the status
      4. If substatus and substatus are present and compatible (substatus is a substatus of the status) we use the status and the substatus
      5. If substatus and substatus are present and not compatible, we use the status and the first substatus of the status

Conclusion

To summarize, you should get the informations of the medias via a GET request and then modify the fields you want to modify. It is better than trying to build the object by yourself.

Also, you can update and should update multiple fields at the same time while removing the unnecessary part of the body to optimize your request!

Now you can see how to update the media's metadata!