API

The API for spamicity.info uses a few functional endpoints.

Each endpoint takes a single Activity Streams activity as an HTTP POST body. The Content-Type for the POST body must be application/json.

Authentication

The API methods require OAuth 1.0 for authorization.

You don't need to provide a token or get one; just get a consumer key and secret by logging in.

Methods

/is-this-spam

Ask if the activity is spam. The activity data is put through a Bayesian spam filter to determine its spamicity (thanks, Paul Graham!).

The result is a JSON document with a single object with the following attributes:

probability: The probability the object is spam. A number between 0 and 1, inclusive. Typical values cluster close to 0 and 1.
isSpam: A boolean. true if spam, false if not. Based on the probability cutoff configured at the server.
bestKeys: . An array of 2-element arrays, each of which having a first element of the key that was used to determine spamicity, and the probability. Useful debugging tool.

/this-is-spam

Trains the activity as spam. Returns a training record, a single JSON object with the following attributes:

cat: The trained category; "spam" for this method.
object: The object that was trained.
date: The date of training.
elapsed: The elapsed training time, in milliseconds.
hash: An MD5 hash of the trained object.

Note: After the initial training, it's more effective to train a Bayesian filter only when its current results are wrong. So, call /is-this-spam first.

/this-is-ham

Trains the activity as spam. Returns a training record, a single JSON object with the following attributes:

cat: The trained category; "ham" for this method.
object: The object that was trained. For reference.
date: The date of training.
elapsed: The elapsed training time, in milliseconds.
hash: An MD5 hash of the trained object.

Note: After the initial training, it's more effective to train a Bayesian filter only when its current results are wrong. So, call /is-this-spam first.

/tokenize

Utility that shows how an activity will be tokenized. Possibly useful for debugging; also a nice idempotent method to test your OAuth keys with.

Returns a JSON document with an array of strings.