API

Stillio API (version 3)

You can use the Stillio API for interacting with the webpages and screenshots stored on the Stillio platform. This reference outlines version 3 of the API.

Contents

• About the API
• Authentication
• Errors
• Endpoints
  • Webpages
    • Get webpages
    • Get a webpage
    • Delete a webpage
  • Screenshots
    • Get screenshots of a webpage
    • Get a screenshot
  • General information
    • Get API context information

About the API

• The API uses pragmatic REST as its architectural style
• Requests use JSON-LD 1.0 as method for serializing data
• The API uses shared, established vocabularies for modelling data: Hydra for collections and errors and Schema.org for webpages and screenshots. For specific properties Stillio uses its own vocabulary
• The API may change. For example, new properties may be added to the headers or body of endpoints

Authentication

The API uses a Bearer token for authentication. You can create your token in the Stillio app. Do not share the token with untrusted parties or use it directly in your browser client.

Errors

The API uses common HTTP status codes: 2xx for success, 4xx for errors caused by the caller and 5xx for server errors. The table underneath lists the most common errors that can occur:

Status	Description
400	The request is invalid
401	The Bearer token is invalid
404	The resource does not exist
415	The content type is not supported
422	The resource cannot be processed
500	A server error has occurred
503	The server is under maintenance

Response

Headers

Name	Value
Status	HTTP status, e.g. 400 Bad Request, 404 Not Found, 500 Internal Server Error
Content-Type	application/json
Link	<https://api.stillio.com/v3/contexts>; rel="http://www.w3.org/ns/json-ld#context"; type="application/ld+json"

Example body

{
    "type": "Error",
    "title": "Bad Request",
    "description": "..."
}

Endpoints

Webpages

Get webpages

Request

GET https://api.stillio.com/v3/webpages?page={page}&limit={limit}&sort={sort}&order={order}

Headers

Name	Value
Authorization	Bearer: {token}
Accept	application/json

Query string parameters

Property	Data type	Required	Description
page	Number	No	Page index. Default: 1
limit	Number between 1 and 100	No	Number of items per page. Default: 50
sort	Text: dateCreated, isPartOf.name, name, url	No	Field to sort the items by. Default: isPartOf.name
order	Text: asc, desc	No	Sorting direction of the items: ascending or descending. Default: asc

Example requests

GET https://api.stillio.com/v3/webpages

GET https://api.stillio.com/v3/webpages?page=2

GET https://api.stillio.com/v3/webpages?page=2&limit=5

GET https://api.stillio.com/v3/webpages?sort=dateCreated&order=desc

Response

Headers

Name	Value
Status	200 OK
Content-Type	application/json
Link	<https://api.stillio.com/v3/contexts>; rel="http://www.w3.org/ns/json-ld#context"; type="application/ld+json"

Body

Property	Data type	Description
type	Text	Type of the collection: Collection
id	URI	URL of the collection
totalItems	Number	Number of webpage records in the collection
members	List	List of webpage records
members[].type	Text	Type of the webpage record: WebPage
members[].id	URI	URL of the webpage record
members[].identifier	Text	Unique identifier of the webpage record
members[].name	Text	Name of the webpage record
members[].url	URI	URL of the webpage
members[].keywords	List	List of keywords or tags to describe the webpage record
members[].dateCreated	Date, in ISO 8601 date format	Date and time at which the webpage record was created (UTC)
members[].dateModified	Date, in ISO 8601 date format	Date and time at which the webpage record was modified (UTC)
members[].subjectOf	Resource	Reference to the collection of screenshots of this webpage record
members[].subjectOf.type	Text	Type of the screenshot collection: Collection
members[].subjectOf.id	URI	URL of the screenshot collection
members[].isPartOf	Resource	The webpage group the webpage record belongs to
members[].isPartOf.type	Text	Type of the webpage group record: WebPageGroup
members[].isPartOf.name	Text	Name of the webpage group record. This name is derived from the URL of the webpage
view	Resource	Controls for paginating the collection
view.type	Text	Type of the resource: PartialCollectionView
view.id	URI	URL of the current page in the collection
view.first	URI	URL of the first page in the collection. Not set if there is no first page
view.previous	URI	URL of the previous page in the collection. Not set if there is no previous page
view.next	URI	URL of the next page in the collection. Not set if there is no next page
view.last	URI	URL of the last page in the collection. Not set if there is no last page

Example body

