Skip to main content
GET
/
projects
/
{project_id}
/
ads
List
curl --request GET \
  --url https://api.beyondwords.io/v1/projects/{project_id}/ads \
  --header 'X-Api-Key: <api-key>'
[
  {
    "id": 1,
    "type": "custom",
    "enabled": true,
    "placement": "pre-roll",
    "vast_url": null,
    "title": "My first ad",
    "click_through_url": "https://example.com",
    "image_url": "https://example.com/image.png",
    "media_url": "https://example.com/advert.mp3",
    "media": [
      {
        "id": 123,
        "content_type": "audio/mpeg",
        "url": "https://example.com/transcoded.mp3",
        "duration": 15000
      },
      {
        "id": 124,
        "content_type": "application/vnd.apple.mpegurl",
        "url": "https://example.com/transcoded.m3u8",
        "duration": 15000
      }
    ],
    "theme": null,
    "dark_theme": null,
    "light_theme": null,
    "video_theme": null,
    "time_range": {
      "start": "2023-12-01 00:00:00 UTC",
      "end": "2023-12-31 23:59:59 UTC"
    },
    "created": "2023-01-01 00:00:00 UTC",
    "updated": "2023-01-01 00:00:05 UTC"
  },
  {
    "id": 2,
    "type": "vast",
    "enabled": true,
    "placement": "pre-roll",
    "vast_url": "https://example.com/vast.xml",
    "title": "My second ad",
    "click_through_url": null,
    "media_url": null,
    "media": [],
    "theme": "auto",
    "dark_theme": null,
    "light_theme": null,
    "video_theme": null,
    "time_range": null,
    "created": "2023-01-01 00:00:00 UTC",
    "updated": "2023-01-01 00:00:05 UTC"
  }
]

Authorizations

​
X-Api-Key
string
header
required

Path Parameters

​
project_id
string
required

The numeric ID of your project

Query Parameters

​
pagination[limit]
integer

'limit' sets the number of results to return in each page.

​
pagination[offset]
integer

'offset' sets the first position to return from the results of the query. The default is 0, which starts the page at the first result.

​
filter[title]
string

filter by title

Response

OK

​
id
integer

Unique identifier for the object

​
type
enum<string>

The type of ad, either custom or vast. Ads of type custom must have title, url and media fields. Ads of type vast must have title and vast_url fields.

Available options:
custom,
vast
​
enabled
boolean

Whether the ad will play in the BeyondWords player

​
placement
enum<string>

Whether the ad should play before/during/after the audio content. Possible values are pre-roll, mid-roll, or post-roll

Available options:
pre-roll,
mid-roll,
post-roll
​
vast_url
string<uri> | null

A VAST-compliant URL that contains the ads to be played

Maximum length: 2048
​
title
string | null

The title of the ad

​
click_through_url
string<uri> | null

The click-through URL of the custom ad to show in the player

Maximum length: 2048
​
image_url
string<uri> | null

The image URL to show in the player while the ad is playing

Maximum length: 2048
​
media_url
string<uri> | null

The URL of the media file of the custom ad to play in the player

Maximum length: 2048
​
audio_url
string<uri> | null

The URL of the audio file of the custom ad to play in the player

Maximum length: 2048
​
video_url
string<uri> | null

The URL of the video file of the custom ad to play in the player

Maximum length: 2048
​
media
object[]

The transcoded media of the custom ad to play in the player This is read-only and generated automatically from the media_url.

​
audio
object[]

The transcoded media of the custom ad to play in the player This is read-only and generated automatically from the media_url.

​
video
object[]

The array of video files.

​
theme
enum<string> | null

The color theme to use for the ad when it is playing. Possible values are auto, dark, light. The auto theme is based on the user's light/dark mode system preference.

Available options:
auto,
dark,
light
​
dark_theme
object | null

The dark theme colors

​
light_theme
object | null

The light theme colors

​
video_theme
object | null

The video theme colors

​
time_range
object | null

The time range for when the ad should play in the player

​
created
string

Time at which the object was created (ISO 8601)

​
updated
string

Time at which the object was updated (ISO 8601)