The VantaSpec API

Search the catalogue. Open to anonymous callers: a key only raises your rate ceiling, it does not gate access.

The top six products and up to three categories for a partly typed search, as the site's search box shows them. Ranked by how well the name answers the words, then by what people opened after the same search and by page views. Open to anonymous callers; a key only raises the rate ceiling. Cached for a minute.

Records that a product was opened after a search, which search ranking learns from. Sent by the site for visitors who accepted analytics; stores the query's words and the product, nothing about the visitor. Open to anonymous callers; a key only raises the rate ceiling.

Price history for one product as step series: each retailer's price holds until its next change, runs to now while the retailer still lists it, and the lowest line is the cheapest retailer selling at each moment. New-condition offers only. Read-only.

The browser extension's lookup: given a shop's product page that we list, the other shops with the same part in stock for at least £1 less, cheapest first, from prices read in the last 14 days. Matched on the shop's URL, never on the page's name or barcode. Read-only. Open to anonymous callers; a key only raises the rate ceiling.

The browser extension's admin mode: report the price and stock a shop's product page shows, for the offer we already hold at that exact URL. Developer, admin or owner accounts only, by signed-in session (with the x-vantaspec-extension: 1 header) or a scraper:write key. Dry run unless apply is true. Never creates an offer or a product; writes through the same path and checks as the feed price refresh, and says why when it refuses.

The browser extension's admin mode, one photo per call: the image bytes as the body, for the product the exact shop page belongs to. Developer, admin or owner accounts only: a signed-in session with the x-vantaspec-extension: 1 header, or an x-api-key with scraper:write. Runs the scraper image route's checks and stores onto the CDN; max 10 MB.

The extension's Not on VantaSpec yet panel: suggest a shop page we do not list. Developer, admin or owner accounts only: a signed-in session with the x-vantaspec-extension: 1 header, or an x-api-key with scraper:write. Dry run unless apply is true. Nothing here touches the catalogue; the scraper's --leads run does that.

The queued leads, oldest first. x-api-key with scraper:write held by a privileged owner.

Mark a lead. The scraper's key as above, or a signed-in admin.

This paired phone's name and push toggles; also how the app checks it is still paired. Paired phone only: the x-mobile-token from pairing in /admin/system. Never a session or an API key.

Register the phone's Expo push token and save its toggles. Paired phone only: the x-mobile-token from pairing in /admin/system. Never a session or an API key.

Send this paired phone a test push and wait briefly for Expo's receipt, so a missing Firebase key is reported. Paired phone only: the x-mobile-token from pairing in /admin/system. Never a session or an API key.

Price drop alerts for the phone app's watchlist, for any install, no account. Registers or replaces this phone's watched products and the price each was saved at; the alerts cron pushes once per drop (at least £2 or 3%), 8am to 9pm UK time. Stores only the push token and the list; untouched for 60 days, it is deleted. Open to anonymous callers; rate limited, and new phones per address are limited again.

Turn this phone's price drop alerts off: its row is deleted. Open to anonymous callers; rate limited.

Unpair this phone from the phone. Paired phone only: the x-mobile-token from pairing in /admin/system. Never a session or an API key.

The phone app's Deals tab: the /deals page's 30-day price drops and biggest shop gaps, 40 of each, and the 12 most popular parts with today's cheapest in-stock price, held five minutes, plus the site's current seasonal theme so the app wears the same accent. Each row carries `displayName`, the product page's heading (the shop title without its own part number). Public, read-only.

One published product for the phone app's product screen: specs, every shop's offer cheapest first with a tracked buy link, and the cheapest in-stock offer. Unpublished products are a 404. Open to anonymous callers like product search: a key only raises the rate ceiling.

The phone app's barcode scanner: the published products carrying a barcode, so a box scanned in a shop opens the page with every UK price. EAN-13, UPC-A or GTIN-14, normalised; a code that fails its check digit is a 400. Up to five matches, since a shop can list a code against the wrong part. Open to anonymous callers; a key only raises the rate ceiling. Cached five minutes.

The Build Planner for the phone app: the same plan as /api/recommendations, with each part's cheapest offer as a tracked buy link. Open to anonymous callers; a key only raises the rate ceiling. Plans are held ten minutes per budget and use.