{
    "type": "Collection",
    "id": "https://api.stillio.com/v3/webpages",
    "totalItems": 123,
    "members": [
        {
            "type": "WebPage",
            "id": "https://api.stillio.com/v3/webpages/{webpageId}",
            "identifier": "{webpageId}",
            "name": "Some page",
            "url": "http://www.example.org/somePage.html?q=a",
            "keywords": ["Example1", "Example2"],
            "dateCreated": "2019-01-29T11:24:58.743Z",
            "dateModified": "2019-01-29T11:24:58.743Z",
            "subjectOf": {
                "type": "Collection",
                "id": "https://api.stillio.com/v3/webpages/{webpageId}/screenshots"
            },
            "isPartOf": {
                "type": "WebPageGroup",
                "name": "example.org"
            }
        },
        // ...
    ],
    "view": {
        "type": "PartialCollectionView",
        "id": "https://api.stillio.com/v3/webpages?page=3",
        "first": "https://api.stillio.com/v3/webpages?page=1",
        "previous": "https://api.stillio.com/v3/webpages?page=2",
        "next": "https://api.stillio.com/v3/webpages?page=4",
        "last": "https://api.stillio.com/v3/webpages?page=15"
    }
}

Get a webpage

Request

GET https://api.stillio.com/v3/webpages/{webpageId}

Headers

Name	Value
Authorization	Bearer: {token}
Accept	application/json

Response

Headers

Name	Value
Status	200 OK
Content-Type	application/json
Link	<https://api.stillio.com/v3/contexts>; rel="http://www.w3.org/ns/json-ld#context"; type="application/ld+json"

Body

Property	Data type	Description
type	Text	Type of the webpage record: WebPage
id	URI	URL of the webpage record
identifier	Text	Unique identifier of the webpage record
name	Text	Name of the webpage record
url	URI	URL of the webpage
keywords	List	List of keywords or tags to describe the webpage record
dateCreated	Date, in ISO 8601 date format	Date and time at which the webpage record was created (UTC)
dateModified	Date, in ISO 8601 date format	Date and time at which the webpage record was modified (UTC)
subjectOf	Resource	Reference to the collection of screenshots of this webpage record
subjectOf.type	Text	Type of the screenshot collection: Collection
subjectOf.id	URI	URL of the screenshot collection
isPartOf	Resource	The webpage group the webpage record belongs to
isPartOf.type	Text	Type of the webpage group record: WebPageGroup
isPartOf.name	Text	Name of the webpage group record. This name is derived from the URL of the webpage
collection	URI	URL of the collection to which this webpage record belongs

Example body

{
    "type": "WebPage",
    "id": "https://api.stillio.com/v3/webpages/{webpageId}",
    "identifier": "{webpageId}",
    "name": "Some page",
    "url": "http://www.example.org/somePage.html?q=a",
    "keywords": ["Example1", "Example2"],
    "dateCreated": "2019-01-29T11:24:58.743Z",
    "dateModified": "2019-01-29T11:24:58.743Z",
    "subjectOf": {
        "type": "Collection",
        "id": "https://api.stillio.com/v3/webpages/{webpageId}/screenshots"
    },
    "isPartOf": {
        "type": "WebPageGroup",
        "name": "example.org"
    },
    "collection": "https://api.stillio.com/v3/webpages"
}

Delete a webpage

Note: Deleting a webpage also deletes all the screenshots associated with it.

Request

DELETE https://api.stillio.com/v3/webpages/{webpageId}

Headers

Name	Value
Authorization	Bearer: {token}
Accept	application/json

Response

Headers

Name	Value
Status	204 No Content
Link	<https://api.stillio.com/v3/contexts>; rel="http://www.w3.org/ns/json-ld#context"; type="application/ld+json"

Body

No body

Screenshots

Get screenshots of a webpage

Request

GET https://api.stillio.com/v3/webpages/{webpageId}/screenshots?page={page}&limit={limit}&sort={sort}&order={order}

Headers

Name	Value
Authorization	Bearer: {token}
Accept	application/json

Query string parameters

Property	Data type	Required	Description
page	Number	No	Page index. Default: 1
limit	Number between 1 and 100	No	Number of items per page. Default: 50
sort	Text: dateCreated	No	Field to sort the items by. Default: dateCreated
order	Text: asc, desc	No	Sorting direction of the items: ascending or descending. Default: desc
isFavorite	Boolean: true, false	No	Flag indicating whether only items must be returned that have been marked as favorite (true) or not (false)

Example requests

GET https://api.stillio.com/v3/webpages/{webpageId}/screenshots

GET https://api.stillio.com/v3/webpages/{webpageId}/screenshots?page=2

GET https://api.stillio.com/v3/webpages/{webpageId}/screenshots?page=2&limit=5

GET https://api.stillio.com/v3/webpages/{webpageId}/screenshots?sort=dateCreated&order=desc

GET https://api.stillio.com/v3/webpages/{webpageId}/screenshots?isFavorite=true

