Back to top

Stories

The Storify Stories API allows you to create and manage stories, and provides the following calls:


Custom CSS for story embed (Storify Enterprise Plan only)

You can add a css parameter when you load the embed script to pass the URL of a custom CSS file. For example:

<script src="//storify.com/ajstream/top-kashmiri-police-officer-s-son-shares-vip-treat.js?css=http%3A%2F%2Fyourdomain%2Fcss%2Fembed.css"></script>

Please note that you must URL encode the URL before passing it to the css parameter of the embed script.

This custom CSS file will be loaded after the default rules so that you can override them. Inspect the HTML code of the embed to see which classes are available for customization.

Please note that embedded Tweets and Facebook posts can't be customized.

For example:

/* Hide the Storify header */
.s-header .s-info {
  display: none;
}

/* Change the font */
h1, h2, div {
  font-family: Arial, Verdana !important;
}

/* Change the title */
.s-title {
  color: blue;
}

/* Change the description */
.s-description {
  font-size: 14pt;
  color: red;
}

Search stories

To get a list of stories based on a search query string (?q=... parameter) and sorted by published dates make a GET request:

GET /stories/search/?q=

Parameters

The search stories API accepts the following parameters:

  • q: (required) search query string. This is the value by which relevancy will be determined.
  • per_page: (optional) number of results to return in a single response (page). For example: per_page=10. Default is per_page=20.
  • page: (optional) page number. For example: page=1, page=2. Default is page=1.

Response

This is a response to a GET call http://api.storify.com/v1/stories/search?q=pope&page=1&per_page=3:

{
   content:{
      page:1,
      per_page:3,
      stories:[
         {
            sid:"5147adbb4ea1de8703005453",
            title:"A day of prayer, song, pomp to welcome new pope",
            slug:"a-day-of-prayer-song-pomp-to-welcome-new-pope",
            status:"published",
            version:1,
            permalink:"http://storify.com/SherwinMariano/a-day-of-prayer-song-pomp-to-welcome-new-pope",
            shortlink:"http://sfy.co/dFpK",
            description:null,
            thumbnail:"http://storify.com/public/img/default-thumb.gif",
            date:{
               created:"2013-03-19T00:13:47.615Z",
               modified:"2013-03-19T00:13:48.603Z",
               published:"2013-03-19T00:13:48.603Z"
            },
            private:false,
            topics:[

            ],
            siteposts:[

            ],
            meta:{
               quoted:[
                  {
                     username:"vishalmali06",
                     name:"veeshal mali",
                     userid:"1098216048",
                     avatar:"http://a0.twimg.com/profile_images/3255659963/76836ae767570b2f2730d6e676151190_normal.jpeg",
                     source:"twitter",
                     notified_at:null
                  }
               ],
               hashtags:[

               ],
               created_with:{
                  href:"http://storify.com",
                  appname:"storify",
                  name:"storify"
               }
            },
            stats:{
               popularity:0,
               views:0,
               likes:0,
               comments:0,
               elementComments:0,
               embeds:[

               ],
               elements:{
                  text:0,
                  quote:1,
                  image:0,
                  video:0,
                  link:0,
                  other:0
               }
            },
            modified:false,
            deleted:false,
            author:{
               username:"SherwinMariano",
               _access:0,
               name:"Sherwin Mariano",
               bio:"",
               location:"",
               website:"http://storify.com/SherwinMariano",
               avatar:"http://graph.facebook.com/iansherwinmariano23/picture",
               permalink:"http://storify.com/SherwinMariano",
               settings:{
                  comments:"facebook",
                  facebook_autoshare:true,
                  facebook_quoteimg:true,
                  facebook_post:true,
                  twitter_post:true,
                  notifications:{
                     newsletter:true,
                     digest:true,
                     likes:true,
                     comments:true,
                     follower:true,
                     quoted:true,
                     friend_quoted:true,
                     autoshare:true,
                     element_comment:true,
                     element_like:true,
                     story_comment:true,
                     story_like:true
                  }
               },
               lang:"en",
               stats:{
                  views:0,
                  subscriptions:1,
                  subscribers:2,
                  stories:922,
                  embeds:0
               },
               date:{
                  updated:"2013-03-19T00:13:48.735Z",
                  last_story:"2013-03-19T00:13:48.603Z",
                  last_seen:"2013-03-18T01:49:22.877Z",
                  last_email:null,
                  featured:null,
                  created:"2013-01-05T16:10:43.024Z"
               },
               coverPhoto:{
                  url:"http://storify.com/public/img/cover.jpg",
                  width:958,
                  height:200
               },
               canFeatureStories:false,
               featuredStories:[

               ]
            },
            canEdit:false
         },
         {...},
         {...}
      ]
   },
   code:200
}

Try it out: http://api.storify.com/v1/stories/search?q=pope&page=1&per_page=10

Get a list of public stories

Stories listed are published and paginated.

GET /stories

GET /stories/browse/latest

GET /stories/browse/featured

GET /stories/browse/popular

GET /stories/browse/topic/:topic

Parameters

