Redux API Documentation

The Redux API consists of the Info API, an API that can be used to query data in a structured manner.

Info API

The Info API provides read-only access to most of the data in the Redux system. It is very flexible; with a single request you can get data on specific users, channels, and shares, global streams and popular channels, and the interconnections between all these things.

Basic Usage

To use the API, you must send a POST request to the endpoint http://redux.com/api.info with JSON describing the query as the POST data. Be sure to specify the content type application/json with your request—it probably won't work without that. The format for the JSON data is most easily described using an example:

{
  "channels": {
    "7": {
      "descr": true
    }
  },
  "users": {
    "6": {}
  }
}

At the top level there is a dictionary mapping strings naming object categories to dictionaries that map IDs to more dictionaries where further details of the query are specified. This particular request gets information about the user with ID 6 (Brent) and the channel with ID 7 (caturday). For the channel, the description, which would not normally be present in the response (since it can be rather long), is also requested. The response has the same structure as the request, but information has been "filled in" where there was previously no data:

{
  "channels": {
    "7": {
      "url": "http://redux.com/stream/channel/caturday",
      "imagebase": "http://files.redux.com/images/acb3b8980d37689a4637f40999839317/",
      "shortname": "caturday",
      "name": "The Redux Caturday Festival",
      "descr": "Share your cat-related posts here every caturday! And other days too.",
      "creatoruserid": "1337"
    }
  },
  "users": {
    "6": {
      "username": "Brent",
      "imagebase": "http://files.redux.com/images/15f9759d7200637c9b8868386398caeb/",
      "fullname": "",
      "url": "http://redux.com/Brent"
    }
  }
}

The values in this response, aside from the channel description, are all provided by default. Each type of object has different additional data that can be requested. Refer to the sections for each type for the full list of what is available.

Now suppose you also wanted to know about the creator of the caturday channel. From the API response we can see that his user ID is 1337. You could do a second request using this knowledge to get his info (eg, {"users":{"1337":{}}}), but this is not necessary. For channels, additional data about the creator can be queried without having to know the creator's user ID ahead of time by using the "creator" key in the query details dictionary:

{
  "channels": {
    "7": {
      "creator": {}
    }
  }
}

The dictionary specified here for the "creator" key works the same way the dictionary for the ID key "6" worked in the first request. The response will now include details about user 1337:

{
  "channels": {
    "7": {
      "url": "http://redux.com/stream/channel/caturday",
      "imagebase": "http://files.redux.com/images/acb3b8980d37689a4637f40999839317/",
      "shortname": "caturday",
      "name": "The Redux Caturday Festival",
      "creatoruserid": "1337"
    }
  },
  "users": {
    "1337": {
      "username": "Prateek",
      "imagebase": "http://files.redux.com/images/e7dd159d854c860df89dfc7ffb9a7dd6/",
      "fullname": "Prateek Bhakta",
      "url": "http://redux.com/Prateek"
    }
  }
}

Channel Queries

The two pieces of additional information that can be queried for a channel have been demonstrated in the above examples: "descr" and "creator". In the future, data such as a list of members and admins will be supported.

User Queries

Currently, the only additional information that can be queried for a user is a list of channels he or she is a part of. Getting this is a little more complicated than the description or creator of a channel because pagination is necessary. This is because a user can be a member of many channels. You can retrieve a slice of this list by including a key of the format "channels:<begin>:<end>:<limit>" in the user data dictionary. Each of the start, stop, and limit parameters are optional and have reasonable defaults. To get a slice of the beginning of the list, simply leave the begin and end positions empty. The response will contain the begin and end positions of the data returned, and these can be used for future calls to get the next pages of data. The value associated with the "channels..." key can be either false to get only the channel IDs, or detail dictionaries if data for the channels is desired. In this example, we request the first five channels that user 6 is a part of, and for each one, the channel description is also requested:

{
  "users": {
    "1337": {
      "channels:::5": {
        "descr": true
      }
    }
  }
}

In the response, the same "channels:::5" key that was requested is now associated with a dictionary containing the IDs, the begin and end position, and two entries specifying whether more pages of results follow ("moreafter") or precede ("morebefore") this page. And since {"descr": true} was the value associated with the "channels..." key, the default data plus the description is included for each channel mentioned in the list.