Response

Headers

Name	Value
Status	200 OK
Content-Type	application/json
Link	<https://api.stillio.com/v3/contexts>; rel="http://www.w3.org/ns/json-ld#context"; type="application/ld+json"

Body

Property	Data type	Description
type	Text	Type of the collection: Collection
id	URI	URL of the collection
totalItems	Number	Number of screenshot records in the collection
members	List	List of screenshot records
members[].type	Text	Type of the screenshot record: ImageObject
members[].id	URI	URL of the screenshot record
members[].identifier	Text	Unique identifier of the screenshot record
members[].isFavorite	Boolean	Flag indicating whether the screenshot record has been marked as favorite (true) or not (false)
members[].dateCreated	Date, in ISO 8601 date format	Date and time at which the screenshot record was created (UTC)
members[].dateModified	Date, in ISO 8601 date format	Date and time at which the screenshot record was modified (UTC)
members[].contentUrl	URI	URL of the screenshot image
members[].encodingFormat	Text, in MIME format	Media type of the screenshot image, e.g. image/png
members[].thumbnail	Resource	The thumbnail version of the screenshot image
members[].thumbnail.type	Text	Type of the thumbnail image: ImageObject
members[].thumbnail.contentUrl	URI	URL of the thumbnail image
members[].thumbnail.encodingFormat	Text, in MIME format	Media type of the thumbnail image, e.g. image/png
members[].about	Resource	The webpage record the screenshot record is about
members[].about.type	Text	Type of the webpage record: WebPage
members[].about.id	URI	URL of the webpage record
view	Resource	Controls for paginating the collection
view.type	Text	Type of the resource: PartialCollectionView
view.id	URI	URL of the current page in the collection
view.first	URI	URL of the first page in the collection. Not set if there is no first page
view.previous	URI	URL of the previous page in the collection. Not set if there is no previous page
view.next	URI	URL of the next page in the collection. Not set if there is no next page
view.last	URI	URL of the last page in the collection. Not set if there is no last page

Example body

{
    "type": "Collection",
    "id": "https://api.stillio.com/v3/webpages/{webpageId}/screenshots",
    "totalItems": 123,
    "members": [
        {
            "type": "ImageObject",
            "id": "https://api.stillio.com/v3/webpages/{webpageId}/screenshots/{screenshotId}",
            "identifier": "{screenshotId}",
            "isFavorite": true,
            "dateCreated": "2019-01-29T11:23:58.624Z",
            "dateModified": "2019-01-29T11:24:58.743Z",
            "contentUrl": "https://stillio-hosting/path/to/image.png",
            "encodingFormat": "image/png",
            "thumbnail": {
                "type": "ImageObject",
                "contentUrl": "https://stillio-hosting/path/to/thumbnail.png",
                "encodingFormat": "image/png"
            },
            "about": {
                "type": "WebPage",
                "id": "https://api.stillio.com/v3/webpages/{webpageId}"
            }
        },
        // ...
    ],
    "view": {
        "type": "PartialCollectionView",
        "id": "https://api.stillio.com/v3/webpages/{webpageId}/screenshots?page=3",
        "first": "https://api.stillio.com/v3/webpages/{webpageId}/screenshots?page=1",
        "previous": "https://api.stillio.com/v3/webpages/{webpageId}/screenshots?page=2",
        "next": "https://api.stillio.com/v3/webpages/{webpageId}/screenshots?page=4",
        "last": "https://api.stillio.com/v3/webpages/{webpageId}/screenshots?page=15"
    }
}

Get a screenshot

Request

GET https://api.stillio.com/v3/webpages/{webpageId}/screenshots/{screenshotId}

Headers

Name	Value
Authorization	Bearer: {token}
Accept	application/json

Response

Headers

Name	Value
Status	200 OK
Content-Type	application/json
Link	<https://api.stillio.com/v3/contexts>; rel="http://www.w3.org/ns/json-ld#context"; type="application/ld+json"

Body

Property	Data type	Description
type	Text	Type of the screenshot record: ImageObject
id	URI	URL of the screenshot record
identifier	Text	Unique identifier of the screenshot record
isFavorite	Boolean	Flag indicating whether the screenshot record has been marked as favorite (true) or not (false)
dateCreated	Date, in ISO 8601 date format	Date and time at which the screenshot record was created (UTC)
dateModified	Date, in ISO 8601 date format	Date and time at which the screenshot record was modified (UTC)
contentUrl	URI	URL of the screenshot image
encodingFormat	Text, in MIME format	Media type of the screenshot image, e.g. image/png
thumbnail	Resource	The thumbnail version of the screenshot image
thumbnail.type	Text	Type of the thumbnail image: ImageObject
thumbnail.contentUrl	URI	URL of the thumbnail image
thumbnail.encodingFormat	Text, in MIME format	Media type of the thumbnail image, e.g. image/png
about	Resource	The webpage record the screenshot record is about
about.type	Text	Type of the webpage record: WebPage
about.id	URI	URL of the webpage record
collection	URI	URL of the collection to which this screenshot record belongs

