Skip to content

Mars API

Jump to bottom
Velo4 edited this page Aug 27, 2024 · 29 revisions

Mars API

Mars will strictly return a 404 status code when no data is found, instead of:

  • backend: HTTP Status: 200, Body: {"status": 404}
  • frontend: 😅

Error Schema

{
    "error": "string"
}

Result Schema

{
    "result": "string"
}

Public API

The public API is basically the same as api.papermc.io, except that some behaviors may be different.

The public API does not require authentication.

index-controller

[Any] /

Before v1.3.0

{
    "server": "Tranic Mars",
    "github": "https://github.com/LevelTranic/Mars",
    "docs": "https://github.com/LevelTranic/Mars/wiki/Mars-API",
    "platform": "windows/amd64"
}

v1.3.0

{
    "server": "Tranic Mars",
    "github": "https://github.com/LevelTranic/Mars",
    "docs": "https://github.com/LevelTranic/Mars/wiki/Mars-API",
    "platform": "windows/amd64",
    "version": {
        "core": "v1.3.0",
        "private_api": "v1.1.0",
        "public_api": "v1.3.0",
        "database": "v1.2.0"
    }
}

projects-controller

[GET] /v2/projects

{
    "projects": [
        "string"
    ]
}

project-controller

[GET] /v2/projects/{project}

{
  "project_id": "paper",
  "project_name": "Paper",
  "version_groups": [
    "string"
  ],
  "versions": [
    "string"
  ]
}

version-controller

[GET] /v2/projects/{project}/versions/{version}/builds

[GET] /v2/projects/{project}/versions/{version}/builds?channel={channel} (in v1.4.0)

{
    "project_id": "levelbukkit",
    "project_name": "levelbukkit",
    "version": "1.20.6",
    "builds": [
        {
            "build": 1,
            "time": "2024-07-03T15:06:54Z",
            "channel": "default",
            "promoted": false,
            "changes": {
                "commit": "string",
                "summary": "string",
                "message": "string"
            },
            "downloads": {
                "bundler": {
                    "name": "levelbukkit-bundler-1.20.6-R0.1-SNAPSHOT-mojmap.jar",
                    "sha256": "14f78ffd94d596ed33f7f92f391f9e18a571885f5a22329cbdebcbef5418cfd1"
                },
                "paperclip": {
                    "name": "levelbukkit-paperclip-1.20.6-R0.1-SNAPSHOT-mojmap.jar",
                    "sha256": "958274a3add23b5599e6426f63c0bde77718619f77f46645c2b6b0a646724cf6"
                }
            }
        },
        {
            "build": 2,
            "time": "2024-07-03T20:20:27Z",
            "channel": "default",
            "promoted": false,
            "changes": null,
            "downloads": null
        }
    ]
}

version-build-controller

v1.4.2

Starting from this version, {build} can be latest

Before v1.4.2

[GET] /v2/projects/{project}/versions/{version}/builds/{build}

{
    "project_id": "levelbukkit",
    "project_name": "levelbukkit",
    "channel": "default",
    "version": "1.20.6",
    "build": 1,
    "promoted": false,
    "time": "2024-07-03T15:06:54Z",
    "changes": {
        "commit": "string",
        "summary": "string",
        "message": "string"
    },
    "downloads": {
        "bundler": {
            "name": "levelbukkit-bundler-1.20.6-R0.1-SNAPSHOT-mojmap.jar",
            "sha256": "14f78ffd94d596ed33f7f92f391f9e18a571885f5a22329cbdebcbef5418cfd1"
        },
        "paperclip": {
            "name": "levelbukkit-paperclip-1.20.6-R0.1-SNAPSHOT-mojmap.jar",
            "sha256": "958274a3add23b5599e6426f63c0bde77718619f77f46645c2b6b0a646724cf6"
        }
    }
}

download-controller

Both APIs are available

v1.0.0

[GET] /v2/projects/{project}/versions/{version}/builds/{build}/downloads

v1.1.0

[GET] /v2/projects/{project}/versions/{version}/builds/{build}/downloads/{downloadID}

v1.4.2

Starting from this version, {build} can be latest

version-family-controller

Before v1.3.0

