{
 "openapi": "3.1.0",
 "info": {
  "title": "Art Spotter - Eye of the Beholder",
  "version": "1.0.0",
  "description": "Art Spotter finds original art and prints sold directly by independent artists, and helps artists sell. One search covers about 21,000 works in 190 independent artists' own shops (checked live for availability) and eBay art, with search links for Saatchi Art, Etsy, Artfinder and Singulart. It also gives a fair price for new work by size and medium, wall sizing, scam checks, what each selling platform leaves an artist after fees, commission pricing and contract points, open calls and grants in the UK, US and Canada, UK resale royalty maths, and a free artwork passport. Every answer has a say field with a ready-made summary. Nothing about users is stored.",
  "contact": {
   "name": "Art Spotter",
   "email": "artspotter@goodturnstudio.com",
   "url": "https://artspotter.pages.dev"
  },
  "license": {
   "name": "Free to use; see terms",
   "url": "https://artspotter.pages.dev/terms"
  }
 },
 "servers": [
  {
   "url": "https://artspotter.pages.dev/v1"
  }
 ],
 "paths": {
  "/search": {
   "get": {
    "operationId": "searchArt",
    "summary": "Find art for sale from independent artists",
    "description": "Searches works in independent artists' own shops and eBay art by words (subject, style, place, artist), kind, original or print, price, size and colour. Results show title, artist, size, price, where it ships from, an image and a link to buy straight from the artist.",
    "parameters": [
     {
      "name": "q",
      "in": "query",
      "required": false,
      "description": "What to look for, for example abstract blue, linocut bird, Scottish landscape or a dog portrait.",
      "schema": {
       "type": "string"
      }
     },
     {
      "name": "kind",
      "in": "query",
      "required": false,
      "description": "painting, print, printmaking, photography, drawing, watercolour, ceramics, sculpture, textile, illustration or other.",
      "schema": {
       "type": "string",
       "enum": [
        "painting",
        "print",
        "printmaking",
        "photography",
        "drawing",
        "watercolour",
        "ceramics",
        "sculpture",
        "textile",
        "illustration",
        "other"
       ]
      }
     },
     {
      "name": "original",
      "in": "query",
      "required": false,
      "description": "true for one-off originals only, false for prints only.",
      "schema": {
       "type": "boolean"
      }
     },
     {
      "name": "max_price",
      "in": "query",
      "required": false,
      "description": "Highest price, in the currency given (or the buyer's local currency).",
      "schema": {
       "type": "number"
      }
     },
     {
      "name": "min_price",
      "in": "query",
      "required": false,
      "description": "Lowest price.",
      "schema": {
       "type": "number"
      }
     },
     {
      "name": "currency",
      "in": "query",
      "required": false,
      "description": "Currency for prices, for example USD, GBP or EUR.",
      "schema": {
       "type": "string"
      }
     },
     {
      "name": "min_size",
      "in": "query",
      "required": false,
      "description": "Smallest longest side, in unit.",
      "schema": {
       "type": "number"
      }
     },
     {
      "name": "max_size",
      "in": "query",
      "required": false,
      "description": "Largest longest side, in unit.",
      "schema": {
       "type": "number"
      }
     },
     {
      "name": "unit",
      "in": "query",
      "required": false,
      "description": "in or cm. Defaults to in.",
      "schema": {
       "type": "string",
       "enum": [
        "in",
        "cm"
       ]
      }
     },
     {
      "name": "colour",
      "in": "query",
      "required": false,
      "description": "A main colour, for example blue or ochre.",
      "schema": {
       "type": "string"
      }
     },
     {
      "name": "country",
      "in": "query",
      "required": false,
      "description": "Buyer's two-letter country code, for eBay and currency, for example US or GB.",
      "schema": {
       "type": "string"
      }
     },
     {
      "name": "ships_from",
      "in": "query",
      "required": false,
      "description": "Only artists based in this two-letter country.",
      "schema": {
       "type": "string"
      }
     },
     {
      "name": "limit",
      "in": "query",
      "required": false,
      "description": "How many results, 1 to 20.",
      "schema": {
       "type": "integer"
      }
     }
    ],
    "responses": {
     "200": {
      "description": "Works for sale with a say line"
     }
    }
   }
  },
  "/fair_price": {
   "get": {
    "operationId": "getFairArtPrice",
    "summary": "Fair price for a new artwork by size and medium",
    "description": "What original work or prints of about this size and kind sell for in independent artists' own shops: the typical price, the middle half of prices and the price per square inch, from comparable works for sale.",
    "parameters": [
     {
      "name": "width",
      "in": "query",
      "required": true,
      "description": "Width, in unit.",
      "schema": {
       "type": "number"
      }
     },
     {
      "name": "height",
      "in": "query",
      "required": true,
      "description": "Height, in unit.",
      "schema": {
       "type": "number"
      }
     },
     {
      "name": "unit",
      "in": "query",
      "required": false,
      "description": "in or cm.",
      "schema": {
       "type": "string",
       "enum": [
        "in",
        "cm"
       ]
      }
     },
     {
      "name": "kind",
      "in": "query",
      "required": false,
      "description": "Kind of work. Defaults to painting.",
      "schema": {
       "type": "string",
       "enum": [
        "painting",
        "print",
        "printmaking",
        "photography",
        "drawing",
        "watercolour",
        "ceramics",
        "sculpture",
        "textile",
        "illustration",
        "other"
       ]
      }
     },
     {
      "name": "original",
      "in": "query",
      "required": false,
      "description": "true for originals (the default), false for prints.",
      "schema": {
       "type": "boolean"
      }
     },
     {
      "name": "currency",
      "in": "query",
      "required": false,
      "description": "Currency for the answer, for example USD or GBP.",
      "schema": {
       "type": "string"
      }
     }
    ],
    "responses": {
     "200": {
      "description": "Price range"
     }
    }
   }
  },
  "/where_to_sell": {
   "get": {
    "operationId": "compareWhereToSell",
    "summary": "What an artist keeps on each selling platform",
    "description": "For a sale price, what the artist keeps after fees on Etsy, eBay, Saatchi Art, Artfinder, Singulart, their own Shopify shop and direct card payments, sorted by money kept, with print-on-demand options for prints. US and UK fee tables.",
    "parameters": [
     {
      "name": "price",
      "in": "query",
      "required": true,
      "description": "The price the buyer pays.",
      "schema": {
       "type": "number"
      }
     },
     {
      "name": "currency",
      "in": "query",
      "required": false,
      "description": "USD or GBP.",
      "schema": {
       "type": "string",
       "enum": [
        "USD",
        "GBP"
       ]
      }
     },
     {
      "name": "shipping",
      "in": "query",
      "required": false,
      "description": "Shipping charged to the buyer, if any.",
      "schema": {
       "type": "number"
      }
     },
     {
      "name": "kind",
      "in": "query",
      "required": false,
      "description": "original (the default) or print.",
      "schema": {
       "type": "string",
       "enum": [
        "original",
        "print"
       ]
      }
     }
    ],
    "responses": {
     "200": {
      "description": "Options"
     }
    }
   }
  },
  "/commission_price": {
   "get": {
    "operationId": "priceCommission",
    "summary": "Price and terms for commissioning a piece",
    "description": "A price guide for a commissioned piece by size and the artist's level, what similar finished originals sell for, the usual deposit, revision rounds, cancellation fees, copyright and a contract checklist for buyer and artist.",
    "parameters": [
     {
      "name": "width",
      "in": "query",
      "required": true,
      "description": "Width, in unit.",
      "schema": {
       "type": "number"
      }
     },
     {
      "name": "height",
      "in": "query",
      "required": true,
      "description": "Height, in unit.",
      "schema": {
       "type": "number"
      }
     },
     {
      "name": "unit",
      "in": "query",
      "required": false,
      "description": "in or cm.",
      "schema": {
       "type": "string",
       "enum": [
        "in",
        "cm"
       ]
      }
     },
     {
      "name": "medium",
      "in": "query",
      "required": false,
      "description": "Kind of work, for example painting or drawing.",
      "schema": {
       "type": "string"
      }
     },
     {
      "name": "level",
      "in": "query",
      "required": false,
      "description": "emerging (the default), mid or established.",
      "schema": {
       "type": "string",
       "enum": [
        "emerging",
        "mid",
        "established"
       ]
      }
     }
    ],
    "responses": {
     "200": {
      "description": "Price guide and checklist"
     }
    }
   }
  },
  "/wall_fit": {
   "get": {
    "operationId": "sizeArtForWall",
    "summary": "What size art fits a wall and how high to hang it",
    "description": "Art width for the furniture or wall, the hanging height, the gap above furniture and gallery wall spacing, with a ready search for works in that size range.",
    "parameters": [
     {
      "name": "furniture_width",
      "in": "query",
      "required": false,
      "description": "Width of the sofa, bed or sideboard below the art.",
      "schema": {
       "type": "number"
      }
     },
     {
      "name": "wall_width",
      "in": "query",
      "required": false,
      "description": "Width of the wall, if there's no furniture below.",
      "schema": {
       "type": "number"
      }
     },
     {
      "name": "unit",
      "in": "query",
      "required": false,
      "description": "in or cm.",
      "schema": {
       "type": "string",
       "enum": [
        "in",
        "cm"
       ]
      }
     }
    ],
    "responses": {
     "200": {
      "description": "Sizing"
     }
    }
   }
  },
  "/open_calls": {
   "get": {
    "operationId": "listOpenCalls",
    "summary": "Open calls, prizes and residencies for artists",
    "description": "Recurring open exhibitions, prizes, residencies and listing sites in the UK, US and Canada, with entry fees, usual closing month, media and official links.",
    "parameters": [
     {
      "name": "country",
      "in": "query",
      "required": false,
      "description": "UK, US or CA.",
      "schema": {
       "type": "string"
      }
     },
     {
      "name": "media",
      "in": "query",
      "required": false,
      "description": "For example painting, watercolour, print or photography.",
      "schema": {
       "type": "string"
      }
     },
     {
      "name": "kind",
      "in": "query",
      "required": false,
      "description": "open call, prize, residency or listing hub.",
      "schema": {
       "type": "string"
      }
     }
    ],
    "responses": {
     "200": {
      "description": "Open calls"
     }
    }
   }
  },
  "/artist_money": {
   "get": {
    "operationId": "getArtistFunding",
    "summary": "Grants, buyer finance, royalties and copyright for artists",
    "description": "For the UK: arts council grants, Own Art 0% buyer finance and the Artist's Resale Right. For the US: grants and the $85 group copyright registration for 2 to 20 artworks.",
    "parameters": [
     {
      "name": "country",
      "in": "query",
      "required": false,
      "description": "GB or US.",
      "schema": {
       "type": "string"
      }
     }
    ],
    "responses": {
     "200": {
      "description": "Funding and rights"
     }
    }
   }
  },
  "/resale_royalty": {
   "get": {
    "operationId": "calculateResaleRoyalty",
    "summary": "UK Artist's Resale Right on a resale",
    "description": "The royalty owed to an artist on a UK resale through a gallery, dealer or auction house, by band, with the cap and who collects it.",
    "parameters": [
     {
      "name": "price",
      "in": "query",
      "required": true,
      "description": "Resale price in pounds.",
      "schema": {
       "type": "number"
      }
     }
    ],
    "responses": {
     "200": {
      "description": "Royalty"
     }
    }
   }
  },
  "/scam_check": {
   "get": {
    "operationId": "checkArtListing",
    "summary": "Check an art listing before buying",
    "description": "Whether a link is an independent artist in the index or a marketplace with buyer protection, reverse image search links for the picture, and the checks that catch stolen images, AI work sold as hand-made and payment scams.",
    "parameters": [
     {
      "name": "url",
      "in": "query",
      "required": false,
      "description": "The listing or shop address.",
      "schema": {
       "type": "string"
      }
     },
     {
      "name": "image",
      "in": "query",
      "required": false,
      "description": "The address of the artwork's picture.",
      "schema": {
       "type": "string"
      }
     }
    ],
    "responses": {
     "200": {
      "description": "Checks"
     }
    }
   }
  },
  "/passport": {
   "get": {
    "operationId": "makeArtworkPassport",
    "summary": "A free artwork passport for an artist's work",
    "description": "Makes a certificate for a work (title, artist, year, medium, size, edition) with a fingerprint of its picture, as printable text and schema.org data the artist can publish, so anyone can later check the picture is unchanged.",
    "parameters": [
     {
      "name": "image",
      "in": "query",
      "required": true,
      "description": "The https address of the work's picture.",
      "schema": {
       "type": "string"
      }
     },
     {
      "name": "title",
      "in": "query",
      "required": true,
      "description": "Title of the work.",
      "schema": {
       "type": "string"
      }
     },
     {
      "name": "artist",
      "in": "query",
      "required": true,
      "description": "Artist's name.",
      "schema": {
       "type": "string"
      }
     },
     {
      "name": "year",
      "in": "query",
      "required": false,
      "description": "Year made.",
      "schema": {
       "type": "string"
      }
     },
     {
      "name": "medium",
      "in": "query",
      "required": false,
      "description": "For example oil on canvas.",
      "schema": {
       "type": "string"
      }
     },
     {
      "name": "size",
      "in": "query",
      "required": false,
      "description": "For example 60 x 90 cm.",
      "schema": {
       "type": "string"
      }
     },
     {
      "name": "edition",
      "in": "query",
      "required": false,
      "description": "For example 3/25, for prints.",
      "schema": {
       "type": "string"
      }
     }
    ],
    "responses": {
     "200": {
      "description": "Passport"
     }
    }
   }
  },
  "/passport_verify": {
   "get": {
    "operationId": "verifyArtworkPassport",
    "summary": "Check a picture matches an artwork passport",
    "description": "Recomputes the picture's fingerprint and says whether it matches the one in the passport.",
    "parameters": [
     {
      "name": "image",
      "in": "query",
      "required": true,
      "description": "The https address of the picture.",
      "schema": {
       "type": "string"
      }
     },
     {
      "name": "sha256",
      "in": "query",
      "required": true,
      "description": "The fingerprint from the passport.",
      "schema": {
       "type": "string"
      }
     }
    ],
    "responses": {
     "200": {
      "description": "Match result"
     }
    }
   }
  },
  "/feed_check": {
   "get": {
    "operationId": "checkArtworksFeed",
    "summary": "Check an artist's artworks.json",
    "description": "Reads an artist's artworks.json (the open format at artspotter.pages.dev/artworks that lets assistants find work sold direct) and lists anything to fix.",
    "parameters": [
     {
      "name": "url",
      "in": "query",
      "required": true,
      "description": "The https address of the artworks.json file.",
      "schema": {
       "type": "string"
      }
     }
    ],
    "responses": {
     "200": {
      "description": "Validation result"
     }
    }
   }
  }
 }
}