openapi: 3.2.0
info:
  version: '2.0'
  title: ZENSIE Highlight API
servers:
- url: https://api.30mhz.com/api
tags:
- name: highlight
paths:
  /highlight:
    get:
      tags:
      - highlight
      summary: Return all highlights
      description: Authentication required for this operation.
      operationId: getAllHighlights
      security:
      - Bearer: []
      responses:
        '200':
          description: All highlights returned.
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/Highlight'
            application/zensie-v2+json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/Highlight'
        '403':
          description: Not enough permissions to perform the operation.
    post:
      tags:
      - highlight
      summary: Create a highlight
      description: Authentication required for this operation.
      operationId: createHighlight
      security:
      - Bearer: []
      responses:
        '201':
          description: New highlight created.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Highlight'
            application/zensie-v2+json:
              schema:
                $ref: '#/components/schemas/Highlight'
        '403':
          description: User not authorized.
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/HighlightNew'
  /highlight/{publishedAt}:
    get:
      tags:
      - highlight
      summary: Return the highlight with the given publication date
      description: Authentication required for this operation.
      operationId: getHighlightByPublishedAt
      parameters:
      - name: publishedAt
        in: path
        required: true
        schema:
          type: string
      - name: language
        in: query
        description: IETF language tag, e.g. en-US
        required: true
        schema:
          type: string
      security:
      - Bearer: []
      responses:
        '200':
          description: The highlight.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Highlight'
            application/zensie-v2+json:
              schema:
                $ref: '#/components/schemas/Highlight'
        '403':
          description: Not enough permissions to perform the operation.
    put:
      tags:
      - highlight
      summary: Patch a highlight (PUT not supported)
      description: Authentication required for this operation.
      operationId: putHighlight
      parameters:
      - name: publishedAt
        in: path
        required: true
        schema:
          type: string
      - name: language
        in: query
        description: IETF language tag, e.g. en-US
        required: false
        schema:
          type: string
      security:
      - Bearer: []
      responses:
        '200':
          description: Highlight patched
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Highlight'
            application/zensie-v2+json:
              schema:
                $ref: '#/components/schemas/Highlight'
        '400':
          description: Invalid data in the properties to be patched.
        '403':
          description: User not authorized.
        '404':
          description: Highlight not found.
        '500':
          description: Error while patching the highlight.
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/HighlightEditable'
    delete:
      tags:
      - highlight
      summary: Delete a highlight
      description: Authentication required for this operation.
      operationId: deleteHighlight
      parameters:
      - name: publishedAt
        in: path
        required: true
        schema:
          type: string
      - name: language
        in: query
        description: IETF language tag, e.g. en-US
        required: true
        schema:
          type: string
      security:
      - Bearer: []
      responses:
        '204':
          description: Highlight has been deleted.
        '403':
          description: User not authorized.
        '404':
          description: Highlight not found.
    patch:
      tags:
      - highlight
      summary: Patch a highlight
      description: Authentication required for this operation.
      operationId: patchHighlight
      parameters:
      - name: publishedAt
        in: path
        required: true
        schema:
          type: string
      - name: language
        in: query
        description: IETF language tag, e.g. en-US
        required: true
        schema:
          type: string
      security:
      - Bearer: []
      responses:
        '200':
          description: Highlight patched
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Highlight'
            application/zensie-v2+json:
              schema:
                $ref: '#/components/schemas/Highlight'
        '400':
          description: Invalid data in the properties to be patched.
        '403':
          description: User must be authenticated.
        '404':
          description: Highlight not found.
        '500':
          description: Error while patching the highlight.
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/HighlightEditable'
  /highlight/last:
    get:
      tags:
      - highlight
      summary: Return the last highlight
      description: Authentication required for this operation.
      operationId: getLastHighlight
      parameters:
      - name: language
        in: query
        description: IETF language tag, e.g. en-US
        required: true
        schema:
          type: string
      security:
      - Bearer: []
      responses:
        '200':
          description: The highlight.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Highlight'
            application/zensie-v2+json:
              schema:
                $ref: '#/components/schemas/Highlight'
        '403':
          description: Not enough permissions to perform the operation.
components:
  schemas:
    HighlightEditable:
      type: object
      properties:
        buttonTitle:
          type: string
          description: The text to display inside the button.
        imagePaths:
          type: array
          description: Ordered paths to images used by the highlight
          items:
            type: string
        links:
          type: array
          description: Ordered links used by the highlight
          items:
            type: string
        message:
          type: string
          description: Message informed in the highlight.
        publishedAt:
          type: string
          description: UTC ISO 8601 timestamp of publication, e.g., 2025-02-21T15:00:00Z.
        title:
          type: string
          description: Displayable title.
      description: Object containing the editable properties of a Highlight.
    Highlight:
      type: object
      properties:
        buttonTitle:
          type: string
          description: The text to display inside the button.
        imagePaths:
          type: array
          description: Ordered paths to images used by the highlight
          items:
            type: string
        links:
          type: array
          description: Ordered links used by the highlight
          items:
            type: string
        message:
          type: string
          description: Message informed in the highlight.
        publishedAt:
          type: string
          description: UTC ISO 8601 timestamp of publication, e.g., 2025-02-21T15:00:00Z.
        title:
          type: string
          description: Displayable title.
        language:
          type: string
      description: Information for users about platform tips, improvements or features release.
    HighlightNew:
      type: object
      required:
      - language
      - message
      - publishedAt
      - title
      properties:
        buttonTitle:
          type: string
          description: The text to display inside the button.
        imagePaths:
          type: array
          description: Ordered paths to images used by the highlight
          items:
            type: string
        links:
          type: array
          description: Ordered links used by the highlight
          items:
            type: string
        message:
          type: string
          description: Message informed in the highlight.
        publishedAt:
          type: string
          description: UTC ISO 8601 timestamp of publication, e.g., 2025-02-21T15:00:00Z.
        title:
          type: string
          description: Displayable title.
        language:
          type: string
          description: IETF language tag, e.g. en-US
      description: Object holding the required properties to create a new Highlight.
  securitySchemes:
    Bearer:
      description: ''
      type: apiKey
      name: Authorization
      in: header