Search artworks
search_artworksUse this when someone wants to find original paintings, prints, photographs or sculpture from independent artists: by subject, style, colour, size or budget; for a particular wall; or like a work or a photo they have. It returns only works that meet everything asked for, each with what it met. near_matches come apart, each saying what it misses or what its seller left unsaid: a blank fact is unknown, never a no. Write the request in words ("a large blue abstract painting under $2,000"; misspellings, and Spanish, Portuguese, French, Italian and German, are read) or send filters — min_price_usd, max_price_usd, orientation, subject, style, medium, colors, min_height_in, max_height_in, min_width_in, max_width_in, ships_to, framed, ready_to_hang, signed, edition — and a filter wins over the words. applied_filters lists every constraint and where it came from; understood says how each word was read (read_as, corrected); correct a misreading with a filter. A word about the work that names no constraint must appear in its own words to match ("lighthouse"). Words of mood ("calm") and of where it will hang ("hallway") only order the results; "to hang" and "a gift" are not used. A place it ships to, with its state or ZIP, is read as ships_to. fold_derived marks Fold’s reading of the seller’s words. This catalogue CANNOT be filtered by authenticity or provenance strength: Fold verifies sellers, not works (see _verification). Works on sale now; include_sold adds sold works. Attributes are the seller’s; null means unspecified, never estimated. completeness says whether every work was checked. A wall — wall: {width, height, furniture_width, furniture_height, unit} — keeps only works whose size suits it by Fold’s rules of thumb, and wall_fit gives the size range and the reasoning to relay: a rule of thumb, not a measurement of the room. With a wall, query may be left out. similar_to {artwork_id | image_url | image_base64} keeps only works that look like it, at or above Fold’s similarity threshold, the closest first, each with its similarity from 0 to 1: how alike the photographs look to an image model, not a judgement of style or quality. With similar_to, query may be left out. A photo is used for this search only and kept nowhere. Each of the first 5 matches carries offer — the impression to buy (listing_id), whether it can be bought now, its price, delivery, ship-by and arrival dates and returns — and, with the buyer’s US ZIP code in ships_to, the first 3 a delivered_estimate with sales tax. Pass offer.listing_id straight to the checkout, which checks availability itself. Every answer ends with next_actions: the next call, its ids filled in. The first 3 works shown come with a small picture of each, attached after the answer as images, so you can see how they look — colour, mood, whether one suits a room or a photo — rather than going by words alone; image.url is the full size.
Input Schema
| Name | Required | Description | Default |
|---|---|---|---|
| wall | No | The wall the work will hang on: only works whose size suits it. | |
| limit | No | Maximum matches. Default 10, hard cap 100. | |
| query | No | What the buyer is looking for, in their words. Leave it out only to search by a wall or similar_to alone. | |
| style | No | Any of these styles. | |
| colors | No | Every one of these among the colours the seller confirmed for the work. | |
| framed | No | Framed (true) or unframed (false), as the seller stated. | |
| medium | No | Any of these media; a family such as painting or print includes its members. | |
| signed | No | Signed by the artist, as the seller stated. | |
| edition | No | unique: one of a kind; edition: one impression of an edition. | |
| subject | No | Any of these subjects. | |
| ships_to | No | Where the buyer wants it delivered. Fold delivers to the 50 US states and DC. | |
| similar_to | No | A work, or a photo, the works must look like. | |
| orientation | No | Any of: portrait (taller than wide), landscape (wider than tall), square. | |
| include_sold | No | Also include works that have already sold. Off by default. Works taken off sale are never returned either way. | |
| max_width_in | No | Width at most this, in inches. | |
| min_width_in | No | Width at least this, in inches. | |
| max_height_in | No | Height at most this, in inches. | |
| max_price_usd | No | Highest acceptable price, in US dollars. | |
| min_height_in | No | Height at least this, in inches. | |
| min_price_usd | No | Lowest acceptable price, in US dollars. | |
| ready_to_hang | No | Ready to hang, as the seller stated. |