API tác giả danh mục

Mọi thao tác của tác giả với tài liệu trên site đều có thể thực hiện từ script hoặc build pipeline của bạn: tạo bản nháp, tải lên phiên bản mới, chỉnh sửa trang, thay đổi giá và xem doanh số. Để làm điều này, bạn cần khóa tác giả — một chuỗi dạng mca_live_….

Khóa chỉ hoạt động với tài liệu của bạn: những tài liệu mà bạn là tác giả. Bạn không thể đụng đến tác phẩm của người khác bằng khóa này, kể cả khi bạn biết địa chỉ của nó.

Khóa

Khóa được cấp trong hồ sơ của bạn, ở mục tác giả. Đặt tên cho khóa và chọn các scope; khóa chỉ được hiển thị một lần — hãy lưu nó vào secrets của pipeline. Nếu làm mất, hãy thu hồi và cấp khóa mới. Bạn có thể có tối đa mười khóa đang hoạt động. Thay đổi mật khẩu hoặc email sẽ thu hồi toàn bộ khóa của tài khoản — hãy cấp khóa mới sau đó.

Chỉ cấp cho pipeline những gì nó cần: khóa build thường đi kèm versions:write và stats:read.

Tất cả endpoint nằm dưới https://api.millida.net/v2; khóa được truyền trong header:

Authorization: Bearer mca_live_…

Tài liệu của tôi

GET /catalog/author-api/items

[
  {
    "slug": "my-pack",
    "type": "MODPACK",
    "title": "My modpack",
    "status": "PUBLISHED",
    "moderationStatus": "PUBLISHED",
    "pricing": "ONE_TIME",
    "priceKopecks": 49900,
    "versionsCount": 12,
    "downloads": 5310,
    "publicUrl": "/modpacks/my-pack"
  }
]

Tài liệu mới

POST /catalog/author-api/items
{ "type": "MOD", "title": "My mod", "summary": "Briefly about the mod" }

Tài liệu xuất hiện dưới dạng bản nháp. Địa chỉ (slug) được lấy từ tên; địa chỉ đã bị chiếm sẽ trả về 409 kèm gợi ý một địa chỉ còn trống. Giá khi tạo (pricing, priceKopecks) chỉ có thể được truyền bằng khóa có scope pricing:write; nếu không, phản hồi là 403 MISSING_SCOPE.

Phiên bản mới

1. URL tải lên:

POST /catalog/author-api/items/my-pack/upload-url
{ "version": "1.4.0", "fileName": "my-pack-1.4.0.zip", "size": 734003200 }

{ "uploadUrl": "https://…", "storageKey": "catalog/packs/my-pack/…", "expiresIn": 3600 }

2. Tải tệp lên bằng request PUT tới uploadUrl — trực tiếp đến storage, không qua chúng tôi:

curl -X PUT --upload-file my-pack-1.4.0.zip "$UPLOAD_URL"

3. Đăng ký phiên bản:

POST /catalog/author-api/items/my-pack/versions
{
  "version": "1.4.0",
  "storageKey": "catalog/packs/my-pack/…",
  "gameVersions": ["1.20.1"],
  "loaders": ["fabric"],
  "loaderVersion": "0.16.0",
  "changelog": "New quests"
}

Phiên bản sẽ vào duyệt tự động và hiển thị với người chơi sau đó. Mỗi lần tải lên là một tệp mới: bạn không thể ghi đè phiên bản đã phát hành.

Gửi để duyệt

Tài liệu mới chỉ vào catalog sau khi moderator duyệt. Khi tài liệu có ít nhất một phiên bản, hãy xác nhận rằng tác phẩm là của bạn và bạn đã chọn giấy phép. Đây là một request riêng: gửi để duyệt không tự động làm điều đó.

POST /catalog/author-api/items/my-pack/authorship

{ "ok": true }

Sau đó gửi tài liệu:

POST /catalog/author-api/items/my-pack/submit

{ "ok": true, "status": "PENDING" }

Nếu không xác nhận, phản hồi là 400 “Confirm that the modpack is yours and the license was chosen by you”; nếu không có phiên bản, 400 “Upload the modpack file first”.

Trang

PUT /catalog/author-api/items/my-pack/page
{ "title": "My modpack", "summary": "…", "descriptionMd": "## What's inside\n…" }

Đây là bản nháp: người chơi vẫn thấy trang trước đó cho đến khi trang mới vượt qua kiểm duyệt. Hình ảnh trong mô tả chỉ được tải lên cho chúng tôi; liên kết chỉ được trỏ đến các trang Millida. Hãy tải lên icon (iconUrl), ảnh chụp màn hình (gallery) và ảnh trong mô tả trước:

curl -H "Authorization: Bearer $MCA_KEY" -F "file=@icon.png" https://api.millida.net/v2/catalog/author-api/images

{ "url": "https://…/uploads/…/icon.png" }

Hỗ trợ PNG, JPG, WebP và AVIF tối đa 15 MB; không hỗ trợ GIF. Tải lên yêu cầu scope page:write; phản hồi chứa địa chỉ mà bạn có thể đặt vào trang. Gửi để duyệt:

POST /catalog/author-api/items/my-pack/page/submit

Giá

PUT /catalog/author-api/items/my-pack/pricing
{ "pricing": "ONE_TIME", "priceKopecks": 49900 }

• Số tiền tính bằng kopecks. Giá tối thiểu cho tài liệu trả phí là 300 ₽ (30000), với skin và áo choàng — 50 ₽ (5000); tối đa là 100.000 ₽ (10000000).
• Nền tảng lấy 30% từ mỗi giao dịch; phần còn lại vào ví Millida của bạn.
• Tiền từ một giao dịch có thể dùng ngay trong Millida, nhưng chỉ có thể rút sau 7 ngày kể từ khi mua.
• Chỉ những người có quyền truy cập mới tải được tệp của tài liệu trả phí. Với vai trò tác giả, bạn luôn có quyền truy cập.

Thống kê

GET /catalog/author-api/items/my-pack/stats

{
  "versions": [{ "version": "1.4.0", "downloads": 312, "reviewStatus": "APPROVED" }],
  "players": { "players": 1204, "playersRecent": 380, "days": [{ "day": "2026-09-24", "players": 41 }] },
  "sales": {
    "totalKopecks": 998000,
    "netKopecks": 698600,
    "count": 20,
    "refundedCount": 0,
    "holdDays": 7,
    "last30d": [{ "day": "2026-09-24", "count": 3, "netKopecks": 104790 }]
  }
}

Doanh số của tất cả tài liệu cùng lúc:

GET /catalog/author-api/sales

Lỗi

Phản hồi lỗi luôn chứa message — bạn có thể hiển thị nguyên văn cho người dùng — và thường có code — thuận tiện để rẽ nhánh trong script.

Giới hạn

• 120 request mỗi phút cho mỗi khóa.
• Tài liệu mới — 10 mỗi giờ, URL tải lên và phiên bản — mỗi loại 30 mỗi giờ, chỉnh sửa trang — 120 mỗi giờ, hình ảnh — 60 mỗi giờ, thay đổi giá — 60 mỗi giờ.