Automattic

Akismet API

Akismet is Automattic's spam-classification service. Six operations — key verification, comment check, submit spam, submit ham, key sites and usage limit — authenticated with an Akismet API key. Automattic publishes an OpenAPI 3.0.3 document for it.

Documentation GitHub OpenAPI

Work with this as data

Every API here is available over the APIs.io API and to AI agents over MCP.

MCP server

One button, every client — Claude, Cursor, VS Code and the rest.

https://apis.io/mcp

Tools for apis

7 MCP tools reach this

find_apisBrowse and filter every API in the catalog.
get_api_artifactsOne API's artifacts, grouped by type.
get_openapiThe primary OpenAPI for this API.
find_similar_apisAPIs that look like this one.
apis_io_searchSTART HERE — APIs, providers and tags for one query, each with its total.
resolveTurn a domain, URL or GitHub org into the provider it belongs to.
find_cohortsEvery scored population of providers in the catalog.

All 92 tools

Call it yourself

curl for this page

This API

curl "https://apis.io/api/v1/apis/akismet-api"

All apis

curl "https://apis.io/api/v1/apis?limit=25"

Discovery needs no key. Ratings and market analysis are Pro.

Get an API key

Free tier, no email required.

GitHub Google LinkedIn

A second provider on the same verified email joins the account you already have.

OpenAPI Specification

openapi: 3.0.3
info:
  title: Akismet API
  description: Developer API to interact with the Akismet spam detection service.
  version: 1.0.1
  contact:
    name: Contact Akismet
    url: https://akismet.com/contact
servers:
  - url: https://rest.akismet.com
externalDocs:
  description: Akismet Developers Documentation
  url: https://akismet.com/developers
components:
  headers:
    DebugHelpHeader:
      description: Extra context for any error that has occurred.
      schema:
        type: string  
  responses:
    ThanksResponse:
      description: Successful submission
      content:
        text/plain:
          schema:
            type: string
          examples:
            thanks:
              value: "Thanks for making the web a better place."
  schemas:
    KeyVerificationParameters:
      type: object
      properties:
        key:
          type: string
          description: The Akismet API key for authorization.
        blog:
          type: string
          description: The front page or home URL of the instance making the request.
      required:
        - key
        - blog

    StandardParameters:
      type: object
      properties:
        api_key:
          type: string
          description: The Akismet API key for authorization.
        blog:
          type: string
          description: The front page or home URL of the instance making the request.
        user_ip:
          type: string
          description: The IP address of the comment submitter.
        user_agent:
          type: string
          description: The user agent string of the comment submitter's browser.
        comment_author:
          type: string
          description: |
            The name of the comment author. Please provide a name or pseudonym.
        comment_author_email:
          type: string
          description: The email address of the comment author.
        comment_author_url:
          type: string
          description: The URL of the comment author.
        comment_content:
          type: string
          description: The content of the comment.
        permalink:
          type: string
          description: The permanent URL of the entry where the comment was submitted.
        comment_type:
          type: string
          description: The type of the comment. Accepted values are "comment", "trackback", "pingback", or a custom type.
        comment_date_gmt:
          type: string
          format: date-time
          description: The GMT date and time the comment was created.
        comment_post_modified_gmt:
          type: string
          format: date-time
          description: The GMT date and time the post containing the comment was last modified.
        comment_parent:
          type: string
          description: The ID of the parent comment, if applicable.
        referrer:
          type: string
          description: The referrer URL of the comment submitter.
        user_role:
          type: string
          description: The role of the comment submitter.
        is_test:
          type: boolean
          description: Indicates whether the submission is a test. Default is false.
        recheck_reason:
          type: string
          description: The reason for rechecking the comment.
        honeypot_field_name:
          type: string
          description: The name of the honeypot field.
        comment_context:
          type: string
          description: The context or location of the comment within the website.
      required:
        - api_key
        - blog
        - user_ip

    UsageLimitResponse:
      type: object
      properties:
        limit:
          # This can actually be an integer or string, but oneOf is not well supported by code generators
          type: string
          description: The number of monthly API calls your plan entitles you to. Returns `none` if your key is unlimited.
        usage:
          type: integer
          description: Number of calls (spam + ham) since the beginning of the current month, to date.
        percentage:
          type: string
          description: The percentage of your limit used since the beginning of the current month, to date.
        throttled:
          type: boolean
          description: Indicates if your requests are currently being throttled for having consistently gone over your plan’s limit.
      required:
        - limit
        - usage
        - percentage
        - throttled      
