> ## Documentation Index > Fetch the complete documentation index at: https://docs.mottostreaming.com/llms.txt > Use this file to discover all available pages before exploring further. # Create banner > CreateBanner Creates new banner. ## OpenAPI ````yaml post /cms/banners/v2 openapi: 3.0.3 info: title: Studio API - Motto version: 0.0.0 servers: - url: https://api.mottostreaming.com description: Production server security: - BearerAuth: [] tags: - name: AccountService description: Account management service - name: ActionConfigurationService description: Action configuration service definition - name: ActionSecretService description: Action type service definition - name: ActionService description: Action service definition - name: ActionTypeService description: Action type service definition - name: ActivityService description: Activity service definition - name: AdService description: Ad management service. - name: AnnotationService description: Annotation service definition - name: AnnotationSetService description: Annotation service definition - name: AnnotationTypeService description: Annotation service definition - name: AssetService description: Asset management service. - name: AuthService description: Auth service definition - name: BannerService description: Banner service definition - name: BannerV2Service_v2 description: Banner service definition - name: CleengService description: CleengService service definition - name: ClipService description: ClipService is the service that handles Clip operations. - name: ConfigurationService description: >- Configuration management service. These configurations allow modifying the behavior of streams, uploads, simulcasts, etc. - name: ContentTypeService description: ContentType service definition - name: CreativeWorkService description: CreativeWork service definition - name: EntitlementService description: Entitlement service definition - name: EntityService description: Entity service definition - name: EventService description: Event service definition - name: FileService description: OTT files management. - name: IngestService description: Ingest management service. - name: IngestService_v2 description: Ingest management service. - name: LiveStreamService description: LiveStream management service. - name: LiveStreamService_v2 description: LiveStream management service. - name: OfferService description: Offer service definition - name: OrganizationService description: Organization management service. - name: PageService description: Page service definition - name: PlatformService description: Platform service definition - name: PlaylistService description: Playlist management service. - name: ProjectService description: Project management service. - name: SimulcastService description: Simulcast management service. - name: SlugService description: Slug service definition - name: SpiideoService description: SpiideoService service definition - name: StandingService description: Standing service definition - name: StitcherService description: StitcherService is the service that handles stitching operations. - name: StripeService description: StripeService service definition - name: SubscriptionService description: Subscription service definition - name: SubtitleService description: SubtitleService is the service that handles Subtitle operations. - name: TransactionService description: Transaction service definition - name: UploadService description: Upload management service. - name: UsageService description: The UsageService provides methods to retrieve usage data for SKUs. - name: UserService description: User management service - name: VODService description: VODService is the service that handles VOD operations. - name: VODService_v2 description: VODService is the service that handles VOD operations. - name: VideoProtectionService description: VideoProtection management service. - name: VideoProtectionService_v2 description: VideoProtection management service. - name: VideoService description: Video management service. paths: /cms/banners/v2: post: tags: - BannerV2Service_v2 description: |- CreateBanner Creates new banner. operationId: BannerV2Service_v2_CreateBanner requestBody: content: application/json: schema: $ref: '#/components/schemas/motto.cms.banner.v2.Banner' required: true responses: '200': description: OK content: application/json: schema: $ref: '#/components/schemas/motto.cms.banner.v2.CreateBannerResponse' default: description: Default error response content: application/json: schema: $ref: '#/components/schemas/google.rpc.Status' components: schemas: motto.cms.banner.v2.Banner: required: - project_id - name - banner_type - template_type type: object properties: id: readOnly: true type: string description: System generated unique identifier for the banner. project_id: type: string name: type: string description: >- A name for visual identification within the management UI. Does not appear towards end users. banner_type: enum: - BANNER_TYPE_UNSPECIFIED - BANNER_TYPE_DEFAULT - BANNER_TYPE_EVENT - BANNER_TYPE_CREATIVE_WORK - BANNER_TYPE_ENTITY type: string description: The type of banner that determines how content is sourced. format: enum content_id: type: string description: >- Single banner - it is connected to a single content item (either an event, entity, or creative work). Important: at most one of `content_id`, `dynamic_target` may be set per request. dynamic_target: allOf: - $ref: '#/components/schemas/motto.cms.banner.v2.DynamicBannerTarget' description: >- Dynamic banner - it is not connected to a single content item, but derives its content from a set of filters. Important: at most one of `content_id`, `dynamic_target` may be set per request. template_type: type: string description: |- The type of template that should be rendered. Refer to the documentation to find the available types. Examples: "team-vs-team-hero", "simple", "video-bg", "highlighted-event", etc. background_assets: type: array items: $ref: '#/components/schemas/motto.cms.banner.v2.BannerAsset' description: >- A list of assets to be shown in the background (as the main banner image). Each asset is meant for a different screen size, determined by its `breakpoint_width` property. E.g. if you only want a single asset for this banner, you can set `breakpoint_width` to 0. E.g. if you want to show a different asset for mobile vs desktop, you can set `breakpoint_width` to 0 for the mobile asset and 1024 for the desktop asset. data: type: object description: >- Data needed by individual templates. Each template can have its own data structure. Refer to the documentation for the specific template to see what data is needed. To reference properties of the connected content item, use variable keypaths like `{event.title}`, `{entity.name}`, `{event.fields.competition.item.banner}` etc. environments: type: array items: type: string description: >- The environments in which this banner should be rendered. The available options are: "web", "ios", "android", "tvos", "lg", "samsung", "androidtv" Important: this should always be a subset of the environments configured at the page-component level for the associated banner collection. For example, if a page component is configured to be "ios" only, but a banner inside that component has "web" only, that banner will never be shown. css_classes: type: array items: type: string description: >- Web only. A list of CSS classes that should be added to the banner's container element. This can be used to apply custom styling to the banner. visibility: enum: - VISIBILITY_UNSPECIFIED - VISIBILITY_PUBLISHED - VISIBILITY_UNLISTED - VISIBILITY_HIDDEN type: string format: enum overrides: type: object additionalProperties: $ref: '#/components/schemas/motto.cms.banner.v2.BannerOverride' description: >- A map of overrides for the banner. This is useful for scenarios where some subset of Banner instantiations should have different properties. The key is a `content_id` (either event ID, entity ID, or creative work ID), the value is the override to apply when that content is in context. Note that a hit on a banner override will entirely replace the banner template and data; it will not merge with the base banner. geo_applicability_exempt: allOf: - $ref: '#/components/schemas/motto.cms.banner.v2.CountryCodes' description: >- Viewers from these countries will not have this video ad shown. Important: at most one of `geo_applicability_exempt`, `geo_applicability_apply` may be set per request. geo_applicability_apply: allOf: - $ref: '#/components/schemas/motto.cms.banner.v2.CountryCodes' description: >- Viewers from these countries will have this video ad shown. Important: at most one of `geo_applicability_exempt`, `geo_applicability_apply` may be set per request. destination_url: type: object additionalProperties: type: string description: >- Optional. A map of localized destination URLs. The key is the language code (ISO 639 - set 1), e.g. "en", "de", "fr", etc. If you want to localize the URL for different regions of the same language, you can add the country code (ISO 3166-1 alpha-2), e.g. "en-US", "en-GB", etc. Note that this is not necessary for banners of type BANNER_TYPE_EVENT, BANNER_TYPE_CREATIVE_WORK, or BANNER_TYPE_ENTITY, as the destination URL will be derived from the connected content item in those cases. is_preview: type: boolean description: >- Indicates that this banner is a preview banner. Preview banner are not shown to end users, but can be used for testing and previewing changes. When you wish to deploy a preview banner to production (your main platform for end users), you should use `CloneBanner`. source_banner_id: type: string description: >- The banner ID of the production page that this preview banner is based on. This field is only relevant when "is_preview" is true. It will be set automatically when using the "CloneBanner" API method. is_fallback: type: boolean description: >- Indicates that this banner is a fallback banner. Fallback banners are shown only when there are no other banners that can be shown based on their targeting criteria in `connected_content`. If multiple fallback banners exist in a banner collection, only the first one in a banner collection will be used. description: >- Banner represents a single banner that can be displayed on an end-user facing web/app page. Banners can be either static (with fixed content) or dynamic (content derived from parameters). motto.cms.banner.v2.CreateBannerResponse: type: object properties: banner: $ref: '#/components/schemas/motto.cms.banner.v2.Banner' google.rpc.Status: type: object properties: code: type: integer description: >- The status code, which should be an enum value of [google.rpc.Code][google.rpc.Code]. format: int32 message: type: string description: >- A developer-facing error message, which should be in English. Any user-facing error message should be localized and sent in the [google.rpc.Status.details][google.rpc.Status.details] field, or localized by the client. details: type: array items: $ref: '#/components/schemas/google.protobuf.Any' description: >- A list of messages that carry the error details. There is a common set of message types for APIs to use. description: >- The `Status` type defines a logical error model that is suitable for different programming environments, including REST APIs and RPC APIs. It is used by [gRPC](https://github.com/grpc). Each `Status` message contains three pieces of data: error code, error message, and error details. You can find out more about this error model and how to work with it in the [API Design Guide](https://cloud.google.com/apis/design/errors). motto.cms.banner.v2.DynamicBannerTarget: type: object properties: filter: type: string description: >- Filter the result-set by properties using a subset of the Kibana Query Language. This will make a List API call to retrieve the relevant resource for this banner. For BANNER_TYPE_EVENT, this would be a ListEvents call. For BANNER_TYPE_CREATIVE_WORK, this would be a ListCreativeWorks call. For BANNER_TYPE_ENTITY, this would be a ListEntities call, For example, let's say a BANNER_TYPE_EVENT banner is shown on a competition page, and the goal is to show the first upcoming event from that competition in the banner. The filter could be: `status:EVENT_STATUS_SCHEDULED and fields.competition.id:{id}` in combination with the `order_by` value of `start_time asc` to get the next upcoming event. order_by: type: string description: >- To be used in combination with `filter`. See documentation there for more details. offset: type: string description: >- The number of items to offset the result-set by. This is useful when multiple banners exist with the same filter/order_by, and you want to show different items in each banner. motto.cms.banner.v2.BannerAsset: type: object properties: options: type: array items: $ref: '#/components/schemas/motto.cms.banner.v2.BannerAsset_Option' description: >- Multiple options to choose from for this asset. The first option that resolves to a valid asset URL will be used. This is typically useful when there are several keypaths that may contain a usable asset, in which case the first one that resolves to a valid URL will be selected. Typically it is recommended to put the `asset_id` option last, so that it acts as a fallback if none of the keypaths resolve to a valid asset. However, for static banners it may make sense to only provide a single `asset_id` option. breakpoint_width: type: integer description: >- The `min-width` at which this image/video should be shown (unless another asset is closer to the min-width). format: int32 motto.cms.banner.v2.BannerOverride: type: object properties: template_type: type: string description: |- The type of template that should be rendered. Refer to the documentation to find the available types. Examples: "team-vs-team-hero", "simple", "video-bg", "highlighted-event", etc. background_assets: type: array items: $ref: '#/components/schemas/motto.cms.banner.v2.BannerAsset' description: >- A list of assets to be shown in the background (as the main banner image). Each asset is meant for a different screen size, determined by its `breakpoint_width` property. E.g. if you only want a single asset for this banner, you can set `breakpoint_width` to 0. E.g. if you want to show a different asset for mobile vs desktop, you can set `breakpoint_width` to 0 for the mobile asset and 1024 for the desktop asset. data: type: object description: >- Data needed by individual templates. Each template can have its own data structure. Refer to the documentation for the specific template to see what data is needed. For static banners, this would contain the fixed content (texts, assets, destination_url). For dynamic banners, this can contain template references like `{event.title}`, `{entity.name}`, etc. environments: type: array items: type: string description: >- The environments in which this banner should be rendered. The available options are: "web", "ios", "android", "tvos", "lg", "samsung", "androidtv" If left empty, the banner will be rendered in all environments (when possible). css_classes: type: array items: type: string description: >- Web only. A list of CSS classes that should be added to the banner's container element. This can be used to apply custom styling to the banner. visibility: enum: - VISIBILITY_UNSPECIFIED - VISIBILITY_PUBLISHED - VISIBILITY_UNLISTED - VISIBILITY_HIDDEN type: string format: enum geo_applicability_exempt: allOf: - $ref: '#/components/schemas/motto.cms.banner.v2.CountryCodes' description: >- Viewers from these countries will not have this video ad shown. Important: at most one of `geo_applicability_exempt`, `geo_applicability_apply` may be set per request. geo_applicability_apply: allOf: - $ref: '#/components/schemas/motto.cms.banner.v2.CountryCodes' description: >- Viewers from these countries will have this video ad shown. Important: at most one of `geo_applicability_exempt`, `geo_applicability_apply` may be set per request. destination_url: type: object additionalProperties: type: string description: >- Optional. A map of localized destination URLs. The key is the language code (ISO 639 - set 1), e.g. "en", "de", "fr", etc. If you want to localize the URL for different regions of the same language, you can add the country code (ISO 3166-1 alpha-2), e.g. "en-US", "en-GB", etc. Note that this is not necessary for banners of type BANNER_TYPE_EVENT, BANNER_TYPE_CREATIVE_WORK, or BANNER_TYPE_ENTITY, as the destination URL will be derived from the connected content item in those cases. description: >- BannerOverride is a subset of the Banner message. It can be used to modify default behavior of a banner. motto.cms.banner.v2.CountryCodes: type: object properties: country_codes: type: array items: type: string description: >- A country code (ISO 3316-1 alpha-2: https://en.wikipedia.org/wiki/List_of_ISO_3166_country_codes) description: A list of country codes google.protobuf.Any: type: object properties: '@type': type: string description: The type of the serialized message. additionalProperties: true description: >- Contains an arbitrary serialized message along with a @type that describes the type of the serialized message. motto.cms.banner.v2.BannerAsset_Option: type: object properties: asset_id: allOf: - $ref: '#/components/schemas/motto.cms.banner.v2.BannerAssetIDs' description: >- A map of either an image or video assets. The key is the language code (ISO 639 - set 1), e.g. "en", "de", "fr", etc. If you want to localize the assets for different regions of the same language, you can add the country code (ISO 3166-1 alpha-2), e.g. "en-US", "en-GB", etc. keypath: type: string description: >- A keypath on the associated content resource. This should resolve to a Motto-hosted asset URL. Unlike the `asset_id` field, this will already be localized based on the end user's language preference. E.g.: `event.fields.competition.item.banner` motto.cms.banner.v2.BannerAssetIDs: type: object properties: asset_id: type: object additionalProperties: type: string description: >- A map of either an image or video assets. The key is the language code (ISO 639 - set 1), e.g. "en", "de", "fr", etc. If you want to localize the assets for different regions of the same language, you can add the country code (ISO 3166-1 alpha-2), e.g. "en-US", "en-GB", etc. securitySchemes: BearerAuth: type: http scheme: bearer ````