Links for every item

Keeping previews fresh

Caching, invalidation and what chat apps remember.

A card is cached at several levels. This page says what each remembers and how to refresh it when an item changes or is deleted.

What remembers what#

Where	For how long	Refreshed by
Beck Links, memory of each redirect process	Up to the cache time you set	Invalidation, or the next call after it expires
Beck Links, shared cache (database)	Cache time, then an old copy up to `stale_if_error_seconds` if your API fails	Invalidation, or the next call after it expires
Chat apps and social networks	Hours to days, decided by them	Their own "scrape again" tools; not by Beck Links

A fresh answer is used without calling you. An expired one is served once more while Beck Links refreshes it; if your API fails, an old copy can be served until stale_if_error_seconds ends, then a generic card.

Invalidate items#

Call this when an item is updated, unpublished or deleted:

Bash

curl -X POST https://api.becklinks.com/v1/resources/invalidate \
  -H "Authorization: Bearer $SECRET_KEY" \
  -H "Idempotency-Key: $(uuidgen)" \
  -H "Content-Type: application/json" \
  -d '{"resource_type":"challenge","ids":["4521","4522"]}'

JSON

{ "resource_type": "challenge", "requested": 2, "removed": 1 }

The key needs the links:write scope and belongs to one project environment (a test key invalidates test, a live key live).
Up to 1,000 ids per call. removed counts the ids that had a remembered answer.
The call removes the shared copies and notifies every Beck Links process, which drops its memory copy, so the next preview asks your endpoint again. A fetch that was already running when you invalidated is thrown away when it finishes, so an old answer cannot come back.
Idempotency-Key is optional: the call is idempotent by nature.
Call it from your code on update, unpublish and delete. Bulk updates that bypass your application events will show their old card until the cache time ends.

Chat apps keep their own copy#

WhatsApp, Facebook, X and others fetch a link once and remember the card for a long time. Beck Links answering correctly does not change that. To refresh a card, use the platform's own tool (the Facebook Sharing Debugger, the LinkedIn Post Inspector, …). A change of title therefore shows in new shares within the cache time, and in old ones when the platform decides.

Verify it works#

Change the item's title, curl the crawler URL, and note it is still the old title (cache).
Call invalidate, curl again: the new title, and your endpoint logged one call.
Delete the item and invalidate: the card says "not available".