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
ⓘ
Where this information came from
This is an independent, third-party profile of Akismet API, published by
API Evangelist. We do not operate, host, resell, or
support these APIs, and we are not affiliated with or endorsed by the company unless stated above.
Everything here is built from publicly available information — the company's own site,
developer portal, documentation, public repositories, and the specifications it publishes for public use.
Nothing is obtained by breaching a system, defeating an access control, or using credentials.
The Kin Score and Agent Readiness rating are independently calculated assessments of a company's
public API artifacts, scored against a published rubric. They are not certifications,
endorsements, security assessments, or audits.
Corrections, re-scores, and removal are free — no partnership or purchase required, and
you do not need to justify the request. A removed company is recorded as unrated, never scored
zero for having asked. Acknowledgement within one business day; removal within two.
info@apievangelist.com
·
Read the full data-sourcing policy →
On a security or compliance team? Put security in the subject line and
you will get a person, not a form — we will tell you exactly which public URLs this profile was built from.