Parameters include pagination, sorting, and the following options:

  • permalink: (optional) filter by story permalink. (For example: 'http://storify.com/storify/testimonails')
  • tag: (optional) filter by hashtag. (For example: '#storify')
  • containingElement: (optional) filter by stories containing element with this permalink. (/stories only. For example: 'http://twitter.com/BillGates/status/121746029308678145')

Response

{
    "content": {
        "page": 1
      , "per_page": 20
      , "stories": [
            {
                "id": "4e3b61378d06cda259000004"
              , "title": "Some Awesome Story"
              , "slug": "some-awesome-story"
              , "description": "This has got to be the best made up story ever."
              , "thumbnail": "http://static1.robohash.com/some-awesome-story"
              , "created": "2011-08-05T03:19:19.082Z"
              , "updated": "2011-08-05T03:19:19.082Z"
              , "status": "published"
              , "private": false
              , "author": {
                    "username": "dummy"
                  , "name": "Dummy User"
                  , "bio": "I wish I was real :("
                  , "location": "Somewhere"
                  , "website": "http://storify.com"
                  , "avatar": "http://static1.robohash.com/dummy"
                }
            }
          , { ... }
          , { ... }
          , { ... }
          ...
        ]
    }
  , "code": 200
}

Try it out: http://api.storify.com/v1/stories


Get a list of a user's stories

If authenticated, can also see private and working stories.

GET /stories/:username

Response

{
    "content": {
        "page": 1
      , "per_page": 20
      , "stories": [
            {
                "id": "4e3b61378d06cda259000004"
              , "title": "Some Awesome Story"
              , "slug": "some-awesome-story"
              , "description": "This has got to be the best made up story ever."
              , "thumbnail": "http://static1.robohash.com/some-awesome-story"
              , "created": "2011-08-05T03:19:19.082Z"
              , "updated": "2011-08-05T03:19:19.082Z"
              , "status": "published"
              , "private": false
              , "author": {
                    "username": "dummy"
                  , "name": "Dummy User"
                  , "bio": "I wish I was real :("
                  , "location": "Somewhere"
                  , "website": "http://storify.com"
                  , "avatar": "http://static1.robohash.com/dummy"
                }
            }
          , { ... }
          , { ... }
          , { ... }
          ...
        ]
    }
  , "code": 200
}

Try it out: http://api.storify.com/v1/stories/storify


Get a story (including elements)

If the storify is private or not published, an error will be shown for unauthorized users. The elements array is paginated.

GET /stories/:username/:slug

Response

{
    "content": {
        "id": "4e3b610b8ff3a97f59000004"
      , "title": "Some Awesome Story"
      , "slug": "some-awesome-story"
      , "description": "This has got to be the best made up story ever."
      , "thumbnail": "http://static1.robohash.com/some-awesome-story"
      , "created": "2011-08-05T03:18:35.768Z"
      , "updated": "2011-08-05T03:18:35.768Z"
      , "status": "working"
      , "private": false
      , "page": 1
      , "per_page": 20
      , "elements": [
            { ... }
          , { ... }
          , { ... }
          ...
        ]
      , "author": {
            "username": "dummy"
          , "name": "Dummy User"
          , "bio": "I wish I was real :("
          , "location": "Somewhere"
          , "website": "http://storify.com"
          , "avatar": "http://static1.robohash.com/dummy"
        }
    }
  , "code": 200
}

Try it out: http://api.storify.com/v1/stories/storify/testimonials


Create a story

Creates and stores a working story with :username as the author.

POST /stories/:username/create

Parameters

  • publish: (true/false) Publish the story right away. (Default: false)
  • story: serialized JSON string. (Example below)
    • title
    • slug
    • description
    • thumbnail
    • elements: an array of permalinks or element objects.

{
    "title": "Some Awesome Story"
  , "slug": "some-awesome-story"
  , "description": "This has got to be the best made up story ever."
  , "thumbnail": "http://static1.robohash.com/some-awesome-story"
  , "elements": [
        'https://twitter.com/#!/Storify/status/179918677372715008'
      , 'http://www.youtube.com/watch?v=gWEXwkikhMs'
      , 'http://instagr.am/p/IKy8knBQZT'
      ...
    ]
}

Response

{
    "content": {
        "id": 
      , "title": "Some Awesome Story"
      , "slug": "some-awesome-story"
      , "description": "This has got to be the best made up story ever."
      , "thumbnail": "http://static1.robohash.com/some-awesome-story"
      , "created": "2011-08-05T03:18:35.768Z"
      , "updated": "2011-08-05T03:18:35.768Z"
      , "status": "working"
      , "private": false
    }
  , "code": 200
}


Save a story

POST /stories/:username/:slug/save

Parameters

  • story: serialized JSON string. (Example below)
    • title
    • slug
    • description
    • thumbnail
    • elements

{
    "title": "Some Incredible Story"
  , "slug": "i-like-making-crazy-slugs"
  , "description": "This is a really cool description."
  , "thumbnail": "http://static1.robohash.com/i-like-making-crazy-slugs"
  , "elements": [
        { ... }
      , { ... } 
      , { ... }
      ...
    ]
}

Response

