Responses and metadata

Get the file, JSON with a file URL, or nothing, plus metadata such as the page title, Open Graph tags and HTTP status.

Response types

response_type decides what a successful request returns:

Value	Returns
`by_format` (default)	The file itself, with its `Content-Type` (`image/png`, `application/pdf`, …).
`json`	JSON with the URL of the uploaded file and any metadata you asked for.
`empty`	`200` with no body. Useful to warm the cache.

The file

The body is the file. Metadata, if requested, comes as response headers. attachment_name makes browsers download it under that name:

curl -X POST "https://shotkit.net/api/take" \
  -H "X-Access-Key: YOUR_ACCESS_KEY" \
  -H "Content-Type: application/json" \
  -d '{"url":"https://example.com","format":"pdf","attachment_name":"example"}' \
  --fail-with-body -o shot.pdf

Response headers:

Header	Value
`Content-Type`	The format's media type.
`X-Render-Time-Ms`	Time spent on the request, in milliseconds.
`Content-Disposition`	`attachment; filename="example.pdf"` with `attachment_name`.
`X-Cache`, `X-Cache-Url`	With `cache=true`: `HIT` or `MISS`, and the cached file's URL.
`X-Page-Title`, `X-Open-Graph`, …	Metadata (see below), as URL-encoded JSON.

JSON

With response_type=json, the file is uploaded and you get its URL:

curl -X POST "https://shotkit.net/api/take" \
  -H "X-Access-Key: YOUR_ACCESS_KEY" \
  -H "Content-Type: application/json" \
  -d '{"url":"https://example.com","response_type":"json","metadata_page_title":true,"metadata_image_size":true}' \
  --fail-with-body -o shot.json

{
  "screenshot_url": "https://shotkit.net/cdn/files/…/….jpg",
  "metadata": {
    "page_title": "Example Domain",
    "image_size": { "width": 1280, "height": 1024 }
  }
}

Files stay available for cache_ttl seconds (4 hours by default, up to 30 days), then they're deleted. Download them if you need them longer.

Metadata

Turn on what you need. Each adds a field to metadata in JSON, or an X-… header otherwise.

Option	JSON field	Header
`metadata_image_size`	`metadata.image_size`: `{ width, height }` of the output	`X-Image-Size`
`metadata_page_title`	`metadata.page_title`	`X-Page-Title`
`metadata_icon`	`metadata.icon`: `{ url, type }` of the favicon	`X-Icon`
`metadata_open_graph`	`metadata.open_graph`: `og:*` tags without the prefix	`X-Open-Graph`
`metadata_fonts`	`metadata.fonts`: font families the page uses	`X-Fonts`
`metadata_http_response_status_code`	`http_response.status_code`	`X-Http-Response`
`metadata_http_response_headers`	`http_response.headers`	`X-Http-Response`
`metadata_content`	`content`: `{ url, expires, format }`	`X-Content-Url`, `X-Content-Expires`
`vision_prompt` + `openai_api_key`	`vision.completion`	`X-Vision`

Everything at once:

curl -X POST "https://shotkit.net/api/take" \
  -H "X-Access-Key: YOUR_ACCESS_KEY" \
  -H "Content-Type: application/json" \
  -d '{"url":"https://github.com","response_type":"json","metadata_page_title":true,"metadata_icon":true,"metadata_open_graph":true,"metadata_fonts":true,"metadata_http_response_status_code":true}' \
  --fail-with-body -o shot.json

{
  "screenshot_url": "https://shotkit.net/cdn/files/…/….jpg",
  "metadata": {
    "page_title": "GitHub · Build and ship software on a single, collaborative platform",
    "icon": { "url": "https://github.githubassets.com/favicons/favicon.svg", "type": "image/svg+xml" },
    "open_graph": { "title": "GitHub", "image": "https://github.githubassets.com/…", "type": "website" },
    "fonts": ["Mona Sans", "-apple-system", "BlinkMacSystemFont"]
  },
  "http_response": { "status_code": 200 }
}

Header values are URL-encoded JSON. To read one:

const title = JSON.parse(decodeURIComponent(res.headers.get("x-page-title")));

Errors

Failures return JSON with a 4xx or 5xx status, whatever the response type. See Errors.