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",
        "title" : "poster",
        "count" : 1,
        "popular" : false
      }, {
        "slug" : "poll",
        "title" : "poll",
        "count" : 1,
        "popular" : false
      }, {
        "slug" : "newpostman",
        "title" : "newpostman",
        "count" : 1,
        "popular" : false
      }, {
        "slug" : "loser",
        "title" : "loser",
        "count" : 1,
        "popular" : false
      }, {
        "slug" : "light",
        "title" : "light",
        "count" : 1,
        "popular" : false
      }, {
        "slug" : "science",
        "title" : "science",
        "count" : 0,
        "popular" : true
      }, {
        "slug" : "embedname",
        "title" : "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",
        "title" : "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",
    "title" : "poster",
    "count" : 1,
    "popular" : false
  }, {
    "slug" : "poll",
    "title" : "poll",
    "count" : 1,
    "popular" : false
  }, {
    "slug" : "newpostman",
    "title" : "newpostman",
    "count" : 1,
    "popular" : false
  }, {
    "slug" : "loser",
    "title" : "loser",
    "count" : 1,
    "popular" : false
  }, {
    "slug" : "light",
    "title" : "light",
    "count" : 1,
    "popular" : false
  }, {
    "slug" : "science",
    "title" : "science",
    "count" : 0,
    "popular" : true
  }, {
    "slug" : "embedname",
    "title" : "embedname",
    "count" : 0,
    "popular" : false
  } ],
  "_links" : {
    "self" : {
      "href" : "..."
    },
    "stories" : {
      "href" : "..."
    },
    "socialPosts" : {
      "href" : "..."
    },
    "walls" : {
      "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",
    "title" : "poster",
    "count" : 1,
    "popular" : false
  }, {
    "slug" : "poll",
    "title" : "poll",
    "count" : 1,
    "popular" : false
  }, {
    "slug" : "newpostman",
    "title" : "newpostman",
    "count" : 1,
    "popular" : false
  }, {
    "slug" : "loser",
    "title" : "loser",
    "count" : 1,
    "popular" : false
  }, {
    "slug" : "light",
    "title" : "light",
    "count" : 1,
    "popular" : false
  }, {
    "slug" : "science",
    "title" : "science",
    "count" : 0,
    "popular" : true
  }, {
    "slug" : "embedname",
    "title" : "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,
      "newsroomId" : 62,
      "channelId" : 123,
      "slug" : "wb-8nyM57d013254203fDOP",
      "title" : "Clean & Simple",
      "type" : "web",
      "wallTypes" : [ "story", "social" ],
      "customization" : "<script src=\"https://mag.ic/script.js></script>",
      "options" : {
        "bg_color" : "#eeeeee",
        "branding" : "1",
        "hasTop" : "0",
        "layout" : "1",
        "selected_tags" : "[\"277\"]",
        "social_bg_color" : "#ffffff"
      },
      "tags" : [ {
        "name" : "poster",
        "title" : "poster",
        "count" : 1,
        "type" : "required",
        "popular" : false
      }, {
        "name" : "poll",
        "title" : "poll",
        "count" : 1,
        "type" : "navigation",
        "popular" : false
      }, {
        "name" : "loser",
        "title" : "loser",
        "count" : 1,
        "type" : "navigation",
        "popular" : false
      }, {
        "name" : "light",
        "title" : "light",
        "count" : 1,
        "type" : "normal",
        "popular" : false
      }, {
        "name" : "newpostman",
        "title" : "newpostman",
        "count" : 1,
        "type" : "normal",
        "popular" : false
      }, {
        "name" : "embedname",
        "title" : "embedname",
        "count" : 0,
        "type" : "normal",
        "popular" : false
      }, {
        "name" : "science",
        "title" : "science",
        "count" : 0,
        "type" : "normal",
        "popular" : true
      } ],
      "adPosts" : [ ],
      "_links" : {
        "self" : {
          "href" : "..."
        },
        "css" : {
          "href" : "..."
        },
        "preview" : {
          "href" : "..."
        },
        "wall" : {
          "href" : "..."
        }
      }
    }, {
      "id" : 507,
      "newsroomId" : 62,
      "channelId" : 124,
      "slug" : "wb-T05975f6e99e30eZ",
      "title" : "CustomDemo",
      "type" : "web",
      "wallTypes" : [ "story", "social" ],
      "customization" : "<script src=\"https://mag.ic/script.js></script>",
      "options" : {
        "bg_color" : "#eeeeee",
        "branding" : "1",
        "hasTop" : "0",
        "layout" : "1",
        "loadmore_type" : "autoload",
        "share_url" : "http://www.suissetoy.ch/desktopdefault.aspx/tabid-4101/",
        "social_bg_color" : "#123456"
      },
      "tags" : [ {
        "name" : "light",
        "title" : "light",
        "count" : 1,
        "type" : "normal",
        "popular" : false
      }, {
        "name" : "loser",
        "title" : "loser",
        "count" : 1,
        "type" : "normal",
        "popular" : false
      }, {
        "name" : "newpostman",
        "title" : "newpostman",
        "count" : 1,
        "type" : "normal",
        "popular" : false
      }, {
        "name" : "poll",
        "title" : "poll",
        "count" : 1,
        "type" : "normal",
        "popular" : false
      }, {
        "name" : "poster",
        "title" : "poster",
        "count" : 1,
        "type" : "normal",
        "popular" : false
      }, {
        "name" : "embedname",
        "title" : "embedname",
        "count" : 0,
        "type" : "normal",
        "popular" : false
      }, {
        "name" : "science",
        "title" : "science",
        "count" : 0,
        "type" : "normal",
        "popular" : true
      } ],
      "adPosts" : [ ],
      "_links" : {
        "self" : {
          "href" : "..."
        },
        "css" : {
          "href" : "..."
        },
        "preview" : {
          "href" : "..."
        },
        "wall" : {
          "href" : "..."
        }
      }
    }, {
      "id" : 508,
      "newsroomId" : 62,
      "channelId" : 125,
      "slug" : "wb-bla",
      "title" : "CustomDemo2",
      "type" : "teaser",
      "wallTypes" : [ "story" ],
      "customization" : "<script src=\"https://mag.ic/script.js></script>",
      "options" : {
        "bg_color" : "#eeeeee",
        "branding" : "1",
        "hasTop" : "0",
        "social_bg_color" : "#123456"
      },
      "tags" : [ {
        "name" : "light",
        "title" : "light",
        "count" : 1,
        "type" : "normal",
        "popular" : false
      }, {
        "name" : "loser",
        "title" : "loser",
        "count" : 1,
        "type" : "normal",
        "popular" : false
      }, {
        "name" : "newpostman",
        "title" : "newpostman",
        "count" : 1,
        "type" : "normal",
        "popular" : false
      }, {
        "name" : "poll",
        "title" : "poll",
        "count" : 1,
        "type" : "normal",
        "popular" : false
      }, {
        "name" : "poster",
        "title" : "poster",
        "count" : 1,
        "type" : "normal",
        "popular" : false
      }, {
        "name" : "embedname",
        "title" : "embedname",
        "count" : 0,
        "type" : "normal",
        "popular" : false
      }, {
        "name" : "science",
        "title" : "science",
        "count" : 0,
        "type" : "normal",
        "popular" : true
      } ],
      "adPosts" : [ ],
      "_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,
  "newsroomId" : 62,
  "channelId" : 124,
  "slug" : "wb-T05975f6e99e30eZ",
  "title" : "CustomDemo",
  "type" : "web",
  "wallTypes" : [ "story", "social" ],
  "customization" : "<script src=\"https://mag.ic/script.js></script>",
  "options" : {
    "bg_color" : "#eeeeee",
    "branding" : "1",
    "hasTop" : "0",
    "layout" : "1",
    "loadmore_type" : "autoload",
    "share_url" : "http://www.suissetoy.ch/desktopdefault.aspx/tabid-4101/",
    "social_bg_color" : "#123456"
  },
  "tags" : [ {
    "name" : "light",
    "title" : "light",
    "count" : 1,
    "type" : "normal",
    "popular" : false
  }, {
    "name" : "loser",
    "title" : "loser",
    "count" : 1,
    "type" : "normal",
    "popular" : false
  }, {
    "name" : "newpostman",
    "title" : "newpostman",
    "count" : 1,
    "type" : "normal",
    "popular" : false
  }, {
    "name" : "poll",
    "title" : "poll",
    "count" : 1,
    "type" : "normal",
    "popular" : false
  }, {
    "name" : "poster",
    "title" : "poster",
    "count" : 1,
    "type" : "normal",
    "popular" : false
  }, {
    "name" : "embedname",
    "title" : "embedname",
    "count" : 0,
    "type" : "normal",
    "popular" : false
  }, {
    "name" : "science",
    "title" : "science",
    "count" : 0,
    "type" : "normal",
    "popular" : true
  } ],
  "adPosts" : [ ],
  "_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",
      "slug" : "the slug",
      "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" : "2016-07-13T12:15:47Z",
        "resolution" : "desktop",
        "ratio" : "2:1"
      }, {
        "id" : "http://mobile.jpg",
        "title" : "label2",
        "media" : [ ],
        "type" : "image",
        "source" : "Newsroom Demo ",
        "url" : "http://mobile.jpg",
        "date" : "2016-07-13T12:15:47Z",
        "resolution" : "tablet",
        "ratio" : "4:3"
      } ],
      "type" : "story",
      "source" : "Newsroom Demo ",
      "url" : "http://app.newsroom.co/2468",
      "date" : "2016-07-13T12:15:47Z",
      "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, channelId, slug.

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

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

