TMBO API Specification

This document describes functions, their arguments, return values, error codes, and other information used to interact with the TMBO server at thismight.be.

Authentication

There are three methods of authentication:

Tokens - A token generated by the login method can be used as an argument to any call except logout. This is the preferred method of authentication.
Session cookie - A client that supports cookies may log in with the login method, which will attempt to set a session cookie for short-term authentication if a token is not requested.
Basic access authentication - The username and password is provided for every call using HTTP basic access authentication.

Parameter Types

The API supports 5 distinct data types for parameters, as described below.

string - UTF-8 string.
integer - Whole number.
date - Any format parseable by strtotime is appropriate. The server time zone is America/Los_Angeles.
limit - Format: "%d,%d" or "%d". Syntax is the same as LIMIT in SQL. Default and largest accepted set size is 200.
float - Double precision floating point number.

Return Types

The API supports 4 formats, which are determined by the server by the filetype extension of the request.

json - A JSON structure, especially suitable for use by Javascript clients.
plist - An XML-formatted Property List structure, especially suitable for use by Cocoa clients.
php - A serialized PHP structure, especially suitable for use by PHP clients.
xml - A basic XML-formatted structure, suitable for use by no one.

Status Codes

The following error codes are used by the site as return values:

200 OK - Call completed as dialled.
304 Not Modified - If a Conditional GET is used, this indicates that there are no changes to report.
400 Bad Request - The call is erroneous. The body will contain debugging information.
401 Unauthorized - Login failure. Either your credentials weren't valid, or you did not provide any.
403 Forbidden - This content is not available to you.
404 Not Found - The function being requested does not exist.
500 Internal Server Error - kaboom. Please report if reproducible.
502 Bad Gateway - TMBO is down for maintenance. Please wait a few minutes and try your call again.
503 Service Unavailable - Refusal. You have attempted to log in too many times in a rolling 30 minute period and you are blocked from any more attempts. Wait and try again later.

Don't be Retarded

Like the RSS feeds, requests are limited to a maximum of 200 returned elements. If you want to download the entire history of the world since the dawn of time for your research project, that's fine but please sleep between requests.

This API does not support the load of TMBO on its own, so you may find some queries are inefficient and take a while to complete. If you notice calls taking more than two seconds, please send an email or open a ticket with the method/arguments you're requesting, and try to reduce your usage until the problem is addressed.

The user-agent of the client is used to identify the client.
If you are developing an application, please send an email or open a ticket with your application name and a sample user agent.

Examples

Here are some useful examples:

Get a front page of data: https://thismight.be/offensive/api.php/getuploads.plist?type=image&limit=100&token=yourtoken
Get the hall of fame: https://thismight.be/offensive/api.php/getuploads.plist?type=image&limit=100&sort=votes_desc&token=yourtoken

More examples for each method can be found with its documentation.

Function Definitions

To jump to a function, click its link below:

getuploads
getupload
getyearbook
getuser
getposse
login
logout
getcomments
postcomment
searchuser
searchuploads
getlocation
setlocation
get_preference
set_preference
unreadcomments
subscribe
resetsubscription

getuploads

Get one or more uploads' metadata, including (if possible) links to the uploaded files themselves, and their thumbnails.

Arguments:

type (string) - optional. Can be any of {"image","topic","avatar","audio"}. Get uploads of this type.
userid (integer) - optional. Get uploads posted by this user.
after (date) - optional. Get uploads newer than this.
before (date) - optional. Get uploads older than this.
max (integer) - optional. Get uploads before this fileid, inclusive.
since (integer) - optional. Get uploads since this fileid, inclusive.
sort (string) - optional. Can be any of {"date_desc","date_asc","votes_asc","votes_desc","comments_asc","comments_desc","activity_asc","activity_desc"}. Default:"date_desc" Result sorting. Sort by vote does not consider [-].
limit (limit) - optional. Default and maximum is 200.
nsfw (integer) - optional. Can be any of {"0","1"}. Set to 0, suppresses posts that are not safe for work. Set to 1, only returns results that are not safe for work.
tmbo (integer) - optional. Can be any of {"0","1"}. Set to 0, suppresses posts that might be offensive. Set to 1, only returns results that might be offensive.

Returns:

Array of Upload objects.

Examples:

getuploads.xxx?type=image&nsfw=0&sort=date_asc&limit=3,10: json plist php xml

getupload

Get an upload's metadata, including (if possible) links to the uploaded files themselves, and their thumbnails.

Calling this function updates your pickuplink.

Arguments:

fileid (integer) - required. Get upload with this id.

Returns:

A singleton Upload object or an Error object if upload does not exist.

Examples:

getupload.xxx?fileid=2: json plist php xml

getupload.xxx?fileid=112: json plist php xml

getyearbook

Get upload metadata for one or more users' current avatars.

To access non-current avatars, use getuploads(type=avatar).

Arguments:

userid (integer) - optional. Get the current avatar for this user only.
limit (limit) - optional. Default and maximum is 200.
sort (string) - optional. Can be any of {"date_desc","date_asc","uname_asc","uname_desc"}. Default:"uname_desc" Sort by username or upload date.

Returns:

A singleton Upload object if userid is specified, an array of Upload objects otherwise. Returns false if the userid does not exist.

Examples:

getyearbook.xxx?userid=2054: json plist php xml

getyearbook.xxx?limit=2&sort=date_asc: json plist php xml

getuser

Get a user's metadata.

Arguments:

userid (integer) - optional. Get metadata for this user. Defaults to the current user.

Returns:

If the userid exists, returns a user metadata object. Returns false if the userid does not exist.

Examples:

getuser.xxx?userid=151: json plist php xml

getposse

Get a user's posse.

Arguments:

userid (integer) - optional. Get metadata for this user. Defaults to the current user.

Returns:

If the userid exists, returns a possibly-empty array of user metadata objects. Returns false if userid does not exist.

Examples:

getposse.xxx?userid=2054: json plist php xml

getposse.xxx?userid=22: json plist php xml

login

Establish a session for future requests and/or generate a token.

The token is named after the user-agent of the requesting application and can be revoked by the user at any time in /offensive/?c=settings.

Arguments:

username (string) - required. User's name.
password (string) - required. User's password.
gettoken (integer) - optional. Can be any of {"0","1"}. Do you want to generate a new token?

Returns:

a token object or the metadata for the current user.

Examples:

login.xxx?username=jonxp&password=tester: json plist php xml

login.xxx?username=ray&password=tester&gettoken=1: json plist php xml

logout

Destroys the current session and invalidates the rememberme cookie.

Unnecessary if you are only using a token to authenticate, which doesn't create a login session.

This method takes no arguments.

Returns:

true

Examples:

logout.xxx?: json plist php xml

getcomments

Arguments:

votefilter (string) - optional. Can contain any of "+-xrc" in any order. Other characters are ignored. Applies the following filters:
• + - vote is 'this is good'.
• - - vote is 'this is bad'.
• x - vote includes 'this might be offensive'.
• r - vote includes 'this is a repost'.
• c - comment is not empty.
userid (integer) - optional. Get comments made by this user only.
after (date) - optional. Get comments newer than this date.
before (date) - optional. Get comments older than this date.
idmin (integer) - optional. Get comments after this commentid, inclusive.
idmax (integer) - optional. Get comments before this commentid, inclusive.
id (integer) - optional. Get comment with this id.
threadmin (integer) - optional. Get comments from threads after this one, inclusive.
threadmax (integer) - optional. Get comments from threads before this one, inclusive.
thread (integer) - optional. Get comments from this thread.
sort (string) - optional. Can be any of {"date_desc","date_asc"}. Default:"date_desc" Sort by comment date.
limit (limit) - optional. Default and maximum is 200.

Returns:

An array of comment objects.

Examples:

getcomments.xxx?thread=112: json plist php xml

postcomment

Post a comment to a thread.

All parameters to this function are processed via the POST method, to prevent malicious votes via link shorteners.

No examples yet pending doc system support for POST in examples. Sorry.

Arguments:

fileid (integer) - required. Post comment to this thread.
comment (string) - optional. Comment text.
vote (string) - optional. Can be any of {"thisisgood","thisisbad","novote"}. Default:"novote" The intended vote.
offensive (integer) - optional. Can be any of {1,0}. Default: 0 Vote [this might be offensive].
repost (integer) - optional. Can be any of {1,0}. Default: 0 Vote [this is a repost].
subscribe (integer) - optional. Can be any of {1,0}. Default: 1 if vote is "this is bad" or comment is not empty, 0 otherwise. Setting to 1 ensures thread subscription, setting to 0 does nothing (the default will override argument of 0).

Returns:

Comment object or false if nothing was added to the database.

searchuser

Find a user by username.

Arguments:

q (string) - required. Full or partial username.
limit (limit) - optional. Default and maximum is 200.

Returns:

Array of User objects matching query string.

Examples:

searchuser.xxx?q=max&limit=3: json plist php xml

searchuploads

Find an upload by filename.

Arguments:

q (string) - required. Full or partial filename.
limit (limit) - optional. Default and maximum is 200.
type (string) - optional. Can be any of {"image","topic","avatar","audio"}. Find only uploads of this type.

Returns:

Array of Upload objects matching query string.

Examples:

searchuploads.xxx?q=weekend&limit=5: json plist php xml

getlocation

Get the reported location of one or more maxxers.

This data is user-reported, so it's likely that everyone is lying.

The format of the data returned from this call is unstable and subject to change. Do not use this in a shipping application.

Arguments:

userid (integer) - optional. Get the current location for this user only.
minlat (float) - optional. Get locations with latitudes larger than this.
maxlat (float) - optional. Get locations with longitudes larger than this.
minlong (float) - optional. Get locations with longitudes larger than this.
limit (limit) - optional. Default and maximum is 200.

