Storyshaker API

The Storyshaker API is split into a private and a public section. The private section can only be accessed with the credentials of an existing storyshaker account. The public section can freely be accessed when one knows the token that is associated to every newsroom. This associated token can be found via the private endpoint "newsrooms".

Environments

  • Test ⇒ test-api.newsroom.co

  • Prod ⇒ api.newsroom.co

Terminology

This section provides a quick overview over the terms used.

  • Social Wall ⇒ A Storyshaker view that only shows posts from social media.

  • Story Wall ⇒ A Storyshaker view that shows only stories which are owned or distributed via content network.

  • Storyshaker Wall ⇒ A Storyshaker view that incorporates stories and social posts.

The term "walls" is used when working with the API.

Data types

The following data types are used in this API:

Private

Retrieve all associated newsrooms

The main entry point to the API is https://api.newsroom.co/private/newsrooms. Sending an authenticated request to it

$ curl 'https://api.newsroom.co/private/newsrooms' -i -u 'demo:demo' -X GET \
    -H 'Accept: application/json'

returns a list of the newsrooms available to you:

{
  "_embedded" : {
    "newsroomList" : [ {
      "id" : 62,
      "slug" : "newsroomdemo",
      "title" : "Newsroom Demo ",
      "icon" : "https://nrcm.s3.amazonaws.com/newsroom/images/icon/56b82a97a5a91.png",
      "token" : "xxxhrj2a204m",
      "tags" : [ {
        "slug" : "poster",
        "count" : 1,
        "popular" : false
      }, {
        "slug" : "poll",
        "count" : 1,
        "popular" : false
      }, {
        "slug" : "newpostman",
        "count" : 1,
        "popular" : false
      }, {
        "slug" : "loser",
        "count" : 1,
        "popular" : false
      }, {
        "slug" : "light",
        "count" : 1,
        "popular" : false
      }, {
        "slug" : "science",
        "count" : 0,
        "popular" : true
      }, {
        "slug" : "embedname",
        "count" : 0,
        "popular" : false
      } ],
      "_links" : {
        "self" : {
          "href" : "..."
        }
      }
    }, {
      "id" : 63,
      "slug" : "books",
      "title" : "Education",
      "icon" : "https://nrcm.s3.amazonaws.com/newsroom/images/icon/56b82b9661273.png",
      "token" : "1wza00t3kj4ti",
      "tags" : [ {
        "slug" : "suspended",
        "count" : 1,
        "popular" : false
      } ],
      "_links" : {
        "self" : {
          "href" : "..."
        }
      }
    } ]
  },
  "_links" : {
    "self" : {
      "href" : "..."
    }
  }
}
Relation Description

self

Link to this newsroom.

Retrieve specific newsroom

When the self link of the desired newsroom is followed

$ curl 'https://api.newsroom.co/private/newsrooms/62' -i -u 'demo:demo' -X GET \
    -H 'Accept: application/json'

more details are provided:

{
  "id" : 62,
  "slug" : "newsroomdemo",
  "title" : "Newsroom Demo ",
  "icon" : "https://nrcm.s3.amazonaws.com/newsroom/images/icon/56b82a97a5a91.png",
  "token" : "xxxhrj2a204m",
  "tags" : [ {
    "slug" : "poster",
    "count" : 1,
    "popular" : false
  }, {
    "slug" : "poll",
    "count" : 1,
    "popular" : false
  }, {
    "slug" : "newpostman",
    "count" : 1,
    "popular" : false
  }, {
    "slug" : "loser",
    "count" : 1,
    "popular" : false
  }, {
    "slug" : "light",
    "count" : 1,
    "popular" : false
  }, {
    "slug" : "science",
    "count" : 0,
    "popular" : true
  }, {
    "slug" : "embedname",
    "count" : 0,
    "popular" : false
  } ],
  "_links" : {
    "self" : {
      "href" : "..."
    },
    "stories" : {
      "href" : "..."
    },
    "socialPosts" : {
      "href" : "..."
    },
    "walls" : {
      "href" : "..."
    },
    "search" : {
      "href" : "..."
    },
    "public" : {
      "href" : "..."
    }
  }
}
Relation Description

self

Link to this newsroom.

public

