Many parts of Polymart require JavaScript to function correctly.
Click here to enable JavaScript.
   
Prefer light mode? Click the lightbulb!
 

Developer API

Back to Wiki Home
To make a request to the Developer API, make a POST request to https://api.polymart.org/v1/api-action-here. For example, to verify a user token, you would make a POST request to https://api.polymart.org/v1/verifyAuthToken/

More info about all of the API actions available to you are given below. Make sure to send all of the parameters in POST data (unless otherwise stated).

The response will be in JSON format, like this: {"request": {...}, "response": {...}}. You can get more info about the response formats below.

If there's an API action that you would like to use but you don't see here, shoot us a message and we'll add it!

General Actions
/v1/search — Search for a resource on Polymart


Actions for Minecraft Plugins
/v1/verifyPurchase — Verify that a give user has in-fact purchased the given resource on Polymart
/v1/requestUpdateURL — Request a URL that can be used to download the latest version of a resource. This should be used inside of your resource (for example, in the .jar file of a plugin). This will verify that the jar was actually purchased and downloaded from Polymart. If it was, then you'll get a URL. Otherwise, this call will fail.
If you're looking for something that can be used to download a resource on behalf of a user (for example, if you're a Minecraft server host and want to give users access to download resources directly from your control panel), you should use /v1/getDownloadURL instead


Actions for Resources
/v1/postUpdate — Upload a new version for one of your resources
/v1/getResourceUserData — Get info about a resource purchase for a given resource and user. DON'T use this if you want to verify a download. Instead, use /v1/verifyPurchase

Actions for Resource Managers
/v1/generateUserVerifyURL — Generate a URL that can be used to verify a user (useful for verifying a discord account, etc)
/v1/verifyUser — After sending the user to the URL at /v1/generateUserVerifyURL, they'll get a token. Pass the token here to verify the user


Actions for Hosts, Control Panels, and Platforms
/v1/authorizeUser — Get a token you can use to take actions Polymart on a user's behalf. For example, for a hosting site to allow users to download resources directly
/v1/verifyAuthToken — Verify that a token received from /v1/authorizeUser is valid
/v1/invalidateAuthToken — Invalidate a token received from /v1/authorizeUser
/v1/getDownloadURL — get a URL that you can use to download a resource from Polymart on a user's behalf. This is useful for Minecraft server hosts
/v1/verifyPurchase Back to top
This only works for premium resources.

Verifies that a given user has in-fact downloaded a resource from Polymart. The parameters can be provided either as GET or as POST parameters. REMEMBER that a motivated attacker can always gain access to the source code of your plugin, so if you're using this as a piracy check, it only works as well as you can hide it. We recommend that you also use Polymart's automatic obfuscator to combat piracy.

Parameters

NOTE that ALL of these parameters are required. If you do not provide all of them, verification will always fail. In addition, this API call will only work if the resource as downloaded from Polymart (and not if it was purchased and downloaded on another marketplace). You can use the %%__POLYMART__%% placeholder to check this.

inject_version — the version of the resource injector for this download. You can use the %%__INJECT_VER__%% placeholder for this

resource_id — the ID of the resource in question. You can use the %%__RESOURCE__%% placeholder for this

user_id — the ID of the user in question. You can use the %%__USER__%% placeholder for this

nonce — the nonce given to the download by Polymart. You can use the %%__NONCE__%% placeholder for this

download_agent — the agent that downloaded the resource from Polymart. You can use the %%__AGENT__%% placeholder for this

download_time — the time the resource was downloaded from Polymart. You can use the %%__TIMESTAMP__%% placeholder for this

download_token — the download token from Polymart. You can use the %%__VERIFY_TOKEN__%% placeholder for this

Response

Format
{
  "request": "...",
  "response": {
    "success": <true/false>
  }
}
Example
{
  "request": "...",
  "response": {
    "success": true
  }
}

Usage

Use this to verify that a given resource download is authentic. For example,

https://api.polymart.org/v1/verifyPurchase/
   ?download_token=MDAwY2QzZDk0MjdkYWNm
   &user_id=1
   &resource_id=4
   &nonce=7318
   &inject_version=1
   &download_agent=000000
   &download_time=1587928929


