API Documentation


Introduction


This document describes version 1 of the Kernl API. As time goes on more endpoints will be documented and ready for use.


Examples


If seeing the API in action is more your style, head over to our API GitHub repo where you'll find fully-baked runnable examples to play around with.

https://github.com/vital101/Kernl-API-Examples


Request Headers & Bodies


All POST, PUT, and PATCH requests to Kernl expect JSON request bodies and to have the Content-Type header to be set to appplication/json. For examples of how to do this, see the Kernl API Examples below.

https://github.com/vital101/Kernl-API-Examples


Authorization


To interact with Kern's API, all of your requests require an authorization token. To retrieve an authorization token you must request one from Kernl.

/api/v1/auth

The retrieve your authorization token, make a POST request to /api/v1/auth with your email address and password as the body.

POST https://kernl.us/api/v1/auth
{
  "email": "youremail@kernl.us",
  "password": "yourPassword"
}

On success, Kernl will return 200 OK for the status code and the request body will be your authorization token. Your token will expire in 5 hours.

On failure, Kernl will return 401 UNAUTHORIZED for the status code and the request body will return details on why you were not authorized.

Setting The Authorization Header

Once you have your authorization token simply add it as a header to every request you make to Kernl.

Authorization: Bearer myAuthorizationTokenThatIgotFromTheAuthEndpoint

Read-Only API Keys


If you want access to the Kernl API that is read-only, you can create a read-only API key. To create a read-only API key, log in to Kernl and go to your profile (upper left under your name). Scroll down the until you see the section for read-only API keys. Create as many read-only keys as you need and revoke them at any time.

Authentication

While using an API key, before you can interact with the API you must authenticate with the key. To do that, POST to the /api/v1/auth/api-key endpoint. Be sure that your 'Content-Type' header is set to 'application/json'.

POST https://kernl.us/api/v1/auth/api-key
{
  "key": "myApiKey"
}

On success, Kernl will return 200 OK for the status code and the request body will be your authorization token. Your token will expire in 5 hours.

On failure, Kernl will return 401 UNAUTHORIZED for the status code and the request body will return details on why you were not authorized.

Setting The Authorization Header

Once you have your authorization token simply add it as a header to every request you make to Kernl.

Authorization: Bearer myAuthorizationTokenThatIgotFromTheApiKeyAuthEndpoint
Read-Only Endpoints

Not all endpoints are available when using a read-only API key. The following endpoints can be used with read-only keys with the GET method:

/api/v1/changelog - The plugin and theme changelog endpoints.
/api/v1/plugins - The plugin and plugin version endpoints (undocumented).
/api/v1/themes - The theme and theme version endpoints (undocumented).
/api/v1/purchase-codes - The plugin and theme purchase code endpoints.

Using wp_remote_post


While not 100% necessary, you'll likely be interacting with Kernl's API from within Wordpress. Wordpress provides a function called wp_remote_post. The syntax for getting the body of the POST to be correct can be a little counter-intuitive.

wp_remote_post Example

To use wp_remote_post with Kernl, you just need to make sure that the args array is set up correctly.

$args = array(
   'body' => array(
      'email' => 'yourEmail@example.com',
      'password => 'yourPassword'
   )
);
wp_remote_post('https://kernl.us/api/v1/auth', $args);

For more information about wp_remote_post check out the Wordpress codex.


Purchase Code API


WARNING: The purchase code API will soon be removed in favor of the license management API. It is highly recommended that you do not use this API to manage licenses from this point forward.

The purchase code API allows you to get, add, and delete purchase codes from your plugins and themes.

/api/v1/purchase-codes/:plugin-or-theme-id:

This endpoint allows two operations: GET and POST. Performing a GET operation against this endpoint will return a list of all the purchase codes associated with this particular plugin or theme.

GET https://kernl.us/api/v1/purchase-codes/somePluginOrThemeUUID

The above GET operation returns and array of purchase codes:

[
{"_id":"55e39264f034c3eb02e5f08d",
"code":"abc123",
"notes":"http://re-cycledair.com",
"user":"553f746e7a1fa8663be442a9",
"__v":0,
"created_date":"2015-08-30T23:31:48.395Z",
"active":true}
]

