openapi: 3.1.0
info:
  title: Zadar TV LLMS API
  description: |
    OpenAPI specifikacija za Zadar TV LLMS feed. API izlaže konsolidirane informacije iz WordPressa (Posts, Yoast News Sitemap, Video Sitemap)
    s ciljem lakše integracije od strane AI sustava i developera. Podržani formati: JSON, NDJSON, TXT.
  version: 1.0.0
  termsOfService: https://zadar.tv/dokumenti/
  contact:
    name: Zadar TV
    url: https://zadar.tv/kontakt/
    email: info@zadar.tv
  license:
    name: © Zadar TV — navođenje izvora poželjno
    url: https://zadar.tv/
servers:
  - url: https://zadar.tv/wp-json
    description: Production server
tags:
  - name: llms
    description: LLMS feed i povezane rute
  - name: health
    description: Health check endpoint
paths:
  /zadar-tv/v1/llms:
    get:
      tags: [llms]
      summary: Dohvat LLMS feeda
      description: |
        Vraća strukturirane informacije o stranicama, kategorijama i postovima iz zadnjih X sati.
        Podržava više formata odgovora kroz query parametar `fmt`.
      parameters:
        - in: query
          name: fmt
          description: Format odgovora
          required: false
          schema:
            type: string
            enum: [json, ndjson, txt]
            default: json
        - in: query
          name: window_hours
          description: Prozor (u satima) za recentne objave (ako je podržano na serveru)
          required: false
          schema:
            type: integer
        - in: query
          name: recent_limit
          description: Maksimalan broj recentnih postova (ako je podržano)
          required: false
          schema:
            type: integer
      responses:
        '200':
          description: Uspješan odgovor
          headers:
            ETag:
              description: MD5/ETag vrijednost sadržaja
              schema:
                type: string
            Last-Modified:
              description: Datum zadnje izmjene payload-a
              schema:
                type: string
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/LlmsPayload'
              examples:
                basic:
                  summary: Osnovni primjer JSON odgovora
                  value:
                    generated_at: '2025-11-23T03:25:42+00:00'
                    language: HR
                    brand_title: 'Zadar TV'
                    sitemaps:
                      index: 'https://zadar.tv/sitemap_index.xml'
                      news: 'https://zadar.tv/news-sitemap.xml'
                      video: 'https://zadar.tv/video-sitemap.xml'
                    stats:
                      new_24h: 10
                      updated_24h: 10
                      video: 4
                    pages:
                      - label: 'O nama'
                        url: 'https://zadar.tv/o-nama-zadar-tv/'
                    categories:
                      - label: 'Vijesti'
                        url: 'https://zadar.tv/category/vijesti/'
                    posts:
                      - title: 'Program Muzeja antičkog stakla u Zadru...'
                        url: 'https://zadar.tv/program-muzeja-antickog-stakla-u-zadru-povodom-dana-grada-i-blagdana-sv-krsevana/'
                        published_at: '2025-11-22T17:41:00+01:00'
                        flags: ['NEW','UPDATED','FROM_NEWS_SITEMAP']
                        score: 90
                        video: null
            text/plain:
              schema:
                type: string
              examples:
                txt:
                  summary: TXT format primjer
                  value: |
                    # Zadar TV — LLMS feed (TXT)
                    Najnoviji članci (48h):
                    - Program Muzeja antičkog stakla ... [NEW][UPDATED]
                    - Hrvatska protiv Poljske na Croatia Kupu ... [NEW]
            application/x-ndjson:
              schema:
                type: string
                description: NDJSON (po jedan JSON objekt po liniji)
      x-robots-tag: all
  /zadar-tv/v1/health:
    get:
      tags: [health]
      summary: Health check
      description: Provjera dostupnosti i statusa API-ja.
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                type: object
                properties:
                  status:
                    type: string
                    example: ok
                  timestamp:
                    type: string
                    format: date-time
components:
  schemas:
    LlmsPayload:
      type: object
      properties:
        generated_at:
          type: string
          format: date-time
        brand_title:
          type: string
        brand_subtitle:
          type: string
        language:
          type: string
          example: HR
        sitemaps:
          type: object
          properties:
            index:
              type: string
              format: uri
            news:
              type: string
              format: uri
            video:
              type: string
              format: uri
        stats:
          type: object
          properties:
            new_24h:
              type: integer
            updated_24h:
              type: integer
            video:
              type: integer
        fallback_used:
          type: boolean
        recent_limit:
          type: integer
        window_hours:
          type: integer
        cache_ttl:
          type: integer
        pages:
          type: array
          items:
            $ref: '#/components/schemas/PageItem'
        categories:
          type: array
          items:
            $ref: '#/components/schemas/CategoryItem'
        posts:
          type: array
          items:
            $ref: '#/components/schemas/PostItem'
    PageItem:
      type: object
      properties:
        label:
          type: string
        url:
          type: string
          format: uri
    CategoryItem:
      type: object
      properties:
        label:
          type: string
        url:
          type: string
          format: uri
    PostItem:
      type: object
      properties:
        title:
          type: string
        url:
          type: string
          format: uri
        published_at:
          type: string
          format: date-time
        modified_at:
          type: string
          format: date-time
          nullable: true
        author:
          type: string
          nullable: true
        categories:
          type: array
          items:
            type: string
        tags:
          type: array
          items:
            type: string
        summary:
          type: string
          nullable: true
        image_url:
          type: string
          format: uri
          nullable: true
        flags:
          type: array
          items:
            type: string
        score:
          type: integer
        video:
          type: object
          nullable: true
          properties:
            video_url:
              type: string
              format: uri
              nullable: true
            thumbnail_url:
              type: string
              format: uri
              nullable: true
            duration:
              type: integer
              nullable: true
            publication_at:
              type: string
              format: date-time
              nullable: true
            family_friendly:
              type: string
              nullable: true
x-logo:
  url: https://zadar.tv/wp-content/uploads/2025/01/logo-zadar-tv.png
  backgroundColor: '#0b1e2d'