Keepeek API

Authentication

Credentials S4

1. An administrator creates a regular Keepeek user for the integration: Settings → Users → Create a user. There is no separate "API key" object; the API user is a normal user whose group rights bound what the integration can see and do S4 S48.
2. Check it with GEThttps://{tenant}.keepeek.com/api/dam and Authorization: Basic base64(login:password) — 200 means OK S4. Without credentials /api/dam returns 401 {"code":"security-notAuthorized"} S41.

JWT ("OAuth 2 / Token JWT") S5 S6

This is a self-issued, shared-secret JWT scheme, not an OAuth authorization server flow: there is no token endpoint, no authorization code and no refresh token in the API documentation S6.

Identity provider (UI login, Keepicker) — each instance publishes GET/api/public/iam-configuration pointing to a Keycloak realm on auth.keepeek.com (OIDC discovery + SAML IdP descriptor), and GET/api/public/sso-configuration (ssoEnabled, googleOAuthEnabled) S41 S42. The Keepicker component authenticates through a Keycloak client (keycloak-client-id, optional keycloak-idp for an SSO button) S43. Whether third-party back-ends may call /api/dam with Keycloak-issued access tokens is Unknown Unverified (not documented; the realm's discovery document lists generic Keycloak grants that say nothing about API acceptance).

Access-control errors specific to UIs S9: 401 error.account.to_be_validated, user-need-registration-{hash} (points to a registration form), user-access-forbidden-for-ui.

Core resources

Paths relative to https://{tenant}.keepeek.com. The spec has 266 paths / 378 operations (227 GET, 65 POST, 60 DELETE, 26 PUT) S2. Keepeek asks clients to follow _links rather than build URIs, as URI layout may change S11. Minimum release per feature from the API guide S3.

Not exposed in the documented API: webhooks/event subscriptions, metadata-schema writes (forms and fields are read-only), rights configuration (folder ACLs, ABAC rules, statuses definitions), workflow template/step actions, SSO/IP-filtering settings S2.

Data model

• Media: integer id; top-level technical properties (title, status, statusUpdateDate, permission, downloadLevel, width, height, resolution, orientation, mediaType (MIME), fileSize, totalSize, originalFileName, creationDate, updateDate, importDate, trashDate, duration, pageCount, colorSpace, latitude/longitude/address, duplicationStatus, thumbnailGenerationStatus, statViews, statDownloads, checkSums{md5,crc32}, formType, pointOfInterest, fileVersionCount…) S2.
• Enumerations S2: status ∈ IMPORT, BASKET, DRAFT, PUBLISHED, ARCHIVED, TRASH (plus instance-defined custom statuses); permission ∈ READ, WRITE, PUBLISH, DELETE, ADMIN; downloadLevel ∈ NONE, BD (low def), HD; formType ∈ PICTURE, DOCUMENT, VIDEO, SOUND, RICH_MEDIA, OTHER.
• Metadata: _embedded.metadata[] items {id, name, value, _links.kpk:field}; id is the field's internal name (e.g. title, legend); empty fields omitted unless embedAllMetadata=true S13 S20. Localized fields are addressed with a locale suffix in search (e.g. title.FR) S19; content language negotiated with Accept-Language / returned in Content-Language; writes target languages via Content-Language S15 S23.
• Forms ("fiches"): each media has a metadata form (metamodel); field types TEXT, TEXT_AREA, HTML, HTML_AREA, DATE, DATETIME, NUMBER, EMAIL, URL, CHECK_BOX, SIMPLE_LIST, MULTIPLE_LIST, PERSON_LIST, THESAURUS, GEO, FIELD_SET; field flags mandatory, indexed, indexSuggest, forceSelection, editable, visible S2 S13 S23.
• Taxonomy: hierarchical, multilingual thesauri attached to "microthesaurus" fields; nodes have numeric ids S16 S36. Folder tree (classification plan) with numeric folder ids; a media can be in several folders S11 S13. Labels, basket tags and statuses complete the taxonomy S2.
• HAL conventions: CURIE prefix kpk (/api/doc/rels/{rel}); single embedded items are returned as an object unless forceArrays=true (4.20.0+) S11 S14.
• Ephemeral resources: uploaded files, selections, exports, bulk jobs and API-created advanced searches expire and may be purged — do not persist their URIs S21 S19 S24 S32.

Search & querying

S16 unless noted.

Uploads & binaries

Upload flow S4 S21 S22

1. POST/api/dam/files with the raw bytes as body and headers Content-Type, Content-Length, and X-KPK-FileName (ISO-8859-1) or X-KPK-Base64FileName (recommended) → 201 + temporary file descriptor (id, expirationDate, _links.self).
2. Large files: POST/api/dam/files with Content-Length: 0, X-KPK-Upload-Content-Type, X-KPK-Upload-Content-Length; then PUT chunks to the descriptor with Content-Range (202 per chunk, 200 on the last; nextExpectedRanges in the body; 416 on a bad range; GET the descriptor to resume, 4.31.0+).
3. Create the media: POST/api/dam/folders/{folderId}/medias (4.16.0+) or POST/api/dam/medias with {"_links":{"from":{"href":"…/api/dam/files/{id}"}}}, optionally a kpk:form link → 201 + Location S20.

Downloads & renditions

• Thumbnail relations on each media: kpk:medium (112 px), kpk:large (224 px), kpk:xlarge (448 px), preview (607 px), kpk:whr (web hi-res, 1200 px) — default sizes, configurable S27.
• Permalinks (/medias/{id}/permalinks) are generated at import for configured formats S2 S59.
• Express download: GET/download-express?mid={id}&mid={id} (Basic or JWT) — one id returns the file, several return a ZIP S26.
• Formatted exports: selection → POST…/exports with per-media-type kpk:*-export-format links; acceptTermsOfUse required S32 S39. Asynchronous download requests (/api/dam/download-requests, status PROCESSING/SUCCESS/ERROR, target ZIP URL; also contact sheets, 4.68.0+) S25 S2.
• Dynamic resizing service "Dynameek" (URLs of the form kpk://dynameek-kpk/{size}/… returned by Keepicker) S43 S67; its public URL grammar is Not public.

Events & webhooks

• No webhook or event-subscription mechanism is documented in the API guide or present in the Swagger spec S2 S3.
• Webhook-style notifications can be implemented with custom scripts on the instance (project-specific, not a self-service API feature) S115.
• The only notification resource is PUT/api/public/notifications/{email} to disable e-mail notifications S35.
• Integration alternatives: poll search/media on updateDate ranges S16; server-side scripts that can be triggered by API (/api/dam/script-runs) S34; statistics hit search (/api/stat/search/hit, max 1,000,000 results, ≤ 10 parallel searches) S33. Keepeek also sells custom "synchronization scripts" as integration services S88.

Limits & quirks

SDKs, tools & code samples

Changelog of the API

Release dates for 4.x versions are Not public (no public release-notes archive beyond S40).