Examples:

  • …​/walls?channelId=123 returns all entries that are in channel 123.

  • …​/walls?channelId=123&tag=top returns all entries which are in channel 123 and have the tag top.

  • …​/walls?channelId=123&tag=!top returns all entries which are in channel 123 and don’t have the tag top.

  • …​/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;
}

Full text search

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" : {
    "wallList" : [ {
      "id" : "P9878051",
      "title" : "",
      "slug" : "",
      "leadText" : "",
      "featuredImage" : "",
      "media" : [ {
        "id" : "https://twitter.com/i/web/status/801703417018257408",
        "media" : [ ],
        "type" : "link",
        "source" : "twitter",
        "url" : "https://twitter.com/i/web/status/801703417018257408",
        "date" : "2016-11-24T08:26:04Z",
        "resolution" : "desktop",
        "ratio" : "2:1",
        "htmlSnippet" : "<a href=\"https://twitter.com/newsroomz/status/801703417018257408\" target=\"_blank\"><img class=\"bigimage\" src=\"https://nrcm.s3.amazonaws.com/newsroom/images/social/5836a6aeac00d.jpeg\"><br><span class=\"gridmedia_title\">Newsroom Community on Twitter</span></a>"
      } ],
      "type" : "tweet",
      "contentType" : "rich",
      "source" : "twitter",
      "url" : "https://twitter.com/newsroomz/status/801703417018257408",
      "mediaUrl" : "https://twitter.com/i/web/status/801703417018257408",
      "date" : "2016-11-24T08:26:04Z",
      "dates" : {
        "created" : "2016-11-24T08:38:02Z",
        "published" : "2016-11-24T08:26:04Z",
        "updated" : "2016-11-24T08:37:03Z"
      },
      "text" : "Learning from the best: We are at #SIF2016 to experience latest innovations and learn from companies that made it h… https://t.co/X14Yexq16W",
      "html" : "Learning from the best: We are at  <a href=\"https://twitter.com/hashtag/SIF2016\" target=\"_blank\" rel=\"nofollow\">#SIF2016</a> to experience latest innovations and learn from companies that made it h… <a href=\"https://t.co/X14Yexq16W\" target=\"_blank\">https://t.co/X14Yexq16W</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" : {
        "wall" : {
          "href" : "..."
        }
      }
    }, {
      "id" : "P7268291",
      "title" : "",
      "slug" : "",
      "leadText" : "",
      "featuredImage" : "",
      "media" : [ ],
      "type" : "retweet",
      "contentType" : "text",
      "source" : "twitter",
      "url" : "https://twitter.com/hellotmrc/status/778561317489799168",
      "date" : "2016-09-21T11:47:37Z",
      "dates" : {
        "created" : "2016-09-21T11:52:02Z",
        "published" : "2016-09-21T11:47:37Z",
        "updated" : "2016-09-21T11:53:01Z"
      },
      "text" : "We now have a curated news hub on @hellotmrc! Huge THX to @storyshaker for making this happen! See our latest news:… https://t.co/qa194qdO61",
      "html" : "We now have a curated news hub on <a href=\"http://twitter.com/hellotmrc\" target=\"_blank\" rel=\"nofollow\">@hellotmrc</a>! Huge THX to <a href=\"http://twitter.com/storyshaker\" target=\"_blank\" rel=\"nofollow\">@storyshaker</a> for making this happen! See our latest news:… <a href=\"https://t.co/qa194qdO61\" target=\"_blank\">https://t.co/qa194qdO61</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" : {
        "wall" : {
          "href" : "..."
        }
      }
    }, {
      "id" : "P3801027",
      "title" : "",
      "slug" : "",
      "leadText" : "",
      "featuredImage" : "",
      "media" : [ ],
      "type" : "reply",
      "contentType" : "text",
      "source" : "twitter",
      "url" : "https://twitter.com/newsroomz/status/745495638306000900",
      "date" : "2016-06-22T05:56:25Z",
      "dates" : {
        "created" : "2016-06-22T06:22:02Z",
        "published" : "2016-06-22T05:56:25Z",
        "updated" : "2016-06-22T06:23:01Z"
      },
      "text" : "@danielbieri ihr könnt auch gleich den Bus Nr. 19 Richtung Elfenau nehmen, dann seid ihr gleich vor dem Büro. Haltestelle #Willadingweg",
      "html" : "<a href=\"http://twitter.com/danielbieri\" target=\"_blank\" rel=\"nofollow\">@danielbieri</a> ihr könnt auch gleich den Bus Nr. 19 Richtung Elfenau nehmen, dann seid ihr gleich vor dem Büro. Haltestelle  <a href=\"https://twitter.com/hashtag/Willadingweg\" target=\"_blank\" rel=\"nofollow\">#Willadingweg</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" : {
        "wall" : {
          "href" : "..."
        }
      }
    }, {
      "id" : "P1210491",
      "title" : "",
      "slug" : "",
      "leadText" : "",
      "featuredImage" : "",
      "media" : [ {
        "id" : "https://nrcm.s3.amazonaws.com/newsroom/images/social/56e6d14b1b5e2.jpeg",
        "media" : [ ],
        "type" : "image",
        "source" : "twitter",
        "url" : "https://nrcm.s3.amazonaws.com/newsroom/images/social/56e6d14b1b5e2.jpeg",
        "date" : "2016-03-14T14:01:14Z",
        "resolution" : "desktop",
        "ratio" : "2:1",
        "htmlSnippet" : "<img class=\"bigimage\" src=\"https://nrcm.s3.amazonaws.com/newsroom/images/social/56e6d14b1b5e2.jpeg\"/>"
      } ],
      "type" : "tweet",
      "contentType" : "photo",
      "source" : "twitter",
      "url" : "https://twitter.com/newsroomz/status/709378859276374017",
      "mediaUrl" : "https://nrcm.s3.amazonaws.com/newsroom/images/social/56e6d14b1b5e2.jpeg",
      "date" : "2016-03-14T14:01:14Z",
      "dates" : {
        "created" : "2016-03-14T14:25:02Z",
        "published" : "2016-03-14T14:01:14Z",
        "updated" : "2016-05-18T04:26:01Z"
      },
      "text" : "Today we present our latest innovation at #CeBIT visit us and let's discuss our publishing ideas #contentcommunity https://t.co/bRwkyTDNsp",
      "html" : "Today we present our latest innovation at  <a href=\"https://twitter.com/hashtag/CeBIT\" target=\"_blank\" rel=\"nofollow\">#CeBIT</a> visit us and let's discuss our publishing ideas  <a href=\"https://twitter.com/hashtag/contentcommunity\" target=\"_blank\" rel=\"nofollow\">#contentcommunity</a> <a href=\"https://t.co/bRwkyTDNsp\" target=\"_blank\">https://t.co/bRwkyTDNsp</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" : {
        "wall" : {
          "href" : "..."
        }
      }
    }, {
      "id" : "P988695",
      "title" : "",
      "slug" : "",
      "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" : {
        "wall" : {
          "href" : "..."
        }
      }
    }, {
      "id" : "P137",
      "title" : "",
      "slug" : "",
      "leadText" : "",
      "featuredImage" : "",
      "media" : [ {
        "id" : "https://twitter.com/WebSummitHQ/status/657573836909604865",
        "media" : [ ],
        "type" : "link",
        "source" : "twitter",
        "url" : "https://twitter.com/WebSummitHQ/status/657573836909604865",
        "date" : "2015-10-23T16:22:28Z",
        "resolution" : "desktop",
        "ratio" : "2:1",
        "htmlSnippet" : "<a href=\"https://twitter.com/WebSummitHQ/statuses/657573836909604865\" target=\"_blank\"><img class=\"bigimage\" src=\"https://nrcm.s3.amazonaws.com/newsroom/images/social/56939b30e3417.png\"><br><span class=\"gridmedia_title\">Web Summit on Twitter</span></a>"
      } ],
      "type" : "tweet",
      "contentType" : "rich",
      "source" : "twitter",
      "url" : "https://twitter.com/newsroomz/status/657592939305156608",
      "mediaUrl" : "https://twitter.com/WebSummitHQ/status/657573836909604865",
      "date" : "2015-10-23T16:22:28Z",
      "dates" : {
        "created" : "2016-01-11T12:06:03Z",
        "published" : "2015-10-23T16:22:28Z",
        "updated" : "2016-05-15T15:48:37Z"
      },
      "text" : "We are thrilled to meet some of the brightest people at #WebSummit! Make sure to visit us at T147 on day 1! #Startup https://t.co/lwxY0wKmWM",
      "html" : "We are thrilled to meet some of the brightest people at  <a href=\"https://twitter.com/hashtag/WebSummit\" target=\"_blank\" rel=\"nofollow\">#WebSummit</a>! Make sure to visit us at T147 on day 1!  <a href=\"https://twitter.com/hashtag/Startup\" target=\"_blank\" rel=\"nofollow\">#Startup</a> <a href=\"https://t.co/lwxY0wKmWM\" target=\"_blank\">https://t.co/lwxY0wKmWM</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" : {
        "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" : "P9878051",
      "title" : "",
      "slug" : "",
      "leadText" : "",
      "featuredImage" : "",
      "media" : [ {
        "id" : "https://twitter.com/i/web/status/801703417018257408",
        "media" : [ ],
        "type" : "link",
        "source" : "twitter",
        "url" : "https://twitter.com/i/web/status/801703417018257408",
        "date" : "2016-11-24T08:26:04Z",
        "resolution" : "desktop",
        "ratio" : "2:1",
        "htmlSnippet" : "<a href=\"https://twitter.com/newsroomz/status/801703417018257408\" target=\"_blank\"><img class=\"bigimage\" src=\"https://nrcm.s3.amazonaws.com/newsroom/images/social/5836a6aeac00d.jpeg\"><br><span class=\"gridmedia_title\">Newsroom Community on Twitter</span></a>"
      } ],
      "type" : "tweet",
      "contentType" : "rich",
      "source" : "twitter",
      "url" : "https://twitter.com/newsroomz/status/801703417018257408",
      "mediaUrl" : "https://twitter.com/i/web/status/801703417018257408",
      "date" : "2016-11-24T08:26:04Z",
      "dates" : {
        "created" : "2016-11-24T08:38:02Z",
        "published" : "2016-11-24T08:26:04Z",
        "updated" : "2016-11-24T08:37:03Z"
      },
      "text" : "Learning from the best: We are at #SIF2016 to experience latest innovations and learn from companies that made it h… https://t.co/X14Yexq16W",
      "html" : "Learning from the best: We are at  <a href=\"https://twitter.com/hashtag/SIF2016\" target=\"_blank\" rel=\"nofollow\">#SIF2016</a> to experience latest innovations and learn from companies that made it h… <a href=\"https://t.co/X14Yexq16W\" target=\"_blank\">https://t.co/X14Yexq16W</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" : {
        "wall" : {
          "href" : "..."
        }
      }
    }, {
      "id" : "P7268291",
      "title" : "",
      "slug" : "",
      "leadText" : "",
      "featuredImage" : "",
      "media" : [ ],
      "type" : "retweet",
      "contentType" : "text",
      "source" : "twitter",
      "url" : "https://twitter.com/hellotmrc/status/778561317489799168",
      "date" : "2016-09-21T11:47:37Z",
      "dates" : {
        "created" : "2016-09-21T11:52:02Z",
        "published" : "2016-09-21T11:47:37Z",
        "updated" : "2016-09-21T11:53:01Z"
      },
      "text" : "We now have a curated news hub on @hellotmrc! Huge THX to @storyshaker for making this happen! See our latest news:… https://t.co/qa194qdO61",
      "html" : "We now have a curated news hub on <a href=\"http://twitter.com/hellotmrc\" target=\"_blank\" rel=\"nofollow\">@hellotmrc</a>! Huge THX to <a href=\"http://twitter.com/storyshaker\" target=\"_blank\" rel=\"nofollow\">@storyshaker</a> for making this happen! See our latest news:… <a href=\"https://t.co/qa194qdO61\" target=\"_blank\">https://t.co/qa194qdO61</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" : {
        "wall" : {
          "href" : "..."
        }
      }
    }, {
      "id" : "P3801027",
      "title" : "",
      "slug" : "",
      "leadText" : "",
      "featuredImage" : "",
      "media" : [ ],
      "type" : "reply",
      "contentType" : "text",
      "source" : "twitter",
      "url" : "https://twitter.com/newsroomz/status/745495638306000900",
      "date" : "2016-06-22T05:56:25Z",
      "dates" : {
        "created" : "2016-06-22T06:22:02Z",
        "published" : "2016-06-22T05:56:25Z",
        "updated" : "2016-06-22T06:23:01Z"
      },
      "text" : "@danielbieri ihr könnt auch gleich den Bus Nr. 19 Richtung Elfenau nehmen, dann seid ihr gleich vor dem Büro. Haltestelle #Willadingweg",
      "html" : "<a href=\"http://twitter.com/danielbieri\" target=\"_blank\" rel=\"nofollow\">@danielbieri</a> ihr könnt auch gleich den Bus Nr. 19 Richtung Elfenau nehmen, dann seid ihr gleich vor dem Büro. Haltestelle  <a href=\"https://twitter.com/hashtag/Willadingweg\" target=\"_blank\" rel=\"nofollow\">#Willadingweg</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" : {
        "wall" : {
          "href" : "..."
        }
      }
    }, {
      "id" : "P1210491",
      "title" : "",
      "slug" : "",
      "leadText" : "",
      "featuredImage" : "",
      "media" : [ {
        "id" : "https://nrcm.s3.amazonaws.com/newsroom/images/social/56e6d14b1b5e2.jpeg",
        "media" : [ ],
        "type" : "image",
        "source" : "twitter",
        "url" : "https://nrcm.s3.amazonaws.com/newsroom/images/social/56e6d14b1b5e2.jpeg",
        "date" : "2016-03-14T14:01:14Z",
        "resolution" : "desktop",
        "ratio" : "2:1",
        "htmlSnippet" : "<img class=\"bigimage\" src=\"https://nrcm.s3.amazonaws.com/newsroom/images/social/56e6d14b1b5e2.jpeg\"/>"
      } ],
      "type" : "tweet",
      "contentType" : "photo",
      "source" : "twitter",
      "url" : "https://twitter.com/newsroomz/status/709378859276374017",
      "mediaUrl" : "https://nrcm.s3.amazonaws.com/newsroom/images/social/56e6d14b1b5e2.jpeg",
      "date" : "2016-03-14T14:01:14Z",
      "dates" : {
        "created" : "2016-03-14T14:25:02Z",
        "published" : "2016-03-14T14:01:14Z",
        "updated" : "2016-05-18T04:26:01Z"
      },
      "text" : "Today we present our latest innovation at #CeBIT visit us and let's discuss our publishing ideas #contentcommunity https://t.co/bRwkyTDNsp",
      "html" : "Today we present our latest innovation at  <a href=\"https://twitter.com/hashtag/CeBIT\" target=\"_blank\" rel=\"nofollow\">#CeBIT</a> visit us and let's discuss our publishing ideas  <a href=\"https://twitter.com/hashtag/contentcommunity\" target=\"_blank\" rel=\"nofollow\">#contentcommunity</a> <a href=\"https://t.co/bRwkyTDNsp\" target=\"_blank\">https://t.co/bRwkyTDNsp</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" : {
        "wall" : {
          "href" : "..."
        }
      }
    }, {
      "id" : "P988695",
      "title" : "",
      "slug" : "",
      "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" : {
        "wall" : {
          "href" : "..."
        }
      }
    }, {
      "id" : "P137",
      "title" : "",
      "slug" : "",
      "leadText" : "",
      "featuredImage" : "",
      "media" : [ {
        "id" : "https://twitter.com/WebSummitHQ/status/657573836909604865",
        "media" : [ ],
        "type" : "link",
        "source" : "twitter",
        "url" : "https://twitter.com/WebSummitHQ/status/657573836909604865",
        "date" : "2015-10-23T16:22:28Z",
        "resolution" : "desktop",
        "ratio" : "2:1",
        "htmlSnippet" : "<a href=\"https://twitter.com/WebSummitHQ/statuses/657573836909604865\" target=\"_blank\"><img class=\"bigimage\" src=\"https://nrcm.s3.amazonaws.com/newsroom/images/social/56939b30e3417.png\"><br><span class=\"gridmedia_title\">Web Summit on Twitter</span></a>"
      } ],
      "type" : "tweet",
      "contentType" : "rich",
      "source" : "twitter",
      "url" : "https://twitter.com/newsroomz/status/657592939305156608",
      "mediaUrl" : "https://twitter.com/WebSummitHQ/status/657573836909604865",
      "date" : "2015-10-23T16:22:28Z",
      "dates" : {
        "created" : "2016-01-11T12:06:03Z",
        "published" : "2015-10-23T16:22:28Z",
        "updated" : "2016-05-15T15:48:37Z"
      },
      "text" : "We are thrilled to meet some of the brightest people at #WebSummit! Make sure to visit us at T147 on day 1! #Startup https://t.co/lwxY0wKmWM",
      "html" : "We are thrilled to meet some of the brightest people at  <a href=\"https://twitter.com/hashtag/WebSummit\" target=\"_blank\" rel=\"nofollow\">#WebSummit</a>! Make sure to visit us at T147 on day 1!  <a href=\"https://twitter.com/hashtag/Startup\" target=\"_blank\" rel=\"nofollow\">#Startup</a> <a href=\"https://t.co/lwxY0wKmWM\" target=\"_blank\">https://t.co/lwxY0wKmWM</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" : {
        "wall" : {
          "href" : "..."
        }
      }
    } ]
  },
  "_links" : {
    "self" : {
      "href" : "..."
    }
  }
}