{
  "channels": {
    "1": {
      "name": "Redux",
      "descr": "This group is for employees and friends of Redux.",
      "creatoruserid": "6",
      "url": "http://redux.com/stream/channel/redux",
      "imagebase": "http://files.redux.com/images/87c5d49c781518ded8290f6b3d36dadf/",
      "shortname": "redux"
    },
    "2": {
      "name": "Wolfire Friends and Fans",
      "descr": "This group is for friends,fans, and employees of Wolfire Software. ",
      "creatoruserid": "4",
      "url": "http://redux.com/stream/channel/Wolfire",
      "imagebase": "http://files.redux.com/images/2084ceebc889971dd0e14e6066ad2872/",
      "shortname": "Wolfire"
    },
    "5": {
      "name": "Feed the Trollz",
      "descr": "For the lulz... /b/tards and memes welcome.",
      "creatoruserid": "17491",
      "url": "http://redux.com/stream/channel/Trollz",
      "imagebase": "http://files.redux.com/images/5bb24fc8b8129ce4c6d81528b5fbd373/",
      "shortname": "Trollz"
    },
    "7": {
      "name": "The Redux Caturday Festival",
      "descr": "Share your cat-related posts here every caturday! And other days too.",
      "creatoruserid": "1337",
      "url": "http://redux.com/stream/channel/caturday",
      "imagebase": "http://files.redux.com/images/acb3b8980d37689a4637f40999839317/",
      "shortname": "caturday"
    },
    "6": {
      "name": "4/4: A place for dance music",
      "descr": "If you know the difference between tech house and techno, AND feel that one is grossly superior to the other, welcome home.",
      "creatoruserid": "32",
      "url": "http://redux.com/stream/channel/fourfour",
      "imagebase": "http://files.redux.com/images/fd5129ee32630bd0b3c0b1b2a12fb5ee/",
      "shortname": "fourfour"
    }
  },
  "users": {
    "1337": {
      "username": "Prateek",
      "imagebase": "http://files.redux.com/images/e7dd159d854c860df89dfc7ffb9a7dd6/",
      "fullname": "Prateek Bhakta",
      "channels:::5": {
        "end": "4",
        "begin": "0",
        "morebefore": false,
        "ids": [
          "1",
          "2",
          "5",
          "6",
          "7"
        ],
        "moreafter": true
      },
      "url": "http://redux.com/Prateek"
    }
  }
}

In order to request the next page of content, take the end position from the above response and use that as the begin position in the "channels..." key in a new call. The results are non-inclusive of the specified begin and end positions, so this will give the next page of channels starting where the first one ended. In case you're wondering, the reason for this non-inclusivity, and for the begin and end positions being strings rather than numbers, is for consistency with pagination for stream queries (covered later), which have non-numeric position values. So the query for the next page, this time excluding the channel data, looks like this:

{
  "users": {
    "1337": {
      "channels:4::5": false
    }
  }
}

The response:

{
  "users": {
    "1337": {
      "username": "Prateek",
      "imagebase": "http://files.redux.com/images/e7dd159d854c860df89dfc7ffb9a7dd6/",
      "fullname": "Prateek Bhakta",
      "url": "http://redux.com/Prateek",
      "channels:4::5": {
        "end": "9",
        "begin": "5",
        "morebefore": true,
        "ids": [
          "8",
          "9",
          "11",
          "12",
          "13"
        ],
        "moreafter": true
      }
    }
  }
}

In the future, it will be possible to get more information about a user, such as lists of his followers and followees and extended profile information.

Stream Queries

In the Redux system, a stream is essentially an ordered collection of shares. Users and channels each have streams associated with them, and there are global streams such as the popular stream. Requesting stream data is similar to requesting a user's channel list. Let's start with an example:

{
  "streams": {
    "popular": {
      "shares::::5": false
    }
  }
}

This gets the IDs of the five latest shares in the popular stream. The format for the "shares..." key is "shares:<filter>:<begin>:<end>:<limit>". The begin, end, and limit parameters work in the same way as they do with the user channel list; simply think of the stream as a list of shares sorted in reverse chronological order. The filter parameter can be used to return shares of only a certain type. The filters are unfortunately not very clearly named, so refer to this table to see the possible values and what they do:

The response for the above query looks like:

{
  "streams": {
    "popular": {
      "shares::::5": {
        "end": "1280362284.4037499,1459459",
        "begin": "1280461761.4799409,1460996",
        "morebefore": false,
        "ids": [
          "1460996",
          "1460999",
          "1460997",
          "1459455",
          "1459459"
        ],
        "moreafter": true
      }
    }
  }
}

