Skip to main content
POST
/
projects
/
{project_id}
/
ads
curl --request POST \
  --url https://api.beyondwords.io/v1/projects/{project_id}/ads \
  --header 'Content-Type: application/json' \
  --header 'X-Api-Key: <api-key>' \
  --data '{
  "type": "custom",
  "enabled": true,
  "placement": "pre-roll",
  "vast_url": null,
  "title": "My Ad",
  "click_through_url": "https://example.com",
  "image_url": "https://example.com/image.png",
  "media_url": "https://example.com/advert.mp3",
  "theme": "dark",
  "dark_theme": {
    "text_color": "#fff",
    "background_color": "#333",
    "icon_color": "#ff0"
  },
  "light_theme": null,
  "time_range": {
    "start": "2023-12-01 00:00:00 UTC",
    "end": "2023-12-31 23:59:59 UTC"
  }
}'
{
  "id": 1,
  "type": "custom",
  "enabled": true,
  "placement": "pre-roll",
  "vast_url": null,
  "title": "My advert title",
  "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": "dark",
  "dark_theme": {
    "text_color": "#fff",
    "background_color": "#333",
    "icon_color": "#ff0"
  },
  "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"
}

Authorizations

​
X-Api-Key
string
header
required

Path Parameters

​
project_id
string
required

The numeric ID of your project

Body

application/json
  • Custom ad
  • Vast ad

Create ad with custom type

​
type
enum<string>
default:custom

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
​
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
​
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
​
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
​
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

Response

201 - application/json

successful

​
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)