paths:
  /1.1/verify-key:
    post:
      operationId: postVerifyKey
      summary: Verify Akismet API key
      description: |
        Verifies the provided Akismet API key to check its validity and ensure it can be used for API requests.
      requestBody:
        required: true
        content:
          application/x-www-form-urlencoded:
            schema:
              $ref: '#/components/schemas/KeyVerificationParameters'
      responses:
        '200':
          description: |
            Key verification response.

            If the verification returns "invalid", it usually includes an extra HTTP header with some debug information indicating exactly what was invalid about the call.
          content:
            text/plain:
              schema:
                type: string
              examples:
                valid:
                  value: valid
                invalid:
                  value: invalid
          headers:
            X-akismet-debug-help:
              $ref: '#/components/headers/DebugHelpHeader'
      tags:
        - key-verification
  /1.1/comment-check:
    post:
      operationId: postCommentCheck      
      summary: Check comment for spam
      description: |
        Checks a comment against the Akismet spam database to determine if it is spam or not.
      requestBody:
        content:
          application/x-www-form-urlencoded:
            schema:
              $ref: '#/components/schemas/StandardParameters'
      responses:
        '200':
          description: Comment check successful
          content:
            text/plain:
              schema:
                type: string
              examples:
                spam:
                  value: "true"
                ham:
                  value: "false"
                error:
                  value: "invalid"
          headers:
            X-akismet-alert-code:
              description: Error code. A full list is available at https://akismet.com/developers/errors/.
              schema:
                type: string
            X-akismet-alert-msg:
              description: Message describing the error code that can be shown to the end user.
              schema:
                type: string
            X-akismet-debug-help:
              $ref: '#/components/headers/DebugHelpHeader'
            X-akismet-pro-tip:
              description: |
                If this header is set to 'discard', then Akismet has determined that the comment is blatant 
                spam, and you can safely discard it without saving it in any spam queue.
              schema:
                type: string
      tags:
        - spam
  /1.1/submit-spam:
    post:
      operationId: postSubmitSpam      
      summary: Submit spam
      description: |
        Submits a comment as spam to Akismet for retraining.
      requestBody:
        content:
          application/x-www-form-urlencoded:
            schema:
              $ref: '#/components/schemas/StandardParameters'
      responses:
        '200':
          $ref: '#/components/responses/ThanksResponse'
      tags:
        - spam
  /1.1/submit-ham:
    post:
      operationId: postSubmitHam
      summary: Submit ham (false positives)
      description: |
        Submits a false positive (legitimate comment marked as spam) to Akismet for training purposes.
      requestBody:
        content:
          application/x-www-form-urlencoded:
            schema:
              $ref: '#/components/schemas/StandardParameters'
      responses:
        '200':
          $ref: '#/components/responses/ThanksResponse'
      tags:
        - spam
  /1.2/key-sites:
    get:
      operationId: getKeySites
      summary: Keep track of the sites that are using your Akismet API key.
      description: |
        Lists sites using your API key along with stats on their API usage.
      parameters:
        - name: api_key
          in: query
          description: The Akismet API key for authorization.
          required: true
          schema:
            type: string

        - name: month
          in: query
          description: |
            The month for which you would like to get the report (in `YYYY-MM` format). Defaults to the current month.
          required: false
          schema:
            type: string

        - name: filter
          in: query
          description: |
            Filter results by site URL or partial site URL.
          required: false
          schema:
            type: string

        - name: format
          in: query
          description: |
            The format in which you would like the results to be returned. Allowed values are `json` (default) and `csv`. Defaults to `json`.
          required: false
          schema:
            type: string
            enum:
              - json
              - csv

        - name: order
          in: query
          description: |
            The column by which you would like the results to be sorted. Defaults to `total`.
          required: false
          schema:
            type: string
            enum:
              - total
              - spam
              - ham
              - missed_spam
              - false_positives

        - name: limit
          in: query
          description: |
            The maximum number of results returned in the report (defaults to 500).
          required: false
          schema:
            type: integer

        - name: offset
          in: query
          description: The offset of the results returned in the report (defaults to 0).
          required: false
          schema:
            type: integer
            minimum: 0
      responses:
          '200':
            description: Key sites response.
            content:
              application/json:
                schema:
                  type: object
                  # OpenAPI Generator doesn't work well with a mixture of properties and additionalProperties, 
                  # so have left the response free-form
                  additionalProperties: true
                  example:
                    '2023-07':
                      - site: example.com
                        api_calls: "1000"
                        spam: "434"
                        ham: "544"
                        missed_spam: "5"
                        false_positives: "2"
                        is_revoked: false
                      - site: example.org
                        api_calls: "250"
                        spam: "150"
                        ham: "100"
                        missed_spam: "0"
                        false_positives: "1"
                        is_revoked: false
                    limit: 500
                    offset: 0
                    total: 2

              text/csv:
                schema:
                  type: string
                example: |
                  Active sites for 123YourAPIKey during 2022-09 (limit: 10, offset: 0, total: 4).
                  Site,Total API Calls,Spam,Ham,Missed Spam,False Positives,Is Revoked
                  site6735.domain.tld,14446,33,13,0,9,false
                  site3026.domain.tld,8677,101,6,0,0,false
                  site3737.domain.tld,4230,65,5,2,0,true
                  site5653.domain.tld,2921,30,1,2,6,false
              text/plain:
                schema:
                  type: string
                examples:
                  error:
                    value: "invalid"
      tags:
        - key-usage
  /1.2/usage-limit:
    get:
      operationId: getUsageLimit
      summary: Keep track of your Akismet API usage.
      description: |
        Returns your API usage limit and your usage for the current month.
      parameters:
        - name: api_key
          in: query
          description: The Akismet API key for authorization.
          required: true
          schema:
            type: string
      responses:
          '200':
            description: API usage response.
            content:
              application/json:
                schema:
                  $ref: '#/components/schemas/UsageLimitResponse'
              text/plain:
                schema:
                  type: string
                examples:
                  error:
                    value: "invalid"
      tags:
        - key-usage
tags:
  - name: key-verification
    description: Verify Akismet API key
  - name: spam
    description: Check for spam, and submit spam or ham (false positives)
  - name: key-usage
    description: Check which sites use your API key and how many requests are being made