{
    "content": {
        "id": "4e3b610b8ff3a97f59000004"
      , "title": "Some Incredible Story"
      , "slug": "i-like-making-crazy-slugs"
      , "description": "This has got to be the best made up story ever."
      , "thumbnail": "http://static1.robohash.com/i-like-making-crazy-slugs"
      , "created": "2011-08-05T03:18:35.768Z"
      , "updated": "2011-08-05T03:18:35.768Z"
      , "status": "working"
      , "private": false
      , "page": 1
      , "per_page": 20
      , "elements": [
            { ... }
          , { ... }
          , { ... }
          ...
        ]
      , "author": {
            "username": "dummy"
          , "name": "Dummy User"
          , "bio": "I wish I was real :("
          , "location": "Somewhere"
          , "website": "http://storify.com"
          , "avatar": "http://static1.robohash.com/dummy"
        }
    }
  , "code": 200
}


Publish a story

POST /stories/:username/:slug/publish

Parameters

  • story
    • title
    • slug
    • description
    • thumbnail
    • elements

Response

{
    "content": {
        "id": "4e3b610b8ff3a97f59000004"
      , "title": "Some Incredible Story"
      , "slug": "i-like-making-crazy-slugs"
      , "description": "This has got to be the best made up story ever."
      , "thumbnail": "http://static1.robohash.com/i-like-making-crazy-slugs"
      , "created": "2011-08-05T03:18:35.768Z"
      , "updated": "2011-08-05T03:18:35.768Z"
      , "status": "published"
      , "private": false
      , "page": 1
      , "per_page": 20
      , "elements": [
            { ... }
          , { ... }
          , { ... }
          ...
        ]
      , "author": {
            "username": "dummy"
          , "name": "Dummy User"
          , "bio": "I wish I was real :("
          , "location": "Somewhere"
          , "website": "http://storify.com"
          , "avatar": "http://static1.robohash.com/dummy"
        }
    }
  , "code": 200
}

Edit a story's URL

Make an authorized request to Storify API endpoint with an old story URL and a new slug parameter.

POST /v1/stories/:username/:story-slug/editslug

Parameters

  • slug: string value of a new story slug (URL).
  • api_key: Storify application API key.
  • username: Storify username of the user on behalf of whom this call is made. (Usually the author or editor of the story.)
  • _token: _token of the user. Get this token by making a call to /auth Storify API endpoint. (For more information, see dev.storify.com/api/summary#auth).

Request Example

?slug=amazing-trip-around-americas&
api_key=517199588f0a912cee1b703f&
username=modernews&
_token=25abc09b35eb860c8029a67e399c5fbc

Request Example in JSON

"slug": "amazing-trip-around-americas",
"api_key": "517199588f0a912cee1b703f",
"username": "modernews",
"_token": "25abc09b35eb860c8029a67e399c5fbc"

Request Example in CURL

curl -X POST -d "username=modernews&slug=amazing-trip-around-americas&_token=25abc09b35eb860c8029a67e399c5fbc&api_key=517199588f0a912cee1b703f" http://api.storify.com/v1/stories/modernews/amazing-trip/editslug

Request Example in Node.js/JavaScript

var superagent = require('superagent');
superagent.post('/v1/stories/modernews/amazing-trip/editslug').type('form').send({
  "slug": "amazing-trip-around-americas",
  "api_key": "517199588f0a912cee1b703f",
  "username": "modernews",
  "_token": "25abc09b35eb860c8029a67e399c5fbc"  
}).end(function(res) {
  var story;
  try {
    story = JSON.parse(res.text);    
  } catch (e) {
  }
  console.log(story);
});

Response Example

{ content:
   { sid: '51674bee82a6bf50a30004e8',
     title: 'Amazing Trip Around Americas!',
     slug: 'amazing-trip-around-americas',
     status: 'working',
     version: 1,
     permalink: 'http://storify.com/azat_co/amazing-trip-around-americas',
     shortlink: 'http://sfy.co/q4LP',
     description: null,
     thumbnail: 'http://storify.com/public/img/default-thumb.gif',
     date:
      { created: '2013-04-11T23:49:02.104Z',
        modified: '2013-04-11T23:49:04.259Z',
        published: '2013-04-11T23:49:04.259Z' },
     private: false,
     not_indexed: false,
     topics: [],
     siteposts: [],
     meta: { quoted: [], hashtags: [], created_with: [Object] },
     stats:
      { popularity: 0,
        views: 0,
        likes: 0,
        comments: 0,
        elementComments: 0,
        embeds: [],
        elements: [Object] },
     modified: false,
     deleted: false },
  code: 200 }

Note: A story's URL (slug) must be unique and may not contain any special characters.

OAuth Echo

OAuth Echo allows the creation of stories by Storify (delegator) from your application (consumer) by delegating an identity verification through the service provider (SP) OAuth authorization header.

Use case: iOS Twitter client application on behalf of their user (who has authorized the app on Twitter) sends Twitter OAuth authorization header to Storify API (no Storify account, password or username needed). Storify API verifies the credentials and returns sfy.co link of the conversation (which contains the user's Tweets).

This feature is experimental. Please contact us at @StorifyDev or by email if you want to get access and/or need more documentation.