Link to this newsroom in the public API. This is the main entry point to the public section of the API.

Public

Token

In order to be able to call the API endpoints for a specific newsroom without user credentials, you need to use a token.

Retrieve a newsroom by token

The main entry point to the public part is provided by the public link of the private newsroom resource. This link contains the token needed to access the API without credentials. A request to it

$ curl 'https://api.newsroom.co/newsrooms?token=xxxhrj2a204m' -i -X GET \
    -H 'Accept: application/json'

returns the same newsroom as the private API:

{
  "id" : 62,
  "slug" : "newsroomdemo",
  "title" : "Newsroom Demo ",
  "icon" : "https://nrcm.s3.amazonaws.com/newsroom/images/icon/56b82a97a5a91.png",
  "token" : "xxxhrj2a204m",
  "tags" : [ {
    "slug" : "poster",
    "count" : 1,
    "popular" : false
  }, {
    "slug" : "poll",
    "count" : 1,
    "popular" : false
  }, {
    "slug" : "newpostman",
    "count" : 1,
    "popular" : false
  }, {
    "slug" : "loser",
    "count" : 1,
    "popular" : false
  }, {
    "slug" : "light",
    "count" : 1,
    "popular" : false
  }, {
    "slug" : "science",
    "count" : 0,
    "popular" : true
  }, {
    "slug" : "embedname",
    "count" : 0,
    "popular" : false
  } ],
  "_links" : {
    "self" : {
      "href" : "..."
    },
    "stories" : {
      "href" : "..."
    },
    "socialPosts" : {
      "href" : "..."
    },
    "walls" : {
      "href" : "..."
    },
    "search" : {
      "href" : "..."
    },
    "embeds" : {
      "href" : "..."
    }
  }
}
Relation Description

self

Link to the newsroom.

stories

Link to the stories of this newsroom.

socialPosts

Link to the social posts of this newsroom.

walls

Link to all wall entries of this newsroom.

search

Link to a full text search over the wall entries of this newsroom.

embeds

Link to the embeds of this newsroom.

Embeds

Following the embeds link of the newsroom

$ curl 'https://api.newsroom.co/embeds?token=xxxhrj2a204m' -i -X GET \
    -H 'Accept: application/json'

returns these embeds:

{
  "_embedded" : {
    "embedList" : [ {
      "id" : 1,
      "slug" : "wb-8nyM57d013254203fDOP",
      "title" : "Clean & Simple",
      "type" : "web",
      "wallTypes" : [ "story", "social" ],
      "customization" : "<script src=\"https://mag.ic/script.js></script>",
      "options" : {
        "bg_color" : "#eeeeee",
        "layout" : "1",
        "selected_tags" : "[\"277\"]",
        "social_bg_color" : "#ffffff"
      },
      "tags" : [ {
        "name" : "poster",
        "count" : 1,
        "type" : "required",
        "popular" : false
      }, {
        "name" : "poll",
        "count" : 1,
        "type" : "navigation",
        "popular" : false
      }, {
        "name" : "loser",
        "count" : 1,
        "type" : "navigation",
        "popular" : false
      }, {
        "name" : "light",
        "count" : 1,
        "type" : "normal",
        "popular" : false
      }, {
        "name" : "newpostman",
        "count" : 1,
        "type" : "normal",
        "popular" : false
      }, {
        "name" : "embedname",
        "count" : 0,
        "type" : "normal",
        "popular" : false
      }, {
        "name" : "science",
        "count" : 0,
        "type" : "normal",
        "popular" : true
      } ],
      "_links" : {
        "self" : {
          "href" : "..."
        },
        "css" : {
          "href" : "..."
        },
        "preview" : {
          "href" : "..."
        },
        "wall" : {
          "href" : "..."
        }
      }
    }, {
      "id" : 507,
      "slug" : "wb-T05975f6e99e30eZ",
      "title" : "CustomDemo",
      "type" : "web",
      "wallTypes" : [ "story", "social" ],
      "customization" : "<script src=\"https://mag.ic/script.js></script>",
      "options" : {
        "bg_color" : "#eeeeee",
        "layout" : "1",
        "loadmore_type" : "autoload",
        "share_url" : "http://www.suissetoy.ch/desktopdefault.aspx/tabid-4101/",
        "social_bg_color" : "#123456"
      },
      "tags" : [ {
        "name" : "light",
        "count" : 1,
        "type" : "normal",
        "popular" : false
      }, {
        "name" : "loser",
        "count" : 1,
        "type" : "normal",
        "popular" : false
      }, {
        "name" : "newpostman",
        "count" : 1,
        "type" : "normal",
        "popular" : false
      }, {
        "name" : "poll",
        "count" : 1,
        "type" : "normal",
        "popular" : false
      }, {
        "name" : "poster",
        "count" : 1,
        "type" : "normal",
        "popular" : false
      }, {
        "name" : "embedname",
        "count" : 0,
        "type" : "normal",
        "popular" : false
      }, {
        "name" : "science",
        "count" : 0,
        "type" : "normal",
        "popular" : true
      } ],
      "_links" : {
        "self" : {
          "href" : "..."
        },
        "css" : {
          "href" : "..."
        },
        "preview" : {
          "href" : "..."
        },
        "wall" : {
          "href" : "..."
        }
      }
    }, {
      "id" : 508,
      "slug" : "wb-bla",
      "title" : "CustomDemo2",
      "type" : "teaser",
      "wallTypes" : [ "story" ],
      "customization" : "<script src=\"https://mag.ic/script.js></script>",
      "options" : {
        "bg_color" : "#eeeeee",
        "social_bg_color" : "#123456"
      },
      "tags" : [ {
        "name" : "light",
        "count" : 1,
        "type" : "normal",
        "popular" : false
      }, {
        "name" : "loser",
        "count" : 1,
        "type" : "normal",
        "popular" : false
      }, {
        "name" : "newpostman",
        "count" : 1,
        "type" : "normal",
        "popular" : false
      }, {
        "name" : "poll",
        "count" : 1,
        "type" : "normal",
        "popular" : false
      }, {
        "name" : "poster",
        "count" : 1,
        "type" : "normal",
        "popular" : false
      }, {
        "name" : "embedname",
        "count" : 0,
        "type" : "normal",
        "popular" : false
      }, {
        "name" : "science",
        "count" : 0,
        "type" : "normal",
        "popular" : true
      } ],
      "_links" : {
        "self" : {
          "href" : "..."
        },
        "css" : {
          "href" : "..."
        },
        "preview" : {
          "href" : "..."
        },
        "wall" : {
          "href" : "..."
        }
      }
    } ]
  }
}

If you want to retrieve exactly one embed, follow the self link of the corresponding entry

$ curl 'https://api.newsroom.co/embeds/wb-T05975f6e99e30eZ?token=xxxhrj2a204m' -i -X GET \
    -H 'Accept: application/json'

which gives

{
  "id" : 507,
  "slug" : "wb-T05975f6e99e30eZ",
  "title" : "CustomDemo",
  "type" : "web",
  "wallTypes" : [ "story", "social" ],
  "customization" : "<script src=\"https://mag.ic/script.js></script>",
  "options" : {
    "bg_color" : "#eeeeee",
    "layout" : "1",
    "loadmore_type" : "autoload",
    "share_url" : "http://www.suissetoy.ch/desktopdefault.aspx/tabid-4101/",
    "social_bg_color" : "#123456"
  },
  "tags" : [ {
    "name" : "light",
    "count" : 1,
    "type" : "normal",
    "popular" : false
  }, {
    "name" : "loser",
    "count" : 1,
    "type" : "normal",
    "popular" : false
  }, {
    "name" : "newpostman",
    "count" : 1,
    "type" : "normal",
    "popular" : false
  }, {
    "name" : "poll",
    "count" : 1,
    "type" : "normal",
    "popular" : false
  }, {
    "name" : "poster",
    "count" : 1,
    "type" : "normal",
    "popular" : false
  }, {
    "name" : "embedname",
    "count" : 0,
    "type" : "normal",
    "popular" : false
  }, {
    "name" : "science",
    "count" : 0,
    "type" : "normal",
    "popular" : true
  } ],
  "_links" : {
    "self" : {
      "href" : "..."
    },
    "css" : {
      "href" : "..."
    },
    "preview" : {
      "href" : "..."
    },
    "wall" : {
      "href" : "..."
    }
  }
}
Relation Description

