API Docs

Base URL: https://dgen.uk/snapmeta/api/v1 · Auth: Authorization: Bearer <your key>

Your first API call

1. Create an account, open the newest verification email and confirm it. Pending accounts cannot use the API.
2. Save the key shown once after verification in your password manager. A browser login is not an API Bearer key. If you lose a key, sign in to the dashboard to create a replacement and revoke the lost key.
3. Save the Python 3 example below as first_call.py and run python first_call.py in a terminal. Paste your key at the hidden prompt. It reads usage, fetches metadata, then reads usage again; no extra packages are needed.

import getpass
import json
from urllib.error import HTTPError
from urllib.parse import urlencode
from urllib.request import Request, urlopen

base_url = "https://dgen.uk/snapmeta"
api_key = getpass.getpass("Snapmeta API key: ").strip()
paths = ["usage", "metadata?" + urlencode({"url": "https://example.com"}), "usage"]
try:
    for path in paths:
        request = Request(base_url + "/api/v1/" + path,
                          headers={"Authorization": "Bearer " + api_key})
        with urlopen(request, timeout=30) as response:
            print(json.dumps(json.load(response)))
except HTTPError as error:
    print("HTTP", error.code, error.read().decode())
    raise SystemExit(1)

Expect three JSON lines: your plan and UTC month, metadata for Example Domain, then usage with one more metadata unit. Reading usage costs no units; even a cached metadata response uses one. Screenshots, PDFs and markdown require a paid plan and share its render allowance. Download an artifactUrl with your Bearer key within 24 hours.

Keep keys out of source code, shared screenshots, shell history and support messages. The example does not retry: each admitted retry can use another unit. For recovery, use the error guide or Support.

Agent authentication

Use your existing API key, or follow auth.md to grant an agent limited access. Sign in with a verified account, enter the code shown by your agent, review its resource and scopes, then approve. Grants expire after one hour; tokens last at most 15 minutes. Revoke any time from Agent access.

OAuth scopes are metadata:read, render:execute, usage:read and artifacts:read. Use resource https://dgen.uk/snapmeta/ for REST or https://dgen.uk/snapmeta/mcp for MCP. The same account, plan, quota and artifact-ownership checks apply. Registered OAuth clients may also use authorization code with S256 PKCE.

Interactive API explorer

Try the public endpoints below, rendered from the live OpenAPI schema.

Monthly usage

Every account has one metadata allowance and one shared render allowance for screenshots, PDFs and markdown. All API keys and MCP tools use those same allowances. Months start at 00:00 UTC on the first day; a request belongs to the month in which it is admitted, even if it finishes later.

One unit is reserved when a request is admitted, including cache hits. Successful requests, blocked URLs, fetch/render failures, cancellations and interrupted requests count. Invalid parameters or authentication, unavailable paid features, rate limits, a full render queue and disabled rendering do not count. In-flight reservations are included in usage. Requests with an unknown outcome stay charged; retrying is a new request. A quota rejection uses HTTP 402 (an MCP tool error for MCP calls).

Endpoints

curl "https://dgen.uk/snapmeta/api/v1/metadata?url=https://example.com" \
  -H "Authorization: Bearer sk_live_..."

curl "https://dgen.uk/snapmeta/api/v1/screenshot?url=https://example.com&width=1280&height=720&full_page=true&format=png" \
  -H "Authorization: Bearer sk_live_..."

curl "https://dgen.uk/snapmeta/api/v1/pdf?url=https://example.com&format=A4&landscape=false" \
  -H "Authorization: Bearer sk_live_..."

curl "https://dgen.uk/snapmeta/api/v1/markdown?url=https://example.com" \
  -H "Authorization: Bearer sk_live_..."

curl "https://dgen.uk/snapmeta/api/v1/usage" -H "Authorization: Bearer sk_live_..."

MCP (AI agents)

JSON-RPC endpoint: POST https://dgen.uk/snapmeta/mcp with the same Bearer key. Tools: get_metadata, get_screenshot, get_pdf, get_markdown. Add to Claude Desktop or Cursor:

{
  "mcpServers": {
    "snapmeta": {
      "url": "https://dgen.uk/snapmeta/mcp",
      "headers": { "Authorization": "Bearer sk_live_..." }
    }
  }
}

Errors and recovery

Check the HTTP status and response body before retrying. Application errors normally include status and detail; parameter-validation errors use a detail list. A proxy may return another format. MCP tool failures can arrive in an HTTP 200 JSON-RPC response: inspect the tool result's isError and message.

Rate limits: 10 req/s metadata, 1 render per 2s, 4 concurrent renders max (429 + Retry-After beyond that).