Posting API

Private Token

In order to be able to post new stories and upload new images to the API, need to send http requests with the x-api-key header.

To get a new private token, you can go to the newsroom settings and click on the generate button. If you re-generate or remove the token, the old one is not valid anymore, so requests that use old token will receive 403 error response.

Example of token: eyJ0eXAiOiJKV1QiLCJhbGciOiJIUzI1NiJ9.eyJpc3MiOiJodHRwczpcL1wvc3RvcnlzaGFrZXIudGVzdCIsInN1YiI6OTYzLCJhaWQiOjU3OSwiaWF0IjoxNTU5OTMxODIzfQ.oJJNw0XnlWEVl-r1mW7didpK03_B_XTPGe2bg4_d2GU

Note
 Private Token for posting API is not the same as the one described in a previous section. You need to generate this token to be able to use posting API. Public Token is used only for fetching data.

Image uploading

Before posting stories you might need to upload images for the header and the post itself. Note that for better post presenting, you need to upload images for 4 main ratios - 2:1, 4:3, 1:1, 16:9

Method and endpoint for posting new stories - POST https://api.newsroom.co/file, where the body is form-data with the key file and value is a desired file.

The result will be be a JSON object with the url of the image.

Example of response:

{
    "url": "https://nrcm.s3.amazonaws.com/newsroom/images/api/333/85096d73-a1b8-4229-ba94-6060cef31bf1.gif"
}

