Back to top

Thank you for contributing to the Storify community. Unfortunately, Storify.com will no longer be available after May 16, 2018. The APIs will continue to function until 5pm PT on May 16, 2018. Please read the FAQ for more information.

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.

Storify API: * Rules * Basics * Authentication * Pagination * Sorting * API Rate Limits * Errors

Rules

  • You must include a "Powered by Storify" link on all pages which display content originating with the Storify API. That link must point to your story or user page on Storify.com.

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. For example:

$ 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

To make an authenticated call to the Storify API you must 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 save only the user token.

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

Use standard pagination to handle large sets of results:

  • per_page: the number of results to return 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

Lists of stories may be sorted. Refer to documentation on specific endpoints for supported sort fields.

  • sort: the 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

API Rate Limits

Storify rate limits its community users' API calls. Storify Community users may access the Read and Write APIs at the following rates: * Read (GET): 40 an hour * Write (POST/PUT/DELETE): 10 an hour

Please contact api@storify.com to inquire about higher API call rates.

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'"
  }
}