> ## Documentation Index
> Fetch the complete documentation index at: https://docs.beyondwords.io/llms.txt
> Use this file to discover all available pages before exploring further.

# Update ad

> Updates an ad in a project



## OpenAPI

````yaml put /projects/{project_id}/ads/{id}
openapi: 3.0.1
info:
  title: BeyondWords REST API
  description: |-
    This is the documentation for the BeyondWords REST API.
              You can use this API to use BeyondWords programmatically.
              You can get your API Key and Project ID for each project in the Project settings tab in the BeyondWords
              <a href="https://dash.beyondwords.io/dashboard">dashboard</a>.
  version: 1.0.0
servers:
  - url: https://api.beyondwords.io/v1
security: []
paths:
  /projects/{project_id}/ads/{id}:
    parameters:
      - name: project_id
        in: path
        description: The numeric ID of your project
        required: true
        schema:
          type: string
      - name: id
        in: path
        description: The numeric ID of your ad
        required: true
        schema:
          type: string
    put:
      tags:
        - Ads
      summary: Update
      description: Updates an ad in a project
      operationId: ads#update
      parameters: []
      requestBody:
        content:
          application/json:
            schema:
              oneOf:
                - $ref: '#/components/schemas/requestBodyCustomTypeAdUpdate'
                - $ref: '#/components/schemas/requestBodyVastTypeAdUpdate'
            examples:
              example_custom:
                $ref: '#/components/examples/requestBodyCustomAdExample'
              example_vast:
                $ref: '#/components/examples/requestBodyVastAdExample'
      responses:
        '200':
          description: successful
          content:
            application/json:
              examples:
                example:
                  $ref: '#/components/examples/adExample'
              schema:
                $ref: '#/components/schemas/adModel'
      security:
        - apiKey: []