The PSU calculator for the phone app: the estimated draw of a processor and graphics card plus the rest of the PC, the wattage to buy, and the six cheapest in-stock units at that size with tracked buy links. No wattage is advised when a chosen part's draw cannot be read. Open to anonymous callers; a key only raises the rate ceiling.

The weekly price movers for the phone app: the same falls and rises as /price-movers (today's price at a shop selling it against the same shop 7 days ago), each with its photo. Open to anonymous callers; a key only raises the rate ceiling. Rebuilt at most every ten minutes.

What will it run? for one graphics card, for the phone app: its estimated tier (comfortable, playable or struggles) at 1080p, 1440p and 4K, how it compares with a game's published requirements, and the frame rates people measured, as medians once a setup has enough approved results. Also the game, card and resolution lists to pick from. Open to anonymous callers; a key only raises the rate ceiling.

The admin app's dashboard and task list; the same read as the TV, held 45 seconds, plus `needs`: cards on the owner in To do and pending beta requests. Paired phone only: the x-mobile-token from pairing in /admin/system. Never a session or an API key.

The bell's list for the paired phone, newest first. Paired phone only: the x-mobile-token from pairing in /admin/system. Never a session or an API key.

Mark notifications read. Paired phone only: the x-mobile-token from pairing in /admin/system. Never a session or an API key.

The living-room dashboard's one read (/tv). Auth is the pairing token from /admin/system in x-tv-token, never a session or an API key. Read only.

Derived price statistics for one product: current, lowest, highest and average over the window.

Submit a product for review. Lands as pending with automatic risk flags; it is never published directly.

All 15 categories with product counts.

Side-by-side data for several products at once.

The best compatible PC the live catalogue can build for a budget, the engine behind /build-planner. Open to anonymous callers; a key only raises the rate ceiling. Tries every priced graphics card and processor model against each other at their cheapest believable listing, fills the rest with the cheapest parts that fit (socket, memory generation, cooler socket, case size, power supply against estimated peak draw), and never relaxes a compatibility rule: when nothing fits it returns ok: false with the cheapest possible total.

Find people by handle or display name. Returns only what a public profile already shows.

List your builds.

Create a build.

One build with its parts. Public builds are readable by anyone; a private build returns 403 to everyone but its owner.

Update a build's name, description or visibility. Owner only.

Delete a build. Owner only.

Post to TikTok (beta): start connecting your own TikTok account. Redirects to TikTok's consent screen and back to the page you came from; signed out, it redirects to sign in instead.

Forget your connected TikTok account.

What the TikTok share page needs for one of your builds: your connected TikTok, the audiences and settings TikTok offers you, the latest video for the build and a suggested caption.

Start drawing a video of one of your builds. Poll /api/share/tiktok/[id] for it.

One build video's progress. Owner only.

The rendered build video, for the preview before posting. Owner only.

Post a previewed build video to your own TikTok with the audience and settings you chose. A post with no privacy level is refused; nothing is chosen for you.

Add a part to a build.

Remove a part from a build.

The build's total price alert, its current total and a suggested target. Owner only.

Set or change the alert on the build's total. Every part needs a current in-stock price, and the target must be under today's total.

Remove the build's total alert.

Compatibility verdict for the build as it stands.

CPU/GPU bottleneck estimate for the build.

Parts that would improve the build most for the money: the upgrade advisor run on the build's processor, card, memory and supply, the limiting side first. Public builds need no session.

Products that fit a given slot on this build.

Comments on a public build, oldest first (up to 200), each with its author and whether you may delete it. 404 for a private build.

Comment on a public build. Plain text up to 2,000 characters; at most 5 comments in 10 minutes.

Delete a comment (?comment=<id>): its author, the build's owner, or a moderator.

Upvote a public build, or take your upvote back if you had given one. Not your own build (403); a private build is 404. At most 30 votes a minute. The count shows on /builds, whose Most upvoted row lists up to 8 public builds with at least one vote, and on the build page.

Photos of your finished build, each with its review status (pending, approved or rejected). Your own builds only.

Add a photo of your finished build (multipart form). JPEG, PNG or WebP up to 8 MB; at most 4 per build and 12 a day. Location and camera data are removed. Shown on /builds/gallery once staff approve it and while the build is public.

Remove one of your build's photos (?photo=<id>), and its file.

Send a frame rate measured on your own PC for /what-will-it-run. Held until staff approve it, and shown only as the median of a game, chip, resolution and preset with at least 3 approved results. At most 10 a day.

Read a build by its share code.

Toggle a product as a favourite.

List your price and back-in-stock alerts.

Create or replace your alert on a product (one per product). A restock alert fires once, when any shop has it in stock again, then switches off.

Delete your alert on a product.

List your saved search alerts.

Save a category listing with filters. You hear about products that newly match it, and, if it has a max price, a match falling to that price. Saving the same filters again switches the search back on. Up to 20 per member.

Pause or resume a saved search.

Delete a saved search.

Post a review.

Delete your own review.

Forum categories with thread counts.

Threads in a category.

Start a thread.

One thread with its posts.

Reply to a thread.

Vote on a post.

Published blog posts, newest first.

One blog post by slug.

Your notifications, newest first.

Mark notifications read.

Delete a notification.

Update your display name, bio or handle.

Unlink your Discord account: removes the link, the Verified role on our server and the Discord badge. Refused (409) when Discord is the only way into the account.

List your API keys, masked. Keys are managed from the browser only: a key cannot manage keys.

Create an API key. Maximum 5 active. The full key is shown once and never again.

Revoke an API key.

Change your password.

List your active sessions.

Revoke one session, or all but the current one.

Two-factor status and enrolment data.

Enable or disable two-factor authentication.

Upload a profile image. Processed and stored on the CDN.

Remove your profile image.

Export everything held about you, as JSON (UK GDPR access request).

Delete your account and its data (UK GDPR erasure request).

Your email preferences.

Update your email preferences.

Your privacy settings: whether your favourites show on your public profile.

Your email, whether changing it needs your password, and whether the change is confirmed by a link.

Change your email. With mail configured, a link goes to the new address and the change happens when it is opened.

The confirmation link from the email. Redirects to account settings.

The public key a browser subscribes to desktop notifications with.

Turn on desktop notifications for this browser. Only a Google, Mozilla, Microsoft or Apple push endpoint is accepted.

Turn off desktop notifications for this browser.

Change your privacy settings.

Subscribe an address. Always answers the same regardless of whether the address was already subscribed, so the endpoint cannot be used to test whether someone has an account.

RFC 8058 one-click unsubscribe, the target of the List-Unsubscribe-Post header. Takes ?token= from the email link; an unknown token still answers ok.

Where browsers report what the Report-Only Content-Security-Policy would block. Counted in memory by directive and host; always 204.

Your newsletter preference. Signed out, it answers not subscribed rather than 401.

Update your newsletter preference.

Create an account.

Pre-flight check before sign-in, reporting whether two-factor is required.

Begin a password reset. Answers identically whether or not the address exists.

Complete a password reset with a token.

Container probe. Runs SELECT 1 and answers 503 when the database is down.

Public service health with history. Unauthenticated on purpose: a status page nobody can read during an outage is not a status page. Exposes only up/down, latency and dates.

Beta feature keys this caller may see. An anonymous caller gets the released ones and nothing more, so the response cannot reveal that a disabled feature exists.

Your beta access request status.

Request beta access.

Send a message through the contact form.

Serves an uploaded file. Referenced by image URLs rather than called directly.

First-party page-view beacon. Internal: the site calls this itself.

Counts an outbound retailer click. Internal: the site calls this itself.

Discord posts every slash command here. A key is accepted only in the sense that it raises the rate-limit ceiling; it is not what guards the route and Discord does not send one. What guards it is an Ed25519 signature over the request's exact bytes, made with the application's private key: anything without a valid one gets 401, and Discord itself probes a newly saved endpoint URL with a deliberately invalid request and refuses the URL unless it answers exactly that. Not useful to call by hand: without a signature there is nothing to see. HTTP interactions rather than a gateway bot, so the bot is up exactly when the site is; the trade is no presence, no reading ordinary messages and no voice. Answers /price (cheapest UK offers for a part) and /deals (where retailers disagree most), both replying only to the person who asked.

A generated 1200×630 or 1080×1080 PNG announcing one price, the product photograph with the figures drawn onto it. Open to anonymous callers; a key only raises your rate ceiling. The parameters are claims that are checked, not values that are drawn: the slug must be a published, approved product, the retailer must have a live offer that is not hidden from the site, the price must equal that offer within half a penny, and a `was` must appear in that product's own price history at that retailer. The percentage saved and the "lowest recorded" line are never parameters: they are computed from the rows. Anything that fails returns 409 rather than a picture, so a card can go out of date but cannot go wrong.