Media

The media library holds the files your campaigns use: artwork, sounds, animations and videos. Most teams upload in the dashboard (see Media library). Use the API when you want to load files from your own systems, for example a product catalogue.

The media library needs the Media library feature on your plan.

Supported files

Kind	Types	Largest file
Images	PNG, JPEG, WebP, GIF	8 MB
Sounds	MP3, OGG, WAV	16 MB
Animations	Lottie JSON	2 MB
Videos	MP4, WebM	50 MB

Keliplay checks each file’s contents after upload, so a file whose contents do not match its type is refused. Your plan sets the total storage for your organisation.

Upload a file

Uploading takes three requests. The file goes straight to storage, not through the API.

1. Ask for an upload.

   curl -X POST https://api.keliplay.com/v1/tenant/assets/presign \
     -H "Authorization: Bearer $KELIPLAY_API_KEY" \
     -H "Content-Type: application/json" \
     -d '{
       "filename": "spring-banner.png",
       "contentType": "image/png",
       "sizeBytes": 482113
     }'

   {
     "upload": {
       "url": "https://uploads.example-storage.com/",
       "fields": { "key": "...", "policy": "...", "signature": "..." }
     },
     "asset": {
       "id": "0199f0e2-1a2b-7c3d-8e4f-5a6b7c8d9e0f",
       "filename": "spring-banner.png",
       "contentType": "image/png",
       "url": "https://cdn.example.com/.../spring-banner.png",
       "folderId": null,
       "confirmedAt": null
     }
   }

   Add folderId to put the file in a folder. sizeBytes is optional, but lets the request fail early if the file would take you over your storage allowance.

2. Upload the file.

   Send a multipart/form-data POST to upload.url. Include every entry in upload.fields as a form field, exactly as given, and put the file last in a field called file.

   curl -X POST "$UPLOAD_URL" \
     -F "key=..." \
     -F "policy=..." \
     -F "signature=..." \
     -F "file=@spring-banner.png"

   The upload address is valid for a short time. If it expires, ask for a new one.

3. Confirm it.

   curl -X POST https://api.keliplay.com/v1/tenant/assets/$ASSET_ID/confirm \
     -H "Authorization: Bearer $KELIPLAY_API_KEY"

   Keliplay checks the file and adds it to the library. The response is the asset with confirmedAt set. Until you confirm, the file does not appear in the library and cannot be used.

Use the asset’s url wherever a campaign or branding setting takes a file.

Import from a web address

Instead of uploading, you can give Keliplay a public https address to fetch the file from. Imports work for images and sounds. Videos must be uploaded.

curl -X POST https://api.keliplay.com/v1/tenant/assets/import \
  -H "Authorization: Bearer $KELIPLAY_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "url": "https://www.example.com/images/spring-banner.png" }'

The response is 202 with the new asset, whose importStatus is pending. The file is fetched in the background. Check on it with:

curl "https://api.keliplay.com/v1/tenant/assets/imports?ids=$ASSET_ID" \
  -H "Authorization: Bearer $KELIPLAY_API_KEY"

importStatus becomes done when the file is in the library, or failed with an importError explaining why, such as the address not returning an image. Imports are limited to 10 a minute and 200 an hour.

List files

curl "https://api.keliplay.com/v1/tenant/assets?type=video&limit=50" \
  -H "Authorization: Bearer $KELIPLAY_API_KEY"

Filter with type, folderId (or unfiled for files in no folder) and search. With folderId, add recursive=true to include files in folders inside it. The list is paged; see pagination.

Folders

Create folders with POST /v1/tenant/asset-folders, giving a name and an optional parentId to nest it. Move files with POST /v1/tenant/assets/move, sending up to 200 assetIds and the folderId to move them to (null for no folder). Rename a file or move a single one with PATCH /v1/tenant/assets/{id}.

Deleting a folder that still holds files or folders asks you to confirm first: the response is 409 with the number of files and folders affected. Send the request again with ?confirm=true to go ahead.

Delete a file

curl -X DELETE https://api.keliplay.com/v1/tenant/assets/$ASSET_ID \
  -H "Authorization: Bearer $KELIPLAY_API_KEY"

Deleting is permanent. A campaign that still uses the file will show a blank in its place, so check first with GET /v1/tenant/assets/usage, which lists where each of your files is used.

See the API reference for every field.