Zesty Media API — Files

naftiko: 1.0.0-alpha2
info:
  label: Zesty Media API — Files
  description: 'Zesty Media API — Files. 5 operations. Lead operation: Zesty List all media files. Self-contained Naftiko
    capability covering one Zesty business surface.'
  tags:
  - Zesty
  - Files
  created: '2026-05-19'
  modified: '2026-05-19'
binds:
- namespace: env
  keys:
    ZESTY_API_KEY: ZESTY_API_KEY
capability:
  consumes:
  - type: http
    namespace: media-files
    baseUri: https://media-manager.api.zesty.io
    description: Zesty Media API — Files business capability. Self-contained, no shared references.
    resources:
    - name: files
      path: /files
      operations:
      - name: getfiles
        method: GET
        description: Zesty List all media files
        outputRawFormat: json
        outputParameters:
        - name: result
          type: object
          value: $.
        inputParameters:
        - name: binZUID
          in: query
          type: string
          description: Filter files by bin ZUID.
        - name: groupZUID
          in: query
          type: string
          description: Filter files by group ZUID.
        - name: limit
          in: query
          type: integer
          description: Maximum number of files to return.
        - name: page
          in: query
          type: integer
          description: Page number for pagination.
    - name: files-fileZUID
      path: /files/{fileZUID}
      operations:
      - name: getfile
        method: GET
        description: Zesty Get a media file
        outputRawFormat: json
        outputParameters:
        - name: result
          type: object
          value: $.
        inputParameters:
        - name: fileZUID
          in: path
          type: string
          description: The ZUID of the file.
          required: true
      - name: updatefile
        method: PUT
        description: Zesty Update a media file
        outputRawFormat: json
        outputParameters:
        - name: result
          type: object
          value: $.
        inputParameters:
        - name: fileZUID
          in: path
          type: string
          description: The ZUID of the file.
          required: true
        - name: body
          in: body
          type: object
          description: Request body (JSON).
          required: true
      - name: deletefile
        method: DELETE
        description: Zesty Delete a media file
        outputRawFormat: json
        outputParameters:
        - name: result
          type: object
          value: $.
        inputParameters:
        - name: fileZUID
          in: path
          type: string
          description: The ZUID of the file.
          required: true
    - name: upload-binZUID-groupZUID
      path: /upload/{binZUID}/{groupZUID}
      operations:
      - name: uploadfile
        method: POST
        description: Zesty Upload a media file
        outputRawFormat: json
        outputParameters:
        - name: result
          type: object
          value: $.
        inputParameters:
        - name: binZUID
          in: path
          type: string
          description: The ZUID of the bin to upload to.
          required: true
        - name: groupZUID
          in: path
          type: string
          description: The ZUID of the group (folder) to upload to.
          required: true
        - name: body
          in: body
          type: object
          description: Request body (JSON).
          required: true
    authentication:
      type: apikey
      key: Authorization
      value: '{{env.ZESTY_API_KEY}}'
      placement: header
  exposes:
  - type: rest
    namespace: media-files-rest
    port: 8080
    description: REST adapter for Zesty Media API — Files. One Spectral-compliant resource per consumed operation, prefixed
      with /v1.
    resources:
    - path: /v1/files
      name: files
      description: REST surface for files.
      operations:
      - method: GET
        name: getfiles
        description: Zesty List all media files
        call: media-files.getfiles
        with:
          binZUID: rest.binZUID
          groupZUID: rest.groupZUID
          limit: rest.limit
          page: rest.page
        outputParameters:
        - type: object
          mapping: $.
    - path: /v1/files/{filezuid}
      name: files-filezuid
      description: REST surface for files-fileZUID.
      operations:
      - method: GET
        name: getfile
        description: Zesty Get a media file
        call: media-files.getfile
        with:
          fileZUID: rest.fileZUID
        outputParameters:
        - type: object
          mapping: $.
      - method: PUT
        name: updatefile
        description: Zesty Update a media file
        call: media-files.updatefile
        with:
          fileZUID: rest.fileZUID
          body: rest.body
        outputParameters:
        - type: object
          mapping: $.
      - method: DELETE
        name: deletefile
        description: Zesty Delete a media file
        call: media-files.deletefile
        with:
          fileZUID: rest.fileZUID
        outputParameters:
        - type: object
          mapping: $.
    - path: /v1/upload/{binzuid}/{groupzuid}
      name: upload-binzuid-groupzuid
      description: REST surface for upload-binZUID-groupZUID.
      operations:
      - method: POST
        name: uploadfile
        description: Zesty Upload a media file
        call: media-files.uploadfile
        with:
          binZUID: rest.binZUID
          groupZUID: rest.groupZUID
          body: rest.body
        outputParameters:
        - type: object
          mapping: $.
  - type: mcp
    namespace: media-files-mcp
    port: 9090
    transport: http
    description: MCP adapter for Zesty Media API — Files. One tool per consumed operation, routed inline through this capability's
      consumes block.
    tools:
    - name: zesty-list-all-media-files
      description: Zesty List all media files
      hints:
        readOnly: true
        destructive: false
        idempotent: true
      call: media-files.getfiles
      with:
        binZUID: tools.binZUID
        groupZUID: tools.groupZUID
        limit: tools.limit
        page: tools.page
      outputParameters:
      - type: object
        mapping: $.
    - name: zesty-get-media-file
      description: Zesty Get a media file
      hints:
        readOnly: true
        destructive: false
        idempotent: true
      call: media-files.getfile
      with:
        fileZUID: tools.fileZUID
      outputParameters:
      - type: object
        mapping: $.
    - name: zesty-update-media-file
      description: Zesty Update a media file
      hints:
        readOnly: false
        destructive: false
        idempotent: true
      call: media-files.updatefile
      with:
        fileZUID: tools.fileZUID
        body: tools.body
      outputParameters:
      - type: object
        mapping: $.
    - name: zesty-delete-media-file
      description: Zesty Delete a media file
      hints:
        readOnly: false
        destructive: true
        idempotent: true
      call: media-files.deletefile
      with:
        fileZUID: tools.fileZUID
      outputParameters:
      - type: object
        mapping: $.
    - name: zesty-upload-media-file
      description: Zesty Upload a media file
      hints:
        readOnly: false
        destructive: false
        idempotent: false
      call: media-files.uploadfile
      with:
        binZUID: tools.binZUID
        groupZUID: tools.groupZUID
        body: tools.body
      outputParameters:
      - type: object
        mapping: $.