# 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](https://shotkit.net/docs/caching.md). |

### The file

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

```bash
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:

```bash
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
```

```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:

```bash
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
```

```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:

```js
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](https://shotkit.net/docs/errors.md).