Back to top

Summary

This page describes the Storify API v1.

The Storify API allows you to get all the information about any public story or any public user on Storify. We also offer a write API that allows you to update or create new stories.

Rules

  • All API users need an API KEY before going to production Fill this form to request one.
    If you don't have an API KEY, you will very quickly be rate limited. So make sure you use an API KEY in all your requests before going live on production!

  • You need to show a link "Powered by Storify" on the page where you show content coming out of our API.

Basics

All API calls begin with the base:

http(s)://api.storify.com/v1

Writes are performed using POST and reads are performed using GET. All data is sent as JSON:

$ curl -ki http://api.storify.com/v1

HTTP/1.1 200 OK
X-Powered-By: Express
Content-Type: application/json
Content-Length: 32
Connection: keep-alive

{
    "content": {
      ... 
    }
  , "code": 200
}

Authentication

In order to do an authenticated call to api, you need to provide your api_key and the username/_token of the user on behalf of whom you make the call. This token can be retrieved by calling the authentication endpoint with your api_key and the username/password of the user. We request that you do not save the user's credentials in your app but only save the user token.

If you don't have an api_key, click here to request one. Please provide as much info as you have to describe your application and how you want to use our APIs.

A successful authentication response will contain the user information along with a token that can be used (in conjunction with the username) with any subsequent request requiring authentication.

$ curl -ki -d 'username=dummy&password=test&api_key=50998ab7f964d317f71f0265' https://api.storify.com/v1/auth

HTTP/1.1 200 OK
X-Powered-By: Express
Content-Type: application/json
Content-Length: 154
Connection: keep-alive

{
    "content": {
        "username":"dummy"
      , "name": null
      , "bio": null
      , "location": null
      , "website": null
      , "avatar": null
      , "_token": "bab20ca5c01a09539f3bd280d8798cb2"
    }
  , "code": 200
}

Pagination

In order to handle large sets of results, standard pagination is put in place:

  • per_page - number of results returned per page (min: 1, max: 50, default: 20)
  • page - 1-indexed page (default: 1)

Example: http://api.storify.com/v1/stories?page=5&per_page=2&api_key=50998ab7f964d317f71f0265

Sorting

Currently only lists of stories can be sorted. Refer to documentation on specific endpoints for supported sort fields.

  • sort - field to sort on (default: 'date.created')
  • direction - 'asc' or 'desc' (default: 'desc')

Example: http://api.storify.com/v1/stories?sort=date.published&direction=asc&api_key=50998ab7f964d317f71f0265

Errors

$ curl -ki http://api.storify.com/v1/users/fakeguy?api_key=50998ab7f964d317f71f0265

HTTP/1.1 400 Bad Request
X-Powered-By: Express
Content-Type: application/json
Content-Length: 52
Connection: keep-alive

{
    "code": 400
  , "error": {
      "type": "bad_request"
    , "message": "Invalid user 'fakeguy'"
  }
}