API documentation (v1.3)

1. Getting started

Using a library

The easiest way to get started with our API is to use one of our libraries (choose from PHP, Ruby, Python, .NET or others). These libraries do all of the hard work for you. Once you've downloaded a library, all you'll need is an API key to get started. Otherwise Akismet will never learn to adapt to your sites comments.

Custom integrations

If you choose to write your own integration, there are a few things that you'll want to keep in mind:

1. To interact properly with the Akismet API your application should have a way for users to submit missed spam and false positives, in addition to making comment checks.
2. The more data you send with each comment check, the better chance Akismet has of avoiding false positives.

Development API keys

Please contact Pete, via our support form if you'd like access to a development API key.

Structuring your API calls

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.

When making calls to Akismet, your key is used as a subdomain. So, if you had the key 123YourAPIKey you would make all API calls to 123YourAPIKey.rest.akismet.com.

There are three different types of calls to Akismet:

1. Key verification need only be used if you will have different users with their own Akismet licenses using your platform. This call will verify that they are using a valid API key.
2. Comment check is used to ask Akismet whether or not a given post, comment, profile etc. is spam
3. Submit Spam and Submit Ham are follow-ups to let Akismet know when it got something wrong (missed spam and false positives). These are also very important and you shouldn’t develop using the Akismet API without a facility to include reporting missed spam and false positives.

Setting your user agent

If possible, your user agent string should always use the following format:

So, for the WordPress plugin this would look like:

We're here to help

If you ever get stuck or need need help troubleshooting something, please don't hesitate to contact us.

2. Key verification

Key verification authenticates your key before calling the comment check, submit spam or submit ham. You call this method with the following URL:

This is the one call that can be made without the API key subdomain.

Required parameters

PHP Example

// Call to verify key function
akismet_verify_key('123YourAPIKey', 'http://www.yourblogdomainname.com/');
// Authenticates your Akismet API key
function akismet_verify_key( $key, $blog ) {
	$blog = urlencode($blog);
	$request = 'key='. $key .'&blog='. $blog;
	$host = $http_host = 'rest.akismet.com';
	$path = '/1.1/verify-key';
	$port = 80;
	$akismet_ua = "WordPress/3.1.1 | Akismet/2.5.3";
	$content_length = strlen( $request );
	$http_request  = "POST $path HTTP/1.0\r\n";
	$http_request .= "Host: $host\r\n";
	$http_request .= "Content-Type: application/x-www-form-urlencoded\r\n";
	$http_request .= "Content-Length: {$content_length}\r\n";
	$http_request .= "User-Agent: {$akismet_ua}\r\n";
	$http_request .= "\r\n";
	$http_request .= $request;
	$response = '';
	if( false != ( $fs = @fsockopen( $http_host, $port, $errno, $errstr, 10 ) ) ) {
		
		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 );
	}
	
	if ( 'valid' == $response[1] )
		return true;
	else
		return false;
}
                        

Success response example

The call returns "valid" if the key is valid.

Array
(
    [0] => HTTP/1.1 200 OK
Server: nginx
Date: Mon, 11 Apr 2011 16:31:55 GMT
Content-Type: text/plain; charset=utf-8
Connection: close
X-akismet-server: 192.168.6.47
Content-length: 5
    [1] => valid
)
                        

Error response example

If the verify-key call returns "invalid", it usually includes an extra HTTP header with some debug information about what exactly was invalid about the call.

Array
(
    [0] => HTTP/1.1 200 OK
Server: nginx
Date: Mon, 11 Apr 2011 16:34:54 GMT
Content-Type: text/plain; charset=utf-8
Connection: close
X-akismet-server: 192.168.6.48
X-akismet-debug-help: We were unable to parse your blog URI
Content-length: 7
    [1] => invalid
)
                        

We're here to help

If you ever get stuck or need need help troubleshooting something, please don't hesitate to contact us.

3. Comment check

This is the call you will make the most. It takes a number of arguments and characteristics about the submitted content and then returns a thumbs up or thumbs down. Performance can drop dramatically if you exclude elements. We recommend erring on the side of too much data, as every bit of data is used as part of the Akismet signature.

You call this method with the following URL:

Parameters

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. How the submited content interacts with the server can be very telling, so please include as much of it as possible.

PHP Example

// Call to comment check
$data = array('blog' => 'http://yourblogdomainname.com',
			  'user_ip' => '127.0.0.1',
			  'user_agent' => 'Mozilla/5.0 (Windows; U; Windows NT 6.1; en-US; rv:1.9.2) Gecko/20100115 Firefox/3.6',
			  'referrer' => 'http://www.google.com',
			  'permalink' => 'http://yourblogdomainname.com/blog/post=1',
			  'comment_type' => 'comment',
			  'comment_author' => 'admin',
			  'comment_author_email' => 'test@test.com',
			  'comment_author_url' => 'http://www.CheckOutMyCoolSite.com',
			  'comment_content' => 'It means a lot that you would take the time to review our software.  Thanks again.');
