Back to top

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.

This API is free for NON COMMERCIAL USE ONLY. For any commercial usage, you must upgrade to Storify Enterprise.

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

Rules

  • All API users need an API KEY. Use this form to request an API KEY.
    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 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.

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

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