self

Link to this embed.

css

Link to the CSS for this embed.

preview

Link to the preview of this newsroom and embed.

wall

Link to fetch the wall entries for this embed.

Social wall entries

Following one of the content links

$ curl 'https://api.newsroom.co/walls?token=xxxhrj2a204m&count=1' -i -X GET \
    -H 'Accept: application/json'

returns a list of the newest social wall entries of this newsroom:

{
  "_embedded" : {
    "wallList" : [ {
      "id" : "S2468",
      "title" : "titel",
      "leadText" : "leader",
      "featuredImage" : "http://tablet.jpg",
      "media" : [ {
        "id" : "http://tablet.jpg",
        "title" : "label",
        "media" : [ ],
        "type" : "featured_image",
        "source" : "Newsroom Demo ",
        "url" : "http://tablet.jpg",
        "date" : "2017-05-31T13:08:42Z",
        "resolution" : "desktop"
      }, {
        "id" : "http://mobile.jpg",
        "title" : "label2",
        "media" : [ ],
        "type" : "image",
        "source" : "Newsroom Demo ",
        "url" : "http://mobile.jpg",
        "date" : "2017-05-31T13:08:42Z",
        "resolution" : "tablet"
      } ],
      "type" : "story",
      "source" : "Newsroom Demo ",
      "url" : "http://app.newsroom.co/2468",
      "date" : "2017-05-31T13:08:42Z",
      "dates" : {
        "created" : "2016-07-13T12:15:47Z",
        "published" : "2016-07-13T12:15:47Z",
        "updated" : "2017-05-31T13:08:42Z"
      },
      "html" : "New Story with one new and one old tag",
      "moreHtml" : "<p>After read more</p>",
      "tags" : [ "poll", "newpostman", "light", "loser", "poster" ],
      "polls" : [ ],
      "pinned" : false,
      "priority" : "normal",
      "author" : {
        "id" : "1",
        "realName" : "authorname",
        "name" : "Thought Chimp",
        "userName" : "thoughtchimp",
        "image" : "https://nrcm.s3.amazonaws.com/newsroom/images/icon/56b82a97a5a91.png"
      },
      "authorName" : "authorname",
      "likes" : 0,
      "sponsored" : false,
      "_links" : {
        "self" : {
          "href" : "..."
        },
        "oEmbed" : {
          "href" : "..."
        },
        "embeded" : {
          "href" : "...",
          "templated" : true
        },
        "like" : {
          "href" : "..."
        }
      }
    } ]
  },
  "_links" : {
    "self" : {
      "href" : "..."
    },
    "newer" : {
      "href" : "..."
    },
    "older" : {
      "href" : "..."
    }
  }
}
Relation Description

self

Link to this list.

newer

Link to newer wall entries. Can be used to check if new entries have been created since the last request.

older

Link to older wall entries.

Sort order

These entries are sorted according to their priority and creation date (DESC).

Filtering

The entries can be filtered by attributes. Filtering is done by query parameters with this pattern: &attribute=operator values.

  • Supported attributes are: type, source, tag, date, id.

  • Supported operators are: empty string meaning "equals", ! meaning "not equals" and < and >.

  • Multiple values may be provided by separating them by commas.

E.g. …​/walls?tag=sport,computer&priority=<top returns all entries with tag sport or computer and priority lower than top.

Read more function

It is possible for a story to have "Read more" functionality. If user styles a story with "Read more" in the story editor from within Storyshaker frontend the first part of the story is contained in the field html, and additional content is available in moreHtml.

Styling

The html property of a wall entry contains CSS classes, but no concrete CSS rules for them are defined. This has to be done by the consumer of the API.

For type = callToAction the following CSS rules can be taken as a start:

.cta__content {
    padding: 1px 5px 36px;
}
.cta__text {
    font-size: 36px;
    text-align: center;
}
.cta__button {
    width: 100%;
}
.cta__button a {
    display: inline-block;
    margin-left: 25%;
    width: 50%;
    padding: 5px;
    font-size: 24px;
    text-align: center;
    text-decoration: none;
}

Following the search link

$ curl 'https://api.newsroom.co/walls/search?query=test&token=104riwm8yibza' -i -X GET \
    -H 'Accept: application/json'