Maximum file size is 5mb.

Story Posting

Method and endpoint for posting new stories - POST https://api.newsroom.co/walls

Structure of the body payload:

{
  "title" : "Test title",                          // Title of the story
  "leadText" : "Test lead text",                   // Lead text of the story
  "content" : "This is test content",              // Content of the story. Html is supported.
  "isPin" : true,                                  // [Optional. Default is false]. Is story
                                                   // pinned
  "isSponsored" : false,                           // [Optional. Default is false]. Is story sponsored
  "isTop" : false,                                 // [Optional. Default is false]. Story is a top story
  "ribbon" : "Test ribbon test",                   // Text for the ribon
  "media" : [ {                                    // [Optional] List of the images for the header
    "ratio" : "4:3",                               // Ratio of the image. Possible values:
                                                   // `2:1`, `4:3`, `1:1`, `16:9`
    "url": "http://link-to-the-image.jpg"          // Url for for the image. It could be your
                                                   // own link, or the link you've got from the previous step
  }, {
    "ratio" : "16:9",
    "url": "http://link-to-the-image.jpg"
  } ],
  "tags" : [ "tag1", "tag2", "not", "twitter" ],   // [Optional. Default is empty list] List of
                                                   // the tags. It could contain both existing new new tags.
  "channels" : [ 1, 2, 3 ],                        // [Optional. Default is empty list] List of channels
  "status" : "PUBLISHED",                          // [Optional. Default is PUBLISHED]. Status
                                                   // of the post. Possible values: `PUBLISHED`, `UNPUBLISHED`, `SCHEDULED`
  "published": "2019-06-10T10:06:27.599Z"          // [Optional except for `SCHEDULED`. Default is
                                                   // the current date and time]. Date of the post
                                                   // publishing. For the `SCHEDULED` status
                                                   // the `published` date should be date in the future
}