not support

v1.3.0

[GET] /v2/projects/{project}/version_group/{family}

Result:

{
    "project_id": "levelbukkit",
    "project_name": "levelbukkit",
    "version_group": "1.20",
    "versions": [
        "1.20.4",
        "1.20.5",
        "1.20.6"
    ]
}

version-family-builds-controller

Before v1.4.0

not support

v1.4.0

[GET] /v2/projects/{project}/version_group/{family}/builds

Result:

{
    "project_id": "paper",
    "project_name": "Paper",
    "version_group": "1.20",
    "versions": [
        "1.20",
        "1.20.1",
        "1.20.2",
        "1.20.4",
        "1.20.5",
        "1.20.6"
    ],
    "builds": [
        {
            "version": "1.20",
            "build": 1,
            "time": "2023-06-09T13:49:34.001Z",
            "channel": "experimental",
            "promoted": false,
            "changes": [
                {
                    "commit": "648c000fb2330ca1f9b7833a275e70f06c1fce83",
                    "summary": "Add pitcher plant api (#9286)",
                    "message": "Add pitcher plant api (#9286)\n\n"
                }
            ],
            "downloads": {
                "application": {
                    "name": "paper-1.20-1.jar",
                    "sha256": "40c819d14f2ec30d0acb68dbab88294947fe53f0c2f0371464af5328dda7ed85"
                },
                "mojang-mappings": {
                    "name": "paper-mojmap-1.20-1.jar",
                    "sha256": "96b471b28d1fb626855365cb9a3d5ce9592d26597564d3a41f7cb343238714a5"
                }
            }
        },
        {
            "version": "1.20",
            "build": 2,
            "time": "2023-06-09T18:39:18.118Z",
            "channel": "experimental",
            "promoted": false,
            "changes": [
                {
                    "commit": "0284b272d323cd056816b2e34d7e7dad53e70b84",
                    "summary": "Add API for waxed signs (#9291)",
                    "message": "Add API for waxed signs (#9291)\n\n"
                }
            ],
            "downloads": {
                "application": {
                    "name": "paper-1.20-2.jar",
                    "sha256": "f6745fce5027db7b090ee8f329a53b6231165f144345a3bfe50d593e2cd6632c"
                },
                "mojang-mappings": {
                    "name": "paper-mojmap-1.20-2.jar",
                    "sha256": "63910fdfc03aed545fb6d27c8cd6c68f9facad273d0ffd417b5789b49a49eb6b"
                }
            }
        },
        {
            "version": "1.20",
            "build": 3,
            "time": "2023-06-09T18:57:16.500Z",
            "channel": "experimental",
            "promoted": false,
            "changes": [
                {
                    "commit": "dc30ee591d52a55ac1f6dfce6e731a583cc21fad",
                    "summary": "Properly remove the experimental smithing inventory type (#9290)",
                    "message": "Properly remove the experimental smithing inventory type (#9290)\n\n"
                }
            ],
            "downloads": {
                "application": {
                    "name": "paper-1.20-3.jar",
                    "sha256": "12564fc8f5dedf8fc7a1991b145f14f312fdf8917d39d7801321214180b07595"
                },
                "mojang-mappings": {
                    "name": "paper-mojmap-1.20-3.jar",
                    "sha256": "3a6d5aea0429646a1c445764cea5b368b3e2416b9153cabca1252df54fa25cb4"
                }
            }
        },
        {
            "version": "1.20",
            "build": 4,
            "time": "2023-06-10T06:20:43.750Z",
            "channel": "experimental",
            "promoted": false,
            "changes": [
                {
                    "commit": "2ffb704efaf9811b9da286011e9c4b8f682620a9",
                    "summary": "Don't use event to get block position (#9295)",
                    "message": "Don't use event to get block position (#9295)\n\n"
                }
            ],
            "downloads": {
                "application": {
                    "name": "paper-1.20-4.jar",
                    "sha256": "2e47fb7948b5691e797ece80ade52d982164da14283488ea442c869ea4522e28"
                },
                "mojang-mappings": {
                    "name": "paper-mojmap-1.20-4.jar",
                    "sha256": "267e63022162b0591675757e6995939f9382550f9f85b37e4d0ce523e5a7111d"
                }
            }
        },
        {
            "version": "1.20",
            "build": 5,
            "time": "2023-06-10T15:40:20.694Z",
            "channel": "experimental",
            "promoted": false,
            "changes": [
                {
                    "commit": "3d06377b24681c64301bffc3f81816166c6a8688",
                    "summary": "Allow double removal from player chunk loader",
                    "message": "Allow double removal from player chunk loader\n\nUnlike Folia, players may be incorrectly be double-removed\n\nFixes https://github.com/PaperMC/Paper/issues/9299\n"
                }
            ],
            "downloads": {
                "application": {
                    "name": "paper-1.20-5.jar",
                    "sha256": "1dbf71c8950fe07e3bd8eed979be2ac24e483220a74c81ff16df04ef35808b9d"
                },
                "mojang-mappings": {
                    "name": "paper-mojmap-1.20-5.jar",
                    "sha256": "e02fedc6b1f6ab7e83287871d90686e2961c728499d88f5b2bdf99b9c3fbc66f"
                }
            }
        },
        {
            "version": "1.20",
            "build": 6,
            "time": "2023-06-10T20:53:47.282Z",
            "channel": "experimental",
            "promoted": false,
            "changes": [
                {
                    "commit": "bc3496ea58f8f66c8d0af8ceff317d28f18ab0f6",
                    "summary": "Fix incorrect collision shape for hopper item suck",
                    "message": "Fix incorrect collision shape for hopper item suck\n\nIt shouldn't cost too much more to check the correct shape,\nprovided that it is cached and we use the overall AABB\nto collect possible entities to check against.\n\nThe issues with the old check code is that it will use two\ngetEntitiesOfClass calls plus the addition of streams\n_and_ the toAabbs() logic on VoxelShape. The new code\ncaches toAabbs, uses one getEntitiesOfClass call, and\ndoes not use streams. Then compared to 1.12, we are\nonly performing two additional AABB checks per item.\n"
                }
            ],
            "downloads": {
                "application": {
                    "name": "paper-1.20-6.jar",
                    "sha256": "76034cd97e0e7c46828b3d081ec993d40dc8e2ad4873f5782edb2c4471159dab"
                },
                "mojang-mappings": {
                    "name": "paper-mojmap-1.20-6.jar",
                    "sha256": "1324ab417e884ac10c2e581ba75adae7014e552172a0f295e2899400c6d504f7"
                }
            }
        },
        {
            "version": "1.20",
            "build": 7,
            "time": "2023-06-11T01:07:05.139Z",
            "channel": "experimental",
            "promoted": false,
            "changes": [
                {
                    "commit": "e2e874f5491b76606b50e319d0bdfbb17fb80466",
                    "summary": "Add back the source uuid on exp orb for animals breeding (#9289)",
                    "message": "Add back the source uuid on exp orb for animals breeding (#9289)\n\n"
                }
            ],
            "downloads": {
                "application": {
                    "name": "paper-1.20-7.jar",
                    "sha256": "076db51432956d4e43467dce1287010c8121eefdb37e66f2dd24eaf9b2ba2356"
                },
                "mojang-mappings": {
                    "name": "paper-mojmap-1.20-7.jar",
                    "sha256": "0d0ec0b9807381fb7b70b481dc95886090d1ad010d89775466e72cdb65d9bec3"
                }
            }
        },
        {
            "version": "1.20",
            "build": 8,
            "time": "2023-06-11T01:22:25.336Z",
            "channel": "experimental",
            "promoted": false,
            "changes": [
                {
                    "commit": "3722877c3c16e4e88c45a5133ec7a0e9efdd1f92",
                    "summary": "correctly hide players from entity argument suggestions (#9245)",
                    "message": "correctly hide players from entity argument suggestions (#9245)\n\n"
                }
            ],
            "downloads": {
                "application": {
                    "name": "paper-1.20-8.jar",
                    "sha256": "9e019026fd1967d28a28f29a3a347eae37bb73e90c01d40d0df4718225aa9ec8"
                },
                "mojang-mappings": {
                    "name": "paper-mojmap-1.20-8.jar",
                    "sha256": "10f71a8df64fa50fd9ed9e3bf784cc92b0a373a4a9f8ed5b69602660d49352e9"
                }
            }
        },
        {
            "version": "1.20",
            "build": 9,
            "time": "2023-06-11T18:01:50.511Z",
            "channel": "default",
            "promoted": false,
            "changes": [],
            "downloads": {
                "application": {
                    "name": "paper-1.20-9.jar",
                    "sha256": "8097db849928bf963b9ec85d5b07e2f43289ad16c8db3e04938145dba6851a71"
                },
                "mojang-mappings": {
                    "name": "paper-mojmap-1.20-9.jar",
                    "sha256": "d4c952b6b0366703137b64166f0529c4e86782b6884601e17d631edf7fa9fa0a"
                }
            }
        }
    ]
}

