Media
5 endpointsImages, video and audio in the workspace's media library. Upload a file here, then give its id as a notification's media_asset_id. Which kinds you can upload depends on the plan.
List media#
/mediaNewest first.
Query parameters
An opaque value from a previous page's meta.next_cursor. Omit for the first page.
How many to return, up to 100.
20Only image, video or audio.
Responses
200
{
"data": [
{
"id": "0192f0a4-6b1e-7c3a-9d2f-5e8b1a4d7001",
"name": "flat-white.jpg",
"type": "image",
"mime_type": "image/jpeg",
"size_bytes": 248113,
"width": 1200,
"height": 800,
"duration_seconds": null,
"source": "upload",
"url": "https://media.bubbl.tech/media/0192f0a4-6b1e-7c3a-9d2f-5e8b1a4d0001/3f1c9e2a-7b4d-4e8f-a1c2-5d6e7f8a9b0c/flat-white.jpg",
"thumbnail_url": "https://media.bubbl.tech/media/0192f0a4-6b1e-7c3a-9d2f-5e8b1a4d0001/3f1c9e2a-7b4d-4e8f-a1c2-5d6e7f8a9b0c/thumb.jpg",
"created_at": "2026-09-20T09:12:00+00:00",
"updated_at": "2026-09-20T09:12:00+00:00"
}
],
"meta": {
"next_cursor": null
}
}Response fields
401The token is missing, unknown, revoked or expired.
missing_tokeninvalid_tokentoken_revokedtoken_expired
missing_tokenMissing bearer token.
invalid_tokenUnknown API token. Check it was copied in full, and that it is for this environment.
token_revokedThe token "Zapier" was revoked on 2026-10-06 at 18:27 UTC. Issue a new one from Configuration › Platform API.
token_expiredThis token has expired. Issue a new one from Configuration › Platform API.
{
"error": {
"code": "missing_token",
"message": "Missing bearer token."
}
}403The token or workspace can't do this.
missing_abilityplatform_api_not_enabledwrong_environmentworkspace_pausedsandbox_unavailable
missing_abilityThis token doesn't have the campaigns:write scope.
platform_api_not_enabledThe full Platform API isn't enabled for this workspace yet. Contact customer services to turn it on.
wrong_environmentThis is a Sandbox token: use the Sandbox API address. https://api.sandbox.bubbl.tech/platform/v1
workspace_pausedThis workspace is scheduled for deletion; its API access is paused.
sandbox_unavailableThe Sandbox isn't available for this workspace.
{
"error": {
"code": "missing_ability",
"message": "This token doesn't have the campaigns:write scope."
}
}422Something in the request isn't valid. fields says what, with the dashboard's wording.
invalid_parameterinvalid_cursor
fields says what, with the dashboard's wording.invalid_parameterupdated_since must be a valid date.
invalid_cursorThat cursor is invalid or has expired.
{
"error": {
"code": "invalid_parameter",
"message": "updated_since must be a valid date.",
"fields": {
"updated_since": [
"Must be a valid date."
]
}
}
}429Too many requests. Wait for the number of seconds in Retry-After.
rate_limitedtoo_many_failed_attempts
Retry-After.rate_limitedToo many requests. Slow down and try again shortly.
too_many_failed_attemptsToo many failed attempts. Try again shortly.
{
"error": {
"code": "rate_limited",
"message": "Too many requests. Slow down and try again shortly."
}
}curl 'https://api.bubbl.tech/platform/v1/media?limit=20' \
-H 'Authorization: Bearer bubbl_YOUR_TOKEN' \
-H 'Accept: application/json'const response = await fetch('https://api.bubbl.tech/platform/v1/media?limit=20', {
method: 'GET',
headers: {
Authorization: 'Bearer bubbl_YOUR_TOKEN',
Accept: 'application/json',
},
});
const data = await response.json();import requests
response = requests.request(
'GET',
'https://api.bubbl.tech/platform/v1/media?limit=20',
headers={
'Authorization': 'Bearer bubbl_YOUR_TOKEN',
'Accept': 'application/json',
},
)
response.raise_for_status()
data = response.json()<?php
$client = new \GuzzleHttp\Client();
$response = $client->request('GET', 'https://api.bubbl.tech/platform/v1/media?limit=20', [
'headers' => [
'Authorization' => 'Bearer bubbl_YOUR_TOKEN',
'Accept' => 'application/json',
],
]);
$data = json_decode((string) $response->getBody(), true);Upload a media file#
/mediaA multipart/form-data request with the file (up to 50 MB: a JPEG, PNG, GIF or WebP image, an MP4, MOV or WebM video, or an MP3, M4A, WAV or OGG audio file) and an optional name (the file's own name otherwise). An image's thumbnail is made a few seconds later. A Sandbox holds a limited amount of media in total.
A file over about 700 KB should not be sent in this request: ask for a signed upload first (POST /media/uploads), post the file to S3 with it, and send its token here as file_staged instead of file (with the optional name). Sending the file in this request still works for a smaller one, unchanged for anyone who already does.
Headers
A unique value (e.g. a UUID) for this change. A retry with the same key within 24 hours gets the first response back, with Idempotent-Replayed: true, instead of making the change again.
Request body
multipart/form-dataStoreMediaAssetRequestThe token of a file posted to S3 with a signed upload (POST /media/uploads): send it instead of file for a file over about 700 KB.
Responses
201
{
"data": {
"id": "0192f0a4-6b1e-7c3a-9d2f-5e8b1a4d7001",
"name": "flat-white.jpg",
"type": "image",
"mime_type": "image/jpeg",
"size_bytes": 248113,
"width": 1200,
"height": 800,
"duration_seconds": null,
"source": "upload",
"url": "https://media.bubbl.tech/media/0192f0a4-6b1e-7c3a-9d2f-5e8b1a4d0001/3f1c9e2a-7b4d-4e8f-a1c2-5d6e7f8a9b0c/flat-white.jpg",
"thumbnail_url": "https://media.bubbl.tech/media/0192f0a4-6b1e-7c3a-9d2f-5e8b1a4d0001/3f1c9e2a-7b4d-4e8f-a1c2-5d6e7f8a9b0c/thumb.jpg",
"created_at": "2026-09-20T09:12:00+00:00",
"updated_at": "2026-09-20T09:12:00+00:00"
}
}Response fields
401The token is missing, unknown, revoked or expired.
missing_tokeninvalid_tokentoken_revokedtoken_expired
missing_tokenMissing bearer token.
invalid_tokenUnknown API token. Check it was copied in full, and that it is for this environment.
token_revokedThe token "Zapier" was revoked on 2026-10-06 at 18:27 UTC. Issue a new one from Configuration › Platform API.
token_expiredThis token has expired. Issue a new one from Configuration › Platform API.
{
"error": {
"code": "missing_token",
"message": "Missing bearer token."
}
}403The token or workspace can't do this.
missing_abilityplatform_api_not_enabledwrong_environmentworkspace_pausedsandbox_unavailable
missing_abilityThis token doesn't have the campaigns:write scope.
platform_api_not_enabledThe full Platform API isn't enabled for this workspace yet. Contact customer services to turn it on.
wrong_environmentThis is a Sandbox token: use the Sandbox API address. https://api.sandbox.bubbl.tech/platform/v1
workspace_pausedThis workspace is scheduled for deletion; its API access is paused.
sandbox_unavailableThe Sandbox isn't available for this workspace.
{
"error": {
"code": "missing_ability",
"message": "This token doesn't have the campaigns:write scope."
}
}409A request with the same Idempotency-Key is still running (retry after Retry-After seconds), or the change conflicts with something that depends on it.
request_in_progress
Idempotency-Key is still running (retry after Retry-After seconds), or the change conflicts with something that depends on it.request_in_progressThis request is still being handled. Try again shortly.
{
"error": {
"code": "request_in_progress",
"message": "This request is still being handled. Try again shortly."
}
}422Something in the request isn't valid. fields says what, with the dashboard's wording.
validation_failed
fields says what, with the dashboard's wording.validation_failedThe given data was invalid.
{
"error": {
"code": "validation_failed",
"message": "The given data was invalid.",
"fields": {
"name": [
"The name field is required."
]
}
}
}429Too many requests. Wait for the number of seconds in Retry-After.
rate_limitedtoo_many_failed_attempts
Retry-After.rate_limitedToo many requests. Slow down and try again shortly.
too_many_failed_attemptsToo many failed attempts. Try again shortly.
{
"error": {
"code": "rate_limited",
"message": "Too many requests. Slow down and try again shortly."
}
}curl -X POST 'https://api.bubbl.tech/platform/v1/media' \
-H 'Authorization: Bearer bubbl_YOUR_TOKEN' \
-H 'Accept: application/json' \
-H 'Content-Type: multipart/form-data' \
--data '[object Object]'const response = await fetch('https://api.bubbl.tech/platform/v1/media', {
method: 'POST',
headers: {
Authorization: 'Bearer bubbl_YOUR_TOKEN',
Accept: 'application/json',
'Content-Type': 'multipart/form-data',
},
body: '[object Object]',
});
const data = await response.json();import requests
response = requests.request(
'POST',
'https://api.bubbl.tech/platform/v1/media',
headers={
'Authorization': 'Bearer bubbl_YOUR_TOKEN',
'Accept': 'application/json',
'Content-Type': 'multipart/form-data',
},
data='[object Object]',
)
response.raise_for_status()
data = response.json()<?php
$client = new \GuzzleHttp\Client();
$response = $client->request('POST', 'https://api.bubbl.tech/platform/v1/media', [
'headers' => [
'Authorization' => 'Bearer bubbl_YOUR_TOKEN',
'Accept' => 'application/json',
'Content-Type' => 'multipart/form-data',
],
'body' => '[object Object]',
]);
$data = json_decode((string) $response->getBody(), true);Get a media file#
/media/{media}Path parameters
The media ID
Responses
200
{
"data": {
"id": "0192f0a4-6b1e-7c3a-9d2f-5e8b1a4d7001",
"name": "flat-white.jpg",
"type": "image",
"mime_type": "image/jpeg",
"size_bytes": 248113,
"width": 1200,
"height": 800,
"duration_seconds": null,
"source": "upload",
"url": "https://media.bubbl.tech/media/0192f0a4-6b1e-7c3a-9d2f-5e8b1a4d0001/3f1c9e2a-7b4d-4e8f-a1c2-5d6e7f8a9b0c/flat-white.jpg",
"thumbnail_url": "https://media.bubbl.tech/media/0192f0a4-6b1e-7c3a-9d2f-5e8b1a4d0001/3f1c9e2a-7b4d-4e8f-a1c2-5d6e7f8a9b0c/thumb.jpg",
"created_at": "2026-09-20T09:12:00+00:00",
"updated_at": "2026-09-20T09:12:00+00:00"
}
}Response fields
401The token is missing, unknown, revoked or expired.
missing_tokeninvalid_tokentoken_revokedtoken_expired
missing_tokenMissing bearer token.
invalid_tokenUnknown API token. Check it was copied in full, and that it is for this environment.
token_revokedThe token "Zapier" was revoked on 2026-10-06 at 18:27 UTC. Issue a new one from Configuration › Platform API.
token_expiredThis token has expired. Issue a new one from Configuration › Platform API.
{
"error": {
"code": "missing_token",
"message": "Missing bearer token."
}
}403The token or workspace can't do this.
missing_abilityplatform_api_not_enabledwrong_environmentworkspace_pausedsandbox_unavailable
missing_abilityThis token doesn't have the campaigns:write scope.
platform_api_not_enabledThe full Platform API isn't enabled for this workspace yet. Contact customer services to turn it on.
wrong_environmentThis is a Sandbox token: use the Sandbox API address. https://api.sandbox.bubbl.tech/platform/v1
workspace_pausedThis workspace is scheduled for deletion; its API access is paused.
sandbox_unavailableThe Sandbox isn't available for this workspace.
{
"error": {
"code": "missing_ability",
"message": "This token doesn't have the campaigns:write scope."
}
}404Nothing with that ID in this workspace.
not_found
not_foundNo such resource in this workspace.
{
"error": {
"code": "not_found",
"message": "No such resource in this workspace."
}
}429Too many requests. Wait for the number of seconds in Retry-After.
rate_limitedtoo_many_failed_attempts
Retry-After.rate_limitedToo many requests. Slow down and try again shortly.
too_many_failed_attemptsToo many failed attempts. Try again shortly.
{
"error": {
"code": "rate_limited",
"message": "Too many requests. Slow down and try again shortly."
}
}curl 'https://api.bubbl.tech/platform/v1/media/{media}' \
-H 'Authorization: Bearer bubbl_YOUR_TOKEN' \
-H 'Accept: application/json'const response = await fetch('https://api.bubbl.tech/platform/v1/media/{media}', {
method: 'GET',
headers: {
Authorization: 'Bearer bubbl_YOUR_TOKEN',
Accept: 'application/json',
},
});
const data = await response.json();import requests
response = requests.request(
'GET',
'https://api.bubbl.tech/platform/v1/media/{media}',
headers={
'Authorization': 'Bearer bubbl_YOUR_TOKEN',
'Accept': 'application/json',
},
)
response.raise_for_status()
data = response.json()<?php
$client = new \GuzzleHttp\Client();
$response = $client->request('GET', 'https://api.bubbl.tech/platform/v1/media/{media}', [
'headers' => [
'Authorization' => 'Bearer bubbl_YOUR_TOKEN',
'Accept' => 'application/json',
],
]);
$data = json_decode((string) $response->getBody(), true);Delete a media file#
/media/{media}Refused (409 media_in_use) while a notification uses it: change those notifications' media_asset_id first.
Path parameters
The media ID
Headers
A unique value (e.g. a UUID) for this change. A retry with the same key within 24 hours gets the first response back, with Idempotent-Replayed: true, instead of making the change again.
Responses
200
{
"data": {
"id": "0192f0a4-6b1e-7c3a-9d2f-5e8b1a4d7001",
"deleted": true
}
}Response fields
401The token is missing, unknown, revoked or expired.
missing_tokeninvalid_tokentoken_revokedtoken_expired
missing_tokenMissing bearer token.
invalid_tokenUnknown API token. Check it was copied in full, and that it is for this environment.
token_revokedThe token "Zapier" was revoked on 2026-10-06 at 18:27 UTC. Issue a new one from Configuration › Platform API.
token_expiredThis token has expired. Issue a new one from Configuration › Platform API.
{
"error": {
"code": "missing_token",
"message": "Missing bearer token."
}
}403The token or workspace can't do this.
missing_abilityplatform_api_not_enabledwrong_environmentworkspace_pausedsandbox_unavailable
missing_abilityThis token doesn't have the campaigns:write scope.
platform_api_not_enabledThe full Platform API isn't enabled for this workspace yet. Contact customer services to turn it on.
wrong_environmentThis is a Sandbox token: use the Sandbox API address. https://api.sandbox.bubbl.tech/platform/v1
workspace_pausedThis workspace is scheduled for deletion; its API access is paused.
sandbox_unavailableThe Sandbox isn't available for this workspace.
{
"error": {
"code": "missing_ability",
"message": "This token doesn't have the campaigns:write scope."
}
}404Nothing with that ID in this workspace.
not_found
not_foundNo such resource in this workspace.
{
"error": {
"code": "not_found",
"message": "No such resource in this workspace."
}
}409A request with the same Idempotency-Key is still running (retry after Retry-After seconds), or the change conflicts with something that depends on it.
request_in_progressmedia_in_use
Idempotency-Key is still running (retry after Retry-After seconds), or the change conflicts with something that depends on it.request_in_progressThis request is still being handled. Try again shortly.
media_in_useNotifications use this file; change their media first: 0199a3b2-5c1e-7f42-9d10-3e8b2a6c4f01.
{
"error": {
"code": "request_in_progress",
"message": "This request is still being handled. Try again shortly."
}
}429Too many requests. Wait for the number of seconds in Retry-After.
rate_limitedtoo_many_failed_attempts
Retry-After.rate_limitedToo many requests. Slow down and try again shortly.
too_many_failed_attemptsToo many failed attempts. Try again shortly.
{
"error": {
"code": "rate_limited",
"message": "Too many requests. Slow down and try again shortly."
}
}curl -X DELETE 'https://api.bubbl.tech/platform/v1/media/{media}' \
-H 'Authorization: Bearer bubbl_YOUR_TOKEN' \
-H 'Accept: application/json'const response = await fetch('https://api.bubbl.tech/platform/v1/media/{media}', {
method: 'DELETE',
headers: {
Authorization: 'Bearer bubbl_YOUR_TOKEN',
Accept: 'application/json',
},
});
const data = await response.json();import requests
response = requests.request(
'DELETE',
'https://api.bubbl.tech/platform/v1/media/{media}',
headers={
'Authorization': 'Bearer bubbl_YOUR_TOKEN',
'Accept': 'application/json',
},
)
response.raise_for_status()
data = response.json()<?php
$client = new \GuzzleHttp\Client();
$response = $client->request('DELETE', 'https://api.bubbl.tech/platform/v1/media/{media}', [
'headers' => [
'Authorization' => 'Bearer bubbl_YOUR_TOKEN',
'Accept' => 'application/json',
],
]);
$data = json_decode((string) $response->getBody(), true);Get a signed upload for a large media file#
/media/uploadsFor a file over about 700 KB (a request body can be 1 MB at most). Send filename, size in bytes (up to 50 MB) and optionally content_type. Post the file to the returned url as multipart/form-data with every one of fields first and the file last, in a field named file, within an hour; S3 answers 204. Then create the media file with POST /media, sending the returned token as file_staged and no file. A token works once, for this workspace, and the same limits and plan checks apply as to any upload. Not available (404) unless direct uploads are on for the workspace.
Headers
A unique value (e.g. a UUID) for this change. A retry with the same key within 24 hours gets the first response back, with Idempotent-Replayed: true, instead of making the change again.
Request body
application/jsonobjectrequiredResponses
200
{
"data": {
"url": null,
"fields": [
null
],
"token": "string",
"key": "string",
"expires_at": "string"
}
}Response fields
401The token is missing, unknown, revoked or expired.
missing_tokeninvalid_tokentoken_revokedtoken_expired
missing_tokenMissing bearer token.
invalid_tokenUnknown API token. Check it was copied in full, and that it is for this environment.
token_revokedThe token "Zapier" was revoked on 2026-10-06 at 18:27 UTC. Issue a new one from Configuration › Platform API.
token_expiredThis token has expired. Issue a new one from Configuration › Platform API.
{
"error": {
"code": "missing_token",
"message": "Missing bearer token."
}
}403The token or workspace can't do this.
missing_abilityplatform_api_not_enabledwrong_environmentworkspace_pausedsandbox_unavailable
missing_abilityThis token doesn't have the campaigns:write scope.
platform_api_not_enabledThe full Platform API isn't enabled for this workspace yet. Contact customer services to turn it on.
wrong_environmentThis is a Sandbox token: use the Sandbox API address. https://api.sandbox.bubbl.tech/platform/v1
workspace_pausedThis workspace is scheduled for deletion; its API access is paused.
sandbox_unavailableThe Sandbox isn't available for this workspace.
{
"error": {
"code": "missing_ability",
"message": "This token doesn't have the campaigns:write scope."
}
}409A request with the same Idempotency-Key is still running (retry after Retry-After seconds), or the change conflicts with something that depends on it.
request_in_progress
Idempotency-Key is still running (retry after Retry-After seconds), or the change conflicts with something that depends on it.request_in_progressThis request is still being handled. Try again shortly.
{
"error": {
"code": "request_in_progress",
"message": "This request is still being handled. Try again shortly."
}
}422Validation error
{
"message": "string",
"errors": {}
}429Too many requests. Wait for the number of seconds in Retry-After.
rate_limitedtoo_many_failed_attempts
Retry-After.rate_limitedToo many requests. Slow down and try again shortly.
too_many_failed_attemptsToo many failed attempts. Try again shortly.
{
"error": {
"code": "rate_limited",
"message": "Too many requests. Slow down and try again shortly."
}
}curl -X POST 'https://api.bubbl.tech/platform/v1/media/uploads' \
-H 'Authorization: Bearer bubbl_YOUR_TOKEN' \
-H 'Accept: application/json' \
-H 'Content-Type: application/json' \
--data '{
"filename": "string",
"size": 0,
"content_type": "string"
}'const response = await fetch('https://api.bubbl.tech/platform/v1/media/uploads', {
method: 'POST',
headers: {
Authorization: 'Bearer bubbl_YOUR_TOKEN',
Accept: 'application/json',
'Content-Type': 'application/json',
},
body: JSON.stringify({
filename: 'string',
size: 0,
content_type: 'string',
}),
});
const data = await response.json();import requests
response = requests.request(
'POST',
'https://api.bubbl.tech/platform/v1/media/uploads',
headers={
'Authorization': 'Bearer bubbl_YOUR_TOKEN',
'Accept': 'application/json',
'Content-Type': 'application/json',
},
json={
'filename': 'string',
'size': 0,
'content_type': 'string',
},
)
response.raise_for_status()
data = response.json()<?php
$client = new \GuzzleHttp\Client();
$response = $client->request('POST', 'https://api.bubbl.tech/platform/v1/media/uploads', [
'headers' => [
'Authorization' => 'Bearer bubbl_YOUR_TOKEN',
'Accept' => 'application/json',
'Content-Type' => 'application/json',
],
'json' => [
'filename' => 'string',
'size' => 0,
'content_type' => 'string',
],
]);
$data = json_decode((string) $response->getBody(), true);