Automattic Key Usage API

openapi: 3.2.0
info:
  title: Akismet Key Usage 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
tags:
- name: key-usage
  description: Check which sites use your API key and how many requests are being made
paths:
  /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
                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
components:
  schemas:
    UsageLimitResponse:
      type: object
      properties:
        limit:
          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
externalDocs:
  description: Akismet Developers Documentation
  url: https://akismet.com/developers