All of these parameters should be gathered from %%__PLACEHOLDERS__%% in your resource file. Check the Parameters section above to see which parameter to pass where
/v1/requestUpdateURL Back to top
This only works for premium resources. If you'd like to build an auto-updater for a free resource, go to the resource page and then click "Get Direct Download Link" just below the "Post an Update" button. You can then use this link to provide a direct link for users to download your resource.

Verifies that a given user has in-fact downloaded a resource from Polymart. If they have downloaded the resource from Polymart, requests a download link that can be used to download the resource. The parameters can be provided either as GET or as POST parameters.

Parameters

NOTE that ALL of these parameters are required. If you do not provide all of them, verification will always fail. In addition, this API call will only work if the resource as downloaded from Polymart (and not if it was purchased and downloaded on another marketplace). You can use the %%__POLYMART__%% placeholder to check this.

inject_version — the version of the resource injector for this download. You can use the %%__INJECT_VER__%% placeholder for this

resource_id — the ID of the resource in question. You can use the %%__RESOURCE__%% placeholder for this

user_id — the ID of the user in question. You can use the %%__USER__%% placeholder for this

nonce — the nonce given to the download by Polymart. You can use the %%__NONCE__%% placeholder for this

download_agent — the agent that downloaded the resource from Polymart. You can use the %%__AGENT__%% placeholder for this

download_time — the time the resource was downloaded from Polymart. You can use the %%__TIMESTAMP__%% placeholder for this

download_token — the download token from Polymart. You can use the %%__VERIFY_TOKEN__%% placeholder for this

Response

Format
{
  "request": "...",
  "response": {
    "success": <true/false>,
    "result": {
      "url": <url>,
      "version": <version string>,
      "expires": <unix timestamp>
    }
  }
}
Example
{
  "request": "...",
  "response": {
    "success": true,
    "result": {
      "url": "https://polymart.org/download/1/?param=arg...",
      "version": "2.7.12",
      "expires": 1601484501
    }
  }
}

Usage

This is useful for auto-updaters for premium plugins. If the user is verified to have downloaded the resource, you can use response.result.url to download the latest version of the resource. However, this URL will expire at the unix timestamp given at response.result.expires.

You should check response.result.version to make sure that a new version is in-fact available

If the user did not purchase the plugin on Polymart, response.success will be false. Use this to verify that a given resource download is authentic. For example,

https://api.polymart.org/v1/requestUpdateURL/
   ?download_token=MDAwY2QzZDk0MjdkYWNm
   &user_id=1
   &resource_id=4
   &nonce=7318
   &inject_version=1
   &download_agent=000000
   &download_time=1587928929


All of these parameters should be gathered from %%__PLACEHOLDERS__%% in your resource file. Check the Parameters section above to see which parameter to pass where
/v1/postUpdate Back to top
Uploads a new version for one of your resources. This must be sent as a multipart/form-data POST request. An example JavaScript/HTML form for submitting an update is included below.

Parameters

api_key — your API key. If you don't yet have an API key, visit your account settings to generate one. Security Warning because an API key allows access to your entire account, you should never use it on client-side code. If you don't know what that means, don't use this action.

resource_id — the ID of the resource you'd like to post an update to. This is the number at the end of your resource's link on Polymart. For example, https://polymart.org/resource/item-bridge.4 has the ID 4

version — the new version string, like "1.0" or "2.6.7"
title — the title for your new update
message — the message for your new update. You can use BBCode here
file — the new file you're uploading.

beta (optional) — set this to "1" to mark this version as a beta version.
snapshot (optional) — set this to "1" to mark this version as a snapshot version

Response

Format
{
  "request": "...",
  "response": {
    "success": <true/false>,
    "errors": {
      "global": <global error message>,
      "file": <file error message>,
      "version": <version error message>,
      "title": <update title error message>,
      "message": <update message error message>
    },
    "update": {
      "id": <number>,
      "version": <version used>,
      "beta": <true/false>,
      "snapshot": <true/false>
    },
    "resource": {
      "id": <number>
    }
  }
}
Example
{
  "request": "...",
  "response": {
    "success": true,
    "errors": [],
    "update": {
      "id": 17263,
      "version": "3.6",
      "beta": false,
      "snapshot": false
    },
    "resource": {
      "id": 4
    }
  }
}

