API сайта загрузок

API сайта загрузок позволяет получать список доступных проектов и сборок, фильтровать версии, искать конкретную сборку по метаданным и получать прямые ссылки для скачивания.

Базовый URL текущей версии API:


https://dl.lumi.su/api/v1

API не требует авторизации. Все ответы возвращаются в формате JSON, а GET-запросы поддерживают CORS.

Проверка доступности


GET /api/v1/health

Пример запроса:


curl https://dl.lumi.su/api/v1/health

Ответ:


{
  "status": "ok",
  "version": "v1"
}

Проекты

Получение всех проектов


GET /api/v1/projects

Эндпоинт возвращает массив всех проектов, доступных на сайте загрузок.


curl https://dl.lumi.su/api/v1/projects

Пример ответа:


[
  {
    "id": "lumi",
    "name": "Lumi",
    "description": "Minecraft Bedrock server software",
    "domains": [
      "dl.lumi.su"
    ],
    "branches": [
      {
        "id": "stable",
        "labelKey": "branches.stable",
        "showInAllBranches": true
      },
      {
        "id": "dev",
        "labelKey": "branches.dev",
        "showInAllBranches": true
      }
    ],
    "providers": [
      {
        "id": "stable-releases",
        "label": "Stable / Releases",
        "branch": "stable",
        "branchLabelKey": "branches.stable"
      }
    ],
    "links": {
      "self": "https://dl.lumi.su/api/v1/projects/lumi",
      "versions": "https://dl.lumi.su/api/v1/projects/lumi/versions",
      "website": "https://dl.lumi.su/project/lumi"
    }
  }
]

Получение проекта


GET /api/v1/projects/{projectId}

Параметр projectId соответствует полю id из списка проектов.


curl https://dl.lumi.su/api/v1/projects/lumi

Если проект не существует, API вернёт статус 404:


{
  "message": "Project not found"
}

Версии проекта


GET /api/v1/projects/{projectId}/versions

Без параметров эндпоинт возвращает все отображаемые сборки проекта. Сборки отсортированы от новых к старым.


curl https://dl.lumi.su/api/v1/projects/lumi/versions

Фильтры

Параметр	Описание
`branches`	Одна или несколько веток
`versions`	Одна или несколько серий версий, например `1.6`
`limit`	Максимальное количество результатов от `1` до `1000`

Несколько значений можно передать через запятую:


GET /api/v1/projects/lumi/versions?branches=stable,dev&versions=1.5,1.6

Или повторить параметр:


GET /api/v1/projects/lumi/versions?branches=stable&branches=dev

Чтобы получить последнюю сборку выбранной ветки:


GET /api/v1/projects/lumi/versions?branches=dev&limit=1

Если параметр branches отсутствует, API скрывает сборки провайдеров, у которых отключено отображение в списке всех веток. Чтобы получить такие сборки, укажите нужную ветку явно.

Формат версии

Эндпоинт возвращает массив объектов следующего вида:


[
  {
    "id": "dev-snapshots:1.6.4-SNAPSHOT:Lumi-1.6.4-20260720.124024-6.jar",
    "version": "1.6.4-20260720.124024-6",
    "logicalVersion": "1.6.4-SNAPSHOT",
    "series": "1.6",
    "fileName": "Lumi-1.6.4-20260720.124024-6.jar",
    "modifiedAt": "2026-07-20T12:41:19.813Z",
    "branch": {
      "id": "dev",
      "labelKey": "branches.dev"
    },
    "provider": {
      "id": "dev-snapshots",
      "label": "Dev / Snapshots"
    },
    "source": {
      "text": "refactor: armor trim api",
      "url": "https://github.com/KoshakMineDEV/Lumi/commit/50c58758981f7a890d39f22b3aba073586ea02c8"
    },
    "downloadUrl": "https://dl.lumi.su/download/lumi/dev/Lumi-1.6.4-20260720.124024-6.jar",
    "directDownloadUrl": "https://repo.lumi.su/snapshots/com/koshakmine/Lumi/1.6.4-SNAPSHOT/Lumi-1.6.4-20260720.124024-6.jar",
    "checksumUrl": "https://repo.lumi.su/snapshots/com/koshakmine/Lumi/1.6.4-SNAPSHOT/Lumi-1.6.4-20260720.124024-6.jar.sha1",
    "properties": {
      "git.branch": "dev",
      "git.commit.id": "50c58758981f7a890d39f22b3aba073586ea02c8",
      "git.commit.message.short": "refactor: armor trim api",
      "github.repo": "KoshakMineDev/Lumi"
    }
  }
]

