TVDB API V4 — Movies

naftiko: 1.0.0-alpha2
info:
  label: TVDB API V4 — Movies
  description: 'TVDB API V4 — Movies. 6 operations. Lead operation: Get All Movie. Self-contained Naftiko capability covering one TheTVDB business surface.'
  tags:
  - TheTVDB
  - Television
  - Movies
  created: '2026-05-30'
  modified: '2026-05-30'
binds:
- namespace: env
  keys:
    TVDB_BEARER_TOKEN: TVDB_BEARER_TOKEN
capability:
  consumes:
  - type: http
    namespace: v4-movies
    baseUri: 'https://api4.thetvdb.com/v4'
    description: TVDB API V4 — Movies business capability. Self-contained, no shared references.
    authentication:
      type: bearer
      token: '{{env.TVDB_BEARER_TOKEN}}'
    resources:
    - name: movies
      path: /movies
      operations:
      - name: getAllMovie
        method: GET
        description: TheTVDB Get All Movie
        inputParameters:
        - name: page
          in: query
          type: number
          required: false
          description: page number
        outputRawFormat: json
        outputParameters:
        - name: result
          type: object
          value: $.
    - name: movies-id
      path: '/movies/{id}'
      operations:
      - name: getMovieBase
        method: GET
        description: TheTVDB Get Movie Base
        inputParameters:
        - name: id
          in: path
          type: number
          required: true
          description: id
        outputRawFormat: json
        outputParameters:
        - name: result
          type: object
          value: $.
    - name: movies-id-extended
      path: '/movies/{id}/extended'
      operations:
      - name: getMovieExtended
        method: GET
        description: TheTVDB Get Movie Extended
        inputParameters:
        - name: id
          in: path
          type: number
          required: true
          description: id
        - name: meta
          in: query
          type: string
          required: false
          description: meta
        - name: short
          in: query
          type: boolean
          required: false
          description: reduce the payload and returns the short version of this record without characters, artworks and trailers.
        outputRawFormat: json
        outputParameters:
        - name: result
          type: object
          value: $.
    - name: movies-filter
      path: '/movies/filter'
      operations:
      - name: getMoviesFilter
        method: GET
        description: TheTVDB Get Movies Filter
        inputParameters:
        - name: company
          in: query
          type: number
          required: false
          description: production company
        - name: contentRating
          in: query
          type: number
          required: false
          description: content rating id base on a country
        - name: country
          in: query
          type: string
          required: true
          description: country of origin
        - name: genre
          in: query
          type: number
          required: false
          description: genre
        - name: lang
          in: query
          type: string
          required: true
          description: original language
        - name: sort
          in: query
          type: string
          required: false
          description: sort by results
        - name: status
          in: query
          type: number
          required: false
          description: status
        - name: year
          in: query
          type: number
          required: false
          description: release year
        outputRawFormat: json
        outputParameters:
        - name: result
          type: object
          value: $.
    - name: movies-slug-slug
      path: '/movies/slug/{slug}'
      operations:
      - name: getMovieBaseBySlug
        method: GET
        description: TheTVDB Get Movie Base by Slug
        inputParameters:
        - name: slug
          in: path
          type: string
          required: true
          description: slug
        outputRawFormat: json
        outputParameters:
        - name: result
          type: object
          value: $.
    - name: movies-id-translations-language
      path: '/movies/{id}/translations/{language}'
      operations:
      - name: getMovieTranslation
        method: GET
        description: TheTVDB Get Movie Translation
        inputParameters:
        - name: id
          in: path
          type: number
          required: true
          description: id
        - name: language
          in: path
          type: string
          required: true
          description: language
        outputRawFormat: json
        outputParameters:
        - name: result
          type: object
          value: $.
  exposes:
  - type: rest
    namespace: v4-movies-rest
    port: 8080
    description: REST adapter for TVDB API V4 — Movies. One Spectral-compliant resource per consumed operation, prefixed with /v1.
    resources:
    - path: /v1/movies
      name: movies
      description: REST surface for movies.
      operations:
      - method: GET
        name: getAllMovie
        description: TheTVDB Get All Movie
        call: v4-movies.getAllMovie
        with:
          page: rest.page
        outputParameters:
        - type: object
          mapping: $.
    - path: /v1/movies/{id}
      name: movies-id
      description: REST surface for movies-id.
      operations:
      - method: GET
        name: getMovieBase
        description: TheTVDB Get Movie Base
        call: v4-movies.getMovieBase
        with:
          id: rest.id
        outputParameters:
        - type: object
          mapping: $.
    - path: /v1/movies/{id}/extended
      name: movies-id-extended
      description: REST surface for movies-id-extended.
      operations:
      - method: GET
        name: getMovieExtended
        description: TheTVDB Get Movie Extended
        call: v4-movies.getMovieExtended
        with:
          id: rest.id
          meta: rest.meta
          short: rest.short
        outputParameters:
        - type: object
          mapping: $.
    - path: /v1/movies/filter
      name: movies-filter
      description: REST surface for movies-filter.
      operations:
      - method: GET
        name: getMoviesFilter
        description: TheTVDB Get Movies Filter
        call: v4-movies.getMoviesFilter
        with:
          company: rest.company
          contentRating: rest.contentRating
          country: rest.country
          genre: rest.genre
          lang: rest.lang
          sort: rest.sort
          status: rest.status
          year: rest.year
        outputParameters:
        - type: object
          mapping: $.
    - path: /v1/movies/slug/{slug}
      name: movies-slug-slug
      description: REST surface for movies-slug-slug.
      operations:
      - method: GET
        name: getMovieBaseBySlug
        description: TheTVDB Get Movie Base by Slug
        call: v4-movies.getMovieBaseBySlug
        with:
          slug: rest.slug
        outputParameters:
        - type: object
          mapping: $.
    - path: /v1/movies/{id}/translations/{language}
      name: movies-id-translations-language
      description: REST surface for movies-id-translations-language.
      operations:
      - method: GET
        name: getMovieTranslation
        description: TheTVDB Get Movie Translation
        call: v4-movies.getMovieTranslation
        with:
          id: rest.id
          language: rest.language
        outputParameters:
        - type: object
          mapping: $.
  - type: mcp
    namespace: v4-movies-mcp
    port: 9090
    transport: http
    description: MCP adapter for TVDB API V4 — Movies. One tool per consumed operation, routed inline through this capability's consumes block.
    tools:
    - name: get-movie
      description: TheTVDB Get All Movie
      hints:
        readOnly: true
        destructive: false
        idempotent: true
      call: v4-movies.getAllMovie
      with:
        page: tools.page
      outputParameters:
      - type: object
        mapping: $.
    - name: get-movie-base
      description: TheTVDB Get Movie Base
      hints:
        readOnly: true
        destructive: false
        idempotent: true
      call: v4-movies.getMovieBase
      with:
        id: tools.id
      outputParameters:
      - type: object
        mapping: $.
    - name: get-movie-extended
      description: TheTVDB Get Movie Extended
      hints:
        readOnly: true
        destructive: false
        idempotent: true
      call: v4-movies.getMovieExtended
      with:
        id: tools.id
        meta: tools.meta
        short: tools.short
      outputParameters:
      - type: object
        mapping: $.
    - name: get-movies-filter
      description: TheTVDB Get Movies Filter
      hints:
        readOnly: true
        destructive: false
        idempotent: true
      call: v4-movies.getMoviesFilter
      with:
        company: tools.company
        contentRating: tools.contentRating
        country: tools.country
        genre: tools.genre
        lang: tools.lang
        sort: tools.sort
        status: tools.status
        year: tools.year
      outputParameters:
      - type: object
        mapping: $.
    - name: get-movie-base-slug
      description: TheTVDB Get Movie Base by Slug
      hints:
        readOnly: true
        destructive: false
        idempotent: true
      call: v4-movies.getMovieBaseBySlug
      with:
        slug: tools.slug
      outputParameters:
      - type: object
        mapping: $.
    - name: get-movie-translation
      description: TheTVDB Get Movie Translation
      hints:
        readOnly: true
        destructive: false
        idempotent: true
      call: v4-movies.getMovieTranslation
      with:
        id: tools.id
        language: tools.language
      outputParameters:
      - type: object
        mapping: $.