StarMade Dock API

    DukeofRealms

    Count Duku
    Joined
    Sep 4, 2013
    Messages
    1,472
    Reaction score
    1,594
    • Schine
    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:
    • 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

    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

    https://starmadedock.net/cached-api/resource-categories/{category_id}.json - output of GET resource-categories/{id}/resources

    https://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 resources
    Optional 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 reviews

    GET 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 resource
    GET 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:

    Code:
    {
        "errors": [
            {
    "code": "api_key_not_found",
    "message": "API key provided in request was not found.",
    "params": []
    }
    ]
    }
    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:

    • 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)