/sapi/creative

Contents

Use the /sapi/creative endpoint to manage creatives. Creatives are video or image files intended for use as ads, served through VAST/VPAID or SIMID ad tags. They are a specialised type of mediaclip with usetype: "commercial" and include advertising-specific fields such as event trackers and OMID verification settings.

The /sapi/creative endpoint supports the same operations as /sapi/mediaclip, filtered to commercial content only.

Base URL: https://yourcompanyname.bbvms.com/sapi/creative

All requests must be authenticated. See SAPI Authentication for details. All request bodies must use Content-Type: application/json.

1.0 | Creative Object

1.1 | Example Creative Object

Example creative object

{
   "id": "5812043",
   "type": "MediaClip",
   "mediatype": "video",
   "usetype": "commercial",
   "sourcetype": "on_demand",
   "originalfilename": "summer-campaign-30s.mp4",
   "length": 30,
   "title": "Summer Campaign 30s",
   "description": "30-second product ad for the summer campaign",
   "deeplink": "https://www.example.com/summer",
   "gendeeplink": null,
   "copyright": "",
   "author": "Marketing",
   "status": "published",
   "publicationid": "754",
   "clickableEndscreen": "true",
   "shouldReplay": "false",
   "shouldLoop": "false",
   "eventTrackers": [
      {
         "eventType": "start",
         "url": "https://tracking.example.com/pixel?event=start"
      },
      {
         "eventType": "firstQuartile",
         "url": "https://tracking.example.com/pixel?event=q1"
      },
      {
         "eventType": "midpoint",
         "url": "https://tracking.example.com/pixel?event=q2"
      },
      {
         "eventType": "thirdQuartile",
         "url": "https://tracking.example.com/pixel?event=q3"
      },
      {
         "eventType": "complete",
         "url": "https://tracking.example.com/pixel?event=complete"
      }
   ],
   "omidAdVerifications": [],
   "creativeProjectId": null,
   "createddate": "2025-03-10T09:15:00Z",
   "updateddate": "2025-06-01T11:22:45Z",
   "publisheddate": "2025-03-10T09:15:00Z",
   "views": 18450,
   "width": 1920,
   "height": 1080,
   "dar": "16:9",
   "originalWidth": 1920,
   "originalHeight": 1080,
   "createdBy": "support@bluebillywig.com",
   "updatedBy": "support@bluebillywig.com",
   "src": "/yourcompanyname/media/2025/03/10/5812043.mp4",
   "cat": ["summer", "campaign"],
   "thumbnails": [
      {
         "src": "/yourcompanyname/media/2025/03/10/5812043-1710065800000001.jpg",
         "width": "1920",
         "height": "1080",
         "main": true,
         "crops": {
            "landscape": {
               "x": 0,
               "y": 0,
               "width": 1,
               "height": 1,
               "main": true
            }
         }
      }
   ],
   "assets": [
      {
         "mediatype": "MP4_MAIN",
         "id": "1710065800112233",
         "status": "active",
         "src": "/yourcompanyname/media/2025/03/10/asset-5812043-1710065800001234.mp4",
         "length": "30",
         "exactlength": "30000",
         "width": "1280",
         "height": "720",
         "bandwidth": "2000",
         "mimetype": "video/mp4; codecs=\"avc1.4d481f, mp4a.40.2\""
      }
   ],
   "hasJobs": "false",
   "subtitles": [],
   "timelines": null,
   "audiotracks": null
}

1.2 | Attributes

Editorial fields (read/write)

Property	Type	Description
`title`	string	Creative title. Required.
`description`	string	Creative description.
`deeplink`	string	Click-through URL: the destination page when a viewer clicks the ad.
`copyright`	string	Copyright notice.
`author`	string	Author or creator of the creative.
`status`	string	`draft` or `published`. A published creative is publicly available.
`originalfilename`	string	The original filename of the uploaded file.
`length`	integer	Duration in seconds.
`cat`	array	A list of category tags assigned to the creative.

Advertising fields (read/write)

Property	Type	Description
`clickableEndscreen`	boolean string	`"true"` or `"false"`. When `"true"`, the endscreen displayed after playback is clickable and links to the `deeplink` URL.
`shouldReplay`	boolean string	`"true"` or `"false"`. When `"true"`, the creative replays automatically after it finishes.
`shouldLoop`	boolean string	`"true"` or `"false"`. When `"true"`, the creative loops indefinitely.
`eventTrackers`	array	A list of third-party tracking URLs fired at specific playback events. Each entry has an `eventType` and a `url`. See 1.3 Event Tracker Types below.
`omidAdVerifications`	array	A list of Open Measurement (OMID) verification entries. Each entry has a `vendor` (string), `scriptUrl` (string), and optional `parameters` (string).
`creativeProjectId`	string	The ID of an interactive project linked to this creative, used for interactive (SIMID) ad experiences.