Returns:

An array of location data from the database matching the parameters.

Examples:

getlocation.xxx?limit=5: json plist php xml

getlocation.xxx?userid=2054: json plist php xml

setlocation

Set a user's location

Arguments:

lat (float) - required. User's latitude in degrees.
long (float) - required. User's longitude in degrees.

Returns:

true

Examples:

setlocation.xxx?lat=50&long=50: json plist php xml

get_preference

Retrieves the given user preference

Arguments:

key (string) - The. preference to retrieve. It may be one of the following:
• hide_nsfw - indicates the user wants to hide content that is not safe for work
• hide_tmbo - indicates the user wants to hide content that might be offensive
• hide_bad - indicates the user wants to hide content that has been deemed by others as "bad"
• sortorder_discussions - sorting for discussions
• sortorder_yearbook - sorting for yearbook
• index - type of frontpage, "thumbs" or blank
• thumbnails_in_comments - indicates if the user wants to view thumbnails in comments
• ipickup - pickup id for images
• tpickup - pickup id for topics (no web interface implemented)
• apickup - pickup id for audio
• ypickup - pickup id for yearbook (no web interface implemented)
• key_good - key(s) for "vote good"
• key_bad - key(s) for "vote bad"
• key_next - key(s) for "go to the next post in the stream"
• key_prev - key(s) for "go to the previous post in the stream"
• key_index - key(s) for "go to the index"
• key_comments - key(s) for "go to the comments for this upload"
• key_quick - key(s) for "open the quick reply window"
• key_escape - key(s) for "close modal dialogues"
• key_random - key(s) for "random image jump"
• key_subscribe - key(s) for "subscription toggle"

Returns:

The value of the preference (may be null)

Examples:

get_preference.xxx?key=ipickup: json plist php xml

set_preference

Set the given user preference

Arguments:

key (string) - The. preference to set. It may be one of the following:
• hide_nsfw - indicates the user wants to hide content that is not safe for work
• hide_tmbo - indicates the user wants to hide content that might be offensive
• hide_bad - indicates the user wants to hide content that has been deemed by others as "bad"
• sortorder_discussions - sorting for discussions
• sortorder_yearbook - sorting for yearbook
• index - type of frontpage, "thumbs" or blank
• thumbnails_in_comments - indicates if the user wants to view thumbnails in comments
• ipickup - pickup id for images
• tpickup - pickup id for topics (no web interface implemented)
• apickup - pickup id for audio
• ypickup - pickup id for yearbook (no web interface implemented)
• key_good - key(s) for "vote good"
• key_bad - key(s) for "vote bad"
• key_next - key(s) for "go to the next post in the stream"
• key_prev - key(s) for "go to the previous post in the stream"
• key_index - key(s) for "go to the index"
• key_comments - key(s) for "go to the comments for this upload"
• key_quick - key(s) for "open the quick reply window"
• key_escape - key(s) for "close modal dialogues"
• key_random - key(s) for "random image jump"
• key_subscribe - key(s) for "subscription toggle"
value (string) - The. value to set. Leave blank to unset the preference.

Returns:

true

Examples:

set_preference.xxx?key=ipickup&value=12345: json plist php xml

unreadcomments

Get a list of unchecked activity on subscribed threads.

Arguments:

sort (string) - optional. Can be any of {"comment_desc","comment_asc","file_asc","file_desc"}. Default:"file_asc" Sort order of results.
limit (limit) - optional. Default and maximum is 200.

Returns:

Array of Comment objects containing the oldest unread comment for each thread with unread comments.

Examples:

unreadcomments.xxx?limit=3&sort=file_asc: json plist php xml

Arguments:

threadid (integer) - required. Thread you're adding/removing from your subscriptions.
subscribe (integer) - required. Can be any of {"1","0"}. 0 -> unsubscribe, 1 -> subscribe.

Returns:

unsubscribe always returns true. subscribing returns false if thread does not exist.

Examples:

subscribe.xxx?threadid=211604&subscribe=1: json plist php xml

resetsubscription

Reset your subscription to a thread. New posts made to the thread after this call will cause the subscription to become active again.

Arguments:

threadid (integer) - required. Reset the subscription to this thread.

Returns:

true if reset, false if no subscription or upload does not exist.

Examples:

resetsubscription.xxx?threadid=309779: json plist php xml

Errata

If the API lacks notable functionality, or operates in an unexpected manner, please report this behaviour (expected and actual, if applicable) to the tmbotech mailing list, open a new issue, or send numist an email.

Changelog

August 11, 2008 - Initial draft.
August 14, 2008 - postuploads should take nsfw and tmbo as arguments.
August 15, 2008 - searchuploads and searchcomments get more parameters ([limit, type], limit).
October 18, 2011 - Documentation is now generated/updated by script. Primary input is the documentation in the API code itself. See github for more detailed change information.
February 21, 2012 - This page was generated.