If you need to create a purchase code for this plugin or theme, simply issue a POST request to the same endpoint.

POST https://kernl.us/api/v1/purchase-codes/somePluginOrThemeUUID
{
  "code": "myNewCode",
  "notes": "This code is for customer X."
}

If the code is created successfully the endpoint will return 201 CREATED and the new purchase code object.

{
"__v": 0,
"user": "553f746e7a1fa8663be442a9",
"notes": "This code is for customer X.",
"code": "myNewCode",
"_id": "56bf3f395f1c3a9f5dbb9a4f",
"created_date": "2016-02-13T14:35:37.389Z",
"active":true
}

If you would like to have your purchase code expire on a set date, simply pass the expires_on field with your POST. The expires_on field must be in the format YYYY-MM-DD.

POST https://kernl.us/api/v1/purchase-codes/somePluginOrThemeUUID
{
  "code": "myNewCode",
  "notes": "This code is for customer X.",
  "expires_on": "2016-10-15"
}

If you would like to have your purchase code expire after a number of downloads, pass the max_downloads field with your POST.

POST https://kernl.us/api/v1/purchase-codes/somePluginOrThemeUUID
{
  "code": "myNewCode",
  "notes": "This code is for customer X.",
  "max_downloads": 3
}

If you would like to have your purchase code restricted by domain, pass the domain_restriction field with your POST.

POST https://kernl.us/api/v1/purchase-codes/somePluginOrThemeUUID
{
  "code": "myNewCode",
  "notes": "This code is for customer X.",
  "domain_restriction": "mydomain.com"
}
/api/v1/purchase-codes/:plugin-or-theme-id:/:purchase-code-id:

If you need to delete an existing purchase code, send this endpoint a DELETE request.

DELETE https://kernl.us/api/v1/purchase-codes/somePluginOrThemeUUID/purchaseCodeUUID

This endpoint will return 200 OK as the status code when the purchase code has been removed and body of the reponse will be:

Purchase code deleted.

Changelog API for Plugins


The changelog API allows you to get, add, and delete changelogs from your plugins.

/api/v1/changelog/:plugin-id:

Performing a GET operation against this endpoint will return a list of all the changelogs associated with this particular plugin.

GET https://kernl.us/api/v1/changelog/somePluginUUID

The above GET operation returns and array of changelogs and a status code of 200 if successful, and a status code of 404 if the plugin does not exist:

[
   {
      "id": "12345534309",
      "version": "2.7.7",
      "changelog": "My changlog info"
   },
   {
      "id": "09835345hjk8934",
      "version": "2.7.8",
      "changelog": "Changelog for this version"
   }
]
/api/v1/changelog/:plugin-id/:version-id

If you need to create a changelog for a specific version of this plugin, simply issue a POST request to changelog plugin version endpoint.

POST https://kernl.us/api/v1/changelog/somePluginUUID/someVersionUUID
{
  "changelog": "My new changelog info."
}

If the changelog is created successfully the endpoint will return 201 CREATED and a success message.

Changelog entry added to version x.x.x

To DELETE a changelog entry, simply pass the DELETE method to same endpoint.

DELETE https://kernl.us/api/v1/changelog/somePluginUUID/someVersionUUID
{
   "status": 200,
   "message": "Changelog entry removed for version x.x.x"
}
/api/v1/changelog/html/:plugin-id

If you would like a simple HTML representation of your plugin changelog, send a GET to the changelog HTML endpoint.

GET https://kernl.us/api/v1/changelog/html/somePluginUUID

Latest Plugin or Theme Version


The latest version endpoint allows you see what the latest version number of a plugin or theme is, as well as it's upload date.

/api/v1/latest-version/:plugin-or-theme-uuid

The plugin or theme UUID can be found on the plugin or theme list page in the Kernl admin. If you enter an invalid UUID, Kernl will return 404 NOT FOUND. If you enter a valid UUID but the plugin or theme does not have any versions, then Kernl will also return 404 NOT FOUND.

A successful request looks like the following:

