Shopping a photograph: a field guide.

Shopping a photograph

A working guide to integrating the Inspired API: the decisions the endpoint reference does not make for you.

It is written for someone who has a key and now has to ship a feature — which endpoint to build on, how to make a three-minute read feel like progress rather than a hang, how to choose a focus domain, what an empty result means, and which words you are allowed to put in your UI.

What is in it

• The shape of the pipeline, and why the extraction step being sequential is the fact every other decision follows from.
• Why the asynchronous endpoint is the only integration path, with the synchronous one placed where it belongs.
• Polling: honouring pollAfterMs, and rendering the object list the moment the vision call lands.
• Choosing a domain, why an unknown one is a 400 rather than a fallback, and what focus is and is not for.
• Reading the result honestly — the candidate order is not yours to improve, nothing is verified, and an empty list is a success.
• Which images you get over HTTP versus over MCP, and which of them will eventually 404.
• Spending a trial allowance like it is real, including why re-minting does not get you more requests.
• A failure-mode table and a complete working shell integration.
• A ten-point checklist to run before you ship.

Who it helps

Anyone wiring Inspired into a product: a shopping feature, an agent tool, a catalogue enrichment job. If you are only running one read by hand, the quickstart is enough — come here when it has to work unattended.

Limits

It documents the platform as deployed at inspired.jetskibay.com in September 2026 and says nothing about unreleased behaviour. It does not cover the consumer app's internal routes, which are not a public interface, and it does not teach visual search, computer vision, or retail data in general.

Use the Inspired visual search guide to review the integration in this
repository before we ship it.

Work through it in this order:

1. Read sections 2 and 3 of the guide, then find where we call Inspired. Tell
   me whether we are on POST /api/v1/jobs or POST /api/v1/inspire, and if it is
   the synchronous route, what it would take to move.
2. Check how we poll. We should be reading pollAfterMs out of each response
   rather than using a fixed interval, and we should be rendering the object
   list from progress.items as soon as it exists instead of holding a spinner
   until the read completes.
3. Check the domain. We should pass one explicitly rather than inheriting the
   fashion default, and we should handle the 400 an unknown domain returns —
   that response means nothing was charged, so it must not be retried blindly.
4. Run section 5 against our result handling. Specifically: do we re-sort
   candidates anywhere, do we treat an empty items array as an error, and does
   any user-facing string say "identified", "found", "exact" or "match" where
   the guide requires "spotted" and "visually similar"?
5. Check what we do with candidates[].imageUrl. Those are retailer and Google
   URLs and they expire; anything we persist has to be re-hosted.
6. Finish with the section 10 checklist as a list of pass or fail, and open a
   task for each failure with the guide section that explains it.

Do not change the pipeline's latency expectations to make our UI look better.
A full read is minutes by design, and the guide's answer to that is progressive
disclosure, not a shorter timeout.