Example body

{
    "type": "ImageObject",
    "id": "https://api.stillio.com/v3/webpages/{webpageId}/screenshots/{screenshotId}",
    "identifier": "{screenshotId}",
    "isFavorite": true,
    "dateCreated": "2019-01-29T11:23:58.624Z",
    "dateModified": "2019-01-29T11:24:58.743Z",
    "contentUrl": "https://stillio-hosting/path/to/image.png",
    "encodingFormat": "image/png",
    "thumbnail": {
        "type": "ImageObject",
        "contentUrl": "https://stillio-hosting/path/to/thumbnail.png",
        "encodingFormat": "image/png"
    },
    "about": {
        "type": "WebPage",
        "id": "https://api.stillio.com/v3/webpages/{webpageId}"
    },
    "collection": "https://api.stillio.com/v3/webpages/{webpageId}/screenshots"
}

General information

Get API context information

This endpoint returns contextual information about the API and does not require authentication. You usually only need this information if your application uses Linked Data.

Request

GET https://api.stillio.com/v3/contexts

Headers

Name	Value
Accept	application/json

Response

Headers

Name	Value
Status	200 OK
Content-Type	application/ld+json

Example body

{
    "@context": {
        "type": "@type",
        "id": "@id",
        "as": "https://www.w3.org/ns/activitystreams#",
        "hydra": "http://www.w3.org/ns/hydra/core#",
        "schema": "https://schema.org/",
        "stillio": "https://api.stillio.com/v3/vocab#",
        "ImageObject": "schema:ImageObject",
        "WebPage": "schema:WebPage",
        "WebPageGroup": "stillio:WebPageGroup",
        "IpAddress": "stillio:IpAddress",
        "Collection": "hydra:Collection",
        "PartialCollectionView": "hydra:PartialCollectionView",
        "Error": "hydra:Error",
        "Create": "as:Create",
        "Reject": "as:Reject",
        "summary": {
            "@id": "as:summary"
        },
        "actor": {
            "@id": "as:actor",
            "@type": "@id"
        },
        "object": {
            "@id": "as:object"
        },
        "published": {
            "@id": "as:published",
            "@type": "http://www.w3.org/2001/XMLSchema#dateTime"
        },
        "title": {
            "@id": "hydra:title"
        },
        "description": {
            "@id": "hydra:description"
        },
        "collection": {
            "@id": "hydra:collection",
            "@type": "@id"
        },
        "totalItems": {
            "@id": "hydra:totalItems"
        },
        "members": {
            "@id": "hydra:member"
        },
        "view": {
            "@id": "hydra:view",
            "@type": "@id"
        },
        "first": {
            "@id": "hydra:first",
            "@type": "@id"
        },
        "previous": {
            "@id": "hydra:previous",
            "@type": "@id"
        },
        "next": {
            "@id": "hydra:next",
            "@type": "@id"
        },
        "last": {
            "@id": "hydra:last",
            "@type": "@id"
        },
        "dateCreated": {
            "@id": "schema:dateCreated",
            "@type": "http://www.w3.org/2001/XMLSchema#dateTime"
        },
        "dateModified": {
            "@id": "schema:dateModified",
            "@type": "http://www.w3.org/2001/XMLSchema#dateTime"
        },
        "datePublished": {
            "@id": "schema:datePublished",
            "@type": "http://www.w3.org/2001/XMLSchema#dateTime"
        },
        "identifier": {
            "@id": "schema:identifier"
        },
        "isFavorite": {
            "@id": "stillio:isFavorite"
        },
        "name": {
            "@id": "schema:name"
        },
        "about": {
            "@id": "schema:about"
        },
        "subjectOf": {
            "@id": "schema:subjectOf"
        },
        "isPartOf": {
            "@id": "schema:isPartOf"
        },
        "contentUrl": {
            "@id": "schema:contentUrl",
            "@type": "@id"
        },
        "encodingFormat": {
            "@id": "schema:encodingFormat"
        },
        "url": {
            "@id": "schema:url",
            "@type": "@id"
        },
        "thumbnail": {
            "@id": "schema:thumbnail"
        },
        "isBasedOn": {
            "@id": "schema:isBasedOn",
            "@type": "@id"
        }
    }
}