akismet_comment_check( '123YourAPIKey', $data );
// Passes back true (it's spam) or false (it's ham)
function akismet_comment_check( $key, $data ) {
	$request = 'blog='. urlencode($data['blog']) .
			   '&user_ip='. urlencode($data['user_ip']) .
			   '&user_agent='. urlencode($data['user_agent']) .
			   '&referrer='. urlencode($data['referrer']) .
			   '&permalink='. urlencode($data['permalink']) .
			   '&comment_type='. urlencode($data['comment_type']) .
			   '&comment_author='. urlencode($data['comment_author']) .
			   '&comment_author_email='. urlencode($data['comment_author_email']) .
			   '&comment_author_url='. urlencode($data['comment_author_url']) .
			   '&comment_content='. urlencode($data['comment_content']);
	$host = $http_host = $key.'.rest.akismet.com';
	$path = '/1.1/comment-check';
	$port = 80;
	$akismet_ua = "WordPress/3.1.1 | Akismet/2.5.3";
	$content_length = strlen( $request );
	$http_request  = "POST $path HTTP/1.0\r\n";
	$http_request .= "Host: $host\r\n";
	$http_request .= "Content-Type: application/x-www-form-urlencoded\r\n";
	$http_request .= "Content-Length: {$content_length}\r\n";
	$http_request .= "User-Agent: {$akismet_ua}\r\n";
	$http_request .= "\r\n";
	$http_request .= $request;
	$response = '';
	if( false != ( $fs = @fsockopen( $http_host, $port, $errno, $errstr, 10 ) ) ) {
		
		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 );
	}
	
	if ( 'true' == $response[1] )
		return true;
	else
		return false;
}
                        

This call returns either "true" (if this is spam) or "false" if it's not.

Spam response example

The call returns "true" if the comment is spam. If you are having trouble triggering a spam response you can send "viagra-test-123" as the author and it will trigger a true response, always.

Array
(
    [0] => HTTP/1.1 200 OK
Server: nginx
Date: Mon, 11 Apr 2011 20:17:08 GMT
Content-Type: text/plain; charset=utf-8
Connection: close
X-akismet-server: 192.168.7.7
Content-length: 4
    [1] => true
)
                        

Ham response example

The call returns "false" if the comment is ham.

Array
(
    [0] => HTTP/1.1 200 OK
Server: nginx
Date: Mon, 11 Apr 2011 20:17:08 GMT
Content-Type: text/plain; charset=utf-8
Connection: close
X-akismet-server: 192.168.7.7
Content-length: 4
    [1] => false
)
                        

Error response example

If the call returns neither "true" nor "false" an error message will be returned

Array
(
    [0] => HTTP/1.1 200 OK
Server: nginx
Date: Mon, 11 Apr 2011 16:34:54 GMT
Content-Type: text/plain; charset=utf-8
Connection: close
X-akismet-server: 192.168.6.48
X-akismet-debug-help: We were unable to parse your blog URI
Content-length: 7
    [1] => invalid
)
                        

We're here to help

If you ever get stuck or need need help troubleshooting something, please don't hesitate to contact us.

4. Submit spam (missed spam)

This call is for submitting comments that weren't marked as spam but should've been. You call this method with the following URL:

Parameters

This call takes the same arguments as the comment check call.

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. How the submited content interacts with the server can be very telling, so please include as much of it as possible.

PHP Example

// Call to comment check
$data = array('blog' => 'http://yourblogdomainname.com',
			  'user_ip' => '127.0.0.1',
			  'user_agent' => 'Mozilla/5.0 (Windows; U; Windows NT 6.1; en-US; rv:1.9.2) Gecko/20100115 Firefox/3.6',
			  'referrer' => 'http://www.google.com',
			  'permalink' => 'http://yourblogdomainname.com/blog/post=1',
			  'comment_type' => 'comment',
			  'comment_author' => 'admin',
			  'comment_author_email' => 'test@test.com',
			  'comment_author_url' => 'http://www.CheckOutMyCoolSite.com',
			  'comment_content' => 'It means a lot that you would take the time to review our software.  Thanks again.');