Note that for posts with the SCHEDULED status, the published date should be specified and the date should be in future. For better post presenting, you need to upload header images and put to the media field with correct ratios.

Example of the response:

{
    "id": "S21855",
    "title": "Test title",
    "leadText": "Test lead text",
    "content": "This is test content",
    "isPin": true,
    "isSponsored": false,
    "isTop": false,
    "isCommunity": false,
    "ribbon": "Test ribbon test",
    "authorId": 10,
    "authorName": "",
    "published": "2019-06-10T10:06:27.599Z",
    "created": "2019-06-10T10:06:27.599Z",
    "updated": "2019-06-10T10:06:27.599Z",
    "uuid": "ee51e7e2-56cb-4ae8-84a8-378640630f5f",
    "media": [
        {
            "ratio": "4:3",
            "url": "http://link-to-the-image.jpg",
            "label": "",
            "type": "FEATURED_IMAGE",
            "resolution": "TABLET"
        },
        {
            "ratio": "16:9",
            "url": "http://link-to-the-image.jpg",
            "label": "",
            "type": "FEATURED_IMAGE",
            "resolution": "DESKTOP_EXTRA_LARGE"
        }
    ],
    "tags": [
        "tag1",
        "tag2",
        "not",
        "twitter"
    ],
    "channels": [
        1,
        2,
        10,
        123,
        456
    ]
}

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.

Benjamin Blaser, "Product Owner"

Dmitry Tsinin, "Development Coordinator"

Licensing

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

GPLv3

Isotope Packery

MIT

imagesLoaded

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.