- Joined
- Sep 4, 2013
- Messages
- 1,475
- Reaction score
- 1,616
This is documentation for this website, StarMade Dock. This is not for StarMade the game.
Why is this useful?
The biggest benefit of an SMD API, is the ability for external applications to interact with the Community Content section. Here are a few examples:
All available REST API endpoints: REST API endpoints (2.2)
Accessing the API
Apply for an API Key here!
Cached API
Community Content API endpoints
The official API endpoint documentation for this software has been unfinished for years. Here is an explanation of some of the Community Content (resource) API endpoints.
Optional parameters: page
Only available through cached API: https://starmadedock.net/cached-api/resource-categories/{id}.json (add .gz at end for gzip)
Required parameters: file (available in GET resource-versions/{id}/)
Example:
Example:
Finding a version of a mod that's compatible with the client's StarMade version.
Convoluted, but unfortunately the API isn't really designed for this.
Error handling
Code example
This example has no error handling, make sure you do!
Why is this useful?
The biggest benefit of an SMD API, is the ability for external applications to interact with the Community Content section. Here are a few examples:
- Catalog manager to browse and download ships and space stations within StarMade. As implemented in the mod loader Starloader.
- In-game mod browser. As implemented in the mod loader Starloader.
- Mod packs.
- Skin, texture pack, configuration, npc factions etc. browser.
- Faction page integrations.
- A mod to randomly download ships and space stations for pirates or factions to use.
All available REST API endpoints: REST API endpoints (2.2)
Accessing the API
All API responses will be returned in JSON format, except in cases where a binary file is specifically requested (such as when downloading an attachment). Errors will always return a response code in the 400 range. Successful requests will return a 200 code. While not commonly used, redirects will return a 300-range code.
Requests bodies must be sent using the application/x-www-form-urlencoded encoding or, if a file is being uploaded, the multipart/form-data encoding. Parameters may also be passed via the query string.
All request data must use the UTF-8 character set.
Requests must pass the API key to use via the XF-Api-Key header. This must be present in all requests.
REST API endpoints: REST API endpoints (2.2)
REST API documentation: REST API - XenForo 2.0 Documentation
Requests bodies must be sent using the application/x-www-form-urlencoded encoding or, if a file is being uploaded, the multipart/form-data encoding. Parameters may also be passed via the query string.
All request data must use the UTF-8 character set.
Requests must pass the API key to use via the XF-Api-Key header. This must be present in all requests.
REST API endpoints: REST API endpoints (2.2)
REST API documentation: REST API - XenForo 2.0 Documentation
Apply for an API Key here!
- Explain what you want to do and the access you need.
Cached API
Some endpoints have been restricted due to their performance impact, and are only available in our cached api. The cached api is updated every 10 minutes.
resource-categories
Available category ids
resource-categories
https://starmadedock.net/cached-api/resource-categories/{category_id}.json - output of GET resource-categories/{id}/resourceshttps://starmadedock.net/cached-api/resource-categories/{category_id}.json.gz - gzip version of above, good for larger outputs, like Ships which is 20MB json, 1.2MB gzip.Available category ids
- 2 - Ships
- 3 - Space Stations
- 4 - Texture Packs
- 5 - Skins
- 6 - Mods
- 7 - Logic
- 8 - Turrets
- 9 - Templates
- 10 - Configurations
- 17 - NPC Faction Packs
Community Content API endpoints
The official API endpoint documentation for this software has been unfinished for years. Here is an explanation of some of the Community Content (resource) API endpoints.
GET resources/ - Gets 1 page of all resourcesOptional parameters: page
GET resources/{id}/ - Gets information on a specific resource. Useful info like description, latest version's StarMade version compatibility, latest version download.
JSON:
{
"resource": {
"alt_support_url": "",
"can_download": true,
"can_edit": false,
"can_edit_icon": false,
"can_edit_tags": false,
"can_hard_delete": false,
"can_soft_delete": false,
"can_view_description_attachments": true,
"Category": {
"allow_commercial_external": false,
"allow_external": true,
"allow_fileless": false,
"allow_local": true,
"can_add": false,
"can_upload_images": false,
"description": "",
"display_order": 1,
"enable_support_url": true,
"enable_versioning": true,
"last_resource_id": 8174,
"last_resource_title": "TRV Mercury-class Runabout",
"last_update": 1604094328,
"min_tags": 0,
"parent_category_id": 0,
"resource_category_id": 2,
"resource_count": 5741,
"title": "Ships"
},
"currency": "",
"current_files": [
{
"id": 57675,
"filename": "TRV Mercury Runabout V1b.sment",
"size": 19131,
"download_url": "https://starmadedock.net/api/resource-versions/11017/download?file=57675"
}
],
"custom_fields": {
"Gameversion": "0.202.87"
},
"description": "[CENTER][I][COLOR=rgb(124, 112, 107)]damnit we have waaay too many ships called Mercury-class i need to cut down on them lmao[/COLOR][/I]\n[ATTACH type=\"full\" alt=\"1603915219851.png\"]57630[/ATTACH]\n[B][I][SIZE=3]PLEASE NOTE THIS SHIP IS MOSTLY EMPTY AND DESIGNED FOR THE END USER TO FIT SYSTEMS INTO.[/SIZE][/I][/B]\n\n[SIZE=5][B][I]Mercury[/I]-class Runabout[/B][/SIZE]\n\nDetailed further here: [WIP page]\n\nThe [I]Mercury[/I]-class is a class of small but independent starships typically used by Trident Foundries as small couriers and transports.\n[IMG]https://i.imgur.com/LzKvulv.png[/IMG]\nDesigned at the height of the Generation 2 program, the [I]Mercury[/I]-class incorporates military grade systems into a small but bulky and utilitarian chassis, able to be used for most utility roles, and can even be pressed into combat if needed due to it's above-average armament consisting of a nose-mounted plasma cannon and twin linked fusion missile launchers.\n[IMG]https://i.imgur.com/NPu74lU.png[/IMG]\nA plasma drive engine from the [I]Spectre[/I]-class and two other custom-built thrusters provide the craft with plenty of pulling power.\n[IMG]https://i.imgur.com/dQW78C3.png[/IMG]\nDespite it's small size, this class has a fairly extensive interior and provisions for up to six people.\n[IMG]https://i.imgur.com/XogColh.png[/IMG]\n[IMG]https://i.imgur.com/X6zeTo9.png[/IMG]\n[IMG]https://i.imgur.com/U0fA8GJ.png[/IMG]\n[IMG]https://i.imgur.com/IwhTLoP.png[/IMG]\n[IMG]https://i.imgur.com/cun7cVF.png[/IMG]\n\n[B]This project originated when Plaz kept reminding me that I never build exteriors for Trident ships (and haven't since I modified the original [I]Quantum[/I]-class in early 2015-ish), so I built something chunky that's reminiscent of the pre-Trident [I]Lancia[/I]-class heavy fighter that I used to fly around in late 2014-ish.[/B][/CENTER]",
"description_attach_count": 1,
"DescriptionAttachments": [
{
"attach_date": 1603915221,
"attachment_id": 57630,
"content_id": 11704,
"content_type": "resource_update",
"file_size": 368236,
"filename": "1603915219851.png",
"height": 200,
"thumbnail_url": "https://starmadedock.net/data/attachments/106/106008-9d578534a5529af1314b357c7b295e8c.jpg",
"view_count": 1,
"width": 1000
}
],
"download_count": 8,
"external_url": "",
"icon_url": "https://starmadedock.net/data/resource_icons/8/8174.jpg?1603916378",
"last_update": 1604094328,
"prefix_id": 0,
"price": "0.00",
"rating_avg": 0,
"rating_count": 0,
"rating_weighted": 3,
"reaction_score": 7,
"resource_category_id": 2,
"resource_date": 1603916378,
"resource_id": 8174,
"resource_state": "visible",
"resource_type": "download",
"review_count": 0,
"tag_line": "Jake made a ship (yay!)",
"tags": [
"civilian",
"runabout",
"trident",
"trident foundries",
"trident industries"
],
"title": "TRV Mercury-class Runabout",
"update_count": 1,
"User": {
"avatar_urls": {
"o": "https://starmadedock.net/data/avatars/o/299/299820.jpg?1545690345",
"h": "https://starmadedock.net/data/avatars/h/299/299820.jpg?1545690345",
"l": "https://starmadedock.net/data/avatars/l/299/299820.jpg?1545690345",
"m": "https://starmadedock.net/data/avatars/m/299/299820.jpg?1545690345",
"s": "https://starmadedock.net/data/avatars/s/299/299820.jpg?1545690345"
},
"can_ban": false,
"can_converse": false,
"can_edit": false,
"can_follow": false,
"can_ignore": false,
"can_post_profile": false,
"can_view_profile": false,
"can_view_profile_posts": false,
"can_warn": false,
"is_staff": false,
"last_activity": 1604145418,
"location": "London",
"message_count": 830,
"reaction_score": 1311,
"register_date": 1380710922,
"signature": "[CENTER][URL='https://starmadedock.net/threads/the-union-of-intergalactic-states.27014/'][IMG]https://i.imgur.com/WZKEgrf.png[/IMG][/URL]\n[IMG]https://i.imgur.com/tM49oai.png[/IMG] \n[FONT=Arial][SIZE=5][COLOR=#4da6ff][B][URL='http://trident-industries.wikia.com/wiki/Trident_Foundries_Database']The Trident Wiki - Faction and Ship Database[/URL][/B][/COLOR][/SIZE][/FONT][/CENTER]",
"trophy_points": 2050,
"user_id": 299820,
"user_title": "Official Source of Blame",
"username": "Jake_Lancia"
},
"user_id": 299820,
"username": "Jake_Lancia",
"version": "V1b",
"view_count": 142
}GET resources/{id}/reviews - Gets all a resource's reviewsGET resources/{id}/updates - Gets all update posts
JSON:
{
"versions": [
{
"can_download": true,
"can_hard_delete": false,
"can_soft_delete": false,
"download_count": 1,
"files": [
{
"id": 57675,
"filename": "TRV Mercury Runabout V1b.sment",
"size": 19131,
"download_url": "https://starmadedock.net/api/resource-versions/11017/download?file=57675"
}
],
"rating_avg": 0,
"rating_count": 0,
"release_date": 1604094328,
"resource_id": 8174,
"resource_version_id": 11017,
"version_state": "visible",
"version_string": "V1b"
},
{
"can_download": true,
"can_hard_delete": false,
"can_soft_delete": false,
"download_count": 7,
"files": [
{
"id": 57629,
"filename": "TRV Mercury Runabout V1a.sment",
"size": 19078,
"download_url": "https://starmadedock.net/api/resource-versions/11010/download?file=57629"
}
],
"rating_avg": 0,
"rating_count": 0,
"release_date": 1603916378,
"resource_id": 8174,
"resource_version_id": 11010,
"version_state": "visible",
"version_string": "V1.0"
}
]GET resources/{id}/versions
JSON:
{
"versions": [
{
"can_download": true,
"can_hard_delete": false,
"can_soft_delete": false,
"download_count": 1,
"files": [
{
"id": 57675,
"filename": "TRV Mercury Runabout V1b.sment",
"size": 19131,
"download_url": "https://starmadedock.net/api/resource-versions/11017/download?file=57675"
}
],
"rating_avg": 0,
"rating_count": 0,
"release_date": 1604094328,
"resource_id": 8174,
"resource_version_id": 11017,
"version_state": "visible",
"version_string": "V1b"
},
{
"can_download": true,
"can_hard_delete": false,
"can_soft_delete": false,
"download_count": 7,
"files": [
{
"id": 57629,
"filename": "TRV Mercury Runabout V1a.sment",
"size": 19078,
"download_url": "https://starmadedock.net/api/resource-versions/11010/download?file=57629"
}
],
"rating_avg": 0,
"rating_count": 0,
"release_date": 1603916378,
"resource_id": 8174,
"resource_version_id": 11010,
"version_state": "visible",
"version_string": "V1.0"
}
]GET resource-categories/ - Lists all resource categories.
JSON:
{
"categories": [
{
"allow_commercial_external": false,
"allow_external": true,
"allow_fileless": false,
"allow_local": true,
"can_add": false,
"can_upload_images": false,
"description": "",
"display_order": 1,
"enable_support_url": true,
"enable_versioning": true,
"last_resource_id": 8174,
"last_resource_title": "TRV Mercury-class Runabout",
"last_update": 1604094328,
"min_tags": 0,
"parent_category_id": 0,
"resource_category_id": 2,
"resource_count": 5741,
"title": "Ships"
},
]GET resource-categories/{id}/ - Further information about a specific resource category.
JSON:
{
"category": {
"allow_commercial_external": false,
"allow_external": true,
"allow_fileless": false,
"allow_local": true,
"can_add": false,
"can_upload_images": false,
"custom_fields": [
{
"description": "Enter the game version the resource is for.",
"display_group": "above_info",
"display_order": 1,
"field_id": "Gameversion",
"field_type": "textbox",
"match_params": {},
"match_type": "none",
"max_length": 0,
"required": true,
"title": "Game version"
}
],
"description": "",
"display_order": 1,
"enable_support_url": true,
"enable_versioning": true,
"last_resource_id": 8174,
"last_resource_title": "TRV Mercury-class Runabout",
"last_update": 1604094328,
"min_tags": 0,
"parent_category_id": 0,
"prefixes": [],
"resource_category_id": 2,
"resource_count": 5741,
"title": "Ships"
}GET resource-categories/{id}/resources - Gets all resources in the specified category.Only available through cached API: https://starmadedock.net/cached-api/resource-categories/{id}.json (add .gz at end for gzip)
GET resource-reviews/ - Gets all latest reviews for all resources.GET resource-reviews/{id}/ - Gets all reviews for a resource .GET resource-updates/{id}/
JSON:
{
"update": {
"attach_count": 0,
"can_edit": false,
"can_hard_delete": false,
"can_react": false,
"can_soft_delete": false,
"can_view_attachments": true,
"message": "The right missiles were not entirely connected, so I just fixed that.\n\n\n[URL='https://starmadedock.net/content/force-class-a-strike-craft-\u2013-picard.5782/'][B][U]Original Post[/U][/B][/URL]",
"message_state": "visible",
"post_date": 1475727934,
"reaction_score": 0,
"Resource": {
"alt_support_url": "",
"can_download": true,
"can_edit": false,
"can_edit_icon": false,
"can_edit_tags": false,
"can_hard_delete": false,
"can_soft_delete": false,
"can_view_description_attachments": true,
"Category": {
"allow_commercial_external": false,
"allow_external": true,
"allow_fileless": false,
"allow_local": true,
"can_add": false,
"can_upload_images": false,
"description": "",
"display_order": 1,
"enable_support_url": true,
"enable_versioning": true,
"last_resource_id": 8174,
"last_resource_title": "TRV Mercury-class Runabout",
"last_update": 1604094328,
"min_tags": 0,
"parent_category_id": 0,
"resource_category_id": 2,
"resource_count": 5741,
"title": "Ships"
},
"currency": "",
"custom_fields": {},
"download_count": 204,
"external_url": "",
"icon_url": "https://starmadedock.net/data/resource_icons/5/5782.jpg?1480377675",
"last_update": 1475727934,
"prefix_id": 0,
"price": "0.00",
"rating_avg": 0,
"rating_count": 0,
"rating_weighted": 3,
"resource_category_id": 2,
"resource_date": 1475723850,
"resource_id": 5782,
"resource_state": "visible",
"resource_type": "download",
"tag_line": "mid-size fighter of FORCE",
"tags": [
"ezra",
"fighter",
"force",
"ship",
"ship blueprint",
"strike"
],
"title": "FORCE Class A Strike Craft \u2013 Picard",
"User": {
"avatar_urls": {
"o": "https://starmadedock.net/data/avatars/o/676/676065.jpg?1475730216",
"h": "https://starmadedock.net/data/avatars/h/676/676065.jpg?1475730216",
"l": "https://starmadedock.net/data/avatars/l/676/676065.jpg?1475730216",
"m": "https://starmadedock.net/data/avatars/m/676/676065.jpg?1475730216",
"s": "https://starmadedock.net/data/avatars/s/676/676065.jpg?1475730216"
},
"can_ban": false,
"can_converse": false,
"can_edit": false,
"can_follow": false,
"can_ignore": false,
"can_post_profile": false,
"can_view_profile": true,
"can_view_profile_posts": true,
"can_warn": false,
"custom_fields": {
"gender": "male",
"occupation": "CLASSIFIED",
"discord": null,
"jabber": null,
"aim": null,
"icq": null,
"yahoo": null,
"skype": null,
"gtalk": null,
"facebook": null,
"twitter": null
},
"is_staff": false,
"last_activity": 1589434986,
"location": "New Jersey",
"message_count": 2,
"reaction_score": 9,
"register_date": 1468620713,
"signature": "",
"trophy_points": 450,
"user_id": 676065,
"user_title": "",
"username": "Investigator 7",
"website": ""
},
"user_id": 676065,
"username": "Investigator 7",
"version": "1.01",
"view_count": 106
},
"resource_id": 5782,
"resource_update_id": 8174,
"title": "Missile systems fixed",
"warning_message": ""
}GET resource-versions/{id}/ - Get information about a specific version of a resource. You must put in the version_id, which is separate from resource_id. Can be used to find out what version is compatible with a StarMade version.
JSON:
{
"version": {
"can_download": true,
"can_hard_delete": false,
"can_soft_delete": false,
"download_count": 7,
"files": [
{
"id": 57629,
"filename": "TRV Mercury Runabout V1a.sment",
"size": 19078,
"download_url": "https://starmadedock.net/api/resource-versions/11010/download?file=57629"
}
],
"rating_avg": 0,
"rating_count": 0,
"release_date": 1603916378,
"Resource": {
"alt_support_url": "",
"can_download": true,
"can_edit": false,
"can_edit_icon": false,
"can_edit_tags": false,
"can_hard_delete": false,
"can_soft_delete": false,
"can_view_description_attachments": true,
"Category": {
"allow_commercial_external": false,
"allow_external": true,
"allow_fileless": false,
"allow_local": true,
"can_add": false,
"can_upload_images": false,
"description": "",
"display_order": 1,
"enable_support_url": true,
"enable_versioning": true,
"last_resource_id": 8174,
"last_resource_title": "TRV Mercury-class Runabout",
"last_update": 1604094328,
"min_tags": 0,
"parent_category_id": 0,
"resource_category_id": 2,
"resource_count": 5741,
"title": "Ships"
},
"currency": "",
"custom_fields": {
"Gameversion": "0.202.87"
},
"download_count": 8,
"external_url": "",
"icon_url": "https://starmadedock.net/data/resource_icons/8/8174.jpg?1603916378",
"last_update": 1604094328,
"prefix_id": 0,
"price": "0.00",
"rating_avg": 0,
"rating_count": 0,
"rating_weighted": 3,
"resource_category_id": 2,
"resource_date": 1603916378,
"resource_id": 8174,
"resource_state": "visible",
"resource_type": "download",
"tag_line": "Jake made a ship (yay!)",
"tags": [
"civilian",
"runabout",
"trident",
"trident foundries",
"trident industries"
],
"title": "TRV Mercury-class Runabout",
"User": {
"avatar_urls": {
"o": "https://starmadedock.net/data/avatars/o/299/299820.jpg?1545690345",
"h": "https://starmadedock.net/data/avatars/h/299/299820.jpg?1545690345",
"l": "https://starmadedock.net/data/avatars/l/299/299820.jpg?1545690345",
"m": "https://starmadedock.net/data/avatars/m/299/299820.jpg?1545690345",
"s": "https://starmadedock.net/data/avatars/s/299/299820.jpg?1545690345"
},
"can_ban": false,
"can_converse": false,
"can_edit": false,
"can_follow": false,
"can_ignore": false,
"can_post_profile": false,
"can_view_profile": false,
"can_view_profile_posts": false,
"can_warn": false,
"is_staff": false,
"last_activity": 1604145418,
"location": "London",
"message_count": 830,
"reaction_score": 1311,
"register_date": 1380710922,
"signature": "[CENTER][URL='https://starmadedock.net/threads/the-union-of-intergalactic-states.27014/'][IMG]https://i.imgur.com/WZKEgrf.png[/IMG][/URL]\n[IMG]https://i.imgur.com/tM49oai.png[/IMG] \n[FONT=Arial][SIZE=5][COLOR=#4da6ff][B][URL='http://trident-industries.wikia.com/wiki/Trident_Foundries_Database']The Trident Wiki - Faction and Ship Database[/URL][/B][/COLOR][/SIZE][/FONT][/CENTER]",
"trophy_points": 2050,
"user_id": 299820,
"user_title": "Official Source of Blame",
"username": "Jake_Lancia"
},
"user_id": 299820,
"username": "Jake_Lancia",
"version": "V1b",
"view_count": 142
},
"resource_id": 8174,
"resource_version_id": 11010,
"version_state": "visible",
"version_string": "V1.0"
}GET resource-versions/{id}/download - Downloads a specific version of a resource. Must use version_id instead of resource_id.Required parameters: file (available in GET resource-versions/{id}/)
Example:
Example:
Finding a version of a mod that's compatible with the client's StarMade version.
GET resources/{resource_id}/versions - Get all versions of a resourceGET resource-versions/{version_id}/ - Go through all versions to find their compatible Gameversion and their file id for download.GET resource-versions/{version_id}/download?file={file_id} - Download compatible resource version.Convoluted, but unfortunately the API isn't really designed for this.
Error handling
When an error is encountered, the response code will be in the 400 range. Occasionally, a 500-range error may occur, though this indicates that the server was unable to process the request. The API may be temporarily disabled or another server error has occurred.
Error messages have a standardized format. Here is an example:
The top level will be an object with an errors key. This will be an array with 1 or more entries. Each entry is an object with the following parameters:
Error messages have a standardized format. Here is an example:
Code:
{
"errors": [
{
"code": "api_key_not_found",
"message": "API key provided in request was not found.",
"params": []
}
]
}- code - this is a machine readable code for the error. There are many possible error codes as they are situation dependent.
- message - a human readable version of the error. This may change or may be translated and should not be used to identify the type of error.
- params - this is a list of key-value parameters that are relevant to the error triggered. They may supplement the error code and message to give more specific details about the error.
Code example
This example has no error handling, make sure you do!
Python:
import requests
headers = {
'Content-type' : 'application/x-www-form-urlencoded',
'XF-Api-Key' : '{API_KEY}'
}
url = 'https://starmadedock.net/api/resources/'
r = requests.get(url,headers=headers)
data = r.json()
print(data)