Getting started
Creation of user and first call
To get started with Keepeek API, you need to have a valid account on a Keepeek instance. If you have admin access to your Keepeek instance, follow the steps below to create an account, if not, ask an admin to do it. To create an account, go to the settings:
Then click on the "Users" menu:
Then click on the "Create a user" button:
Fill in the form with the user's information and click on the "Save" button.
You now have a user you can use to authenticate to the Keepeek API! We are now going to see how to authenticate to the Keepeek API, by using the user we just created on a simple api call. To check if your user is correctly created, you can use the following url with your user's login and password (do not forget to replace apiUrl with your Keepeek instance url):
Or use this curl command (do not forget to replace apiUrl with your Keepeek instance url and login:password with your base64(login:password))
curl --location --globoff '{{apiUrl}}/api/dam' --header 'Authorization: Basic login:password'
If you have a 200 response, your user is correctly created and you can now use it to authenticate to the Keepeek API, congratulations!
Create your first media
Now that you have a working user, you can create your first media on you Keepeek instance ! Please note that this works for media that are less To create this media in Keepeek, we will create a new folder, import the file in Keepeek, then create a media in the folder with the imported file.
- Create the folder Do a POST request on the path
{{apiUrl}}api/dam/folder-tree
Fill your user and password :
Fill the body with the name of your folder
Or use this curl command (do not forget to replace apiUrl, the authorization and the body to fit your configuration):
curl --location --globoff '{{apiUrl}}api/dam/folder-tree' \
--header 'Content-Type: application/json' \
--header 'Authorization: Basic login:password' \
--data '{
"title":"My new folder"
}'
If the folder is successfully created, the API returns a 201 Created status code and a location of your new folder in the location
header.
- Upload the file Upload your file by sending a POST request on the file upload collection. Do not forget to use your login and password
The mandatory headers are :
- Content-Type (automatically fill by postman)
- Content-Length (automatically fill by postman)
- X-KPK-FileName or X-KPK-Base64FileName X-KPK-FileName and X-KPK-Base64FileName are used to defined the filename of you file. If the filename is encoded in ISO-8859-1, you can use X-KPK-FileName, else use X-KPK-Base64FileName, but encode the filename in base64 before sending the request.
Use the body to to put the binary of the file
Or use this curl command (do not forget to replace apiUrl, the authorization, the headers and the file to fit your configuration):
curl --location --globoff '{{apiUrl}}api/dam/files' \
--header 'X-KPK-FileName: test.jpg' \
--header 'Content-Type: image/jpeg' \
--header 'Content-Length: 157' \
--header 'Authorization: Basic Basic login:password' \
--data '@/home/user/images/photo1-eo.jpg'
If the upload is successful, the API returns a 201 Created status code and a file descriptor (in _links.self.href
.
{
"id": "xxxx",
"expirationDate": "2024-09-04T15:15:42.200Z",
"fileName": "test.jpg",
"fileContentType": "image/jpeg",
"size": 157,
"_links": {
"self": {
"href": "{{apiUrl}}api/dam/files/x73esh6e"
}
}
}
- Create the media in the folder First, we will get the folder created in the first step by using the path returned in the location header.
Do a GET request on this path :
Or use this curl command (do not forget to replace apiUrl and the authorization to fit your configuration):
curl --location --globoff '{{apiUrl}}api/dam/folders/589' \
--header 'Authorization: Basic login:password
You will get a response of this form :
{
"id": 589,
"title": "My new folder",
"description": "",
"path": "/My new folder",
"_links": {
"self": {
"href": "{{apiUrl}}api/dam/folders/589"
},
"curies": [
{
"name": "kpk",
"href": "{{apiUrl}}api/doc/rels/{rel}",
"templated": true
}
],
"kpk:medias": {
"href": "{{apiUrl}}api/dam/folders/589/medias"
},
"kpk:folder-tree-node": {
"href": "{{apiUrl}}api/dam/folder-tree/589"
},
"kpk:responsible-users": {
"href": "{{apiUrl}}api/dam/folders/589/responsible-users"
}
}
}
The kpk:medias link is the one we are interested in, it is the link to the medias in the folder. Now we will create the media in the folder by sending a POST request on the kpk:medias link. Change the url to your own needs, and in the body, use the url of the file descriptor returned in the file upload step.
"_links": {
"self": {
"href": "{{apiUrl}}api/dam/files/x73esh6e"
}
}
If the media creation is succesful, you should receive a 201 Created status code and a location of your new media in the location
header.
Congratulations ! You juste uploaded your first media in Keepeek !
Soon, we will see how to search your image using the search ability of the API !
To go further, you can check the other type of connection wich is JWT token connection on the section below. If you want to know more about the Keepeek API, you can check the other sections of this documentation.