Unsplash API — Photos

naftiko: 1.0.0-alpha2
info:
  label: Unsplash API — Photos
  description: 'Unsplash API — Photos. 6 operations. Lead operation: List Editorial Photos. Self-contained Naftiko capability
    covering one Unsplash business surface.'
  tags:
  - Unsplash
  - Photos
  created: '2026-05-19'
  modified: '2026-05-19'
binds:
- namespace: env
  keys:
    UNSPLASH_API_KEY: UNSPLASH_API_KEY
capability:
  consumes:
  - type: http
    namespace: unsplash-photos
    baseUri: https://api.unsplash.com
    description: Unsplash API — Photos business capability. Self-contained, no shared references.
    resources:
    - name: photos
      path: /photos
      operations:
      - name: listphotos
        method: GET
        description: List Editorial Photos
        outputRawFormat: json
        outputParameters:
        - name: result
          type: object
          value: $.
        inputParameters:
        - name: page
          in: query
          type: integer
          description: Page number to retrieve
        - name: per_page
          in: query
          type: integer
          description: Number of items per page
        - name: order_by
          in: query
          type: string
          description: Order results by latest, oldest, or popular
    - name: photos-random
      path: /photos/random
      operations:
      - name: getrandomphoto
        method: GET
        description: Get a Random Photo
        outputRawFormat: json
        outputParameters:
        - name: result
          type: object
          value: $.
        inputParameters:
        - name: collections
          in: query
          type: string
          description: Comma-separated collection IDs to filter by
        - name: topics
          in: query
          type: string
          description: Comma-separated topic IDs or slugs to filter by
        - name: username
          in: query
          type: string
          description: Limit to photos by a specific user
        - name: query
          in: query
          type: string
          description: Search query to filter random photos
        - name: orientation
          in: query
          type: string
          description: Filter by photo orientation
        - name: content_filter
          in: query
          type: string
          description: Content safety filter level
        - name: count
          in: query
          type: integer
          description: Number of random photos (returns array if count > 1)
    - name: photos-id
      path: /photos/{id}
      operations:
      - name: getphoto
        method: GET
        description: Get a Photo
        outputRawFormat: json
        outputParameters:
        - name: result
          type: object
          value: $.
      - name: updatephoto
        method: PUT
        description: Update a Photo
        outputRawFormat: json
        outputParameters:
        - name: result
          type: object
          value: $.
        inputParameters:
        - name: body
          in: body
          type: object
          description: Request body (JSON).
          required: false
    - name: photos-id-download
      path: /photos/{id}/download
      operations:
      - name: trackphotodownload
        method: GET
        description: Track a Photo Download
        outputRawFormat: json
        outputParameters:
        - name: result
          type: object
          value: $.
    - name: photos-id-statistics
      path: /photos/{id}/statistics
      operations:
      - name: getphotostatistics
        method: GET
        description: Get Photo Statistics
        outputRawFormat: json
        outputParameters:
        - name: result
          type: object
          value: $.
        inputParameters:
        - name: resolution
          in: query
          type: string
          description: Time resolution for statistics
        - name: quantity
          in: query
          type: integer
          description: Number of data points to return
    authentication:
      type: bearer
      token: '{{env.UNSPLASH_API_KEY}}'
  exposes:
  - type: rest
    namespace: unsplash-photos-rest
    port: 8080
    description: REST adapter for Unsplash API — Photos. One Spectral-compliant resource per consumed operation, prefixed
      with /v1.
    resources:
    - path: /v1/photos
      name: photos
      description: REST surface for photos.
      operations:
      - method: GET
        name: listphotos
        description: List Editorial Photos
        call: unsplash-photos.listphotos
        with:
          page: rest.page
          per_page: rest.per_page
          order_by: rest.order_by
        outputParameters:
        - type: object
          mapping: $.
    - path: /v1/photos/random
      name: photos-random
      description: REST surface for photos-random.
      operations:
      - method: GET
        name: getrandomphoto
        description: Get a Random Photo
        call: unsplash-photos.getrandomphoto
        with:
          collections: rest.collections
          topics: rest.topics
          username: rest.username
          query: rest.query
          orientation: rest.orientation
          content_filter: rest.content_filter
          count: rest.count
        outputParameters:
        - type: object
          mapping: $.
    - path: /v1/photos/{id}
      name: photos-id
      description: REST surface for photos-id.
      operations:
      - method: GET
        name: getphoto
        description: Get a Photo
        call: unsplash-photos.getphoto
        outputParameters:
        - type: object
          mapping: $.
      - method: PUT
        name: updatephoto
        description: Update a Photo
        call: unsplash-photos.updatephoto
        with:
          body: rest.body
        outputParameters:
        - type: object
          mapping: $.
    - path: /v1/photos/{id}/download
      name: photos-id-download
      description: REST surface for photos-id-download.
      operations:
      - method: GET
        name: trackphotodownload
        description: Track a Photo Download
        call: unsplash-photos.trackphotodownload
        outputParameters:
        - type: object
          mapping: $.
    - path: /v1/photos/{id}/statistics
      name: photos-id-statistics
      description: REST surface for photos-id-statistics.
      operations:
      - method: GET
        name: getphotostatistics
        description: Get Photo Statistics
        call: unsplash-photos.getphotostatistics
        with:
          resolution: rest.resolution
          quantity: rest.quantity
        outputParameters:
        - type: object
          mapping: $.
  - type: mcp
    namespace: unsplash-photos-mcp
    port: 9090
    transport: http
    description: MCP adapter for Unsplash API — Photos. One tool per consumed operation, routed inline through this capability's
      consumes block.
    tools:
    - name: list-editorial-photos
      description: List Editorial Photos
      hints:
        readOnly: true
        destructive: false
        idempotent: true
      call: unsplash-photos.listphotos
      with:
        page: tools.page
        per_page: tools.per_page
        order_by: tools.order_by
      outputParameters:
      - type: object
        mapping: $.
    - name: get-random-photo
      description: Get a Random Photo
      hints:
        readOnly: true
        destructive: false
        idempotent: true
      call: unsplash-photos.getrandomphoto
      with:
        collections: tools.collections
        topics: tools.topics
        username: tools.username
        query: tools.query
        orientation: tools.orientation
        content_filter: tools.content_filter
        count: tools.count
      outputParameters:
      - type: object
        mapping: $.
    - name: get-photo
      description: Get a Photo
      hints:
        readOnly: true
        destructive: false
        idempotent: true
      call: unsplash-photos.getphoto
      outputParameters:
      - type: object
        mapping: $.
    - name: update-photo
      description: Update a Photo
      hints:
        readOnly: false
        destructive: false
        idempotent: true
      call: unsplash-photos.updatephoto
      with:
        body: tools.body
      outputParameters:
      - type: object
        mapping: $.
    - name: track-photo-download
      description: Track a Photo Download
      hints:
        readOnly: true
        destructive: false
        idempotent: true
      call: unsplash-photos.trackphotodownload
      outputParameters:
      - type: object
        mapping: $.
    - name: get-photo-statistics
      description: Get Photo Statistics
      hints:
        readOnly: true
        destructive: false
        idempotent: true
      call: unsplash-photos.getphotostatistics
      with:
        resolution: tools.resolution
        quantity: tools.quantity
      outputParameters:
      - type: object
        mapping: $.