Поле	Тип	Описание
`id`	`string`	Уникальный идентификатор записи
`version`	`string`	Фактическая версия файла
`logicalVersion`	`string`	Версия артефакта у провайдера
`series`	`string`	Серия версии, например `1.6`
`fileName`	`string`	Название загружаемого файла
`modifiedAt`	`string \| null`	Время изменения в формате ISO 8601
`branch`	`object`	Ветка сборки и ключ её локализации
`provider`	`object`	Провайдер, предоставивший сборку
`source`	`object \| null`	Ссылка на исходный код и его описание
`downloadUrl`	`string`	Ссылка для скачивания через сайт
`directDownloadUrl`	`string`	Прямая ссылка на файл у провайдера
`checksumUrl`	`string \| null`	Ссылка на контрольную сумму
`properties`	`object \| null`	Метаданные сборки, предоставленные провайдером

Содержимое properties зависит от провайдера. Наличие конкретного ключа, например git.commit.id, не гарантируется для всех проектов и сборок.

Поиск конкретной версии


GET /api/v1/projects/{projectId}/versions/lookup

Lookup используется, когда нужно найти ровно одну сборку по её полям или метаданным. Поиск выполняется по точному и регистрозависимому совпадению.

Параметр branch и минимум один дополнительный фильтр обязательны:


GET /api/v1/projects/lumi/versions/lookup?branch=dev&properties.git.commit.id=50c58758981f7a890d39f22b3aba073586ea02c8

Доступные поля

Можно искать по следующим полям версии:


branch
branchLabel
checksumUrl
downloadUrl
fileName
id
logicalVersion
modifiedAt
providerId
providerLabel
series
showInAllBranches
sourceText
sourceUrl
version

Названия фильтров соответствуют внутренним полям VersionEntry. Поэтому downloadUrl в lookup соответствует полю directDownloadUrl в публичном ответе, providerId — provider.id, providerLabel — provider.label, branchLabel — branch.labelKey, а sourceText и sourceUrl — полям объекта source. Для modifiedAt можно передать ISO 8601 или исходный числовой timestamp провайдера.

Для поиска по метаданным используйте формат properties.{ключ}:


GET /api/v1/projects/lumi/versions/lookup?branch=dev&properties.git.commit.id=50c58758981f7a890d39f22b3aba073586ea02c8

Точки внутри названия свойства являются частью ключа. Несколько фильтров объединяются через логическое AND:


GET /api/v1/projects/lumi/versions/lookup?branch=dev&providerId=dev-snapshots&series=1.6&properties.git.commit.id=50c58758981f7a890d39f22b3aba073586ea02c8

Результат поиска


{
  "version": {
    "fileName": "Lumi-1.6.4-20260720.124024-6.jar"
  },
  "position": {
    "index": 0,
    "newerCount": 0,
    "olderCount": 12,
    "total": 13
  },
  "neighbors": {
    "newer": null,
    "older": {
      "fileName": "Lumi-1.6.4-20260719.101500-5.jar"
    }
  }
}

index — позиция сборки в ветке, начиная с нуля;
newerCount — количество более новых сборок;
olderCount — количество более старых сборок;
total — общее количество сборок в ветке;
neighbors.newer — предыдущая, более новая сборка;
neighbors.older — следующая, более старая сборка.

Lookup должен находить ровно одну версию. Если фильтры подходят нескольким сборкам, API вернёт статус 409 и количество совпадений. Добавьте более точный фильтр, например properties.git.commit.id или fileName.

Пример неоднозначного результата:


{
  "matches": 13,
  "message": "More than one version matched the lookup filters"
}

Использование API

curl


curl "https://dl.lumi.su/api/v1/projects/lumi/versions?branches=dev&versions=1.6&limit=1"

JavaScript


const response = await fetch(
  'https://dl.lumi.su/api/v1/projects/lumi/versions?branches=dev&versions=1.6&limit=1'
)
 
if (!response.ok) {
  throw new Error(`API request failed: ${response.status}`)
}
 
const versions = await response.json()
console.log(versions[0])

Python


import requests
 
response = requests.get(
    "https://dl.lumi.su/api/v1/projects/lumi/versions",
    params={
        "branches": "dev",
        "versions": "1.6",
        "limit": 1,
    },
    timeout=30,
)
response.raise_for_status()
 
versions = response.json()
print(versions[0])

Ошибки

Статус	Значение
`400 Bad Request`	Переданы некорректные или неподдерживаемые параметры
`404 Not Found`	Проект, версия или эндпоинт не найдены
`409 Conflict`	Lookup нашёл больше одной версии
`500 Internal Server Error`	Не удалось обработать запрос или получить данные провайдера

Обычная ошибка:


{
  "message": "Version not found"
}

Ошибка валидации дополнительно содержит поле details:


{
  "details": {
    "formErrors": [],
    "fieldErrors": {
      "limit": [
        "Too small: expected number to be >=1"
      ]
    }
  },
  "message": "Invalid query parameters"
}