§FORMAT: 1A HOST: https://api.bukget.org
BukGet is an API for getting data about bukkit plugins. The system parses BukkitDev every 6 hours and looks for new changes in the data to update. All of this is automatic and happens without any developer intervention. If you notice any issues, we encourage you to open a ticket with us over at the issue tracker. This is the only way we can know about parser errors or issues and make any needed corrections. Below is the schedule that BukGet uses for generating the data. Keep in mind that if you update a plugin, it can take just over 6 hours for your plugin to hit the index. The API is served over both HTTP and HTTPS.
| Type | Times (UTC) |
|---|---|
| Normal/Speedy: | Every 6 hours (0000, 0600, 1200, 1800) |
| Status Update: | Weekly (0000 Saturday) |
| Full Generation: | As Needed |
| Ad-Hoc Updates: | As Needed/Ticket Request |
We recommend that when communicating to the API, that you use a custom User-Agent string (UA String) to identify your application. We are tracking these UA strings and are using these to determine what applications are utilizing the API. If you have any questions about User Agent strings, please contact us in the IRC channel.
The following items may be exposed via the API, however these are used internally by the parser and/or the APIs and are not intended for general use.
- _use_dbo: This is an internal flag that is set on a plugin to denote that the plugin parser will use the version parsed from the DBO page over the plugin.yml version. This is pragmatically set when 3 or more plugin versions exist when there is only one unique plugin version pulled from the plugin.yml.
Returns information about the last several generations in the API. Includes things like when, what server, parsing type, how long it took, and what changes had occurred. Optionally the user can specify how many generations back they would like to look.
-
Parameters
- size (optional, Integer,
1) ... How many generations you want info about.
- size (optional, Integer,
-
Model
-
Headers
Content-Type: application/json -
Body
[ { "timestamp": 1395680823, // The current UNIX timestamp that the Generation started at. "parser": "bukkit", // The parser that this generation was run with. "changes": [ // A list of the changes that had occurred in the API. { "version": "1.0.0", // The version of the plugin that was updated. "plugin": "joincommands" // The plugin slug that was updated. }, { "version": "0.1", "plugin": "cakegiver" }, { "version": "1.3.1", "plugin": "emotionz" }, { "version": "2.3.1", "plugin": "minecraftspells" }, { "version": "2.9.1", "plugin": "safewgtool-swgt" }, { "version": "1.1.9", "plugin": "archer" }, { "version": "1.1", "plugin": "plugin-dispenser" } ], "duration": 421, // The number of seconds it took to complete the generation. "type": "speedy", // The type of generation that was run (speedy, full are some examples). "id": "53306637a8f070843817cdfb" // The ID of the generation. } ]
-
Examples:
http://api.bukget.org/3/geninfo
http://api.bukget.org/3/geninfo?size=10
-
Response 200
[Generation Information][]
Returns information about a specific generation in the API. Includes things like when, what server, parsing type, how long it took, and what changes had occurred.
-
Model
-
Headers
Content-Type: application/json -
Body
{ "timestamp": 1395680823, // The current UNIX timestamp that the Generation started at. "parser": "bukkit", // The parser that this generation was run with. "changes": [ // A list of the changes that had occurred in the API. { "version": "1.0.0", // The version of the plugin that was updated. "plugin": "joincommands" // The plugin slug that was updated. }, { "version": "0.1", "plugin": "cakegiver" }, { "version": "1.3.1", "plugin": "emotionz" }, { "version": "2.3.1", "plugin": "minecraftspells" }, { "version": "2.9.1", "plugin": "safewgtool-swgt" }, { "version": "1.1.9", "plugin": "archer" }, { "version": "1.1", "plugin": "plugin-dispenser" } ], "duration": 421, // The number of seconds it took to complete the generation. "type": "speedy", // The type of generation that was run (speedy, full are some examples). "id": "53306637a8f070843817cdfb" // The ID of the generation. }
-
Example:
http://api.bukget.org/3/geninfo/53306637a8f070843817cdfb
-
Response 200
[Specific Generation Information][]
The plugin listing is simply a list of plugins in the API. The information can be represented however the user wishes by modifying the query attributes and pagination directly from the API. Optionally the information can further be narrowed down based on the server platform the plugins are written for (e.g. bukkit).
-
Parameters
- server (optional, String,
bukkit) ... For what server binary the plugins should be. - size (optional, Integer,
10) ... How many documents do you want to return. - start (optional, Integer,
5) ... From where the query should start. - sort (optional, String,
plugin_name) ... Which field to sort by. Use a - before the field name to perform an inverted sort. - fields (optional, String,
slug,plugin_name,description) ... Which fields the request should return.
- server (optional, String,
-
Model
-
Headers
Content-Type: application/json -
Body
// For field descriptions, Please see the plugin details entry. [ { "description": "", "plugin_name": "abag", "slug": "abag" }, { "description": "Get who used the vehicle as last and who placed it.", "plugin_name": "AbandonedCarts", "slug": "abandonedcarts" } ]
-
Examples:
http://api.bukget.org/3/plugins
http://api.bukget.org/3/plugins?size=10
http://api.bukget.org/3/plugins/bukkit?size=10&start=10
-
Response 200
[Plugin Listing][]
The plugin details listing all of the information we know about a given plugin.
-
Parameters
- server (required, String,
bukkit) ... For what server binary the plugins should be. - slug (required, String,
abacus) ... The slug of the plugin you want details for - version (optional, String,
latest) ... The specific version that you want, can also belatestfor the latest version, orrelease,beta,alphafor the latest version of that type. - size (optional, Integer,
10) ... How many versions (if applicable) do you want to return. - fields (optional, String,
slug,plugin_name,description) ... Which fields the request should return.
- server (required, String,
-
Model
-
Headers
Content-Type: application/json -
Body
{ "website": "http://dev.bukkit.org/server-mods/abacus/", // The web-site of the plugin "dbo_page": "http://dev.bukkit.org/server-mods/abacus", // The BukkitDev URL for this plugin (Bukkit Only). "description": "Offers ability to perform calculations while in Minecraft", // A short description of the plugin. "logo_full": "", // The full-size logo from the plugin’s BukkitDev page (Bukkit Only). "versions": [ // A list of version objects. { "status": "Semi-normal", // The BukkitDev version status (Bukkit Only). "commands": [ // List of command objects detailing what commands this plugins has (if parsable). { "usage": "", // Usage Description to be displayed to the user. "aliases": [], // List of aliases for this command. "command": "abacus", // The command name. "permission-message": "§cYou do not have access to that command.", // The message displayed if a user tried to run the command without permissions to. "permission": "abacus.abacus" // The permission this command relies on. } ], "changelog": "LONG STRING OF STUFF!!!!!", // Base64 Encoded string of the version changelog. "game_versions": [ // List of server versions that this specific plug-in version supports. "CB 1.4.5-R0.2" ], "filename": "Abacus.jar", // Version download filename. "hard_dependencies": [], // List of plugins that are required for this plugin to run. "date": 1353964798, // Date Released "version": "0.9.3", // The version number. "link": "http://dev.bukkit.org/server-mods/abacus/files/4-abacus-v0-9-2-cb-1-4-5-r0-2-compatible-w-1-3-2/", // URL for version specific page. "download": "http://dev.bukkit.org/media/files/650/288/Abacus.jar", // The download URL for this version. "md5": "1e1b6b6e131c617248f98c53bf650874", // The MD5Sum of the version download. "type": "Beta", // The version type. "slug": "4-abacus-v0-9-2-cb-1-4-5-r0-2-compatible-w-1-3-2", // The canonical name of this version (example, BukkitDev version slug). This is exclusive to a plugin and cannot be changed. "soft_dependencies": [], // List of plugins that this plugins can optionally depend on. "permissions": [ // List of permission dictionaries details what permissions this plugin has (if parseable). { "default": "op", // Default permission for this role. Example, in Bukkit, there are 4 possibilities (“op”, “not op”, true, false). "role": "abacus.*" // Role name. }, { "default": true, "role": "abacus.abacus" } ] }, ], "plugin_name": "Abacus", // The name of the plugin. This is non-exclusive and multiple plugins could have the same name. "popularity": { "monthly": 133, // The popularity score over the last 30 days. "daily": 994, // The most current popularity score of the plugin. "weekly": 238, // The popularity score over the last 7 days. "total": 1500, // The popularity score since the API added the plugin. }, "server": "bukkit", // The server binary that this plugin is compatible with. For example, ‘bukkit’ would denote a bukkit plugin. "main": "org.ruhlendavis.mc.abacus.Abacus", // This is the main field in the plugin.yml. Bukkit uses this to identify the plugin internally. This is usually the main class. "authors": [ // List of authors that wrote this plug-in. "Feaelin {[email protected]}" ], "logo": "", // A thumb-nailed version of the logo from the plugin’s BukkitDev page (Bukkit Only). "slug": "abacus", // The canonical name (example, BukkitDev slug name). This name is exclusive and cannot be changed. "categories": [ // List of categories that this plugin falls under. "Informational" ], "stage": "Beta" // What BukkitDev stage the plugin is in. }
-
Examples:
http://api.bukget.org/3/plugins/bukkit/abacus
http://api.bukget.org/3/plugins/bukkit/abacus?size=1&fields=slug,plugin_name,versions
http://api.bukget.org/3/plugins/bukkit/abacus/latest
http://api.bukget.org/3/plugins/bukkit/abacus/0.9.3?size=1&fields=slug,plugin_name,versions
-
Response 200
[Plugin Details][]
-
Response 404
-
Headers
Content-Type: application/json -
Body
{ "error": "Plugin Does Not Exist" }
-
This URL is a convenience function to redirect to the download page of the plugin version specified. Optionally the latest version can always be selected by using the “latest” word in place of a specific version.
-
Parameters
- server (required, String,
bukkit) ... For what server binary the plugins should be. - slug (required, String,
abacus) ... The slug of the plugin you want details for - version (required, String,
latest) ... The specific version that you want, can also belatestfor the latest version, orrelease,beta,alphafor the latest version of that type.
- server (required, String,
-
Model
Examples:
http://api.bukget.org/3/plugins/bukkit/abacus/latest/download
http://api.bukget.org/3/plugins/bukkit/abacus/0.9.3/download
-
Response 302
[Plugin Download][]
-
Response 404
-
Headers
Content-Type: application/json -
Body
{ "error": "could not find version" }
-
A list of categories in the database and the number of plugins that each category has.
-
Model
-
Headers
Content-Type: application/json -
Body
[ { "count": 2732, // Number of plugins in this category. "name": "Admin Tools" // Category name. }, { "count": 786, "name": "Anti-Griefing Tools" }, { "count": 979, "name": "Chat Related" }, ]
-
Examples:
http://api.bukget.org/3/categories
-
Response 200
[Category Listing][]
A plugin listing based on the category referenced. Behaves the same as the main plugin listing. Optionally you can restrict the view based on the server binary compatibility.
-
Parameters
- server (optional, String,
bukkit) ... For what server binary the plugins should be. - category (required, String,
bukkit) ... The name of the category. - size (optional, Integer,
10) ... How many documents do you want to return. - start (optional, Integer,
5) ... From where the query should start. - sort (optional, String,
plugin_name) ... Which field to sort by. Use a - before the field name to perform an inverted sort. - fields (optional, String,
slug,plugin_name,description) ... Which fields the request should return.
- server (optional, String,
-
Model
-
Headers
Content-Type: application/json -
Body
// For field descriptions, Please see the plugin details entry. [ { "description": "", "plugin_name": "abag", "slug": "abag" }, { "description": "Get who used the vehicle as last and who placed it.", "plugin_name": "AbandonedCarts", "slug": "abandonedcarts" } ]
-
Examples:
http://api.bukget.org/3/categories/Anti-Griefing%20Tools
http://api.bukget.org/3/categories/Anti-Griefing%20Tools?size=20
http://api.bukget.org/3/categories/bukkit/Anti-Griefing%20Tools?size=20
-
Response 200
[Category Plugin Listing][]
A list of plugin authors in the database and the number of plugins that each author has worked on.
-
Model
-
Headers
Content-Type: application/json -
Body
[ { "count": 1, // Number of plugins in this category. "name": "0xfffc69" // Author name. }, { "count": 2, "name": "14nicholasse" }, { "count": 3, "name": "15kingben" }, ]
-
Examples:
http://api.bukget.org/3/authors
-
Response 200
[Author Listing][]
A plugin listing based on the author referenced. Behaves the same as the main plugin listing. Optionally you can restrict the view based on the server binary compatibility.
-
Parameters
- server (optional, String,
bukkit) ... For what server binary the plugins should be. - author (required, String,
bukkit) ... The name of the author. - size (optional, Integer,
10) ... How many documents do you want to return. - start (optional, Integer,
5) ... From where the query should start. - sort (optional, String,
plugin_name) ... Which field to sort by. Use a - before the field name to perform an inverted sort. - fields (optional, String,
slug,plugin_name,description) ... Which fields the request should return.
- server (optional, String,
-
Model
-
Headers
Content-Type: application/json -
Body
// For field descriptions, Please see the plugin details entry. [ { "description": "", "plugin_name": "abag", "slug": "abag" }, { "description": "Get who used the vehicle as last and who placed it.", "plugin_name": "AbandonedCarts", "slug": "abandonedcarts" } ]
-
Examples:
http://api.bukget.org/3/authors/iAlexak
http://api.bukget.org/3/authors/iAlexak?size=1
http://api.bukget.org/3/authors/bukkit/iAlexak?size=1
-
Response 200
[Author Plugin Listing][]
Outputs the latest, latest release, beta, alpha, versions for each plugin found. Returns hash and current version if the hashes parameter is used.
-
Parameters
- slugs (optional, String,
worldedit,dynmap) ... Which slug(s) to search for. - hashes (optional, String,
49ab15446ae1bfce8801433cd75f8fc9) ... Which file md5(s) to search for. - filenames (optional, String,
dynmap-1.9.3.jar) ... Which filename(s) to search for. - extra_fields (optional, String,
website,main) ... Which extra fields the request should return. - extra_version_fields (optional, String,
status,commands) ... Which extra fields the request should return for each version.
- slugs (optional, String,
-
Model
-
Headers
Content-Type: application/json -
Body [ { "slug": "abitofrealism", // Plugin slug "plugin_name": "AbitOfRealism", // Plugin name "versions": { // List of version objects "latest": { // Version type "version": "0.3.1", // Version "download": "http://dev.bukkit.org/media/files/599/604/AbitOfRealism.jar", // Download link "md5": "236c18df1d15e149fe91675c08efa8b5" // File md5 }, "beta": { "version": "0.3.1", "download": "http://dev.bukkit.org/media/files/599/604/AbitOfRealism.jar", "md5": "236c18df1d15e149fe91675c08efa8b5" }, "current": { // Only returned if "hashes" parameter is used "version": "0.3.1", "download": "http://dev.bukkit.org/media/files/599/604/AbitOfRealism.jar", "md5": "236c18df1d15e149fe91675c08efa8b5" }, "alpha": { "version": "0.1", "download": "http://dev.bukkit.org/media/files/596/293/AbitOfRealism.jar", "md5": "2458133b2813b66e2c162ce7bbdf5c18" } } "hash": "236c18df1d15e149fe91675c08efa8b5" // Only returned if "hashes" parameter is used } ]
-
Examples:
http://api.bukget.org/3/updates?slugs=dynmap,worldedit
http://api.bukget.org/3/updates?hashes=49ab15446ae1bfce8801433cd75f8fc9
http://api.bukget.org/3/updates?slugs=worldedit&hashes=49ab15446ae1bfce8801433cd75f8fc9&filenames=dynmap-1.9.3.jar
-
Response 200
[Updates][]
-
Response 200
[Updates][]
A generalized search function to allow users to look for specific content. Any field can be used for searching as long as you use dot notation to tell the engine where to look.
Valid actions:
- equals: Field equals value.
- not-equals: Field is not Equal to value.
- less: Field is less than value.
- less-equal: Field is less than or equal to value.
- more: Field is greater than value.
- more-equal: Field is greater than or equal to value.
- like: Field is like (partial match) to value.
-
Parameters
- size (optional, Integer,
10) ... How many documents do you want to return. - start (optional, Integer,
5) ... From where the query should start. - sort (optional, String,
plugin_name) ... Which field to sort by. Use a - before the field name to perform an inverted sort. - fields (optional, String,
slug,plugin_name,description) ... Which fields the request should return.
- size (optional, Integer,
-
Model
-
Headers
Content-Type: application/json -
Body
// For field descriptions, Please see the plugin details entry. [ { "description": "", "plugin_name": "abag", "slug": "abag" }, { "description": "Get who used the vehicle as last and who placed it.", "plugin_name": "AbandonedCarts", "slug": "abandonedcarts" } ]
-
Examples:
http://api.bukget.org/3/search/slug/like/world
http://api.bukget.org/3/search/slug/like/world?size=10
-
Response 200
[Plugin Search][]
A generalized search function to allow users to look for specific content. Any field can be used for searching as long as you use dot notation to tell the engine where to look.
Valid actions:
- equals: Field equals value.
- not-equals: Field is not Equal to value.
- less: Field is less than value.
- less-equal: Field is less than or equal to value.
- more: Field is greater than value.
- more-equal: Field is greater than or equal to value.
- like: Field is like (partial match) to value. You can also use it as a case-insensitive equals, by using ^SearchWord$ as the value.
- in: Field is in the list of of values provided.
- not in: Field is not in the list of values provided.
- all: Field contains all of the values in the list provided.
- exists: Field exists.
- and: All values in list provided are matching. See example below.
- or: Some values in the list of objects provided are matching. See example below.
- likeor: Some values in the list of objects provided are partially matching. See OR example below.
- nor: No values in the list of objects provided are matching. See example below.
- not: Performs a logical NOT operation on the specified expressions. See example below.
Filters examples:
[
{
"field": "plugin_name",
"action": "like",
"value": "mc"
},
{
"field": "versions.game_version",
"action": "like",
"value": "1.4.5"
}
]
AND example:
[
{
"field": "",
"action": "and",
"value": [
{
"stage": "Release"
},
{
"slug": "abitofrealism"
}
]
}
]
OR example:
[
{
"field": "",
"action": "or",
"value": [
{
"slug": "abitofrealism"
},
{
"slug": "clearthechat"
}
]
}
]
NOR example:
[
{
"field": "",
"action": "nor",
"value": [
{
"slug": "abitofrealism"
},
{
"slug": "clearthechat"
}
]
}
]
NOT example:
{
"field": "curse_id",
"action": "not",
"value": {
"$lt": 48244 // Usually less than 48244, now where it's not less than 48244
}
}
-
Parameters
- filters (Required, String, ``) ... JSON encoded, refer to the example format for the filters field above.
- size (optional, Integer,
10) ... How many documents do you want to return. - start (optional, Integer,
5) ... From where the query should start. - sort (optional, String,
plugin_name) ... Which field to sort by. Use a - before the field name to perform an inverted sort. - fields (optional, String,
slug,plugin_name,description) ... Which fields the request should return.
-
Model
-
Headers
Content-Type: application/json -
Body
// For field descriptions, Please see the plugin details entry. [ { "description": "", "plugin_name": "abag", "slug": "abag" }, { "description": "Get who used the vehicle as last and who placed it.", "plugin_name": "AbandonedCarts", "slug": "abandonedcarts" } ]
-
-
Response 200
[POST Plugin Search][]
The invalid version list is a list of plugins that have had to be switched over to using the BukkitDev versioning instead of the plugin.yml versioning. This happens when it is detected that there are 3 or more plugins with only 1 unique version between them (e.g. All of the plugin versions are considered v0.1 in the plugin.yml). This generally indicates that the plugin developer hasn’t been updating their plugin.yml to reflect new versions of their code and you should not trust the versioning indicated by the server for these plugins.
-
Model
-
Headers
Content-Type: application/json -
Body
[ { "plugin_name": "ClearTheChat", "authors": [ "FlavourFlave" ], "slug": "youclearthechat" }, { "plugin_name": "Improved Jail", "authors": [ "UntoldAdventures" ], "slug": "improvedjail" }, { "plugin_name": "EasySave", "authors": [ "kamakarzy" ], "slug": "easysave" } ]
-
Example:
http://api.bukget.org/stats/naughty_list
-
Response 200
[Invalid versions list][]
Returns amount of plugins and versions that is currently available in the API.
-
Model
-
Headers
Content-Type: application/json -
Body
{ "plugin_count": 14633, "version_count": 69861 }
-
Example:
http://api.bukget.org/stats/todays_trends
-
Response 200
[Current statistics][]
Returns traffic info about the API.
-
Parameters
- days (required, Integer,
5) ... How many days of trends that should be returned
- days (required, Integer,
-
Model
-
Headers
Content-Type: application/json -
Body
[ { "bukkitdev": 0, "unique": 10792, // Unique IPs "api3": 405927, // Total requests for API 3 "timestamp": 1395658808, // When these statistics were generated "total": 646741, // Total requests "user_agents": { // List of useragents with number of requests "restler": 661, "python-requests": 52, "appengine-google;": 1, "mcma2": 19703, "tcadmin": 954, "global7hosting": 14, "bertware": 26925, "adminium": 168, "clanslots": 37, "pluginupdater": 493, "httpclient": 33 } }, { "bukkitdev": 0, "unique": 12230, "api3": 442621, "timestamp": 1395572409, "total": 646741, "user_agents": { "python-requests": 84, "mcma2": 24268, "tcadmin": 703, "global7hosting": 16, "bertware": 31411, "adminium": 71, "clanslots": 1, "pluginupdater": 362 } } ]
-
Example:
http://api.bukget.org/stats/trend/10
-
Response 200
[Trends][]