The TickClip API

Every published verdict, product, brand, deal and promo code, as JSON. Single-entity reads need no account — the point of this API is that an assistant can use TickClip as a source without signing up for one.

Base URL: https://cloud.tickclip.ai/api/v1

How it works

Authentication

Single-entity GETs are anonymous. That is deliberate: the point of this API is that an AI assistant can use TickClip as a source without an account. List endpoints are anonymous too, at a lower rate. An API key raises your limits and is required for sustained bulk reads.

Rate limits

Anonymous requests are limited per IP and globally. Exceeding a limit returns 429 with a Retry-After header and a machine-readable reason; it never returns a partial or empty result that could be mistaken for an answer.

Pagination

Cursor-based. Pass the previous response's page.nextCursor back as ?cursor=. When nextCursor is null there are no more pages. pageSize defaults to 20 and is capped at 50. There are no offsets: an offset paginator re-reads everything it skips, so paginating to the end would cost quadratic work.

Errors

Every failure is a JSON body with error.reason (a stable enum you can branch on) and error.message (for a human reading a log). A missing or unpublished entity is a 404 with reason not_found or not_published — never a 200 with an empty shell, because a shell read as an answer is how TickClip ends up quoted saying nothing.

Versioning

The version is a path segment, so a stored URL cannot change shape underneath you. A version stays served for at least 12 months after its successor ships, and any removal is announced here and in llms.txt before it happens. Adding an optional field happens inside a version; removing or retyping one gets a new version.

Endpoints

/verdicts

What TickClip published about a product: the decision, the score, the evidence and the conditions that would change it.

Identifier: The public product ID (p_xxxxxxxxxxxx), the canonical verdict slug, or an Amazon ASIN.

  • https://www.tickclip.ai/api/v1/verdicts/p_01abc29xyzde
  • https://www.tickclip.ai/api/v1/verdicts?action=tick&pageSize=20
action
tick | clip | skip — Only verdicts with this decision.
brand
a brand slug, e.g. sony — Only items for this brand. Matched on the normalised key, so spelling variants resolve to one brand.
category
a category key, e.g. electronics — Only items in this category.
trackedLow
true — Only items currently at their tracked all-time low.

/products

What the product IS — identity, brand, category, imagery and marketplace ratings. No verdict, no price.

Identifier: The public product ID, the canonical slug, or an ASIN.

  • https://www.tickclip.ai/api/v1/products/p_01abc29xyzde
  • https://www.tickclip.ai/api/v1/products?brand=a&pageSize=20
brand
a brand slug, e.g. sony — Only items for this brand. Matched on the normalised key, so spelling variants resolve to one brand.

/listings

One seller's offer of a product: the payable price, the currency, the seller and availability.

Identifier: An ASIN, or the explicit form asin:B0DZ75TN5F.

  • https://www.tickclip.ai/api/v1/listings/B0DZ75TN5F
  • https://www.tickclip.ai/api/v1/listings?pageSize=20

/deals

A live price drop, with the price it fell from.

Identifier: The ASIN the deal is for.

  • https://www.tickclip.ai/api/v1/deals/B0DZ75TN5F
  • https://www.tickclip.ai/api/v1/deals?brand=a&pageSize=20
brand
a brand slug, e.g. sony — Only items for this brand. Matched on the normalised key, so spelling variants resolve to one brand.
status
active — Only live deals. Expired and draft deals are never returned.

/promo-codes

A live promo code, its conditions and its expiry.

Identifier: The code itself.

  • https://www.tickclip.ai/api/v1/promo-codes/SAVE20

There is no list endpoint. Enumerating every live code is a scraping surface rather than a discovery one, so codes resolve individually.

brand
a brand slug, e.g. sony — Only items for this brand. Matched on the normalised key, so spelling variants resolve to one brand.

/brands

A brand, with its verdict mix and clean-pricing rate. Every statistic carries its sample size and calculation date.

Identifier: The brand slug.

  • https://www.tickclip.ai/api/v1/brands/sony
  • https://www.tickclip.ai/api/v1/brands?pageSize=20

/sellers

Who sells a product — an identity, independent of any retailer.

Identifier: The public seller ID or its canonical slug.

  • https://www.tickclip.ai/api/v1/sellers/s_01abc29xyzde
  • https://www.tickclip.ai/api/v1/sellers?pageSize=20

/stores

A seller's storefront ON a retailer. Carries both parents: the seller and the retailer.

Identifier: The public store ID.

  • https://www.tickclip.ai/api/v1/stores/st_01abc29xyzde
  • https://www.tickclip.ai/api/v1/stores?retailer=a&pageSize=20
retailer
a retailer slug, e.g. amazon — Only storefronts on this retailer.

/retailers

A retailer, such as Amazon.

Identifier: The retailer slug or key.

  • https://www.tickclip.ai/api/v1/retailers/amazon
  • https://www.tickclip.ai/api/v1/retailers?pageSize=20

Feeds

Active deals

Live Amazon price drops TickClip is tracking, with the price a shopper pays now and the price it actually fell from. Expired deals leave automatically when the feed refreshes.

  • https://www.tickclip.ai/api/v1/feeds/deals

Verified promo codes

Live promo codes with their conditions. Expired and deactivated codes are never returned. effectivePrice is always null — TickClip does not yet calculate what a shopper would pay with a code applied.

  • https://www.tickclip.ai/api/v1/feeds/promo-codes

Recently updated verdicts

Recently published verdicts, newest first. A verdict past its freshness window appears WITH its status and WITHOUT its decision: a feed is a record of activity, so an expired verdict is news, but its old answer is not.

  • https://www.tickclip.ai/api/v1/feeds/verdicts
  • https://www.tickclip.ai/api/v1/feeds/verdicts.atom

Verdict changes

Every verdict whose answer actually changed — previous decision, new decision, the reason, and the methodology version in force. Read from the publication history rather than recomputed, so it reports what was published rather than a second opinion about it. Routine republishes that changed nothing are excluded.

  • https://www.tickclip.ai/api/v1/feeds/verdict-changes
  • https://www.tickclip.ai/api/v1/feeds/verdict-changes.atom

Dataset export

Every published verdict as one record: identity, decision, score, confidence, published price, price baselines, freshness status and the snapshotId it was published under. A withdrawn verdict is included with its identity and status but WITHOUT its decision — a dataset that carried expired verdicts as live ones would let a researcher average scores TickClip has stopped standing behind.

  • https://www.tickclip.ai/api/v1/export/verdicts.ndjson
  • https://www.tickclip.ai/api/v1/export/verdicts.json

Versioning

Pass ?version=verdicts-YYYY-MM-DD to pin the cut; without one the cut is now. Records are ordered by public ID, not recency, so the same version reproduces the same bytes. Every response carries x-tickclip-dataset-checksum (SHA-256 of the body) — verify it, and a mismatch on a re-download means a snapshot in that release has since been pruned.

Licence

CC BY 4.0 — TickClip — independent product verdicts. Cite the snapshotId with any figure taken from this dataset.

Citing a verdict

Every verdict page offers this string under Share → Copy citation, and it is the same format an assistant should produce. The snapshot ID is what makes a citation verifiable: it identifies the exact published version that was quoted, rather than whatever the verdict says today.

TickClip verdict: {Tick|Clip|Skip} ({score}/100) for {product title}. {canonical URL} Checked {DD Mon YYYY}. Methodology {version}. Snapshot {snapshotId}.

A verdict past its freshness window cites as Verdict Needs Refresh with the date it was last true. Do not cite its previous decision — a citation outlives every correction we could make.