components:
  schemas:
    requestBodyCustomTypeAdUpdate:
      type: object
      title: Custom ad
      description: Update ad with custom type
      properties:
        placement:
          type: string
          enum:
            - pre-roll
            - mid-roll
            - post-roll
          description: >-
            Whether the ad should play before/during/after the audio content.
            Possible values are `pre-roll`, `mid-roll`, or `post-roll`
        title:
          type: string
          description: The title of the ad
          nullable: true
        click_through_url:
          type: string
          nullable: true
          description: The click-through URL of the `custom` ad to show in the player
        image_url:
          type: string
          description: The image URL to show in the player while the ad is playing
          nullable: true
        audio_url:
          type: string
          nullable: true
          description: The URL of the audio file of the `custom` ad to play in the player
        video_url:
          type: string
          nullable: true
          description: The URL of the video file of the `custom` ad to play in the player
        theme:
          type: string
          enum:
            - auto
            - dark
            - light
          description: >-
            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.
          nullable: true
        dark_theme:
          type: object
          description: The dark theme colors
          nullable: true
          properties:
            text_color:
              type: string
              description: The hexadecimal text color to use in the player
            background_color:
              type: string
              description: The hexadecimal background color to use in the player
            icon_color:
              type: string
              description: The hexadecimal icon color to use in the player
        light_theme:
          type: object
          description: The light theme colors
          nullable: true
          properties:
            text_color:
              type: string
              description: The hexadecimal text color to use in the player
            background_color:
              type: string
              description: The hexadecimal background color to use in the player
            icon_color:
              type: string
              description: The hexadecimal icon color to use in the player
        video_theme:
          type: object
          description: The video theme colors
          nullable: true
          properties:
            text_color:
              type: string
              description: The hexadecimal text color to use in the player
            background_color:
              type: string
              description: The hexadecimal background color to use in the player
            icon_color:
              type: string
              description: The hexadecimal icon color to use in the player
        time_range:
          type: object
          nullable: true
          description: The time range for when the ad should play in the player
          properties:
            start:
              type: string
              description: The start time within the media when the ad should play
              nullable: true
            end:
              type: string
              description: The end time within the media when the ad should stop playing
              nullable: true
    requestBodyVastTypeAdUpdate:
      type: object
      title: Vast ad
      description: Update ad with vast type
      properties:
        placement:
          type: string
          enum:
            - pre-roll
            - mid-roll
            - post-roll
          description: >-
            Whether the ad should play before/during/after the audio content.
            Possible values are `pre-roll`, `mid-roll`, or `post-roll`
        title:
          type: string
          description: The title of the ad
          nullable: true
        vast_url:
          type: string
          nullable: true
          description: A VAST-compliant URL that contains the ads to be played
        time_range:
          type: object
          nullable: true
          description: The time range for when the ad should play in the player
          properties:
            start:
              type: string
              description: The start time within the media when the ad should play
              nullable: true
            end:
              type: string
              description: The end time within the media when the ad should stop playing
              nullable: true
    adModel:
      type: object
      properties:
        id:
          type: integer
          description: Unique identifier for the object
        type:
          type: string
          enum:
            - custom
            - vast
          description: >-
            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.
        enabled:
          type: boolean
          description: Whether the ad will play in the BeyondWords player
        placement:
          type: string
          enum:
            - pre-roll
            - mid-roll
            - post-roll
          description: >-
            Whether the ad should play before/during/after the audio content.
            Possible values are `pre-roll`, `mid-roll`, or `post-roll`
        vast_url:
          type: string
          description: A VAST-compliant URL that contains the ads to be played
          nullable: true
          format: uri
          maxLength: 2048
        title:
          type: string
          description: The title of the ad
          nullable: true
        click_through_url:
          type: string
          description: The click-through URL of the `custom` ad to show in the player
          nullable: true
          format: uri
          maxLength: 2048
        image_url:
          type: string
          description: The image URL to show in the player while the ad is playing
          nullable: true
          format: uri
          maxLength: 2048
        media_url:
          type: string
          description: The URL of the media file of the `custom` ad to play in the player
          nullable: true
          format: uri
          maxLength: 2048
        audio_url:
          type: string
          description: The URL of the audio file of the `custom` ad to play in the player
          nullable: true
          format: uri
          maxLength: 2048
        video_url:
          type: string
          description: The URL of the video file of the `custom` ad to play in the player
          nullable: true
          format: uri
          maxLength: 2048
        media:
          type: array
          description: >-
            The transcoded media of the `custom` ad to play in the player This
            is read-only and generated automatically from the media_url.
          items:
            $ref: '#/components/schemas/adAudioModel'
        audio:
          type: array
          description: >-
            The transcoded media of the `custom` ad to play in the player This
            is read-only and generated automatically from the media_url.
          items:
            $ref: '#/components/schemas/adAudioModel'
        video:
          type: array
          description: The array of video files.
          items:
            $ref: '#/components/schemas/adVideoModel'
        theme:
          type: string
          enum:
            - auto
            - dark
            - light
          description: >-
            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.
          nullable: true
        dark_theme:
          type: object
          description: The dark theme colors
          nullable: true
          properties:
            text_color:
              type: string
              description: The hexadecimal text color to use in the player
            background_color:
              type: string
              description: The hexadecimal background color to use in the player
            icon_color:
              type: string
              description: The hexadecimal icon color to use in the player
        light_theme:
          type: object
          description: The light theme colors
          nullable: true
          properties:
            text_color:
              type: string
              description: The hexadecimal text color to use in the player
            background_color:
              type: string
              description: The hexadecimal background color to use in the player
            icon_color:
              type: string
              description: The hexadecimal icon color to use in the player
        video_theme:
          type: object
          description: The video theme colors
          nullable: true
          properties:
            text_color:
              type: string
              description: The hexadecimal text color to use in the player
            background_color:
              type: string
              description: The hexadecimal background color to use in the player
            icon_color:
              type: string
              description: The hexadecimal icon color to use in the player
        time_range:
          type: object
          description: The time range for when the ad should play in the player
          nullable: true
          properties:
            start:
              type: string
              description: The start time of when the ad should play
              nullable: true
            end:
              type: string
              description: The end time of when the ad should play
              nullable: true
        created:
          type: string
          description: Time at which the object was created (ISO 8601)
        updated:
          type: string
          description: Time at which the object was updated (ISO 8601)
    adAudioModel:
      type: object
      properties:
        id:
          type: integer
          description: Unique identifier for the object (automatically set)
        content_type:
          type: string
          description: The content type of the media (automatically set)
        url:
          type: string
          description: The URL of the media file
        duration:
          type: integer
          description: The duration of the media in milliseconds (automatically set)
        base64_file:
          type: string
          description: >-
            The content of the media file encoded as base64. Only present for
            .m3u8 metadata files
          nullable: true
    adVideoModel:
      type: object
      properties:
        id:
          type: integer
          description: Unique identifier for the object (automatically set)
        content_type:
          type: string
          description: The content type of the media (automatically set)
        url:
          type: string
          description: The URL of the media file
        duration:
          type: integer
          description: The duration of the media in milliseconds (automatically set)
        base64_file:
          type: string
          description: >-
            The content of the media file encoded as base64. Only present for
            .m3u8 metadata files
          nullable: true
  examples:
    requestBodyCustomAdExample:
      summary: Sample custom ad request
      value:
        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
    requestBodyVastAdExample:
      summary: Sample VAST ad request
      value:
        type: vast
        enabled: true
        placement: pre-roll
        vast_url: https://example.com
        title: My Ad
        click_through_url: null
        media_url: null
        theme: dark
        dark_theme: null
        light_theme: null
        time_range: null
    adExample:
      summary: A sample ad response
      value:
        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
  securitySchemes:
    apiKey:
      type: apiKey
      name: X-Api-Key
      in: header

````