reveals the search results

{
  "_embedded" : {
    "searchResultList" : [ {
      "id" : "P988695",
      "title" : "Super Titel",
      "leadText" : "Dies ist eine Einleitung",
      "featuredImage" : "https://picsum.photos/200/200/?image=472",
      "media" : [ {
        "id" : "https://picsum.photos/200/200/?image=472",
        "title" : "label",
        "media" : [ ],
        "type" : "image",
        "source" : "twitter",
        "url" : "https://picsum.photos/200/200/?image=472",
        "date" : "2016-06-19T21:22:00Z",
        "resolution" : "desktop"
      } ],
      "html" : "Wunderbarer Test! #livecenter",
      "url" : "https://twitter.com/newsroomz/status/705746307390910465",
      "type" : "tweet",
      "source" : "twitter",
      "date" : "2016-06-19T21:22:00Z",
      "_links" : {
        "wall" : {
          "href" : "..."
        }
      }
    }, {
      "id" : "P6281619",
      "title" : "Glück!",
      "leadText" : "Ein glücklicher Text",
      "featuredImage" : "https://picsum.photos/200/200/?image=473",
      "media" : [ {
        "id" : "https://picsum.photos/200/200/?image=473",
        "title" : "label",
        "media" : [ ],
        "type" : "image",
        "source" : "twitter",
        "url" : "https://picsum.photos/200/200/?image=473",
        "date" : "2016-08-26T08:53:00Z",
        "resolution" : "desktop"
      } ],
      "html" : "@newsroomz der test ist geglückt",
      "url" : "https://twitter.com/Leitner_Davos/status/769091168248487936",
      "type" : "mention",
      "source" : "twitter",
      "date" : "2016-08-26T08:53:00Z",
      "_links" : {
        "wall" : {
          "href" : "..."
        }
      }
    } ]
  },
  "_links" : {
    "self" : {
      "href" : "..."
    }
  }
}
Relation Description

self

Link to search query itself.

wall

Link to the wall entry of this search result.

The default search returns only a subset of the properties of wall entries. To get the complete entries, add the parameter resolved=true:

$ curl 'https://api.newsroom.co/walls/search?query=test&token=104riwm8yibza&resolved=true' -i -X GET \
    -H 'Accept: application/json'

which returns the wall entries

{
  "_embedded" : {
    "wallList" : [ {
      "id" : "P988695",
      "title" : "",
      "leadText" : "",
      "featuredImage" : "",
      "media" : [ ],
      "type" : "tweet",
      "contentType" : "text",
      "source" : "twitter",
      "url" : "https://twitter.com/newsroomz/status/705746307390910465",
      "date" : "2016-03-04T13:26:46Z",
      "dates" : {
        "created" : "2016-03-04T13:52:02Z",
        "published" : "2016-03-04T13:26:46Z",
        "updated" : "2016-06-19T21:22:03Z"
      },
      "text" : "Wunderbarer Test! #livecenter",
      "html" : "Wunderbarer Test!  <a href=\"https://twitter.com/hashtag/livecenter\" target=\"_blank\" rel=\"nofollow\">#livecenter</a>",
      "moreHtml" : "",
      "tags" : [ ],
      "polls" : [ ],
      "pinned" : false,
      "priority" : "normal",
      "author" : {
        "id" : "2902106444",
        "name" : "Newsroom",
        "userName" : "newsroomz",
        "image" : "https://pbs.twimg.com/profile_images/652025638082211840/tU1TOYm5_normal.jpg",
        "profile" : "https://twitter.com/newsroomz"
      },
      "authorName" : "",
      "likes" : 0,
      "sponsored" : false,
      "_links" : {
        "self" : {
          "href" : "..."
        },
        "oEmbed" : {
          "href" : "..."
        }
      }
    } ]
  },
  "_links" : {
    "self" : {
      "href" : "..."
    }
  }
}

Contact

Please do not hesitate to ask any questions that might arise. We are open to input and criticism and we will use it to cater for your use cases, if possible.

Licensing

We use third part libraries that either are licensed under GPLv3 or the MIT license.

MIT

Thus, our code is open source and you can freely do with it what you wish as long as you redistribute it (if ever) under GPLv3.