System fields (read-only)

Property	Type	Description
`id`	string	Unique identifier of the creative.
`type`	string	Fixed value: `MediaClip`.
`usetype`	string	Fixed value: `commercial`. Set automatically; do not include in requests.
`mediatype`	string	The type of media: `video` or `image`.
`sourcetype`	string	`on_demand` or `live`.
`publicationid`	string	The ID of the publication this creative belongs to.
`createddate`	string	ISO 8601 date and time the creative was created.
`updateddate`	string	ISO 8601 date and time the creative was last updated.
`publisheddate`	string	ISO 8601 date and time the creative’s status was first set to `published`.
`createdBy`	string	Username or email address of the user who created the creative.
`updatedBy`	string	Username or email address of the user who last updated the creative.
`views`	integer	Total all-time view count (ad impressions).
`width`	integer	Pixel width of the video.
`height`	integer	Pixel height of the video.
`dar`	string	Display aspect ratio (e.g. `16:9`).
`originalWidth`	integer	Pixel width of the original uploaded file.
`originalHeight`	integer	Pixel height of the original uploaded file.
`src`	string	File URI of the primary source file.
`gendeeplink`	string	Auto-generated deeplink URL, if configured.
`hasJobs`	boolean	`true` if there are active transcoding jobs for this creative.

Related entities (read-only)

Property	Type	Description
`assets`	array	A list of transcoded renditions. Writable only on creation; manage renditions after creation via the /sapi/mediaasset endpoint.
`thumbnails`	array	A list of thumbnail images. Each thumbnail has: `src` (file URI), `main` (boolean; `true` for the selected thumbnail), `width` and `height` (in pixels), and optional `crops`.
`subtitles`	array	References to subtitle tracks. Manage via the /sapi/subtitle endpoint.
`timelines`	array	References to linked timeline objects. Manage via the `/sapi/timeline` endpoint.
`audiotracks`	array	References to linked audiotrack objects. Manage via the /sapi/audiotrack endpoint.

1.3 | Event Tracker Types

The eventTrackers array accepts the following eventType values:

Value	Description
`start`	Fired when the creative starts playing.
`clickTracking`	Fired when the viewer clicks the creative.
`firstQuartile`	Fired when 25% of the creative has played.
`midpoint`	Fired when 50% of the creative has played.
`thirdQuartile`	Fired when 75% of the creative has played.
`complete`	Fired when the creative finishes playing.
`skip`	Fired when the viewer skips the creative.
`mute`	Fired when the creative is muted.
`unmute`	Fired when the creative is unmuted.
`rewind`	Fired when the creative is rewound.
`pause`	Fired when playback is paused.
`resume`	Fired when playback is resumed after a pause.
`fullscreen`	Fired when the player enters fullscreen mode.
`exitFullscreen`	Fired when the player exits fullscreen mode.

2.0 | Create/Update

Both creating and updating a creative use a PUT request. The presence or absence of an id in the request body determines whether a new creative is created or an existing one is updated. The usetype is automatically set to commercial; it does not need to be included in the request.

2.1 | Create

PUT /sapi/creative

Omit the id property to create a new creative. The response contains the complete created creative object.

Example request: create a new creative

curl -X PUT "https://yourcompanyname.bbvms.com/sapi/creative" \
  -H "rpctoken: {api_key}" \
  -H "Content-Type: application/json" \
  -d '{
    "type": "MediaClip",
    "mediatype": "video",
    "sourcetype": "on_demand",
    "originalfilename": "summer-campaign-30s.mp4",
    "title": "Summer Campaign 30s",
    "description": "30-second product ad for the summer campaign",
    "deeplink": "https://www.example.com/summer",
    "status": "published",
    "clickableEndscreen": "true",
    "shouldReplay": "false",
    "shouldLoop": "false"
  }'

Direct AWS S3 Upload

To add a video or image file to a newly created creative: upload the file to the AWS S3 source bucket. Read more about uploading directly to AWS S3.

2.2 | Update

PUT /sapi/creative/{id}

