Akismet

• About Akismet
• Download
• FAQ
• Commercial Use
• Blog
• Contact Us

Akismet API Documentation Version 1.1

About the Akismet Service

Akismet is basically a big machine that sucks up all the data it possibly can, looks for patterns, and learns from its mistakes. Thus far it has been highly effective at stopping spam and adapting to new techniques and attempts to evade it, and time will tell how it stands up. I've tried to keep the API interaction as simple as possible.

A Good Consumer

To interact fully with the Akismet API your program really should be putting data back into the system as well as just taking it out. If it is at all possible within the framework of your application you should have a way for your users to submit missed spam and false positives, otherwise Akismet will never learn from its mistakes.

User Agent

If it is at all possible, please modify the user agent string you request with to be of the following format:

Application Name/Version | Plugin Name/Version

So in the WordPress plugin this looks like:

$ksd_user_agent = "WordPress/$wp_version | Akismet/1.11";

Call Structure

All calls to Akismet are POST requests much like a web form would send. The request variables should be constructed like a query string, key=value and multiple variables separated by ampersands. Don't forget to URL escape the values.

In the WordPress plugin the POST part of things is abstracted out in this function:

function ksd_http_post($request, $host, $path, $port = 80) {
	global $ksd_user_agent;

	$http_request  = "POST $path HTTP/1.0\r\n";
	$http_request .= "Host: $host\r\n";
	$http_request .= "Content-Type: application/x-www-form-urlencoded; charset=" . get_settings('blog_charset') . "\r\n";
	$http_request .= "Content-Length: " . strlen($request) . "\r\n";
	$http_request .= "User-Agent: $ksd_user_agent\r\n";
	$http_request .= "\r\n";
	$http_request .= $request;

	$response = '';
	if( false !== ( $fs = @fsockopen($host, $port, $errno, $errstr, 3) ) ) {
		fwrite($fs, $http_request);
		while ( !feof($fs) )
			$response .= fgets($fs, 1160); // One TCP-IP packet
		fclose($fs);
		$response = explode("\r\n\r\n", $response, 2);
	}
	return $response;
}  

This sends a POST request to the specified host and port with a timeout of 3 seconds. The HTTP request is constructed with full headers. The response headers are discarded and the function returns the body of the response.

API Key

Use of the Akismet API requires an API key, which are currently only being provided along with accounts to WordPress.com. The API key is used as a subdomain in the call, for example if you had the API key aoeu1aoue you would make all API calls to aoeu1aoue.rest.akismet.com. The only exception to this is the verify-key call, which may be made to rest.akismet.com without an API key subdomain.

Key Verification — rest.akismet.com/1.1/verify key

The key verification call should be made before beginning to use the service. It requires two variables, key and blog.

key (required)

The API key being verified for use with the API

blog (required)

The front page or home URL of the instance making the request. For a blog or wiki this would be the front page.

The call returns "valid" if the key is valid. This is the one call that can be made without the API key subdomain. Using our example function from above, this is how the API key is verified in the WP plugin:

function akismet_verify_key( $key ) {
	global $ksd_api_host, $ksd_api_port;
	$blog = urlencode( get_option('home') );
	$response = ksd_http_post("key=$key&blog=$blog", 'rest.akismet.com', '/1.1/verify-key', $ksd_api_port);
	if ( 'valid' == $response[1] )
		return true;
	else
		return false;
}

Comment Check — api-key.rest.akismet.com/1.1/comment-check

This is basically the core of everything. This call takes a number of arguments and characteristics about the submitted content and then returns a thumbs up or thumbs down. Almost everything is optional, but performance can drop dramatically if you exclude certain elements. I would recommend erring on the side of too much data, as everything is used as part of the Akismet signature.

blog (required)

The front page or home URL of the instance making the request. For a blog or wiki this would be the front page.

user_ip (required)

IP address of the comment submitter.

user_agent (required)

User agent information.

referrer (note spelling)

The content of the HTTP_REFERER header should be sent here.

permalink

The permanent location of the entry the comment was submitted to.

comment_type

May be blank, comment, trackback, pingback, or a made up value like "registration".

comment_author

Submitted name with the comment

comment_author_email

Submitted email address

comment_author_url

Commenter URL.

comment_content

The content that was submitted.

Other server enviroment variables

In PHP there is an array of enviroment variables called $_SERVER which contains information about the web server itself as well as a key/value for every HTTP header sent with the request. This data is highly useful to Akismet as how the submited content interacts with the server can be very telling, so please include as much information as possible.

This call returns either "true" or "false" as the body content. True means that the comment is spam and false means that it isn't spam. If you are having trouble triggering you can send "viagra-test-123" as the author and it will trigger a true response, always.

Submit Spam — api-key.rest.akismet.com/1.1/submit-spam

This call is for submitting comments that weren't marked as spam but should have been. It takes identical arguments as comment check.

Submit Ham — api-key.rest.akismet.com/1.1/submit-ham

This call is intended for the marking of false positives, things that were incorrectly marked as spam. It takes identical arguments as comment check and submit spam.