API

Table of Contents

Authentication

This site uses API keys to authenticate API requests. To create or manage API keys, log in and click the "API Keys" option in the account menu.

When making a request, add an apiKey query parameter and set it to your key. Example:
https://plugintests.com/api/v1/user?apiKey=exampleKey

Data formats

Errors

When there is an error, the API returns a HTTP response code in the 4xx or 5xx range. The response body contains a JSON document with an error key that may provide more information about the error.

For example, if you request a non-existent plugin, you will get a 404 status code and a JSON document like this:

{
    "error": {
        "message": "Plugin not found.",
        "code": "plugin_not_found"
    }
}

Rate limiting

By default, you can make up to 60 requests per minute. Some endpoints and actions have very different rate limits. You can see the applicable rate limits in the settings of each API key.

Most responses also include special HTTP headers that provide information about the rate limit.

Header name Description
RateLimit-Limit

The maximum number of requests during a certain time window.

Example: 100, 100;w=60

  • 100 - maximum number of requests.
  • 100;w=60 - the applicable rate limit policy is 100 requests per 60 seconds.
Ratelimit-Remaining How many requests you can still make in the current time window.
Ratelimit-Reset Time until the rate limit resets, in seconds. Note that different endpoints can have separate rate limits that reset at different times.

Example:

RateLimit-Limit: 200, 200;w=3600
Ratelimit-Remaining: 198
Ratelimit-Reset: 1715

Rate limit headers may be absent if there is a 4xx/5xx error. However, those requests still count against the limit.

If you exceed the rate limit, you will receive an error response with the status code 429 (Too Many Requests).

Reference

Root endpoint

The root endpoint provides a partial list of accessible resources and a list of enabled API key permissions.

GET /api/v1

Plugins

Common parameters

Name In Description
directory path Owner or plugin directory slug. Use wporg for plugins listed in the WordPress.org plugin directory.
slug path Plugin slug. For plugins hosted on WordPress.org, this is the same as the last part of the plugin URL. For example, if the plugin URL is https://wordpress.org/plugins/example-plugin/ then the slug is example-plugin.

Get a plugin

GET /api/v1/plugins/{directory}/{slug}

List plugin reports

GET /api/v1/plugins/{directory}/{slug}/reports

Get a report

GET /api/v1/plugins/{directory}/{slug}/reports/{reportSlug}

List plugin entities

Get a list of database tables or other things created by the plugin.

GET /api/v1/plugins/{directory}/{slug}/{entityCollection}

Parameters

Name In Description
entityCollection path Must be one of the following: tables, options

Delete a plugin

You can only delete your own plugins. You cannot delete plugins that are hosted on WordPress.org, not even if you are the author of the plugin.

DELETE /api/v1/plugins/{directory}/{slug}

User

Get the current user

GET /api/v1/user

List user plugins

GET /api/v1/user/plugins

List user webhooks

GET /api/v1/user/webhooks

Create a webhook

POST /api/v1/user/webhooks

Parameters

Name In Description
url body The URL that will receive incoming events.
eventType body

Event type. You can only specify a single event type here, but you can can create multiple webhooks with the same URL and different event types. Omit this parameter or set it to NULL to receive all available events.

Event typeDescription
test_finished A test job has finished. Use this event type to be notified every time a public plugin or one of your own plugins is tested.
first_test_finished A plugin has been tested for the first time.

Get a webhook

GET /api/v1/user/webhooks/{webhookId}

Delete a webhook

DELETE /api/v1/user/webhooks/{webhookId}

Test queue

List jobs in queue

Restricted resource. Most users cannot view the queue.

GET /api/v1/test-queue

Add a job to the queue

POST /api/v1/test-queue

Parameters

Name In Description
directory body Owner or plugin directory slug.
slug body Plugin slug.
priority body Job priority as an integer between 1 and 500. Defaults to 100. Larger numbers mean higher priority.
packageSource body

This parameter controls how the test runner will download the plugin. Defaults to stable.

Package sourceDescription
stable Download the latest stable version from WordPress.org.
direct Download a ZIP file from downloadUrl (see below).
downloadUrl body Plugin download URL. Must point to a ZIP file that is structured in the same way as plugins downloaded from WordPress.org.

Miscellaneous

List plugin tables

Get a list of all database tables created by plugins that have at least a certain number of active installations. The list is updated twice per day. Please note that the list is very large and the response size can exceed 1 MB.

GET /api/v1/tablesWith{activeInstalls}installs.json

Parameters

Name In Description
activeInstalls path Minimum number of active installations. Must be either 500 or 10.