openapi: 3.1.0
info:
  title: Adobe Creative Suite Adobe Firefly Accessibility Search API
  description: The Adobe Firefly API provides access to Adobe's generative AI capabilities for creating and editing images, vectors, and video from natural language prompts. Built on Adobe's Firefly family of creative generative models, which are trained on licensed and public domain content. Supports text-to-image generation, generative fill, generative expand, generating similar images, object compositing, and video generation. All generation operations are asynchronous.
  version: 3.0.0
  termsOfService: https://www.adobe.com/legal/terms.html
  contact:
    name: Adobe Developer Support
    url: https://developer.adobe.com/support/
  license:
    name: Adobe Developer Terms
    url: https://www.adobe.com/legal/developer-terms.html
servers:
- url: https://firefly-api.adobe.io/v3
  description: Adobe Firefly API v3 production server
security:
- bearerAuth: []
tags:
- name: Search
  description: Search and discover stock content
paths:
  /Media/1/Search/Files:
    get:
      operationId: searchStockFiles
      summary: Adobe Creative Suite Search Stock Files
      description: Searches the Adobe Stock library for files matching specified criteria such as keywords, content type, orientation, and color. Returns a paginated list of matching stock files with metadata including thumbnails, dimensions, and licensing status. Requires an API key header in addition to authentication.
      tags:
      - Search
      parameters:
      - name: locale
        in: query
        description: BCP 47 locale code for localized search results
        schema:
          type: string
          example: en_US
        example: en_US
      - name: search_parameters[words]
        in: query
        description: Keywords to search for in the stock library
        schema:
          type: string
          example: mountain landscape
        example: mountain landscape
      - name: search_parameters[limit]
        in: query
        description: Maximum number of results to return per page (1-64)
        schema:
          type: integer
          minimum: 1
          maximum: 64
          default: 32
          example: 20
        example: 20
      - name: search_parameters[offset]
        in: query
        description: Number of results to skip for pagination
        schema:
          type: integer
          default: 0
          example: 0
      - name: search_parameters[filters][content_type:photo]
        in: query
        description: Include photos in results (1 = include, 0 = exclude)
        schema:
          type: integer
          enum:
          - 0
          - 1
      - name: search_parameters[filters][content_type:illustration]
        in: query
        description: Include illustrations in results (1 = include, 0 = exclude)
        schema:
          type: integer
          enum:
          - 0
          - 1
      - name: search_parameters[filters][content_type:vector]
        in: query
        description: Include vector files in results (1 = include, 0 = exclude)
        schema:
          type: integer
          enum:
          - 0
          - 1
      - name: search_parameters[filters][content_type:video]
        in: query
        description: Include video files in results (1 = include, 0 = exclude)
        schema:
          type: integer
          enum:
          - 0
          - 1
      - name: search_parameters[filters][orientation]
        in: query
        description: Filter by image orientation
        schema:
          type: string
          enum:
          - horizontal
          - vertical
          - square
          - all
        example: horizontal
      - name: search_parameters[filters][premium]
        in: query
        description: Filter by premium status
        schema:
          type: string
          enum:
          - 'false'
          - 'true'
          - all
        example: 'false'
      - name: result_columns[]
        in: query
        description: Fields to include in the response for each result
        schema:
          type: array
          items:
            type: string
            enum:
            - id
            - title
            - creator_name
            - creator_id
            - country_name
            - width
            - height
            - thumbnail_url
            - thumbnail_width
            - thumbnail_height
            - media_type_id
            - category
            - keywords
            - comp_url
            - is_licensed
            - vector_type
            - content_type
            - nb_results
      - name: x-api-key
        in: header
        required: true
        description: Adobe Stock API key (client ID)
        schema:
          type: string
        example: example_value
      responses:
        '200':
          description: Search results returned successfully
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/SearchResult'
        '400':
          description: Bad request - invalid search parameters
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '401':
          description: Unauthorized - invalid or missing API key or bearer token
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
      x-microcks-operation:
        delay: 0
        dispatcher: FALLBACK
  /Media/1/Search/Files/{content_id}:
    get:
      operationId: getStockFileMetadata
      summary: Adobe Creative Suite Get Stock File Metadata
      description: Retrieves detailed metadata for a specific stock file by its content ID. Returns full file information including title, creator, dimensions, keywords, licensing status, and thumbnail URLs.
      tags:
      - Search
      parameters:
      - name: content_id
        in: path
        required: true
        description: Adobe Stock unique content identifier
        schema:
          type: integer
          example: 123456789
        example: 123456789
      - name: locale
        in: query
        description: BCP 47 locale for localized response data
        schema:
          type: string
          example: en_US
        example: en_US
      - name: result_columns[]
        in: query
        description: Fields to include in the response
        schema:
          type: array
          items:
            type: string
      - name: x-api-key
        in: header
        required: true
        description: Adobe Stock API key (client ID)
        schema:
          type: string
        example: example_value
      responses:
        '200':
          description: File metadata returned successfully
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/StockFileResponse'
        '404':
          description: Stock file not found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '401':
          description: Unauthorized - invalid or missing credentials
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
      x-microcks-operation:
        delay: 0
        dispatcher: FALLBACK
  /Media/1/Search/CategoryTree:
    get:
      operationId: getCategoryTree
      summary: Adobe Creative Suite Get Category Tree
      description: Retrieves the hierarchical category tree used to organize Adobe Stock content. Categories can be used as filters in search queries to narrow results to specific content categories such as Animals, Business, or Technology.
      tags:
      - Search
      parameters:
      - name: locale
        in: query
        description: BCP 47 locale for localized category names
        schema:
          type: string
          example: en_US
        example: en_US
      - name: category_id
        in: query
        description: Root category ID to retrieve subtree from (omit for full tree)
        schema:
          type: integer
        example: 1920
      - name: x-api-key
        in: header
        required: true
        description: Adobe Stock API key (client ID)
        schema:
          type: string
        example: example_value
      responses:
        '200':
          description: Category tree returned successfully
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/Category'
        '401':
          description: Unauthorized - invalid or missing credentials
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
      x-microcks-operation:
        delay: 0
        dispatcher: FALLBACK
