Oh See Software
Oh See Snaps

Documentation

Authentication

Authentication to the Oh See Snaps API happens via a generated API token. All requests must include the API token otherwise they will return a 401 response. Read more on how to authenticate your requests under the Authenticating requests section.

Generating a new API token

You can generate a new API token from the API Tokens page:

Oh See Snaps API Tokens page

Authenticating requests

There are two ways to authenticate your requests via your API token:

  1. Via a token query param
  2. Via an Authorization header

Here's an example of each:

1# `token` query param:
2curl https://ohseesnaps.com/api/snap?url=https://ohseesoftware.com \
3  &token=XXXXX 
4 
5# `Authorizaton` header:
6curl http://ohseesnaps.com/api/snap?url=https://ohseesoftware.com \
7  -H "Authorization: Bearer XXXXX"

Generating Snaps

You can generate snaps via sending a request to the Oh See Snaps API. The most common approach is to set an HTML <img /> element's src attribute to the snap URL, for example:

1<img
2  src="https://ohseesnaps.com/api/snap \
3       ?token=XXXXX \
4       &url=https://ohseesoftware.com"
5/>

Alternatively, you can send an API request via your client of choice (cURL, Guzzle, fetch, etc). The API will return a redirect to the image on our CDN.

Query parameters

The following query parameters can be used to customize each snap.

url

The URL of the website to take a snap of.

Required
Yes
1# Set the URL of the website to snap
2 
3https://ohseesnaps.com/api/snap \
4  ?token=XXXXX \
5  &url=https://example.com

w

The width (in pixels) of the viewport to use when creating the snap.

Default value
1280
Required
No
1# Set the width of the viewport.
2 
3https://ohseesnaps.com/api/snap \
4  ?token=XXXXX \
5  &url=https://example.com
6  &w=1920

h

The height (in pixels) of the viewport to use when creating the snap.

Default value
720
Required
No
1# Set the height of the viewport.
2 
3https://ohseesnaps.com/api/snap \
4  ?token=XXXXX \
5  &url=https://example.com
6  &h=1080

f

The format of the generated snap file.

Allowed values
png, jpeg, pdf
Default value
png
Required
No
1# Generate a PDF file:
2 
3https://ohseesnaps.com/api/snap \
4  ?token=XXXXX \
5  &url=https://example.com
6  &f=pdf

dpi

The device scale factor to use when loading the snap. Use this parameter to replica retina devices.

Default value
1
Required
No
1# Print-sized image
2 
3https://ohseesnaps.com/api/snap \
4  ?token=XXXXX \
5  &url=https://example.com
6  &dpi=3

q

The quality of the generated snap. The quality parameter is only referenced when generating a jpeg format snap.

Allowed values
0 - 100
Default value
90
Required
No
1# 75% quality
2 
3https://ohseesnaps.com/api/snap \
4  ?token=XXXXX \
5  &url=https://example.com
6  &f=jpeg
7  &q=75

mobile

A boolean to indicate if the meta viewport tag should be taken into account when snapping the requested URL.

Default value
false
Required
No
1# Emulate mobile
2 
3https://ohseesnaps.com/api/snap \
4  ?token=XXXXX \
5  &url=https://example.com
6  &mobile=true

fullPage

A boolean to indicate if the snap should be of the full page. If this is set to true, the height parameter on the request is ignored.

Default value
false
Required
No
1# Take a snap of the full page, ignoring height
2 
3https://ohseesnaps.com/api/snap \
4  ?token=XXXXX \
5  &url=https://example.com
6  &fullPage=true

force

A boolean (or string representation of a boolean) to indicate if the cache should be skipped when generating the snap. If true is passed, the cache will be skipped and a snap credit will be consumed.

1# Force a new snap to be generated
2 
3https://ohseesnaps.com/api/snap \
4  ?token=XXXXX \
5  &url=https://example.com
6  &force=true
Default value
false
Required
No