Usage

Use this to post an update to your resource. Here's a HTML/JavaScript implementation of the API action (Remember: NEVER share your API keys)
<html>
<body>
    <form>
        New Version: <input type="text" id="update-ver"><br>
        Update Title: <input type="text" id="update-title"><br>
        Update Message: <input type="text" id="update-desc"><br><br>

        File: <input type="file" id="file-input"><br><br>

        <a href="#!" onclick="pushUpdate()">Send Update</a>
    </form>

    <script type="text/javascript">
        function pushUpdate(){
            var xhttp = new XMLHttpRequest();
            xhttp.onreadystatechange = function() {
                if(this.readyState === 4){
                    let json = JSON.parse(this.responseText);
                    // use the response json in "json"
                }
            };

            xhttp.open("POST", `https://api.polymart.org/v1/postUpdate`, true);
            xhttp.setRequestHeader("enctype", "multipart/form-data"); // It's important to set this

            let formData = new FormData();

            formData.append("resource_id", "YOUR RESOURCE ID")
            formData.append("version", document.getElementById("update-ver").value)
            formData.append("title", document.getElementById("update-title").value)
            formData.append("message", document.getElementById("update-desc").value)
            formData.append("file", document.getElementById("file-input").files[0])
            formData.append("api_key", "YOUR API KEY");

            xhttp.send(formData);
        }
    </script>
</body>
</html>
/v1/getResourceUserData Back to top
Gets information about a resource purchase for a given user. DO NOT USE THIS FOR VERIFYING DOWNLOADS. To verify a download, use the /v1/verifyPurchase action. All data must be sent as a POST request

Parameters

api_key — your API key. If you don't yet have an API key, visit your account settings to generate one. Security Warning because an API key allows access to your entire account, you should never use it on client-side code. If you don't know what that means, don't use this action.

resource_id — the ID of the resource you'd like to check. This is the number at the end of your resource's link on Polymart. For example, https://polymart.org/resource/item-bridge.4 has the ID 4

user_id — the ID of the user that you'd like to check. To verify a user and get their user ID, use the /v1/generateUserVerifyURL and /v1/verifyUser actions

Response

Format
{
  "request": "...",
  "response": {
    "success": <true/false>,
    "result": {
      "id": <resource id>,
      "purchaseValid": <true/false>,
      "purchaseStatus": <None/Manual/Imported/PayPal payment status code>
    },
    "user": {
      "id": <user id>
    },
    "errors": {
      "global": <global error message>
    }
  }
}
Example
{
  "request": "...",
  "response": {
    "success": true,
    "resource": {
      "id": "4",
      "purchaseValid": true,
      "purchaseStatus": "Confirmed"
    },
    "user": {
      "id": 713249
    }
  }
}
/v1/generateUserVerifyURL Back to top
This action generates a URL for verifying a Polymart user. To verify a user, call this action and then send the user to the URL in the response. They'll be given a token you can use to verify their Polymart account. You'll pass this token to /v1/verifyUser to verify the user and get their user ID.

The token that the user is given expires in 30 minutes. Make sure to verify it quickly!

For example, you could use this to verify users on your Discord server.

