# Stillio API (version 3)

## About the API

* The API uses pragmatic REST as its architectural style
* Requests use [JSON-LD 1.0](https://www.w3.org/TR/json-ld/) as method for serializing data
* The API uses shared, established vocabularies for modelling data: [Hydra](http://www.hydra-cg.com/spec/latest/core/) for collections and errors and [Schema.org](https://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](https://support.stillio.com/article/18-use-stillio-api-to-fetch-screenshots-and-urls). 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**

```json
{
    "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**

```json
{
    "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**

```json
{
    "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"
}
```

### 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**

```json
{
    "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**

```json
{
    "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](https://en.wikipedia.org/wiki/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**

```json
{
    "@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"
        }
    }
}
```


---

# Agent Instructions: Querying This Documentation

If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter:

```
GET https://api-docs.stillio.com/stillio-api-version-3.md?ask=<question>
```

The question should be specific, self-contained, and written in natural language.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.