Back to top

Stories

Search stories

Get a list of public stories

Get a list of a user's stories

Get a story (including elements)

Create a story

Save a story

Publish a story

Edit a story URL new

OAuth Echo experimental


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

Search stories API accepts following parameters:

  • q — mandatory — search query string, this is the value by which relevancy will be determined.
  • per_page — optional — number of result to be returned in a single response (page), e.g., per_page=10; by default per_page=20.
  • page — optional — page number, e.g., page=1, page=2; by defult 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

Along with pagination and sorting parameters:

  • permalink - optional - filter by story permalink (ex: 'http://storify.com/storify/testimonails')
  • tag - optional - filter by hashtag (ex: '#storify')
  • containingElement - optional - filter by stories containing element with this permalink (/stories only, ex: '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 - 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 URL

Make 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 how this call is made; usually author or editor of the story.
  • _token: _token of the user, you can get by making call to /auth Storify API endpoint (more info at dev.storify.com/api/summary#auth).

Request Example

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

JSON Format

"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: new story URL (slug) needs to be unique and 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 via 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 user's tweets).

Currently this feature is in experimental state. Please contact us at @StorifyDev or via email if you want to get access and/or need more documentation.