If you're looking to get access to a user's resources (say, if you're a server host and want to allow users to download their premium resources), use /v1/authorizeUser instead

Parameters

service — The unique name of your service — it's recommended that you use reverse-domain format for this to ensure uniqueness. For example, com.jojodmo.CustomItems or org.polymart.PolymartExample

nonce (optional) — For added security, pass a unique, random value here. This ensures that tokens can't be re-used. However, you'll need to pass the same nonce when verifying the user with the /v1/verifyUser action.

Response

Format
{
  "request": "...",
  "response": {
    "success": <true/false>,
    "result": {
      "url": <url>
    }
  }
}
Example
{
  "request": "...",
  "response": {
    "success": true,
    "result": {
      "url": "https://polymart.org/verifyUser?service=example"
    }
  }
}

Usage

Here's an example API call

https://api.polymart.org/v1/generateUserVerifyURL
   ?service=org.polymart.DeveloperAPIExample
   &nonce=Ypy5wONg4d57
/v1/verifyUser Back to top
Verifies a Polymart user given a token from /v1/generateUserVerifyURL

For example, You could use this to verify users on your Discord server.

Parameters

service — The unique name of your service — this MUST be the same thing you passed in /v1/generateUserVerifyURL

nonce (optional) — This MUST be the same thing you passed in /v1/generateUserVerifyURL

token — The token that the user gives you

Response

Format
{
  "request": "...",
  "response": {
    "success": <true/false>,
    "result": {
      "user": {
        "id": <user id>
      }
    }
  }
}
Example
{
  "request": "...",
  "response": {
    "success": true,
    "result": {
      "user": {
        "id": 69444
      }
    }
  }
}

Usage

Here's an example API call (notice how service and nonce are the same as in the /v1/generateUserVerifyURL example above). Log in to generate a valid API call

https://api.polymart.org/v1/verifyUser
   ?service=org.polymart.DeveloperAPIExample
   &nonce=Ypy5wONg4d57
   &token=4CM87Y1
/v1/authorizeUser Back to top
Request access to download resources on a user's behalf. If you're looking for something just to verify a user (say, for example, to verify buyers on your Discord server), use /v1/verifyUser instead.

Parameters

service — the domain from which you're going to make API calls. For example, "api.jojodmo.com" or "skiplit.com"

return_url — the URL that the user will be redirected to upon either allowing or denying access to their account.
IMPORTANT: the domain for this URL must exactly match the one given in service. For example, if your return_url is "https://skiplit.com/polymartResponse", service must be "skiplit.com". Anything else will cause an error.

return_token — Polymart must authorize you to use this parameter before you do. If you haven't yet received authorization from us, please Contact Us first. Set this to "1" if you want this request to return "token" in response.result.

state — a secure, random string that can be used to verify that the response you get in return_url is in-fact valid. If this isn't random, then an attacker could send an invalid token back to your service and trick you into thinking that it is valid. This should only contain URL-safe characters, like letters, numbers, dashes and underscores.

Response

Format
{
  "request": "...",
  "response": {
    "success": <true/false>,
    "result": {
      "url": <redirect url>,
      "token": <token>
    }
  }
}
Example
{
  "request": "...",
  "response": {
    "success": true,
    "result": {
      "url": "https://polymart.org/linkAccount/?param=value...",
      "token": ""
    }
  }
}

Usage

After making the request, redirect the user to the URL in response.result.url
After the user either denies or accepts the request, they will be returned to the parameter you gave for return_url.

If the user denies the request, they will be redirected and the POST parameter success will be 0.

If the user accepts the request, they will be redirected, and there will be two POST parameters passed along: success will be 1, and token will be the token you can use to make downloads on the user's behalf. The token will be less than 255 characters long. Store this in a secure place. The token will expire after a given amount of time, after which you will need to request authorization from the user again. As of now, tokens expire every 365 days, but this could change.

If you set return_token=1 notice that the API action also contains response.result.token. This is the the token that will be validated by the user. You can use /v1/verifyAuthToken to check whether or not the token is valid, and asynchronously verify the token.

Example

Here is an example of a call to /v1/authorizeUser. For example, you might make a request to https://api.polymart.org/v1/authorizeUser with the following POST parameters:
service = api.skiplit.com
return_url = https://api.skiplit.com/polymartResponse
return_token = 1 state = P2cJjcU_-ThLqWpP8NGWNRsm

Then, you would check that response.result.success is true. If it is, you would redirect the user to the URL in response.result.url.

The user would then be taken to a page on Polymart, and asked if they want to give your service access to download plugins on their behalf. Once they enter their password and confirm the request, the user will be redirected back to the return_url you provided, and information about the user would be passed along in the POST parameters.

In this example, the user would be returned to the URL https://api.skiplit.com/polymartResponse. In the POST parameters, you'll see three things:
success will be 1 if the user confirmed the request, and 0 if they didn't.
token will be a token that you can use to make downloads on the user's behalf.
state will be the same value as the one you passed when you were making the original call to /v1/authorizeUser. If it isn't the same, then you know an attacker is trying to trick you into thinking an invalid token is in-fact valid.

For example, you might get these values in the POST parameters of https://api.skiplit.com/polymartResponse:
success = 1
token = A6kVowCTKzdJcn9M0qZ55E7b
state = P2cJjcU_-ThLqWpP8NGWNRsm

The token will be less than 255 characters long. You should store the token in a secure location, and you can later use this token in other requests to the Polymart API. For example, you could pass this token along in the POST data of /v1/verifyAuthToken to verify that the token is valid and has not expired.

Working Example

Here is a working example for a call to /v1/authorizeUser.
When you click the link, the following are also sent as POST parameters:

    service = polymart.org
    return_url = https://polymart.org/wiki/api#authorizeUserForm
    state = P2cJjcU_-ThLqWpP8NGWNRsm (a secure, random string)


If you open the link given in response.result.url in your browser, you will see the results shown below. These are sent as POST parameters back to whatever return_url was set to (in this case, they're set as POST parameters back to this page)

(nothing received yet! Visit the URL given in response.result.url to test out this API call)
/v1/verifyAuthToken Back to top
Verifies a user's token.

Parameters

token — a token for the user. This MUST be sent in the POST parameters of the request. If you don't yet have a token for the user, read about the the /v1/authorizeUser action.

Response

Format
{
  "request": "...",
  "response": {
    "success": <true/false>,
    "result": {
      "success": true,
      "message": <SUCCESS|TOKEN_EXPIRED|TOKEN_INVALID|NO_TOKEN>,
      "user": {
        "id": <user id>
      },
      "expires": <unix timestamp>
    }
  }
}
Example
{
  "request": "...",
  "response": {
    "success": true,
    "result": {
      "success": true,
      "message": "SUCCESS",
      "user": {
        "id": "72631"
      },
      "expires": 1604076201
    }
  }
}

Usage

Use this to verify that a token that you have for a user is valid and has not expired. For example, when you click the link below, the following are also sent as POST parameters:

    token = eyJpZCI6IjI4MDY2LjE2MDE0ODQyMDEiLCJ2YWwiOiJSaGYxVlpXS1I0OVIwS0piIiwic2J4IjoxfQ


/v1/invalidateAuthToken Back to top
Invalidates a user's token. For security reasons, you should call this if a user ever decides to un-link their Polymart account with your service.

Parameters

token — a token for the user. This MUST be sent in the POST parameters of the request.

Response

Format
{
  "request": "...",
  "response": {
    "success": <true/false>,
    "result": {
      "message": <SUCCESS|TOKEN_INVALID|NO_TOKEN>
    }
  }
}
Example
{
  "request": "...",
  "response": {
    "success": true,
    "result": {
      "message": "SUCCESS"
    }
  }
}
/v1/getDownloadURL Back to top
Gets a URL that can be used to download a resource on a user's behalf.

Parameters

resource_id — the ID of the resouce that you would like to download on the user's behalf. This is the number after /resource/ (and after the period) on a Polymart resource page. For example, https://polymart.org/resource/item-bridge.4 has resource_id = "4"

token — a token for the user. It is recommended that you pass this as a POST parameter for free resources, but it isn't strictly necessary. This MUST be sent as a POST paramater for premium resources. If you don't yet have a token for the user, read about the the /v1/authorizeUser action.

Response

Format
{
  "request": "...",
  "response": {
    "success": <true/false>,
    "message": <SUCCESS|NOT_PURCHASED|NO_TOKEN|TOKEN_INVALID|TOKEN_EXPIRED>,
    "result": {
      "url": <download url>,
      "version": <version string>,
      "expires": <unix timestamp>
    }
  }
}
Example
{
  "request": "...",
  "response": {
    "success": true,
    "message": "SUCCESS",
    "result": {
      "url": "https://polymart.org/download/?param=value...",
      "version": "2.17.4",
      "expires": 1601484261
    }
  }
}

Usage

After making the request, you may download the resource from the URL response.result.url In normal cases, this will start the download of the resource.

However, if the download can not proceed (either because the user does not have permission to download the resource, or because the download link is expired), then the URL will return a 400 Bad Request error, and the result will be a JSON string containing an explanation of the problem.

For example, when you click the link below, the following are also sent as POST parameters:

    resource_id = 4
    token = eyJpZCI6IjI4MDY2LjE2MDE0ODQyMDEiLCJ2YWwiOiJSaGYxVlpXS1I0OVIwS0piIiwic2J4IjoxfQ