Artsy Public API

# Artsy Public API — Swagger 2.0 contract harvested verbatim from the provider.
# source: https://api.artsy.net/api/docs/ (HTTP 200, application/json, fetched 2026-09-07)
# method: searched — YAML serialization of openapi/_original/artsy-public-api-swagger-original.json.
# Content is unmodified; no operations, parameters or responses were added.
info:
  title: Artsy Public API
  termsOfService: https://developers.artsy.net/terms
  contact:
    name: Artsy API Developers
    email: artsy-api-developers@googlegroups.com
    url: https://developers.artsy.net
  version: v2
swagger: '2.0'
produces:
- application/hal+json
- application/json
host: api.artsy.net
tags:
- name: artists
  description: Operations about artists
- name: artworks
  description: Operations about artworks
- name: applications
  description: Operations about applications
- name: bidders
  description: Operations about bidders
- name: bidder_positions
  description: Operations about bidder_positions
- name: collection_items
  description: Operations about collection_items
- name: collector_profiles
  description: Operations about collector_profiles
- name: devices
  description: Operations about devices
- name: editions
  description: Operations about editions
- name: fairs
  description: Operations about fairs
- name: genes
  description: Operations about genes
- name: images
  description: Operations about images
- name: lot_standings
  description: Operations about lot_standings
- name: partner_communications
  description: Operations about partner_communications
- name: partner_contacts
  description: Operations about partner_contacts
- name: partners
  description: Operations about partners
- name: profiles
  description: Operations about profiles
- name: sale_artworks
  description: Operations about sale_artworks
- name: sales
  description: Operations about sales
- name: search
  description: Operations about searches
- name: shows
  description: Operations about shows
- name: status
  description: Operations about statuses
- name: tokens
  description: Operations about tokens
- name: user_details
  description: Operations about user_details
- name: user_fair_actions
  description: Operations about user_fair_actions
- name: users
  description: Operations about users
- name: current_user
  description: Operations about current_users
