List your builds on MineMev

How it works

1. We read your list endpoint. New posts are picked up about every 15 minutes, and the whole catalogue is re-read once a day.
2. We read details and files per post. A post's details and files are refreshed about once a week.
3. We store a copy of the metadata only. Titles, descriptions, tags, versions and image URLs are stored. Files are not: downloads go straight to the URLs you return.
4. We remove posts you remove. A post is deleted only after it has been missing from several complete crawls in a row, so a bad deploy on your side won't wipe your listings.

If your API already returns the shapes below, adding you is a small config entry. If it doesn't, we can write an adapter for your existing API. Tell us in the ticket.

Endpoints

Every endpoint is a public GET that returns JSON over HTTPS. Paths are only examples; send us yours.

{id} is your own post id. It must never change for a post, because it is how we match a post between crawls.

Search / list

This endpoint is used to crawl your catalogue page by page.

Query parameters

Parameter names don't have to match: we can map pagesize to limit, newest to createdAt, and so on.

Response

{
  "posts": [
    {
      "uuid": "a1b2c3",
      "post_name": "Iron farm 1.21",
      "description": "Plain-text summary, up to ~255 characters",
      "images": ["https://yoursite.com/img/a1b2c3/1.webp"],
      "thumbnail_url": "https://yoursite.com/img/a1b2c3/thumb.webp",
      "tags": ["iron_farm", "farm"],
      "versions": ["1.20.4", "1.21"],
      "User": "author_name",
      "user_picture": "https://yoursite.com/avatars/author.png",
      "yt_link": "dQw4w9WgXcQ",
      "downloads": 1234,
      "published_at": "2026-05-01T18:30:00Z",
      "url_redirect": "https://yoursite.com/post/a1b2c3"
    }
  ],
  "total_items": 4210,
  "total_pages": 421,
  "page": 1
}

total_pages tells us when a full crawl is finished, so it must be correct. Without it, nothing you delete is ever removed on our side.

Details

GET /api/details/{id} returns one post with everything in the list item, plus:

{
  "uuid": "a1b2c3",
  "post_name": "Iron farm 1.21",
  "description": "Full description as plain text",
  "description_md": "## Rates\n**1,800 iron/h** in a 1.21 world.",
  "creators": "author_name, co_author",
  "images": ["..."],
  "tags": ["iron_farm", "farm"],
  "versions": ["1.21"],
  "User": "author_name",
  "user_picture": "https://...",
  "yt_link": "dQw4w9WgXcQ",
  "downloads": 1234,
  "published_at": "2026-05-01T18:30:00Z",
  "url_redirect": "https://yoursite.com/post/a1b2c3"
}

An unknown or deleted post must return HTTP 404. Don't return 200 with null or an empty object.

Files

GET /api/files/{id} returns the downloadable files of a post as a list. If the post has no files, return [].

[
  {
    "id": 991,
    "default_file_name": "iron_farm_v2.litematic",
    "file": "https://yoursite.com/download/991",
    "file_size": 48213,
    "versions": ["1.21"],
    "downloads": 310,
    "file_type": "litematic"
  }
]

• file is a direct, public download URL. We link to it and never re-host the file.
• file_size is in bytes. Use 0 if you don't know it.
• file_type is one of litematic, schem, schematic, nbt, zip.

Files from other sites are shown on MineMev as external. They are not scanned by our VirusTotal check, so make sure your own uploads are safe.

Tags

Tags are lowercase keys with underscores, such as iron_farm or tree_farm. Using MineMev's existing keys gets your posts into the right categories and translations. The full list is at /api/v2/tags, and the category tree is at /api/tags?tree=1.

Tags we don't know yet are created automatically and checked by our moderators. If your site has its own tag list, expose it at an optional /api/tags endpoint and we will map your tags to ours.

Rules for the data

• Dates are ISO 8601 in UTC with a single Z: 2026-05-01T18:30:00Z. Millisecond epochs work too.
• description is plain text. No HTML. Put formatting in description_md (Markdown). Raw HTML in it is removed.
• URLs are absolute and use HTTPS. This applies to images, avatars, files and url_redirect.
• Ids are stable. Never reuse an id for a different post.
• Missing values use null, [] or 0. Don't leave out the key or invent a placeholder.
• yt_link can be a YouTube id or a full YouTube or Bilibili URL.
• Rate limits: we send a few requests per minute. If you need a key or an allow-listed IP, tell us in the ticket.

Using MineMev's API

Our own API returns posts from every connected site in the same shapes as above. It is public and free to use.