To request the next page of shares, take the end position from the response and specify it as the begin position in the new request (response not show):

{
  "streams": {
    "popular": {
      "shares::1280362284.4037499,1459459::5": false
    }
  }
}

This table shows the supported streams and what they do:

Unique actors here refers to the number of people who have interacted with the share by propping, commenting, or doing a channel add, plus the original sharer. The specific requirements for a share being placed in any of the popularity-based streams may change, and support for the everyone stream may be dropped at some point.

Besides "shares...", it is also possible to request data on the owner of a stream, whether it be a user or channel, using the "owner" key. As a final example of stream querying, we'll request the last two video shares from user 1337, getting the share data by specifying {} instead of false, and also getting the user data for user 1337 using the "owner" key:

{
  "streams": {
    "shares/1337": {
      "owner": {},
      "shares:video:::2": {}
    }
  }
}

The response:

{
  "streams": {
    "shares/1337": {
      "owneruserid": "1337",
      "shares:video:::2": {
        "end": "1278522663.273438,1442747",
        "begin": "1279319888.4238269,1450571",
        "morebefore": false,
        "ids": [
          "1450571",
          "1442747"
        ],
        "moreafter": true
      }
    }
  },
  "users": {
    "1337": {
      "username": "Prateek",
      "imagebase": "http://files.redux.com/images/e7dd159d854c860df89dfc7ffb9a7dd6/",
      "fullname": "Prateek Bhakta",
      "url": "http://redux.com/Prateek"
    }
  },
  "shares": {
    "1442747": {
      "descr": "After Spain beat Germany two years ago at EURO 2008",
      "views": 192,
      "stamp": 1278522663.273438,
      "imagebase": "http://files.redux.com/images/75413a4429c3887b085468e3abada28e/",
      "shareruserid": "1337",
      "url": "http://www.youtube.com/watch?v=Q0V70sVe9pY",
      "props": 2,
      "title": "Spanish Players Teasing Schweinsteiger",
      "type": "video",
      "sharedinchannelid": "5",
      "channelids": [
        "5"
      ]
    },
    "1450571": {
      "descr": "Occasionally he's kinda funny",
      "views": 344,
      "stamp": 1279319888.4238269,
      "imagebase": "http://files.redux.com/images/7ab53b7f1d881fa9bd2827ea6af41998/",
      "shareruserid": "1337",
      "url": "http://www.youtube.com/watch?v=tU5KJt-NgVA",
      "props": 7,
      "title": "Daniel Tosh Is It Racist - Tosh.0",
      "type": "video",
      "sharedinchannelid": "14",
      "channelids": [
        "14"
      ]
    }
  }
}

Share Queries

Share objects support several additional data items that can be requested. Data on the original sharer can be requested using the "sharer" key. Data on the channel the item was originally shared in can be requested using the "sharedin" key. The "channels" key can be used to get data on all channels the share has been added to, including the one given by "sharedin". If the "comments" key is present, the full list of activity on the share will be included. The value for "comments" must be a dictionary, and therein the keys "user", "channel", and "link" can be specified to have data for the user, channel if the action is a channel add, and link if the action is a comment with attached content. This is all demonstrated in this one mega-example:

{
  "shares": {
    "1453338": {
      "channels": {},
      "sharedin": {},
      "comments": {
        "link": true,
        "user": {},
        "channel": {}
      },
      "sharer": {}
    }
  }
}

