Getty Images Assets API

openapi: 3.2.0
info:
  title: Getty Images Assets API
  version: '3'
  description: 'Developer resources for the Getty Images API including SDK, documentation,

    release notes, status, notifications and sample code.'
security:
- Api-Key: []
- OAuth2: []
tags:
- name: Assets
paths:
  /v3/asset-changes/change-sets:
    put:
      tags:
      - Assets
      summary: Get asset change notifications
      description: '# Asset Changes


        Get notifications about new, updated or deleted assets for a specific channel.


        ## Quickstart


        You''ll need an API key and an access token to use this resource.


        Maximum batch size is 2200.


        Change-sets must be confirmed before a new batch of notifications can be retrieved from this endpoint. Use the DELETE asset-changes/change-sets/{change-set-id} endpoint to confirm reciept of these notifications.


        Values returned for asset_type include Image, Film, and null. Values returned for asset_lifecycle include New, Update, and Delete.


        Delete notifications may be provided for asset ids that have not previously been received as New or Update notifications. Delete notifications may return null for the asset_type.


        If there are no notifications in the channel an empty response body will be returned.


        Notifications older than 60 days will be removed from partner channels.'
      parameters:
      - name: channel_id
        in: query
        description: Specifies the id of the channel for the asset data. Valid channel ids can be found in the results of the Get Partner Channel query.
        schema:
          type: integer
          description: Specifies the id of the channel for the asset data. Valid channel ids can be found in the results of the Get Partner Channel query.
          format: int32
      - name: batch_size
        in: query
        description: Specifies the number of assets to return. The default is 2200; maximum is 2200.
        schema:
          type:
          - integer
          - 'null'
          description: Specifies the number of assets to return. The default is 2200; maximum is 2200.
          format: int32
      responses:
        '200':
          description: Success - Channel contains unconfirmed asset change notifications
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/AssetChanges'
        '201':
          description: Created
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/AssetChanges'
        '400':
          description: InvalidChannelIdException
        '403':
          description: Your access token does not authorize access to this resource
        '404':
          description: The channel you specified does not exist
      operationId: putV3AssetChangesChangeSets
      x-operation-id-source: derived
  /v3/asset-changes/change-sets/{change-set-id}:
    delete:
      tags:
      - Assets
      summary: Confirm asset change notifications
      description: '# Delete Asset Changes


        Confirm asset changes acknowledges receipt of asset changes (from the PUT asset-changes endpoint).


        ## Quickstart


        You''ll need an API key and an access token to use this resource.


        Use the change_set_id from the PUT asset-changes/change-sets endpoint to confirm receipt of notifications.'
      parameters:
      - name: change-set-id
        in: path
        description: Specify the change-set-id associated with a transaction resource whose receipt you want to confirm.
        required: true
        schema:
          type: integer
          description: Specify the change-set-id associated with a transaction resource whose receipt you want to confirm.
          format: int64
      responses:
        '200':
          description: Success
        '400':
          description: InvalidChangeSetId
        '403':
          description: Your access token does not authorize access to this resource
        '404':
          description: Transaction was not found
      operationId: deleteV3AssetChangesChangeSetsByChangeSetId
      x-operation-id-source: derived
  /v3/asset-changes/channels:
    get:
      tags:
      - Assets
      summary: Get a list of asset change notification channels
      description: '# Get Partner Channels


        Retrieves the channel data for the partner. This data can be used to populate the channel_id parameter in the Put Asset Changes query.


        ## Quickstart


        You''ll need an API key and an access token to use this resource.


        Partners who have a channel that has been removed should contact their sales representative to be set up again.'
      responses:
        '200':
          description: Success
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/Channel'
        '403':
          description: UnauthorizedToAccessResource
        '404':
          description: ChannelsNotFound
      operationId: getV3AssetChangesChannels
      x-operation-id-source: derived
  /v3/asset-licensing/{assetId}:
    post:
      tags:
      - Assets
      summary: Endpoint for acquiring extended licenses with iStock credits for an asset
      parameters:
      - name: Accept-Language
        in: header
        description: 'Provide a header to specify the language of result values. Supported values: cs (iStock only), de, en-GB, en-US, es, fi (iStock only), fr, hu (iStock only), id (iStock only), it, ja, ko (creative assets only), nl, pl (creative assets only), pt-BR, pt-PT, ro (iStock only), ru (creative assets only), sv, th (iStock only), tr, uk (iStock only), vi (iStock only), zh-HK (creative assets only).'
        schema:
          type: string
          description: 'Provide a header to specify the language of result values. Supported values: cs (iStock only), de, en-GB, en-US, es, fi (iStock only), fr, hu (iStock only), id (iStock only), it, ja, ko (creative assets only), nl, pl (creative assets only), pt-BR, pt-PT, ro (iStock only), ru (creative assets only), sv, th (iStock only), tr, uk (iStock only), vi (iStock only), zh-HK (creative assets only).'
      - name: assetId
        in: path
        description: Getty Images assetId - examples 520621493, 112301284
        required: true
        schema:
          type:
          - string
          - 'null'
          description: Getty Images assetId - examples 520621493, 112301284
      requestBody:
        description: "Structure that specifies an array of LicenseTypes (multiseat, unlimited, resale, indemnification) to acquire,\n            and whether or not to use Team Credits. Authenticated User must have access to Team Credits if UseTeamCredits is set to \"true\"."
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/AcquireAssetLicensesRequest'
      responses:
        '200':
          description: Success
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/AssetLicensingResponse'
        '400':
          description: InvalidRequestParameters
        '401':
          description: AuthorizationTokenRequired
        '402':
          description: NotEnoughCreditsForPurchase
        '404':
          description: StandardLicenseNotFound
      operationId: postV3AssetLicensingByAssetId
      x-operation-id-source: derived
  /v3/asset-management/assets/send-events:
    get:
      tags:
      - Assets
      parameters:
      - name: Accept-Language
        in: header
        description: 'Provide a header to specify the language of result values. Supported values: cs (iStock only), de, en-GB, en-US, es, fi (iStock only), fr, hu (iStock only), id (iStock only), it, ja, ko (creative assets only), nl, pl (creative assets only), pt-BR, pt-PT, ro (iStock only), ru (creative assets only), sv, th (iStock only), tr, uk (iStock only), vi (iStock only), zh-HK (creative assets only).'
        schema:
          type: string
          description: 'Provide a header to specify the language of result values. Supported values: cs (iStock only), de, en-GB, en-US, es, fi (iStock only), fr, hu (iStock only), id (iStock only), it, ja, ko (creative assets only), nl, pl (creative assets only), pt-BR, pt-PT, ro (iStock only), ru (creative assets only), sv, th (iStock only), tr, uk (iStock only), vi (iStock only), zh-HK (creative assets only).'
      - name: last_offset
        in: query
        description: 'Specifies a date/time (with timezone information) for continuing retrieval of events.

          Events occuring _after_ the `last_offset` value provided will be returned.'
        schema:
          type:
          - string
          - 'null'
          description: 'Specifies a date/time (with timezone information) for continuing retrieval of events.

            Events occuring _after_ the `last_offset` value provided will be returned.'
          format: date-time
      - name: event_count
        in: query
        description: Specifies the number of events to return. Default is 50, maximum value is 100.
        schema:
          type:
          - integer
          - 'null'
          description: Specifies the number of events to return. Default is 50, maximum value is 100.
          format: int32
      responses:
        '200':
          description: Success
          content:
            text/plain:
              schema:
                $ref: '#/components/schemas/GetSendEventsResponse'
            application/json:
              schema:
                $ref: '#/components/schemas/GetSendEventsResponse'
            text/json:
              schema:
                $ref: '#/components/schemas/GetSendEventsResponse'
        '400':
          description: EventCountOutOfRange
      summary: Get asset management assets send events
      x-summary-source: derived
      operationId: getV3AssetManagementAssetsSendEvents
      x-operation-id-source: derived
