Skip to content
Tilecast Docs

createWidget

POST
/api/v1/widgets
curl --request POST \
  --url https://example.com/api/v1/widgets \
  --header 'Content-Type: application/json' \
  --cookie tilecast_session=<tilecast_session> \
  --data '{ "provider": "example", "presetId": "leaderboard", "name": "example", "description": "example", "configuration": {} }'

Requires an authenticated dashboard session. Creates a reusable Widget or catalog App. An App recipe may atomically provision one hidden managed Data Source while preserving normal dependency and manifest behavior.

Authorizations

Section titled “Authorizations”

Request Bodyrequired

Section titled “Request Bodyrequired”
Media typeapplication/json
object
provider
required

Closed renderable Widget or App identifier from the release-owned content-definition catalog.

string
/^[a-z][a-z0-9_-]{0,79}$/
presetId
string | null
Allowed values: leaderboard status_board queue_board schedule_departures opening_hours directory
name
required
string
>= 1 characters <= 180 characters
description
string
<= 2000 characters
configuration
required

Provider-specific configuration. Native text Widgets omit textScale for automatic bounds-first sizing or use 25–500 percent; contentPadding defaults to 10 percent per edge and accepts 0–40.

object
key
additional properties
any

Responses

Section titled “ Responses ”

201

Section titled “201”

Widget created

Media typeapplication/json
object
data
required
object
id
required
string format: uuid
name
required
string
description
required
string
type
required
string
Allowed values: image video widget
originalFilename
required
string
declaredMimeType
required
string
detectedMimeType
required
string
sha256
required
string
/^[0-9a-f]{64}$/
originalSize
required
integer format: int64
width
integer
height
integer
durationSeconds
number
frameRate
number
videoCodec
string
audioCodec
string
audioChannels
integer
metadata
required
object
key
additional properties
any
processingStatus
required
string
Allowed values: uploading uploaded queued inspecting processing ready failed deleting deleted
processingProgress
number
<= 1
errorCode
string
errorMessage
string
thumbnailUrl
string
createdAt
required
string format: date-time
updatedAt
required
string format: date-time
availableFrom
string format: date-time
expiresAt
string format: date-time
archivedAt
string format: date-time
variants
required
Array<object>
object
id
required
string format: uuid
kind
required
string
Allowed values: original playback thumbnail poster
mimeType
required
string
fileSize
required
integer format: int64
sha256
required
string
/^[0-9a-f]{64}$/
width
integer
height
integer
durationSeconds
number
frameRate
number
videoCodec
string
audioCodec
string
playerCompatible
required
boolean
createdAt
required
string format: date-time
widget
object
provider
required

Closed renderable Widget or App identifier from the release-owned content-definition catalog.

string
/^[a-z][a-z0-9_-]{0,79}$/
presetId
string | null
Allowed values: leaderboard status_board queue_board schedule_departures opening_hours directory
configVersion
required
integer
>= 1
authorConfiguration

Author-facing App settings before managed-resource IDs are injected.

object
key
additional properties
any
managedDataSourceId

Explicit ownership link for a catalog App’s hidden managed Data Source.

string format: uuid
configuration
required

Provider-specific configuration. Native text Widgets omit textScale for automatic bounds-first sizing or use 25–500 percent; contentPadding defaults to 10 percent per edge and accepts 0–40.

object
key
additional properties
any
playlistUsage
required
integer
creator
object
id
required
string format: uuid
name
required
string
playlistsUsing
Array<object>
object
id
required
string format: uuid
name
required
string
layoutUsage
required
Array<object>
object
id
required
string format: uuid
name
required
string
published
required
boolean
folderId
string format: uuid
tags
required
Array<object>
object
id
required
string format: uuid
name
required
string
color
required
string
assetCount
integer
assignable

On the tag list, whether the caller may apply or remove this tag.

boolean
collectionIds
required
Array<string>
website
object
url
required
string
displayUrl
required
string
allowedHosts
required
Array<string>
javascriptEnabled
required
boolean
domStorageEnabled
required
boolean
cookiePolicy
required
string
Allowed values: disabled first_party first_and_third_party
reloadPolicy
required
string
Allowed values: load_once on_each_activation interval
refreshIntervalSeconds
integer
>= 1
loadTimeoutSeconds
required
integer
zoomPercent
required
integer
scrollX
required
integer
scrollY
required
integer
customUserAgent
required
string
backgroundColor
required
string
failureBehavior
required
string
Allowed values: last_success placeholder fallback_image skip
fallbackImageAssetId
string format: uuid
createdAt
required
string format: date-time
updatedAt
required
string format: date-time
Example
{
  "data": {
    "type": "image",
    "processingStatus": "uploading",
    "variants": [
      {
        "kind": "original"
      }
    ],
    "widget": {
      "presetId": "leaderboard"
    },
    "website": {
      "cookiePolicy": "disabled",
      "reloadPolicy": "load_once",
      "failureBehavior": "last_success"
    }
  }
}

422

Section titled “422”

Provider unknown, Data Source incompatible, or a selected field does not exist