Skip to content
domscoutMenu
domscout / docs
Try Playground
Contents
  1. 01What a template is
  2. 02Creating one
  3. 03The payload
  4. 04Tags and pinning
  5. 05Using them in code
  6. 06Limits

Templates

Save a capture request once

A template is a named capture request body you can load back into the playground or send straight to the API. Most real captures need more than a URL — a viewport, a selector to wait for, two banners to hide — and rebuilding that each time is where the mistakes come from.

01 · Concept

What a template actually stores

Exactly one thing: a JSON request body, the same object you would POST to /screenshot. It stores no results, no schedule and no credentials. Loading a template does not run anything — it fills in a form, or hands you a body to send.

A template is not a monitor. If you want a capture to run on a schedule and alert you when the page changes, that is Monitors. A template is the request; a monitor is the recurrence.

02 · Create

Two ways to make one

From the playground

Build the request with the controls, run it until the result is what you want, then press Save as template. This is the recommended route: you are saving something you have just watched work, rather than a body you believe is correct.

By hand

New template takes a name and a JSON payload directly. Useful when you already have a working request body from your own code and want it saved alongside the others.

03 · Payload

What goes in the JSON

The payload accepts every field the capture API accepts — the OpenAPI contract is the authoritative list, and the API reference explains each one. These are the fields templates use most:

FieldTypeWhat it does
urlstringThe page to capture. Required unless you send html instead.
formatpng | jpeg | webp | pdfOutput format. PDF is a paid-plan format.
width / heightnumberViewport size in CSS pixels.
fullPagebooleanCapture the whole scrollable page rather than the viewport.
extractMarkdownbooleanReturn the page as Markdown alongside the image.
semanticNodesbooleanReturn the interactive elements the page exposes.
selectorstringCapture only the element matching this CSS selector.
hideSelectorsstring[]Elements to remove before capturing — banners, chat widgets.
waitForSelectorstringWait for this element before capturing.
delaynumberExtra milliseconds to wait, 0 to 5000.
injectCSS / injectJSstringStyles or script to run in the page. Business plan and above.
json
{
  "url": "https://example.com/pricing",
  "format": "png",
  "width": 1280,
  "height": 800,
  "fullPage": true,
  "extractMarkdown": true,
  "hideSelectors": ["#cookie-banner", ".chat-widget"],
  "waitForSelector": "#pricing-table"
}

The payload is stored as written and validated only when it is run. A template naming a field your plan does not include — injectJS on a Pro account, say — saves without complaint and fails at capture time. The playground is the quickest way to prove one works.

04 · Organise

Tags, pinning and use counts

  • Tags are free-text labels for filtering — staging, competitor, nightly. They carry no behaviour. Templates saved from the playground are tagged playground automatically.
  • Pinning sorts a template to the top of the list. Nothing else changes.
  • Use count increments when a template is loaded into the playground, not when a capture runs. It answers “which of these do I actually reach for”, which is the question worth asking before deleting any of them. Reading the list does not count as a use.

05 · Reuse

Using a template from your own code

Templates live behind your dashboard session rather than your API key, because they are account furniture rather than part of the capture contract. In a script, read the payload once and send it to the API with your key:

bash
# Read a saved template, then send its payload to the API.
TEMPLATE=$(curl -s https://www.domscout.io/api/dashboard/templates/<id> \
  -H "Cookie: $DASHBOARD_SESSION" | jq -c .template.payload)

curl -X POST https://api.domscout.io/screenshot \
  -H "Content-Type: application/json" \
  -H "x-api-key: $DOMSCOUT_API_KEY" \
  -d "$TEMPLATE"

For anything automated, prefer copying the payload into your own source and version-controlling it there. A template is for iterating by hand; a committed request body is for production.

06 · Limits

What is bounded

Templates per account100
Payload size64 KB
Name length255 characters
Description length1000 characters
Tags20 per template, 60 characters each

These figures are read from the same constants the API validates against, so this table cannot drift from what the server enforces.