The publication based API will return all non-archived publications for a given boxAlias. The Scope Team will provide the appropriate boxAlias for your integration.

The following API call will return the most recent publications:

HTTP GET

https://scope-lb.api.thescope.com/public/api/v1/box/{boxAlias}/publication?sort=DATE

The following API call will return the most recent publications WITHIN a specific project id:

HTTP GET

https://scope-lb.api.thescope.com/public/api/v1/box/{boxAlias}/publication/project/{projectId}?sort=DATE

Data Structure

At the highest level we get a list of publications. A publication has an ID, a body and details related to the project that this publication was published in.

[
{
    "id": 960,
    "body": {
        ...
    },
    "projectDetails": {
        "projectName": "my first project"
    },
    "publicationDate": "2020-01-17T14:03:26Z"
},
...
]

The body describes the structure of the body of an individual publication.

Example for a body:

"body": {
    "intro": {
        "textContent": "This can be used for an intro text that is rendered outside of the main body"
    },
    "mainSection": [
        {
            "type": "TITLE",
            "textContent": "Read these articles"
        },
        {
            "type": "ARTICLELIST",
            "articlesContent": [
                {
                    "articleImageUrl": "https://storage.googleapis.com/scope-test-private-article-images/4919",
                    "articleTitle": "New lolly range sparks sugar row",
                    "articleSource": "cnn.com",
                    "articleComment": "Comment written by the curator",
                    "articleUrl": "https://thescope.com",
                    "articlePublicationDate": "2019-11-28T00:07:00",
                    "tags": [
                                {
                                    "id": "12",
                                    "title": "Cats"
                                }
                            ]
                },
                {
                    "articleImageUrl": "https://storage.googleapis.com/scope-test-private-article-images/4916",
                    "articleTitle": "De la Parte suffers multiple fractures after Vuelta a Espana crash",
                    "articleSource": "tagi.ch",
                    "articleComment": "Comment written by the curator",
                    "articleUrl": "https://thescope.com",
                    "articlePublicationDate": "2019-11-28T00:07:00",
                    "tags": [
                                {
                                    "id": "12",
                                    "title": "Cats"
                                },
                                {
                                    "id": "23",
                                    "title": "Dogs"
                                }
                            ]
                },
                {
                    "articleImageUrl": "https://storage.googleapis.com/scope-test-private-article-images/4917",
                    "articleTitle": "How being in nature promotes healthier body image",
                    "articleSource": "nzz.ch",
                    "articleComment": "Comment written by the curator",
                    "articleUrl": "https://thescope.com",
                    "articlePublicationDate": "2019-11-28T00:07:00",
                    "tags": []
                }
                
            ],
            "renderType": "LARGE_IMAGE"
        },
        {
            "type": "TITLE",
            "textContent": "Example Title above a paragraph of text"
        },
        {
            "type": "SIMPLETEXT",
            "textContent": "Lorem Ipsum is simply dummy text of the printing and typesetting industry."
        }
    ]
}

The Body consists of an intro text ("intro") and a list of body components. This list can be of any size (including zero) and will consist of an arbitrary arrangement of the following types:

The list of components will be extended in the future.

Type	Example	Details
TITLE	`{ "type": "TITLE", "textContent": "Read these articles" }`
SIMPLETEXT	`{ "type": "SIMPLETEXT", "textContent": "Lorem Ipsum is simply dummy text of the printing and typesetting industry." }`	Users are encouraged to use markdown to format their text. The markdown syntax will not be turned into HTML.
ARTICLES	{ "type": "ARTICLELIST", "renderType": "LARGE_IMAGE", "articlesContent": [ { "articleImageUrl": "https://storage.googleapis.com/scope-test-private-article-images/4919", "articleTitle": "New lolly range sparks sugar row", "articleSource": "cnn.com", "articleComment": "Comment written by the curator", "articleUrl": "https://thescope.com", "articlePublicationDate": "2019-11-28T00:07:00", "tags": [ { "id": "12", "title": "Cats" } ] }, { "articleImageUrl": "https://storage.googleapis.com/scope-test-private-article-images/4916", "articleTitle": "De la Parte suffers multiple fractures after Vuelta a Espana crash", "articleSource": "tagi.ch", "articleComment": "Comment written by the curator", "articleUrl": "https://thescope.com", "articlePublicationDate": "2019-11-28T00:07:00", "tags": [ { "id": "12", "title": "Cats" } ] }, { "articleImageUrl": "https://storage.googleapis.com/scope-test-private-article-images/4917", "articleTitle": "How being in nature promotes healthier body image", "articleSource": "nzz.ch", "articleComment": "Comment written by the curator", "articleUrl": "https://thescope.com", "articlePublicationDate": "2019-11-28T00:07:00", "tags": [ { "id": "12", "title": "Cats" } ] } ] }	Users are encouraged to use markdown to format their article comments. The comments can then either be returned as markdown, HTML or plain text. See `renderingStyle` below. The values for `renderType` within an article list are: `SMALL_IMAGE` `LARGE_IMAGE` `COMPACT` The Timezone for the field `articlePublicationDate` is CET (GMT+1) or CEST (GMT+2) → Zurich Time

These elements correspond 1:1 to the values entered by the user in the UI:

Required Parameters

boxAlias - the alias of your box / workspace

Optional Query Arguments

Name	Possible Values	Explanation

Name	Possible Values	Explanation
`renderingStyle`	`RAW_MARKDOWN, HTML_RENDERED, NO_FORMATTING`	RAW_MARKDOWN: All text elements that support rich text formatting are returned with markdown syntax HTML_RENDERED: All text elements that support rich text formatting are returned in HTML All text elements that support rich text formatting are returned in plain text without any styling, format details.

Paging

Without any additional query parameters, the "publications" array (at the root level) will contain the most recent 15 publications, ordered by publication date of the publication (not the articles). Newest publications first. In case your use case requires paging the following additional query parameters can be used:

maxNumberOfPublications	The maximum number of publications that should be returned in this request. If this number exceeds 30, then the number is ignored and the response contains 30 selections.
startAfterPublicationId	Return the publications that were published chronologically on the same date of before the given startAfterPublicationId, the id of a publication is always returned in the field "id".

The endpoint returns a list of publications. The list is sorted by publication date in descending order - newer publication items are before older publication items in the list. The optional parameter startAfterPublicationId is used for pagination. When this parameter is sent, the results will not be ordered by ID but by date. So, startAfterPublicationId is just a starting point, and the returned publications have the exact same or older publication date.

Example URL:

https://scope-lb.api.thescope.com/public/api/v1/box/[boxAlias]/publication?maxNumberOfPublications=2&startAfterPublicationId=523

Image Proxy (CloudImage)

CloudImage provides a fast and reliable infrastructure to deliver images in use case specific sizes or croppings.

Important

All images that are returned from Scope and exposed to users must be proxied through CloudImage. Do not embed these images directly.

URL Format

https://cy1er32c.cloudimg.io/v7/original_image_url?operations&filters

Example URL

https://cy1er32c.cloudimg.io/v7/https://storage.googleapis.com/scope-private-article-images/privatearticleimage-129368-1644562995969.jpg?func=crop&w=600&h=375

Further documentation can be found in the CloudImage documentation: https://docs.cloudimage.io/go/cloudimage-documentation-v7/en/introduction

Changelog

Date	Change-Topic	Details

Date

Change-Topic

Details

May 13th 2020

Article-Tags exposed in the Publication-Based API

Each article that is listed in an article list now contains the new field “tags“.

The “tags“ field is a sorted list of the tags that a user has assigned to the asset and can be empty.

For articles that were added before this change the value of this field is “null“.