{
  "channels": {
    "88": {
      "url": "http://redux.com/stream/channel/LOL",
      "imagebase": "http://files.redux.com/images/21d07ca65eb9ea71090115d08baffd97/",
      "shortname": "LOL",
      "name": "LOL",
      "creatoruserid": "405"
    },
    "232": {
      "url": "http://redux.com/stream/channel/russia",
      "imagebase": "http://files.redux.com/images/87502b411dc371be4318a1654acd1274/",
      "shortname": "russia",
      "name": "Russia",
      "creatoruserid": "23241"
    }
  },
  "users": {
    "24757": {
      "username": "ianhobbies",
      "imagebase": "http://files.redux.com/images/1bf264cbfb290e3514ec09929eaac1d6/",
      "fullname": "ian doroteo",
      "url": "http://redux.com/ianhobbies"
    },
    "32": {
      "username": "AndySchneider",
      "imagebase": "http://files.redux.com/images/df5a72950e14293c1bf369df03270701/",
      "fullname": "Andy Schneider",
      "url": "http://redux.com/AndySchneider"
    },
    "31734": {
      "username": "annied",
      "imagebase": "http://files.redux.com/images/5cf912f22cf8ebd13ea732b4bb109d73/",
      "fullname": "",
      "url": "http://redux.com/annied"
    },
    "1": {
      "username": "max",
      "imagebase": "http://files.redux.com/images/6dbf860daf4202dbd5ece9e76d197f85/",
      "fullname": "Max Crane",
      "url": "http://redux.com/max"
    },
    "29386": {
      "username": "Saffin",
      "imagebase": "http://files.redux.com/images/7c4aa6330f694ca436949dce26a12ac4/",
      "fullname": "",
      "url": "http://redux.com/Saffin"
    },
    "28412": {
      "username": "andmurphoto",
      "imagebase": "http://files.redux.com/images/21f0f2a8882179afebd4d3c07fa5e8d2/",
      "fullname": "Andrew",
      "url": "http://redux.com/andmurphoto"
    }
  },
  "shares": {
    "1453338": {
      "descr": "",
      "views": 191,
      "stamp": 1279631126.3781559,
      "imagebase": "http://files.redux.com/images/b5a1320d72be03a9ef066b227575f9de/",
      "shareruserid": "29386",
      "comments": [
        {
          "stamp": 1279631151.0368669,
          "userid": "24757",
          "type": "comment",
          "text": "wtf.. lol"
        },
        {
          "stamp": 1279631153.997206,
          "userid": "24757",
          "type": "prop"
        },
        {
          "stamp": 1279631751.448674,
          "userid": "28412",
          "type": "prop"
        },
        {
          "stamp": 1279740157.684495,
          "userid": "32",
          "type": "prop"
        },
        {
          "stamp": 1279740170.619072,
          "userid": "32",
          "channelid": "232",
          "type": "channeladd"
        },
        {
          "stamp": 1279890139.7078681,
          "userid": "28412",
          "type": "comment",
          "link": {
            "url": "http://s3.amazonaws.com/twitpic/photos/large/134104191.jpg?AWSAccessKeyId=0ZRYP5X5F6FSMBCCSE82&Expires=1279891301&Signature=pc5cwuk9x7Fk4wpjuZ8aXb9ZWT8%3D",
            "imagebase": "http://files.redux.com/images/7b7c460c2f31992e139ab752fd1aa530/",
            "type": "image"
          },
          "text": "http://s3.amazonaws.com/twitpic/photos/large/134104191.jpg?AWSAccessKeyId=0ZRYP5X5F6FSMBCCSE82&Expires=1279891301&Signature=pc5cwuk9x7Fk4wpjuZ8aXb9ZWT8%3D"
        },
        {
          "stamp": 1280902883.7860701,
          "userid": "31734",
          "type": "prop"
        },
        {
          "stamp": 1281051059.8244231,
          "userid": "1",
          "type": "superprop"
        }
      ],
      "url": "http://www.youtube.com/watch?v=hEep5BrexT0",
      "props": 5,
      "title": "Meanwhile in Russia...",
      "type": "video",
      "sharedinchannelid": "88",
      "channelids": [
        "88",
        "232"
      ]
    }
  }
}

Channel Lists

The final queryable type of object is the channel list. There are several different global lists of channels that are populated based on different criteria. The current supported channel lists are "featured", "popular", and "recentlypopular". The featured channels are manually chosen by Redux staff, and the popular channel lists are based on the amount of activity, either over the full lifetime of the channel for the popular list, or over the last week for the recently popular list. Requesting a channel list is very similar to requesting the channels a user is a member of:

{
  "channellists": {
    "popular": {
      "channels:::5": false
    }
  }
}

{
  "channellists": {
    "popular": {
      "channels:::5": {
        "end": "4",
        "begin": "0",
        "morebefore": false,
        "ids": [
          "88",
          "81",
          "161",
          "7",
          "13"
        ],
        "moreafter": true
      }
    }
  }
}

Image URLs

Users, channels, and shares all have images associated with them. The API returns these in the form of a base URL onto which you must add a size parameter to get the actual image. Refer to this table to see which sizes are available for each type of object:

The raw size is the original image. The thumb sizes are guaranteed to fit in the dimensions, but will probably be smaller than that because the full image is scaled down while maintaining the aspect ratio. The strip sizes will typically be the size of their specified dimensions, unless the original image is smaller than that to begin with. The avatar sizes are square and always fill the dimensions.

Try it out

Play with the Info API below.