GET https://kernl.us/api/v1/latest-version/myPluginUUID
{
    downloadUrl: "https://kernl.us/api/v1/updates/myPluginUUID/download",
    uploadedDate: "2016-05-06T02:32:11.818Z",
    version: "2.4.4"
}

License Management


The license management API allows you add, edit, remove, and list licenses.

/api/v2/license/

This endpoint allows two operations: GET and POST. Performing a GET operation against this endpoint will return a list of all licenses. The licenses will be paginated in groups of 50. You can also filter the list by passing in customer and/or .

GET https://kernl.us/api/v2/license?page=2&customer=myCustomerId&product=myPluginOrThemeId

The above GET operation returns a result object.

{
    "current": 2,
    "pages": 4,
    "results": [{
        "activation_count": 10,
        "activation_limit": 25,
        "customer": "myCustomerId",
        "expires": "2019-01-20T05:00:00.000Z",
        "key": "41121ef1-ee84-4c44-972f-d97f75c76097",
        "product": "myPluginOrThemeId",
        "user": "myUserId",
        "__v": 0,
        "_id": "ee84-4c44-972fee84-4c44-972f",
    ]}
}

If you need to create a license, simply issue a POST request to the same endpoint. The following are the list of fields that can be included in the POST body.

activation_limit - The number of times that this license can be activated. Kernl increments this number internally whenever your plugin/theme is downloaded.
customer [required] - The ID of the customer that this license belongs to.
expires - The day this license expires. Formatted MM/DD/YYYY.
key [required] - The license key.
product - The plugin/theme ID that this license is associated with.

And an example POST request

POST https://kernl.us/api/v2/license
{
  "activation_limit": 3,
  "customer": "myCustomerId", // required
  "expires": "10/31/2020",
  "key": "2324534324-1gbfdqrgfsbf-2efafsdfad", // required
  "product": "myPluginOrThemeId"
}

If the code is created successfully the endpoint will return 201 CREATED and the new license object.

/api/v2/license/:licenseId

This endpoint allows two operations: DELETE and PUT. Performing a DELETE operation against this endpoint will delete the license with the specified ID. Performing a PUT against this endpoint with update the license at the specified ID.

DELETE https://kernl.us/api/v2/license/aLicenseId

If successfully deleted, Kernl will return a status code of <204>No Content.

PUT https://kernl.us/api/v2/license/aLicenseId
{
  "activation_limit": 3,
  "customer": "myCustomerId", // required
  "expires": "10/31/2020",
  "key": "2324534324-1gbfdqrgfsbf-2efafsdfad", // required
  "product": "myPluginOrThemeId"
}

If successfully updated, Kernl will return <200>OK and the updated license object. For a description of each field, see the documentation for the /api/v2/license endpoint.

License Management Public API


The license management pubic API allows you to validate if a license is valid or not without having to authenticate. It also allows you to activate a license without having to authenticate.

/api/v2/public/license/activate

This endpoint is a GET operation that takes a single querystring parameter called "license". It is used to activate licenses and will increase the activated license count.

GET https://kernl.us/api/v2/public/license/activate?license=licenseKeyToCheck

The above GET operation returns 200 OK and "License activated." if the license was activated.

If the license exists but can't be activated because the activation limit has been reached, the endpoint returns 400 and "License activation limit has already been reached."

If the license does not exist, the endpoint returns 404 and "License not found.".

If the url does not contain the 'license' query string parameter, the endpoint returns 400 and '"license" query parameter is required'.

/api/v2/public/license/validate

This endpoint is a GET operation that takes a single querystring parameter called "license".

GET https://kernl.us/api/v2/public/license/validate?license=licenseKeyToCheck

The above GET operation returns 200 OK and a JSON object if the license is valid.

{
   status: 200,
   mssage: 'License valid.',
   err: null
}

If the license exists but is invalid, the endpoint returns 403 Unauthorized and a JSON object.

{
   status: 403,
   message: null,
   err: 'License has expired.'
}

If the license does not exist, the endpoint returns 404 Not Found and a JSON object.

{
   status: 404,
   message: null,
   err: 'License not found.'
}