Private API

Authenticate

Authentication is performed by carrying the mars_token field in the cookie.

Create Project

[POST] /v2/new/project

Schema:

{
    "project_id": "string"
}

Create Version Family/Group

[POST] /v2/new/version_family

Schema:

{
    "name": "string",
    "project": "string"
}

Create Version

[POST] /v2/new/version

Schema:

{
    "version": "string",
    "group": "string",
    "project": "string"
}

Create Build

[POST] /v2/new/build

Schema:

{
    "project": "string",
    "version": "string",
    "family": "string",
    "channel": "string",
    "promoted": "bool",
    "changes": [
        {
            "commit": "string",
            "summary": "string",
            "message": "string"
        }
    ] <- omitempty
}

Result:

{
    "project": "string",
    "version": "string",
    "family": "string",
    "build_id": "int"
}

Create Download (external link) [v1.3.0+]

[POST] /v2/new/external_download

This API and Create Download coexist

v1.4.0

Post Params

  • project: string
  • version: string
  • build: int
  • file: map[string]NewDownloadFileSchema

When Name and SHA256 are empty, and the sniffing is turned on, they will try to sniff the file name and SHA256 from the URL

NewDownloadFileSchema

{
    "name": "string", <- omitempty
    "sha256": "string", <- omitempty
    "url": "string"
}

