public

Queue homepage screenshots for this directory’s listings

Captures each listing’s own website and attaches the result as a site_screenshot media asset, which gets the extra 400x267 site variant cropped from the top. Ordinary media from there on — it appears in listing reads and sorts below anything an editor chose.

Asynchronous. The response reports what was queued, not what was captured; poll GET .../screenshots for coverage.

Only listings with a resolvable website are eligible — website, url, homepage or organizerWebsite in canonicalFields, with a series_of child inheriting its parent series’ site. listingsWithoutUrl in the response is the honest gap: those listings will never get a screenshot from any number of runs.

Listings that already have one are skipped unless you pass force, so re-running is cheap. Never-captured listings are queued before stale ones, so successive runs rotate through a directory bigger than the per-run cap instead of retrying the same slice forever.

Respects enrichmentPolicy.probe === false, which short-circuits before anything is queued.

Sizing. The site variant defaults to 400x267 — 400 wide at the capture's own 3:2. Send width alone to change it and the height follows that aspect. To make a size stick across every sweep, set enrichmentPolicy.screenshot on the directory instead; width/height here override it for one run. The resolved geometry comes back as siteVariant.

post/public/v1/directories/{directory}/screenshots

Request

  • Base URL: https://api.epicdirectories.com
  • URL: https://api.epicdirectories.com/public/v1/directories/{directory}/screenshots
  • Auth: API key in header x-api-key

Path parameters

directorystring required

Headers

Idempotency-Keystring

Optional. Send a unique key per logical operation to make retries safe. 1-256 characters, and only letters, digits, - and _ — colons and other separators are rejected with 400. A retry with the same key replays the original response (status + body) instead of re-executing. Cached for 24h. Reusing a key with a different request body returns 409 — note that a timestamp in the body (e.g. fetchedAt) turns an otherwise-stable key into a permanent 409, so either omit it (snapshots default it server-side) or fold a payload digest into the key. Skipped on 5xx responses (transient errors should be retried fresh).

x-api-keystring required

API Key for authentication

Request body

limitnumber

How many listings to queue this run. Capped at 50 regardless of what you send — rendering is metered browser time on a shared account, so one directory cannot drain the day for every other consumer. The response reports deferred when the cap bit, and the next run picks up where this one stopped.

forceboolean

Re-capture listings that already have a screenshot, replacing it. Off by default, so a repeated sweep is cheap and idempotent rather than re-rendering the whole directory.

Use this when the existing capture is the problem — a challenge page, or a blank that predates the blank-render check. The replacement is stored and live BEFORE the old asset is removed, so a failed re-capture leaves the current screenshot in place rather than clearing it.

widthnumber

Width of the site variant for this run, in pixels. Send this alone and the height follows the capture's 3:2 — 400 becomes 400x267, 600 becomes 600x400. That is almost always what you want, and computing 266.67 by hand is how a directory ends up with a variant whose aspect quietly crops every screenshot.

Capped at 1200, the renderer's own capture width: anything larger is an upscale of pixels that do not exist, which reads as a rendering bug rather than a choice.

Set enrichmentPolicy.screenshot on the directory to make a size stick across every sweep; this parameter is for one run.

heightnumber

Height of the site variant, in pixels. Only needed for an aspect other than the capture's 3:2 — and note that a different aspect means cover-fit CROPS, from the top. 400x252 for instance discards about 5.5% of each capture's height. Capped at 800 for the same reason as width.

listingSlugsstring[]

Capture these listings specifically, by slug, instead of letting the sweep choose.

A named set is an instruction, so the retry window is bypassed — if you can see a listing has no screenshot and ask for it by name, you get an attempt. It does NOT replace an existing screenshot; pass force as well for that.

Use it to retry a listing whose URL you just fixed, or to re-capture a few at a new size without re-rendering the directory. Slugs that match nothing come back as unmatchedSlugs rather than being silently dropped. Still subject to the per-run cap.

Example request

{
  "listingSlugs": [
    "acme-digital",
    "bizapedia"
  ]
}

Response

Captures queued; body reports the counts

Changes

No recorded changes to this operation across all 1 revision of this API.