akismet_comment_check( '123YourAPIKey', $data );
// Passes back true (it's spam) or false (it's ham)
function akismet_comment_check( $key, $data ) {
	$request = 'blog='. urlencode($data['blog']) .
			   '&user_ip='. urlencode($data['user_ip']) .
			   '&user_agent='. urlencode($data['user_agent']) .
			   '&referrer='. urlencode($data['referrer']) .
			   '&permalink='. urlencode($data['permalink']) .
			   '&comment_type='. urlencode($data['comment_type']) .
			   '&comment_author='. urlencode($data['comment_author']) .
			   '&comment_author_email='. urlencode($data['comment_author_email']) .
			   '&comment_author_url='. urlencode($data['comment_author_url']) .
			   '&comment_content='. urlencode($data['comment_content']);
	$host = $http_host = $key.'.rest.akismet.com';
	$path = '/1.1/submit-spam';
	$port = 80;
	$akismet_ua = "WordPress/3.1.1 | Akismet/2.5.3";
	$content_length = strlen( $request );
	$http_request  = "POST $path HTTP/1.0\r\n";
	$http_request .= "Host: $host\r\n";
	$http_request .= "Content-Type: application/x-www-form-urlencoded\r\n";
	$http_request .= "Content-Length: {$content_length}\r\n";
	$http_request .= "User-Agent: {$akismet_ua}\r\n";
	$http_request .= "\r\n";
	$http_request .= $request;
	$response = '';
	if( false != ( $fs = @fsockopen( $http_host, $port, $errno, $errstr, 10 ) ) ) {
		
		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 );
	}
	
	if ( 'valid' == $response[1] )
		return true;
	else
		return false;
}
                        

This call returns a single response:

Array
(
    [0] => HTTP/1.1 200 OK
Server: nginx
Date: Mon, 11 Apr 2011 20:41:15 GMT
Content-Type: text/html; charset=utf-8
Connection: close
Content-length: 41
    [1] => Thanks for making the web a better place.
)
                        

We're here to help

If you ever get stuck or need need help troubleshooting something, please don't hesitate to contact us.

5. Submit ham (false positive)

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. You call this method with the following URL:

Parameters

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. How the submited content interacts with the server can be very telling, so please include as much of it as possible.

PHP Example

// Call to comment check
$data = array('blog' => 'http://yourblogdomainname.com',
			  'user_ip' => '127.0.0.1',
			  'user_agent' => 'Mozilla/5.0 (Windows; U; Windows NT 6.1; en-US; rv:1.9.2) Gecko/20100115 Firefox/3.6',
			  'referrer' => 'http://www.google.com',
			  'permalink' => 'http://yourblogdomainname.com/blog/post=1',
			  'comment_type' => 'comment',
			  'comment_author' => 'admin',
			  'comment_author_email' => 'test@test.com',
			  'comment_author_url' => 'http://www.CheckOutMyCoolSite.com',
			  'comment_content' => 'It means a lot that you would take the time to review our software.  Thanks again.');
akismet_comment_check( '123YourAPIKey', $data );
// Passes back true (it's spam) or false (it's ham)
function akismet_comment_check( $key, $data ) {
	$request = 'blog='. urlencode($data['blog']) .
			   '&user_ip='. urlencode($data['user_ip']) .
			   '&user_agent='. urlencode($data['user_agent']) .
			   '&referrer='. urlencode($data['referrer']) .
			   '&permalink='. urlencode($data['permalink']) .
			   '&comment_type='. urlencode($data['comment_type']) .
			   '&comment_author='. urlencode($data['comment_author']) .
			   '&comment_author_email='. urlencode($data['comment_author_email']) .
			   '&comment_author_url='. urlencode($data['comment_author_url']) .
			   '&comment_content='. urlencode($data['comment_content']);
	$host = $http_host = $key.'.rest.akismet.com';
	$path = '/1.1/submit-ham';
	$port = 80;
	$akismet_ua = "WordPress/3.1.1 | Akismet/2.5.3";
	$content_length = strlen( $request );
	$http_request  = "POST $path HTTP/1.0\r\n";
	$http_request .= "Host: $host\r\n";
	$http_request .= "Content-Type: application/x-www-form-urlencoded\r\n";
	$http_request .= "Content-Length: {$content_length}\r\n";
	$http_request .= "User-Agent: {$akismet_ua}\r\n";
	$http_request .= "\r\n";
	$http_request .= $request;
	$response = '';
	if( false != ( $fs = @fsockopen( $http_host, $port, $errno, $errstr, 10 ) ) ) {
		
		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 );
	}
	
	if ( 'valid' == $response[1] )
		return true;
	else
		return false;
}
                        

This call returns a single response:

Array
(
    [0] => HTTP/1.1 200 OK
Server: nginx
Date: Mon, 11 Apr 2011 20:41:15 GMT
Content-Type: text/html; charset=utf-8
Connection: close
Content-length: 41
    [1] => Thanks for making the web a better place.
)
                        

We're here to help

If you ever get stuck or need need help troubleshooting something, please don't hesitate to contact us.