Schema

{
    "project":"vine",
    "version": "1.20.6",
    "build": 1,
    "file": {
        "tranic": {
             "url": "https://github.com/LevelTranic"
         },
        "404": {
            "name": "vine-server.jar",
            "url": "https://github.com/404Setp"
        }
    }
}

v1.3.0

Post Params

  • project: string
  • version: string
  • build: int
  • file: map[string]string

Schema Example:

{
    "project":"vine",
    "version": "1.20.6",
    "build": 1,
    "file": {
        "tranic": "https://github.com/LevelTranic",
        "404": "https://github.com/404Setp"
    }
}

Create Download

Params [With Query]

  • project: string
  • version: string
  • filename: string [Deprecated in v1.1.0]
  • build: int

v1.0.0

[POST] /v2/new/download?project=string&version=string&build=int&filename=string

File: application=@file.jar

example:

curl -X POST -F 'application=@levelbukkit-paperclip-1.20.6-R0.1-SNAPSHOT-mojmap.jar' -b 'mars_token=****************' 'http://127.0.0.1:7743/v2/new/download?project=levelbukkit&version=1.20.6&build=1&filename=levelbukkit-paperclip-1.20.6-R0.1-SNAPSHOT-mojmap.jar'

v1.1.0

[POST] /v2/new/download?project=string&version=string&build=int

Changes

  • Deprecated filename query parameter
  • Support uploading multiple files at the same time
  • In the same build, if the file hash is different, it is appended to the existing downloads
  • The file header is no longer required to be application

File: application1=@file.jar, application2=@file2.jar, application3=@file3.jar

example:

curl -X POST -F 'paperclip=@levelbukkit-paperclip-1.20.6-R0.1-SNAPSHOT-mojmap.jar' -F 'bundler=@levelbukkit-bundler-1.20.6-R0.1-SNAPSHOT-mojmap.jar' -b 'mars_token=****************' 'http://127.0.0.1:7743/v2/new/download?project=levelbukkit&version=1.20.6&build=1'
Clone this wiki locally