cancel_search_alert
ChatGPTUse this when a buyer wants to stop an alert for new works. Nothing more is sent, and the saved words, filters and address are erased. Needs the search_alert_id and manage_token save_search_alert gave; a buyer can also stop it from any alert e-mail in one click.
check_availability
ChatGPTUse this right before offering a buyer a specific work or impression, to confirm it can still be bought. Re-check whether specific impressions are still purchasable, immediately before presenting them to a buyer or attempting a purchase. Each work here is unique or from a small edition, so an impression can sell between search and checkout. ALWAYS call this before offering a specific impression — offering a sold original is worse than offering nothing.
find_artworks_for_wall
ChatGPTUse this when a buyer says where a work will hang — how wide and high the wall is, and the sofa, bed or sideboard below it if any — and wants to know what size suits it. It answers with the size range that suits the wall by Fold’s rules of thumb (about 60–75% of the width of what it hangs over, hung at eye level or a few inches above the furniture, with a foot of wall clear), the reasoning in plain sentences to relay, and the works on sale in that range, each with what it met. Add the buyer’s words in query, or filters such as max_price_usd, subject or colors, to narrow it. Sizes are the works’ own as their sellers stated them: a frame adds to them. The range is a rule of thumb, not a measurement of the room. Works on sale now only; completeness says whether every work was checked.
find_similar_artworks
ChatGPTUse this when a buyer wants more works that look like one they have seen — a work on Fold, or a photo they have. It answers with the works on sale whose images look like it, each with its similarity from 0 to 1, and only those at or above Fold’s threshold, the closest look first. Send artwork_id, or a photo as image_url (an https address) or image_base64 (a JPEG, PNG or WebP, at most 700 KB). Add the buyer’s words in query, or filters such as max_price_usd, to narrow it; works that look alike but miss a filter come back separately as near_matches. Similarity is how alike the photographs look to an image model, measured on the works’ public images — not a judgement of style or quality, and no claim that the same artist made them. A photo is used for this search only and kept nowhere. completeness says whether every work on sale was compared.
get_artwork
ChatGPTUse this when someone wants the full facts about one work before deciding: what it is, its size, how it looks, what delivery costs and when it ships, whether it can be returned, who made it, and what Fold verified about the seller. Full detail for one artwork: attribution, medium, dimensions, edition structure, provenance, seller, and every individual impression that can be bought with its own price and availability. A numbered edition has one entry per impression — including artist proofs (AP), printer proofs (PP), and the bon à tirer (BAT), which are separate objects from the numbered run and usually priced differently. Each entry in attributes says who stands behind it (seller_stated, fold_derived or fold_verified), and a null means unspecified rather than estimated. Also returns image URLs to show the buyer. A signed URL is TEMPORARY: honour its expires_at and re-fetch rather than caching or redistributing it. An image marked permanent is one of the work’s public images, with no expiry: a clean display copy, or, where it also says preview, a reduced copy watermarked by Fold. Use this before presenting a work to a buyer, and quote the impression label exactly as given.
get_delivered_quote
ChatGPTUse this when a buyer asks what a work will cost delivered to them and when it would arrive. Given one listing_id and a US destination (a five-digit ZIP code, and the state if known), it answers with the price, the seller’s delivery charge, an ESTIMATE of sales tax from Fold’s tax engine for that ZIP code, the total, the date the seller says it ships by and the arrival window their transit estimate gives, the returns that apply, the policy links and how to check out. Read-only: nothing is opened or reserved. Checkout calculates the exact tax from the full address before the buyer pays. Fold delivers only to the 50 US states and DC.
get_order_status
ChatGPTUse this when a buyer asks where their order is or what they can still claim. With the token from the order page’s address, or the order reference from the confirmation e-mail and the e-mail address the buyer gave at checkout, it answers with the order’s status, the tracking the seller recorded, and each return or claim window with when it closes. An order is shown only to whoever proves they placed it; an unknown order and a wrong proof get the same answer.
get_search_alert
ChatGPTUse this when a buyer asks about an alert for new works they saved: whether it is waiting for them to confirm it, active or ended, what it watches, when it last sent works and when it ends. Needs the search_alert_id and manage_token save_search_alert gave.
open_claim
ChatGPTUse this when a buyer wants to return a work or report a problem with an order: damage or a difference from the description on arrival, non-delivery, a doubt about authenticity or title, an agent purchase they did not authorise, cancelling before dispatch, or a 30-day return. It checks the ground against the Returns policy’s window for this order, records the request for a person at Fold, and answers with a link for sending photographs. It refunds nothing: a person at Fold decides every request and replies by e-mail. Needs the same proof as get_order_status.
save_search_alert
ChatGPTUse this when a buyer wants to hear about works listed later that match what they are looking for. It saves the search — the buyer’s words in query and the same filters as search_artworks — and tells the buyer by e-mail, or your own system by webhook, when a work that matches it is listed: only works that meet everything asked, never near matches, at most one alert a day, for 180 days. An e-mail alert starts only when the buyer confirms it from the one e-mail Fold sends to ask; ask the buyer before giving Fold their address. Every alert e-mail has one-click unsubscribe. A webhook alert starts once webhook_url answers a signed verification event by echoing its challenge. Works flagged as mature content are never announced here. Answers with search_alert_id and manage_token, shown once: get_search_alert reads the alert and cancel_search_alert ends it.
search_artworks
ChatGPTUse this when someone wants to find original paintings, prints, photographs or sculpture from independent artists by subject, style, colour, size or budget. It returns only works that meet everything asked for, each with what it met; works that meet only part come back separately as near_matches, each saying what it misses. A request can be written in words ("a large blue abstract painting under $2,000") or sent as 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 same thing read from the words. applied_filters lists every constraint used and where it came from; check it, and correct a misreading with a filter. A word that names no constraint must appear in a work’s own words to match ("lighthouse"); words of mood ("calm") only order the results. This catalogue CANNOT be filtered by authenticity or provenance strength: Fold verifies sellers, not works (see _verification). Works on sale now are returned; include_sold adds sold works. Attributes are as the seller stated them, and a 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; find_artworks_for_wall gives the range and why. 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.
start_checkout
ChatGPTUse this when the buyer has chosen one work and wants to buy it. It answers with checkout_url, a page on Fold’s own site for that one work, where the buyer enters the delivery address, sees the total with sales tax and the terms, and pays. It charges nothing and reserves nothing: the work can still sell to someone else until the buyer presses Pay, and the link works once and lapses at expires_at. Give the link to the buyer or open it in your browser. Call check_availability first; one listing_id per call, since each work is its own purchase. If the work has sold, or another buyer is paying for it, the refusal carries out_of_stock: what the work is now, and up to three similar works on sale here to offer the buyer instead.
cancel_search_alert
ClaudeUse this when a buyer wants to stop an alert for new works. Nothing more is sent, and the saved words, filters and address are erased. Needs the search_alert_id and manage_token save_search_alert gave; a buyer can also stop it from any alert e-mail in one click.
check_availability
ClaudeUse this right before offering a buyer a specific work or impression, to confirm it can still be bought. Re-check whether specific impressions are still purchasable, immediately before presenting them to a buyer or attempting a purchase. Each work here is unique or from a small edition, so an impression can sell between search and checkout. ALWAYS call this before offering a specific impression — offering a sold original is worse than offering nothing.
find_artworks_for_wall
ClaudeUse this when a buyer says where a work will hang — how wide and high the wall is, and the sofa, bed or sideboard below it if any — and wants to know what size suits it. It answers with the size range that suits the wall by Fold’s rules of thumb (about 60–75% of the width of what it hangs over, hung at eye level or a few inches above the furniture, with a foot of wall clear), the reasoning in plain sentences to relay, and the works on sale in that range, each with what it met. Add the buyer’s words in query, or filters such as max_price_usd, subject or colors, to narrow it. Sizes are the works’ own as their sellers stated them: a frame adds to them. The range is a rule of thumb, not a measurement of the room. Works on sale now only; completeness says whether every work was checked.
find_similar_artworks
ClaudeUse this when a buyer wants more works that look like one they have seen — a work on Fold, or a photo they have. It answers with the works on sale whose images look like it, each with its similarity from 0 to 1, and only those at or above Fold’s threshold, the closest look first. Send artwork_id, or a photo as image_url (an https address) or image_base64 (a JPEG, PNG or WebP, at most 700 KB). Add the buyer’s words in query, or filters such as max_price_usd, to narrow it; works that look alike but miss a filter come back separately as near_matches. Similarity is how alike the photographs look to an image model, measured on the works’ public images — not a judgement of style or quality, and no claim that the same artist made them. A photo is used for this search only and kept nowhere. completeness says whether every work on sale was compared.
get_artwork
ClaudeUse this when someone wants the full facts about one work before deciding: what it is, its size, how it looks, what delivery costs and when it ships, whether it can be returned, who made it, and what Fold verified about the seller. Full detail for one artwork: attribution, medium, dimensions, edition structure, provenance, seller, and every individual impression that can be bought with its own price and availability. A numbered edition has one entry per impression — including artist proofs (AP), printer proofs (PP), and the bon à tirer (BAT), which are separate objects from the numbered run and usually priced differently. Each entry in attributes says who stands behind it (seller_stated, fold_derived or fold_verified), and a null means unspecified rather than estimated. Also returns image URLs to show the buyer. A signed URL is TEMPORARY: honour its expires_at and re-fetch rather than caching or redistributing it. An image marked permanent is one of the work’s public images, with no expiry: a clean display copy, or, where it also says preview, a reduced copy watermarked by Fold. Use this before presenting a work to a buyer, and quote the impression label exactly as given.
get_delivered_quote
ClaudeUse this when a buyer asks what a work will cost delivered to them and when it would arrive. Given one listing_id and a US destination (a five-digit ZIP code, and the state if known), it answers with the price, the seller’s delivery charge, an ESTIMATE of sales tax from Fold’s tax engine for that ZIP code, the total, the date the seller says it ships by and the arrival window their transit estimate gives, the returns that apply, the policy links and how to check out. Read-only: nothing is opened or reserved. Checkout calculates the exact tax from the full address before the buyer pays. Fold delivers only to the 50 US states and DC.
get_order_status
ClaudeUse this when a buyer asks where their order is or what they can still claim. With the token from the order page’s address, or the order reference from the confirmation e-mail and the e-mail address the buyer gave at checkout, it answers with the order’s status, the tracking the seller recorded, and each return or claim window with when it closes. An order is shown only to whoever proves they placed it; an unknown order and a wrong proof get the same answer.
get_product
Claudeget_search_alert
ClaudeUse this when a buyer asks about an alert for new works they saved: whether it is waiting for them to confirm it, active or ended, what it watches, when it last sent works and when it ends. Needs the search_alert_id and manage_token save_search_alert gave.
lookup_catalog
Claudeopen_claim
ClaudeUse this when a buyer wants to return a work or report a problem with an order: damage or a difference from the description on arrival, non-delivery, a doubt about authenticity or title, an agent purchase they did not authorise, cancelling before dispatch, or a 30-day return. It checks the ground against the Returns policy’s window for this order, records the request for a person at Fold, and answers with a link for sending photographs. It refunds nothing: a person at Fold decides every request and replies by e-mail. Needs the same proof as get_order_status.
save_search_alert
ClaudeUse this when a buyer wants to hear about works listed later that match what they are looking for. It saves the search — the buyer’s words in query and the same filters as search_artworks — and tells the buyer by e-mail, or your own system by webhook, when a work that matches it is listed: only works that meet everything asked, never near matches, at most one alert a day, for 180 days. An e-mail alert starts only when the buyer confirms it from the one e-mail Fold sends to ask; ask the buyer before giving Fold their address. Every alert e-mail has one-click unsubscribe. A webhook alert starts once webhook_url answers a signed verification event by echoing its challenge. Works flagged as mature content are never announced here. Answers with search_alert_id and manage_token, shown once: get_search_alert reads the alert and cancel_search_alert ends it.
search_artworks
ClaudeUse this when someone wants to find original paintings, prints, photographs or sculpture from independent artists by subject, style, colour, size or budget. 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; find_artworks_for_wall gives the range and why. 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.
search_catalog
Claudestart_checkout
ClaudeUse this when the buyer has chosen one work and wants to buy it. It answers with checkout_url, a page on Fold’s own site for that one work, where the buyer enters the delivery address, sees the total with sales tax and the terms, and pays. It charges nothing and reserves nothing: the work can still sell to someone else until the buyer presses Pay, and the link works once and lapses at expires_at. Give the link to the buyer or open it in your browser. Call check_availability first; one listing_id per call, since each work is its own purchase. If the work has sold, or another buyer is paying for it, the refusal carries out_of_stock: what the work is now, and up to three similar works on sale here to offer the buyer instead.