components:
  schemas:
    AssetType:
      enum:
      - NotSet
      - Image
      - Film
      - Music
      type: string
    Channel:
      type: object
      properties:
        ChannelId:
          type: integer
          format: int32
        AssetFamily:
          $ref: '#/components/schemas/AssetFamily'
        AssetChangeType:
          type:
          - string
          - 'null'
        CreateDateUtc:
          type: string
          format: date-time
        NotificationCount:
          type: integer
          format: int32
        AssetType:
          $ref: '#/components/schemas/AssetType'
        OldestChangeNotificationDateUtc:
          type: string
          format: date-time
        Metadata:
          type:
          - string
          - 'null'
      additionalProperties: false
    AcquireAssetLicensesRequest:
      required:
      - extended_licenses
      type: object
      properties:
        extended_licenses:
          type: array
          items:
            $ref: '#/components/schemas/ExtendedLicenses'
        use_team_credits:
          type: boolean
          description: Defaults to false.
      additionalProperties: false
    AssetFamily:
      enum:
      - NotSet
      - Editorial
      - Creative
      - Both
      type: string
    AssetEvent:
      type: object
      properties:
        timestamp:
          type: string
          format: date-time
        asset_id:
          type:
          - string
          - 'null'
        email_address:
          type:
          - string
          - 'null'
      additionalProperties: false
    AssetLicensingResponse:
      type: object
      properties:
        credits_used:
          type: integer
          format: int32
        acquired_licenses:
          type:
          - array
          - 'null'
          items:
            $ref: '#/components/schemas/ExtendedLicenses'
      additionalProperties: false
    ChangedAssetDetail:
      type: object
      properties:
        asset_changed_utc_datetime:
          type: string
          description: Contains the date of the asset change.
          format: date-time
        asset_lifecycle:
          type:
          - string
          - 'null'
          description: Contains the type of change this asset change is. (i.e. "New," "Updated" or "Deleted")
        asset_type:
          type:
          - string
          - 'null'
          description: Contains the type of asset this asset change is (i.e. "Image").
        id:
          type:
          - string
          - 'null'
          description: Contains the Id for the asset change.
        uri:
          type:
          - string
          - 'null'
          description: Contains the asset download URL for assets with an AssetLifecycle of "New."
      additionalProperties: false
    ExtendedLicenses:
      enum:
      - multiseat
      - unlimited
      - resale
      - indemnification
      type: string
    GetSendEventsResponse:
      type: object
      properties:
        last_offset:
          type:
          - string
          - 'null'
          format: date-time
        asset_send_events:
          type:
          - array
          - 'null'
          items:
            $ref: '#/components/schemas/AssetEvent'
      additionalProperties: false
    AssetChanges:
      type: object
      properties:
        change_set_id:
          type:
          - string
          - 'null'
          description: Contains the identifier for the change-set resource. Passed into ConfirmAssetChanges requests to confirm receipt of the asset changes in the response.
        changed_assets:
          type:
          - array
          - 'null'
          items:
            $ref: '#/components/schemas/ChangedAssetDetail'
          description: Contains a list of ChangedAssetList results for the query.
      additionalProperties: false
  securitySchemes:
    Api-Key:
      type: apiKey
      name: Api-Key
      in: header
    OAuth2:
      type: oauth2
      flows:
        password:
          tokenUrl: https://api.gettyimages.com/v4/oauth2/token
          refreshUrl: https://api.gettyimages.com/v4/oauth2/token
          scopes: {}
        clientCredentials:
          tokenUrl: https://api.gettyimages.com/v4/oauth2/token
          scopes: {}
        authorizationCode:
          authorizationUrl: https://api.gettyimages.com/v4/oauth2/auth
          tokenUrl: https://api.gettyimages.com/v4/oauth2/token
          refreshUrl: https://api.gettyimages.com/v4/oauth2/token
          scopes: {}