openapi: 3.2.0
info:
  title: Brandcast Websites API
  version: 1.0.0
  description: Create, read, update, delete, publish, unpublish, export and password-protect Brandcast websites, and manage their content and media libraries.
  contact:
    name: Brandcast API
    url: https://developer.brandcast.io/
servers:
- url: https://api.brandcast-prod.io/v1
  description: Brandcast production API
security:
- apiKeyHeader: []
tags:
- name: Websites
paths:
  /websites:
    get:
      summary: Get websites
      description: Returns websites for this Brandcast account.
      operationId: getWebsites
      tags:
      - Websites
      responses:
        '200':
          description: Successful response.
          content:
            application/json:
              schema: {}
        '403':
          description: Missing or invalid API key. The Brandcast API gateway answers unauthenticated requests with {"message":"Missing Authentication Token"}.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
    post:
      summary: Create website from template
      description: Creates website from specified template and returns data for the newly created website. However, the website won't be available on the Internet until it's explicitly published.
      operationId: createWebsite
      tags:
      - Websites
      parameters:
      - name: templateId
        in: query
        description: Template ID
        required: true
        schema:
          type: string
      - name: name
        in: query
        description: Name of new website
        required: true
        schema:
          type: string
      - name: subdomain
        in: query
        description: Subdomain for new website
        required: true
        schema:
          type: string
      - name: newId
        in: query
        description: Optional new website ID
        required: false
        schema:
          type: string
      - name: description
        in: query
        description: Optional description for new website
        required: false
        schema:
          type: string
      responses:
        '200':
          description: Successful response.
          content:
            application/json:
              schema: {}
        '403':
          description: Missing or invalid API key. The Brandcast API gateway answers unauthenticated requests with {"message":"Missing Authentication Token"}.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
  /websites/{websiteId}:
    get:
      summary: Get website
      description: Returns data for specified website.
      operationId: getWebsite
      tags:
      - Websites
      parameters:
      - name: websiteId
        in: path
        description: Website ID
        required: true
        schema:
          type: string
      responses:
        '200':
          description: Successful response.
          content:
            application/json:
              schema: {}
        '403':
          description: Missing or invalid API key. The Brandcast API gateway answers unauthenticated requests with {"message":"Missing Authentication Token"}.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
    put:
      summary: Update website
      description: 'Updates a limited set of fields for a Website. Writable fields: description.'
      operationId: updateWebsite
      tags:
      - Websites
      parameters:
      - name: websiteId
        in: path
        description: Website ID
        required: true
        schema:
          type: string
      requestBody:
        description: JSON body
        required: true
        content:
          application/json:
            schema:
              type: string
      responses:
        '200':
          description: Successful response.
          content:
            application/json:
              schema: {}
        '403':
          description: Missing or invalid API key. The Brandcast API gateway answers unauthenticated requests with {"message":"Missing Authentication Token"}.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
    delete:
      summary: Delete website
      description: Deletes specified website, which means removing it from the Internet if it's already been published.
      operationId: deleteWebsite
      tags:
      - Websites
      parameters:
      - name: websiteId
        in: path
        description: Website ID
        required: true
        schema:
          type: string
      responses:
        '200':
          description: Successful response.
          content:
            application/json:
              schema: {}
        '403':
          description: Missing or invalid API key. The Brandcast API gateway answers unauthenticated requests with {"message":"Missing Authentication Token"}.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
  /websites/{websiteId}/content:
    get:
      summary: Get website content
      description: Returns content for specified website. Use the optional name parameter to filter content by name.
      operationId: getWebsiteContent
      tags:
      - Websites
      parameters:
      - name: websiteId
        in: path
        description: Website ID
        required: true
        schema:
          type: string
      - name: name
        in: query
        description: Filters the result by name
        required: false
        schema:
          type: string
      - name: tags
        in: query
        description: Deprecated.  Optional comma delimited list of tags to filter content by
        required: false
        deprecated: true
        schema:
          type: string
      - name: filterLockedContent
        in: query
        description: Enables/Disables the Locked Content Filter.  Defaults to true.
        required: false
        schema:
          type: string
      - name: limit
        in: query
        description: Limits the size of the result set.
        required: false
        schema:
          type: string
      - name: offset
        in: query
        description: If the response value next-offset exists, provide the value here to get the next page of results.
        required: false
        schema:
          type: string
      responses:
        '200':
          description: Successful response.
          content:
            application/json:
              schema: {}
        '403':
          description: Missing or invalid API key. The Brandcast API gateway answers unauthenticated requests with {"message":"Missing Authentication Token"}.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
  /websites/{websiteId}/content/{contentId}:
    put:
      summary: Update website content
      description: Updates content for specified website. The JSON body depends on the type of content being updated (e.g., text, embed, images, video, etc.), which is known by getting the website's content.
      operationId: updateWebsiteContent
      tags:
      - Websites
      parameters:
      - name: websiteId
        in: path
        description: Website ID
        required: true
        schema:
          type: string
      - name: contentId
        in: path
        description: Content ID
        required: true
        schema:
          type: string
      requestBody:
        description: JSON body
        required: true
        content:
          application/json:
            schema:
              type: string
      responses:
        '200':
          description: Successful response.
          content:
            application/json:
              schema: {}
        '403':
          description: Missing or invalid API key. The Brandcast API gateway answers unauthenticated requests with {"message":"Missing Authentication Token"}.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
  /websites/{websiteId}/medialibrary:
    get:
      summary: Get website media library
      description: Returns website's media library.
      operationId: getWebsiteMediaLibrary
      tags:
      - Websites
      parameters:
      - name: websiteId
        in: path
        description: Website ID
        required: true
        schema:
          type: string
      responses:
        '200':
          description: Successful response.
          content:
            application/json:
              schema: {}
        '403':
          description: Missing or invalid API key. The Brandcast API gateway answers unauthenticated requests with {"message":"Missing Authentication Token"}.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
    post:
      summary: Add to website media library
      description: Supported media are video/youtube and video/vimeo. Subsequently, once the media has been added to S3, the media ID can be used to update content in the website.
      operationId: addToWebsiteMediaLibrary
      tags:
      - Websites
      parameters:
      - name: websiteId
        in: path
        description: Website ID
        required: true
        schema:
          type: string
      requestBody:
        description: JSON body
        required: true
        content:
          application/json:
            schema:
              type: string
      responses:
        '200':
          description: Successful response.
          content:
            application/json:
              schema: {}
        '403':
          description: Missing or invalid API key. The Brandcast API gateway answers unauthenticated requests with {"message":"Missing Authentication Token"}.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
  /websites/{websiteId}/medialibrary/upload:
    post:
      summary: Upload to website media library
      description: Returns a media ID for the media and an S3 presigned URL to upload the media content to. Supported media are images, video, PDFs, and ZIP files. Subsequently, once the media has been uploaded to S3, the media ID can be used to update content in the website.
      operationId: uploadToWebsiteMediaLibrary
      tags:
      - Websites
      parameters:
      - name: websiteId
        in: path
        description: Website ID
        required: true
        schema:
          type: string
      - name: fileName
        in: query
        description: Media file name
        required: true
        schema:
          type: string
      responses:
        '200':
          description: Successful response.
          content:
            application/json:
              schema: {}
        '403':
          description: Missing or invalid API key. The Brandcast API gateway answers unauthenticated requests with {"message":"Missing Authentication Token"}.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
  /websites/{websiteId}/publish:
    get:
      summary: Get website publishing history
      description: Returns list of publishing jobs for specified website.
      operationId: getPublishJobs
      tags:
      - Websites
      parameters:
      - name: websiteId
        in: path
        description: Website ID
        required: true
        schema:
          type: string
      responses:
        '200':
          description: Successful response.
          content:
            application/json:
              schema: {}
        '403':
          description: Missing or invalid API key. The Brandcast API gateway answers unauthenticated requests with {"message":"Missing Authentication Token"}.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
    post:
      summary: Publish website
      description: Publishing puts the website on the Internet. This API creates a job that initiates and monitors the publishing process. Returns information about publishing the website, e.g., publishId, publishing status, etc. Then the website's publishing status can be polled via the publishId that's returned.
      operationId: createPublishJob
      tags:
      - Websites
      parameters:
      - name: websiteId
        in: path
        description: Website ID
        required: true
        schema:
          type: string
      requestBody:
        description: Custom Vars
        required: false
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/CustomVars'
      responses:
        '200':
          description: Successful response.
          content:
            application/json:
              schema: {}
        '403':
          description: Missing or invalid API key. The Brandcast API gateway answers unauthenticated requests with {"message":"Missing Authentication Token"}.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
  /websites/{websiteId}/publish/{publishId}:
    get:
      summary: Get status of publishing website
      description: Returns information about publishing the website, e.g., publishing status.
      operationId: getPublishJob
      tags:
      - Websites
      parameters:
      - name: websiteId
        in: path
        description: Website ID
        required: true
        schema:
          type: string
      - name: publishId
        in: path
        description: Publish ID
        required: true
        schema:
          type: string
      responses:
        '200':
          description: Successful response.
          content:
            application/json:
              schema: {}
        '403':
          description: Missing or invalid API key. The Brandcast API gateway answers unauthenticated requests with {"message":"Missing Authentication Token"}.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
  /websites/{websiteId}/unpublish:
    post:
      summary: Unpublish website
      description: Removes specified website from the Internet and returns data for unpublished website.
      operationId: unpublishWebsite
      tags:
      - Websites
      parameters:
      - name: websiteId
        in: path
        description: Website ID
        required: true
        schema:
          type: string
      responses:
        '200':
          description: Successful response.
          content:
            application/json:
              schema: {}
        '403':
          description: Missing or invalid API key. The Brandcast API gateway answers unauthenticated requests with {"message":"Missing Authentication Token"}.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
  /websites/{websiteId}/publish/{publishId}/export:
    post:
      summary: Export website
      description: Starts an export job which will ZIP up all HTML and assets for this publish and provide them for download via an S3 signed URL.  If the file name already exists, it will be modified like filename(1).
      operationId: createExportJob
      tags:
      - Websites
      parameters:
      - name: x-account-id
        in: header
        description: The account context for this action. Required when using Authorization header.
        required: false
        schema:
          type: string
      - name: Authorization
        in: header
        description: A valid JWT. Only required when called by Design Studio.
        required: false
        schema:
          type: string
      - name: websiteId
        in: path
        description: Website ID
        required: true
        schema:
          type: string
      - name: publishId
        in: path
        description: An existing publish ID
        required: true
        schema:
          type: string
      - name: fileName
        in: query
        description: The preferred name for the ZIP file.
        required: true
        schema:
          type: string
      responses:
        '200':
          description: Successful response.
          content:
            application/json:
              schema: {}
        '403':
          description: Missing or invalid API key. The Brandcast API gateway answers unauthenticated requests with {"message":"Missing Authentication Token"}.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
  /websites/{websiteId}/publish/{publishId}/export/{fileName}:
    get:
      summary: Get status of exporting a publish
      description: Returns information about exporting this publish, e.g., status, signed URL.  Calling this API will also refresh the signed URL.
      operationId: getExportJob
      tags:
      - Websites
      parameters:
      - name: x-account-id
        in: header
        description: The account context for this action. Required when using Authorization header.
        required: false
        schema:
          type: string
      - name: Authorization
        in: header
        description: A valid JWT. Only required when called by Design Studio.
        required: false
        schema:
          type: string
      - name: websiteId
        in: path
        description: Website ID
        required: true
        schema:
          type: string
      - name: publishId
        in: path
        description: An existing publish ID
        required: true
        schema:
          type: string
      - name: fileName
        in: path
        description: The name for the ZIP file.
        required: true
        schema:
          type: string
      responses:
        '200':
          description: Successful response.
          content:
            application/json:
              schema: {}
        '403':
          description: Missing or invalid API key. The Brandcast API gateway answers unauthenticated requests with {"message":"Missing Authentication Token"}.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
  /websites/{websiteId}/export:
    get:
      summary: Get a list of exports
      description: Returns a list of exports for this website.
      operationId: getExportList
      tags:
      - Websites
      parameters:
      - name: x-account-id
        in: header
        description: The account context for this action. Required when using Authorization header.
        required: false
        schema:
          type: string
      - name: Authorization
        in: header
        description: A valid JWT. Only required when called by Design Studio.
        required: false
        schema:
          type: string
      - name: websiteId
        in: path
        description: Website ID
        required: true
        schema:
          type: string
      responses:
        '200':
          description: Successful response.
          content:
            application/json:
              schema: {}
        '403':
          description: Missing or invalid API key. The Brandcast API gateway answers unauthenticated requests with {"message":"Missing Authentication Token"}.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
  /websites/{websiteId}/protection:
    put:
      summary: Add or remove password protection
      description: Adds password protection to specified website if optional username and password are specified. Otherwise, removes password protection if they're not.
      operationId: protectWebsite
      tags:
      - Websites
      parameters:
      - name: websiteId
        in: path
        description: Website ID
        required: true
        schema:
          type: string
      - name: username
        in: query
        required: false
        schema:
          type: string
      - name: password
        in: query
        required: false
        schema:
          type: string
      responses:
        '200':
          description: Successful response.
          content:
            application/json:
              schema: {}
        '403':
          description: Missing or invalid API key. The Brandcast API gateway answers unauthenticated requests with {"message":"Missing Authentication Token"}.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
components:
  schemas:
    CustomVars:
      type: object
      properties:
        key: {}
    Error:
      type: object
      description: Error envelope returned by the Brandcast API gateway.
      properties:
        message:
          type: string
  securitySchemes:
    apiKeyHeader:
      type: apiKey
      in: header
      name: x-api-key
      description: API key issued by Brandcast and tied to the developer's Brandcast account. Must be sent over HTTPS.
externalDocs:
  description: Brandcast API developer portal
  url: https://developer.brandcast.io/