paths:
  /api/artists:
    get:
      description: Retrieve a collection of artists.
      produces:
      - application/json
      parameters:
      - in: query
        name: artwork_id
        description: Return artists for a given artwork.
        type: string
        required: false
      - in: query
        name: sale_id
        description: Return artists appearing in a given sale
        type: string
        required: false
      - in: query
        name: similar_to_artist_id
        description: Return artists similar to a given artist.
        type: string
        required: false
      - in: query
        name: similarity_type
        description: Similarity type.
        type: string
        enum:
        - default
        - contemporary
        required: false
      - in: query
        name: gene_id
        description: Return a set of artists that represent a given gene.
        type: string
        required: false
      - in: query
        name: artworks
        description: Only return artists with artworks.
        type: boolean
        required: false
      - in: query
        name: published_artworks
        description: Only return artists with published artworks.
        type: boolean
        required: false
      - in: query
        name: partner_id
        description: Return artists with artworks that belong to the partner.
        type: string
        required: false
      - in: query
        name: sort
        description: Sort order.
        type: string
        enum:
        - _slugs
        - -_slugs
        - created_at
        - -created_at
        - sortable_id
        - -sortable_id
        - -trending
        required: false
      - in: query
        name: offset
        description: Offset from which to retrieve.
        type: integer
        format: int32
        required: false
      - in: query
        name: size
        description: Maximum number of items to retrieve.
        type: integer
        format: int32
        default: 5
        required: false
      - in: query
        name: cursor
        description: Cursor for pagination.
        type: string
        required: false
      - in: query
        name: sample
        description: If present and collection supports sampling, will redirect to a random single object.
        type: string
        required: false
      - in: query
        name: term
        description: Term to match.
        type: string
        required: false
      - in: query
        name: page
        description: Page to retrieve.
        type: integer
        format: int32
        default: 1
        required: false
      - in: query
        name: exact
        description: Find an exact match.
        type: boolean
        default: false
        required: false
      responses:
        '200':
          description: Retrieve a collection of artists.
      tags:
      - artists
      operationId: getApiArtists
  /api/artists/{id}:
    get:
      description: Retrieve an artist by id.
      produces:
      - application/json
      parameters:
      - in: path
        name: id
        description: Artist id.
        type: string
        required: true
      responses:
        '200':
          description: Retrieve an artist by id.
      tags:
      - artists
      operationId: getApiArtistsId
  /api/artworks:
    get:
      description: Retrieve a collection of artworks.
      produces:
      - application/json
      parameters:
      - in: query
        name: offset
        description: Offset from which to retrieve.
        type: integer
        format: int32
        required: false
      - in: query
        name: size
        description: Maximum number of items to retrieve.
        type: integer
        format: int32
        default: 5
        required: false
      - in: query
        name: cursor
        description: Cursor for pagination.
        type: string
        required: false
      - in: query
        name: sample
        description: If present and collection supports sampling, will redirect to a random single object.
        type: string
        required: false
      - in: query
        name: term
        description: Term to match.
        type: string
        required: false
      - in: query
        name: page
        description: Page to retrieve.
        type: integer
        format: int32
        default: 1
        required: false
      - in: query
        name: exact
        description: Find an exact match.
        type: boolean
        default: false
        required: false
      - in: query
        name: artist_id
        description: Only return artworks by this artist.
        type: string
        required: false
      - in: query
        name: partner_id
        description: Only return artworks belonging to this partner.
        type: string
        required: false
      - in: query
        name: show_id
        description: Only return artworks at this show.
        type: string
        required: false
      - in: query
        name: collection_id
        description: Only return artworks within a collection.
        type: string
        required: false
      - in: query
        name: user_id
        description: Only return artworks within a collection that belongs to this user.
        type: string
        required: false
      - in: query
        name: similar_to_artwork_id
        description: Return artworks similar to this artwork.
        type: string
        required: false
      - in: query
        name: published
        description: Retrieve all published artworks.
        type: boolean
        required: false
      responses:
        '200':
          description: Retrieve a collection of artworks.
      tags:
      - artworks
      operationId: getApiArtworks
  /api/artworks/{id}:
    get:
      description: Retrieve an artwork by id.
      produces:
      - application/json
      parameters:
      - in: path
        name: id
        description: Artwork id.
        type: string
        required: true
      responses:
        '200':
          description: Retrieve an artwork by id.
      tags:
      - artworks
      operationId: getApiArtworksId
  /api/applications:
    get:
      description: Retrieve a collection of applications.
      produces:
      - application/json
      parameters:
      - in: query
        name: offset
        description: Offset from which to retrieve.
        type: integer
        format: int32
        required: false
      - in: query
        name: size
        description: Number of items to retrieve for this page or from the current offset.
        type: string
        required: false
      - in: query
        name: cursor
        description: Cursor for pagination.
        type: string
        required: false
      - in: query
        name: user_id
        description: User id.
        type: string
        required: false
      responses:
        '200':
          description: Retrieve a collection of applications.
      tags:
      - applications
      operationId: getApiApplications
    post:
      description: Create an application.
      produces:
      - application/json
      consumes:
      - application/json
      parameters:
      - name: postApiApplications
        in: body
        required: true
        schema:
          $ref: '#/definitions/postApiApplications'
      responses:
        '201':
          description: Create an application.
      tags:
      - applications
      operationId: postApiApplications
  /api/applications/{id}:
    get:
      description: Retrieve an application by id.
      produces:
      - application/json
      parameters:
      - in: path
        name: id
        description: Application id.
        type: string
        required: true
      responses:
        '200':
          description: Retrieve an application by id.
      tags:
      - applications
      operationId: getApiApplicationsId
    put:
      description: Update an application.
      produces:
      - application/json
      consumes:
      - application/json
      parameters:
      - in: path
        name: id
        description: Application id.
        type: string
        required: true
      - name: putApiApplicationsId
        in: body
        required: true
        schema:
          $ref: '#/definitions/putApiApplicationsId'
      responses:
        '200':
          description: Update an application.
      tags:
      - applications
      operationId: putApiApplicationsId
    delete:
      description: Delete an application.
      produces:
      - application/json
      parameters:
      - in: path
        name: id
        description: Application id.
        type: string
        required: true
      responses:
        '204':
          description: Delete an application.
      tags:
      - applications
      operationId: deleteApiApplicationsId
  /api/bidders/{id}:
    get:
      description: Retrieve a bidder by id.
      produces:
      - application/json
      parameters:
      - in: path
        name: id
        description: Bidder id.
        type: string
        required: true
      responses:
        '200':
          description: Retrieve a bidder by id.
      tags:
      - bidders
      operationId: getApiBiddersId
  /api/bidders:
    get:
      description: Retrieve bidders.
      produces:
      - application/json
      parameters:
      - in: query
        name: offset
        description: Offset from which to retrieve.
        type: integer
        format: int32
        required: false
      - in: query
        name: size
        description: Number of items to retrieve for this page or from the current offset.
        type: string
        required: false
      - in: query
        name: cursor
        description: Cursor for pagination.
        type: string
        required: false
      - in: query
        name: sale_id
        description: Sale id.
        type: string
        required: true
      - in: query
        name: with_positions
        description: When true, return only bidders with positions in given sale (sale_id required).
        type: boolean
        required: false
      - in: query
        name: sort
        description: Sort order.
        type: string
        enum:
        - created_at
        - -created_at
        - -last_bid_placed_at
        required: false
      responses:
        '200':
          description: Retrieve bidders.
      tags:
      - bidders
      operationId: getApiBidders
  /api/bidder_positions/{id}:
    get:
      description: Retrieve a bidder position.
      produces:
      - application/json
      parameters:
      - in: path
        name: id
        description: Position id.
        type: string
        required: true
      responses:
        '200':
          description: Retrieve a bidder position.
      tags:
      - bidder_positions
      operationId: getApiBidderPositionsId
  /api/collection_items/{id}:
    get:
      description: Retrieve a collection item by id.
      produces:
      - application/json
      parameters:
      - in: path
        name: id
        description: Collection item id.
        type: string
        required: true
      - in: query
        name: collection_id
        description: Collection id.
        type: string
        required: true
      - in: query
        name: user_id
        description: User id.
        type: string
        required: true
      responses:
        '200':
          description: Retrieve a collection item by id.
      tags:
      - collection_items
      operationId: getApiCollectionItemsId
  /api/collection_items:
    get:
      description: Retrieve collection items.
      produces:
      - application/json
      parameters:
      - in: query
        name: offset
        description: Offset from which to retrieve.
        type: integer
        format: int32
        required: false
      - in: query
        name: size
        description: Number of items to retrieve for this page or from the current offset.
        type: string
        required: false
      - in: query
        name: cursor
        description: Cursor for pagination.
        type: string
        required: false
      - in: query
        name: collection_id
        description: Collection id. (used with user_id)
        type: string
        required: false
      - in: query
        name: user_id
        description: User id.
        type: string
        required: false
      - in: query
        name: artwork_id
        description: Artwork id.
        type: string
        required: false
      responses:
        '200':
          description: Retrieve collection items.
      tags:
      - collection_items
      operationId: getApiCollectionItems
  /api/collector_profiles:
    get:
      description: Retrieve collector profiles.
      produces:
      - application/json
      parameters:
      - in: query
        name: owner_id
        description: Only return the collector profile for a given user or anonymous session.
        type: string
        required: false
      - in: query
        name: offset
        description: Offset from which to retrieve.
        type: integer
        format: int32
        required: false
      - in: query
        name: size
        description: Number of items to retrieve for this page or from the current offset.
        type: string
        required: false
      - in: query
        name: cursor
        description: Cursor for pagination.
        type: string
        required: false
      - in: query
        name: sample
        description: If present and collection supports sampling, will redirect to a random single object.
        type: string
        required: false
      responses:
        '200':
          description: Retrieve collector profiles.
      tags:
      - collector_profiles
      operationId: getApiCollectorProfiles
  /api/collector_profiles/{id}:
    get:
      description: Retrieve a collector profile.
      produces:
      - application/json
      parameters:
      - in: path
        name: id
        description: Collector profile id.
        type: string
        required: true
      responses:
        '200':
          description: Retrieve a collector profile.
      tags:
      - collector_profiles
      operationId: getApiCollectorProfilesId
  /api/devices:
    get:
      description: Retrieve devices.
      produces:
      - application/json
      parameters:
      - in: query
        name: offset
        description: Offset from which to retrieve.
        type: integer
        format: int32
        required: false
      - in: query
        name: size
        description: Number of items to retrieve for this page or from the current offset.
        type: string
        required: false
      - in: query
        name: cursor
        description: Cursor for pagination.
        type: string
        required: false
      - in: query
        name: user_id
        description: User id.
        type: string
        required: false
      - in: query
        name: app_id
        description: Filter to devices matching specified app_ids
        type: array
        items:
          type: string
        required: false
      responses:
        '200':
          description: Retrieve devices.
      tags:
      - devices
      operationId: getApiDevices
  /api/devices/{id}:
    get:
      description: Retrieve individual device.
      produces:
      - application/json
      parameters:
      - in: path
        name: id
        description: Device id.
        type: string
        required: true
      responses:
        '200':
          description: Retrieve individual device.
      tags:
      - devices
      operationId: getApiDevicesId
    delete:
      description: Delete individual device.
      produces:
      - application/json
      parameters:
      - in: path
        name: id
        description: Device id.
        type: string
        required: true
      responses:
        '204':
          description: Delete individual device.
      tags:
      - devices
      operationId: deleteApiDevicesId
  /api/editions:
    get:
      description: Retrieve a collection of edition sets.
      produces:
      - application/json
      parameters:
      - in: query
        name: offset
        description: Offset from which to retrieve.
        type: integer
        format: int32
        required: false
      - in: query
        name: size
        description: Number of items to retrieve for this page or from the current offset.
        type: string
        required: false
      - in: query
        name: cursor
        description: Cursor for pagination.
        type: string
        required: false
      - in: query
        name: artwork_id
        description: Artwork id.
        type: string
        required: true
      - in: query
        name: public
        description: Only return editions of artworks publicly available via the API.
        type: boolean
        default: false
        required: false
      responses:
        '200':
          description: Retrieve a collection of edition sets.
      tags:
      - editions
      operationId: getApiEditions
  /api/editions/{id}:
    get:
      description: Retrieve an edition set for an artwork by id.
      produces:
      - application/json
      parameters:
      - in: path
        name: id
        description: Edition set id.
        type: string
        required: true
      - in: query
        name: artwork_id
        description: Artwork id.
        type: string
        required: true
      responses:
        '200':
          description: Retrieve an edition set for an artwork by id.
      tags:
      - editions
      operationId: getApiEditionsId
  /api/fairs:
    get:
      description: Retrieve a collection of fairs.
      produces:
      - application/json
      parameters:
      - in: query
        name: status
        type: string
        enum:
        - current
        - running
        - closed
        - upcoming
        - running_and_upcoming
        - closing_soon
        - active
        required: false
      - in: query
        name: offset
        description: Offset from which to retrieve.
        type: integer
        format: int32
        required: false
      - in: query
        name: size
        description: Number of items to retrieve for this page or from the current offset.
        type: string
        required: false
      - in: query
        name: cursor
        description: Cursor for pagination.
        type: string
        required: false
      - in: query
        name: sample
        description: If present and collection supports sampling, will redirect to a random single object.
        type: string
        required: false
      - in: query
        name: sort
        description: Sort order.
        type: string
        enum:
        - created_at
        - -created_at
        - start_at
        - -start_at
        - name
        - -name
        required: false
      responses:
        '200':
          description: Retrieve a collection of fairs.
      tags:
      - fairs
      operationId: getApiFairs
  /api/fairs/{id}:
    get:
      description: Retrieve a fair by id.
      produces:
      - application/json
      parameters:
      - in: path
        name: id
        description: Fair id.
        type: string
        required: true
      responses:
        '200':
          description: Retrieve a fair by id.
      tags:
      - fairs
      operationId: getApiFairsId
  /api/genes:
    get:
      description: Retrieve genes.
      produces:
      - application/json
      parameters:
      - in: query
        name: artist_id
        description: Return genes of a given artist.
        type: string
        required: false
      - in: query
        name: artwork_id
        description: Return genes of a given artwork.
        type: string
        required: false
      - in: query
        name: offset
        description: Offset from which to retrieve.
        type: integer
        format: int32
        required: false
      - in: query
        name: size
        description: Number of items to retrieve for this page or from the current offset.
        type: string
        required: false
      - in: query
        name: cursor
        description: Cursor for pagination.
        type: string
        required: false
      - in: query
        name: sample
        description: If present and collection supports sampling, will redirect to a random single object.
        type: string
        required: false
      responses:
        '200':
          description: Retrieve genes.
      tags:
      - genes
      operationId: getApiGenes
  /api/genes/{id}:
    get:
      description: Retrieve a gene by id.
      produces:
      - application/json
      parameters:
      - in: path
        name: id
        description: Gene id.
        type: string
        required: true
      responses:
        '200':
          description: Retrieve a gene by id.
      tags:
      - genes
      operationId: getApiGenesId
  /api/images:
    get:
      description: Retrieve a collection of images.
      produces:
      - application/json
      parameters:
      - in: query
        name: show_id
        description: Return images for a given show.
        type: string
        required: true
      - in: query
        name: offset
        description: Offset from which to retrieve.
        type: integer
        format: int32
        required: false
      - in: query
        name: size
        description: Number of items to retrieve for this page or from the current offset.
        type: string
        required: false
      - in: query
        name: cursor
        description: Cursor for pagination.
        type: string
        required: false
      - in: query
        name: sample
        description: If present and collection supports sampling, will redirect to a random single object.
        type: string
        required: false
      responses:
        '200':
          description: Retrieve a collection of images.
      tags:
      - images
      operationId: getApiImages
  /api/images/{id}:
    get:
      description: Retrieve an image by id.
      produces:
      - application/json
      parameters:
      - in: path
        name: id
        description: Image id.
        type: string
        required: true
      responses:
        '200':
          description: Retrieve an image by id.
      tags:
      - images
      operationId: getApiImagesId
  /api/lot_standings:
    get:
      description: Retrieve standings of individual bidders on lots.
      produces:
      - application/json
      parameters:
      - in: query
        name: bidder_id
        description: Bidder id.
        type: string
        required: true
      responses:
        '200':
          description: Retrieve standings of individual bidders on lots.
      tags:
      - lot_standings
      operationId: getApiLotStandings
  /api/partner_communications:
    get:
      description: Retrieve a collection of partner communications.
      produces:
      - application/json
      parameters:
      - in: query
        name: name
        type: string
        required: false
      - in: query
        name: offset
        description: Offset from which to retrieve.
        type: integer
        format: int32
        required: false
      - in: query
        name: size
        description: Number of items to retrieve for this page or from the current offset.
        type: string
        required: false
      - in: query
        name: cursor
        description: Cursor for pagination.
        type: string
        required: false
      responses:
        '200':
          description: Retrieve a collection of partner communications.
      tags:
      - partner_communications
      operationId: getApiPartnerCommunications
  /api/partner_communications/{id}:
    get:
      description: Retrieve a partner communication by id.
      produces:
      - application/json
      parameters:
      - in: path
        name: id
        description: Partner communication id.
        type: string
        required: true
      responses:
        '200':
          description: Retrieve a partner communication by id.
      tags:
      - partner_communications
      operationId: getApiPartnerCommunicationsId
  /api/partner_contacts:
    get:
      description: Retrieve a collection of partner contacts by partner_id.
      produces:
      - application/json
      parameters:
      - in: query
        name: partner_id
        description: Only return contacts for this partner.
        type: string
        required: false
      - in: query
        name: can_contact
        description: Only return contacts with given value for can_contact.
        type: boolean
        required: false
      - in: query
        name: partner_communication_id
        description: Only return contacts that are subscribed to this partner communication.
        type: string
        required: false
      - in: query
        name: offset
        description: Offset from which to retrieve.
        type: integer
        format: int32
        required: false
      - in: query
        name: size
        description: Number of items to retrieve for this page or from the current offset.
        type: string
        required: false
      - in: query
        name: cursor
        description: Cursor for pagination.
        type: string
        required: false
      - in: query
        name: sample
        description: If present and collection supports sampling, will redirect to a random single object.
        type: string
        required: false
      responses:
        '200':
          description: Retrieve a collection of partner contacts by partner_id.
      tags:
      - partner_contacts
      operationId: getApiPartnerContacts
  /api/partner_contacts/{id}:
    get:
      description: Retrieve a partner contact by id.
      produces:
      - application/json
      parameters:
      - in: path
        name: id
        description: Partner contact id.
        type: string
        required: true
      responses:
        '200':
          description: Retrieve a partner contact by id.
      tags:
      - partner_contacts
      operationId: getApiPartnerContactsId
  /api/partners:
    get:
      description: Retrieve a collection of partners.
      produces:
      - application/json
      parameters:
      - in: query
        name: user_id
        description: Return partners that a given user has access to.
        type: string
        required: false
      - in: query
        name: partner_id
        description: Only return this partner.
        type: string
        required: false
      - in: query
        name: eligible_for_partner_analytics
        description: Only return partners eligible for partner analytics.
        type: boolean
        required: false
      - in: query
        name: offset
        description: Offset from which to retrieve.
        type: integer
        format: int32
        required: false
      - in: query
        name: size
        description: Number of items to retrieve for this page or from the current offset.
        type: string
        required: false
      - in: query
        name: cursor
        description: Cursor for pagination.
        type: string
        required: false
      - in: query
        name: sample
        description: If present and collection supports sampling, will redirect to a random single object.
        type: string
        required: false
      responses:
        '200':
          description: Retrieve a collection of partners.
      tags:
      - partners
      operationId: getApiPartners
  /api/partners/{id}:
    get:
      description: Retrieve a partner by id.
      produces:
      - application/json
      parameters:
      - in: path
        name: id
        description: Partner id.
        type: string
        required: true
      responses:
        '200':
          description: Retrieve a partner by id.
      tags:
      - partners
      operationId: getApiPartnersId
  /api/profiles:
    get:
      description: Retrieve a collection of profiles.
      produces:
      - application/json
      parameters:
      - in: query
        name: offset
        description: Offset from which to retrieve.
        type: integer
        format: int32
        required: false
      - in: query
        name: size
        description: Number of items to retrieve for this page or from the current offset.
        type: string
        required: false
      - in: query
        name: cursor
        description: Cursor for pagination.
        type: string
        required: false
      - in: query
        name: sample
        description: If present and collection supports sampling, will redirect to a random single object.
        type: string
        required: false
      responses:
        '200':
          description: Retrieve a collection of profiles.
      tags:
      - profiles
      operationId: getApiProfiles
  /api/profiles/{id}:
    get:
      description: Retrieve a profile by id.
      produces:
      - application/json
      parameters:
      - in: path
        name: id
        description: Profile id.
        type: string
        required: true
      responses:
        '200':
          description: Retrieve a profile by id.
      tags:
      - profiles
      operationId: getApiProfilesId
  /api/sale_artworks/{id}:
    get:
      description: Retrieve a sale_artwork by id.
      produces:
      - application/json
      parameters:
      - in: path
        name: id
        description: SaleArtwork id.
        type: string
        required: true
      responses:
        '200':
          description: Retrieve a sale_artwork by id.
      tags:
      - sale_artworks
      operationId: getApiSaleArtworksId
  /api/sale_artworks:
    get:
      description: Retrieve sale artworks.
      produces:
      - application/json
      parameters:
      - in: query
        name: offset
        description: Offset from which to retrieve.
        type: integer
        format: int32
        required: false
      - in: query
        name: size
        description: Number of items to retrieve for this page or from the current offset.
        type: string
        required: false
      - in: query
        name: cursor
        description: Cursor for pagination.
        type: string
        

# --- truncated at 32 KB (44 KB total) ---
# Full source: https://raw.githubusercontent.com/api-evangelist/artsy/refs/heads/main/openapi/artsy-public-api-openapi.yml