Include the id property to update an existing creative. Only the properties included in the request body are updated. The response contains the complete updated creative object.

Example request: update an existing creative

curl -X PUT "https://yourcompanyname.bbvms.com/sapi/creative/5812043" \
  -H "rpctoken: {api_key}" \
  -H "Content-Type: application/json" \
  -d '{
    "type": "MediaClip",
    "id": "5812043",
    "title": "Summer Campaign 30s: updated",
    "eventTrackers": [
      {
        "eventType": "start",
        "url": "https://tracking.example.com/pixel?event=start&v2=true"
      },
      {
        "eventType": "complete",
        "url": "https://tracking.example.com/pixel?event=complete&v2=true"
      }
    ]
  }'

3.0 | Retrieve List

GET /sapi/creative

Retrieves a list of creatives. By default, the 50 most recently created creatives are returned.

Example request: retrieve a list of creatives

curl -X GET "https://yourcompanyname.bbvms.com/sapi/creative?limit=10&sort=title+asc" \
  -H "rpctoken: {api_key}"

3.1 | Parameters

Parameter	Type	Description	Example
`q`	string	A query to filter results. See 3.2 Query Syntax below.	`?q=title:"summer campaign"`
`sort`	string	Sort field and direction. Default: `id desc`.	`?sort=title asc`
`limit`	integer	Number of creatives to return. Default: 50. Maximum: 1000.	`?limit=100`
`offset`	integer	Number of results to skip, for pagination.	`?offset=100`

3.2 | Query Syntax

The q parameter uses Solr query syntax. The following patterns are supported:

Pattern	Description	Example
Field match	Match an exact value in a specific field	`?q=title:"summer campaign"`
Date range	Match creatives within a date range (ISO 8601, inclusive)	`?q=createddate:[2025-01-01T00:00:00Z TO 2025-12-31T23:59:59Z]`
Status filter	Filter by publication status	`?q=status:published`

3.3 | Response

A successful request returns a 200 OK response with the following envelope:

Example list response

{
   "type": "MediaClipList",
   "numfound": 34,
   "offset": 0,
   "limit": 50,
   "count": 34,
   "items": [
      { /* creative object */ },
      { /* creative object */ }
   ]
}

Field	Type	Description
`type`	string	Fixed value: `MediaClipList`.
`numfound`	integer	Total number of matching creatives across all pages. Use with `limit` and `offset` to build pagination.
`offset`	integer	The offset used in the current request.
`limit`	integer	The limit used in the current request.
`count`	integer	The number of creatives returned in the current response.
`items`	array	The list of creative objects.

4.0 | Retrieve

GET /sapi/creative/{id}

Retrieves a single creative object.

Example request: retrieve a single creative

curl -X GET "https://yourcompanyname.bbvms.com/sapi/creative/5812043" \
  -H "rpctoken: {api_key}"

A successful request returns a 200 OK response with the full creative object.

5.0 | Delete

DELETE /sapi/creative/{id}

Moves a creative to the trash. To permanently delete the creative, use the purge parameter.

Example request: delete a creative

# Move to trash
curl -X DELETE "https://yourcompanyname.bbvms.com/sapi/creative/5812043" \
  -H "rpctoken: {api_key}"

# Permanently delete
curl -X DELETE "https://yourcompanyname.bbvms.com/sapi/creative/5812043?purge=true" \
  -H "rpctoken: {api_key}"

A successful request returns a 200 OK response.

5.1 | Parameters

Parameter	Type	Description	Example
`purge`	boolean	Permanently deletes the creative. Without this parameter, the creative is moved to the trash.	`?purge=true`

6.0 | HTTP Status Codes

Code	Meaning	When it occurs
`200 OK`	Success	Returned for all successful requests (retrieve, create, update, delete).
`400 Bad Request`	Invalid request	The request body is malformed or contains invalid values.
`401 Unauthorized`	Authentication failed	The `rpctoken` is missing or invalid.
`403 Forbidden`	Insufficient permissions	The authenticated user does not have permission to perform this action.
`404 Not Found`	Resource not found	No creative exists with the given ID or query.
`409 Conflict`	Validation error	The request is valid but violates a business rule (e.g. a required field is missing). The response body includes a `violations` array with details.

Example error response (409)

{
   "type": "Response",
   "code": 409,
   "error": true,
   "violations": [
      "title is required"
   ]
}

Tagged: creative sapi

Was this article helpful?

Yes No

Contact Support

Can't find the answer you're looking for?

Contact Support