components:
  schemas:
    StockFile:
      type: object
      description: Metadata for an Adobe Stock file
      properties:
        id:
          type: integer
          description: Unique Adobe Stock content identifier
          example: 123456789
        title:
          type: string
          description: Title of the stock file as provided by the contributor
          example: Beautiful mountain landscape at sunrise
        creator_name:
          type: string
          description: Display name of the file's creator/contributor
          example: PhotoContributor123
        creator_id:
          type: integer
          description: Unique identifier of the creator on Adobe Stock
          example: 987654
        country_name:
          type: string
          description: Country of origin of the creator
          example: United States
        width:
          type: integer
          description: Original width of the file in pixels
          example: 6000
        height:
          type: integer
          description: Original height of the file in pixels
          example: 4000
        media_type_id:
          type: integer
          description: Numeric identifier for the media type (1=photo, 2=illustration, 3=vector, 4=video, 6=3D, 7=template)
          example: 1
        content_type:
          type: string
          description: MIME type of the stock file
          example: image/jpeg
        keywords:
          type: array
          description: List of keywords describing the file content
          items:
            type: object
            properties:
              name:
                type: string
                description: Keyword text
          example:
          - name: mountain
          - name: landscape
          - name: sunrise
        comp_url:
          type: string
          description: URL of the watermarked comp image for preview purposes
          example: https://t3.ftcdn.net/jpg/01/23/45/67/240_F_123456789_abc.jpg
        thumbnail_url:
          type: string
          description: URL of the thumbnail image
          example: https://t3.ftcdn.net/jpg/01/23/45/67/160_F_123456789_abc.jpg
        thumbnail_width:
          type: integer
          description: Width of the thumbnail image in pixels
          example: 160
        thumbnail_height:
          type: integer
          description: Height of the thumbnail image in pixels
          example: 107
        is_licensed:
          type: string
          description: Licensing status of the file for the authenticated user
          enum:
          - Standard
          - Extended
          - Video_HD
          - Video_4K
          - ''
          example: ''
        vector_type:
          type: string
          description: Vector file subtype (svg or zip) if applicable
          enum:
          - svg
          - zip
          - ''
          example: svg
        category:
          $ref: '#/components/schemas/Category'
        nb_results:
          type: integer
          description: Total number of results matching the search query (on first item only)
          example: 4521
    StockFileResponse:
      type: object
      description: Response wrapper for a single stock file metadata request
      properties:
        files:
          type: array
          description: Array containing the requested file (always contains one item)
          items:
            $ref: '#/components/schemas/StockFile'
    SearchResult:
      type: object
      description: Paginated search results from the Adobe Stock library
      properties:
        nb_results:
          type: integer
          description: Total number of files matching the search query
          example: 4521
        files:
          type: array
          description: List of matching stock files
          items:
            $ref: '#/components/schemas/StockFile'
    Category:
      type: object
      description: A stock content category
      properties:
        id:
          type: integer
          description: Unique category identifier
          example: 1043
        name:
          type: string
          description: Localized category name
          example: Nature
        link:
          type: string
          description: URL to browse this category on the Adobe Stock website
          example: example_value
        children:
          type: array
          description: Child subcategories (present in category tree responses)
          items:
            $ref: '#/components/schemas/Category'
    ErrorResponse:
      type: object
      description: Standard error response
      properties:
        code:
          type: integer
          description: Numeric error code
          example: 1920
        message:
          type: string
          description: Human-readable error description
          example: example_value
  securitySchemes:
    bearerAuth:
      type: http
      scheme: bearer
      bearerFormat: JWT
      description: OAuth 2.0 access token obtained from Adobe IMS