API

Quick start

Send the log text to https://api.minelog.org and you get a link back. Sending it as plain text means there's nothing to escape, which suits shell scripts and Java mods.

curl --data-binary @latest.log \
  -H "Content-Type: text/plain" \
  "https://api.minelog.org/v2/logs?source=MyLauncher"

A successful upload returns 201 and the details of the saved log:

{
  "id": "k7M2xq9D4",
  "url": "https://minelog.org/k7M2xq9D4",
  "raw": "https://api.minelog.org/v2/logs/k7M2xq9D4/raw",
  "source": "MyLauncher",
  "kind": "server",
  "lines": 1204,
  "size": 88012,
  "errors": 3,
  "warnings": 11,
  "privacyApplied": true,
  "createdAt": "2026-09-24T10:40:55Z",
  "expiresAt": "2027-01-22T10:40:55Z",
  "deleteToken": "Vt3mQ8xZk1cR7pLw0aNe5Yf2HbJdUgS4",
  "deletableUntil": "2026-09-24T11:40:55Z"
}

Open url to see the log. That's the link you give to a player or paste into a support thread.

Basics

Everything is on https://api.minelog.org, separate from the website, so a launcher only needs one short host. Logs are still read on https://minelog.org, and every url in a response points there.

There are two protocols on the same host. /v2 is ours, and it's the one to use for new work. /1 copies the mclo.gs API, so tools written for it work once you change the host. Both use the same storage: a log saved through one opens through the other.

• Requests and responses are UTF-8. /v2 dates are ISO 8601 in UTC.
• You can gzip large uploads with Content-Encoding: gzip. The size limits apply to the unpacked text.
• Every endpoint allows cross-origin requests, so a web page can upload straight from the browser.
• You don't need an account or an API key. Limits are per connection.

Limits

These are the same limits the website uses, so anything that uploads there uploads here.

Largest log

15 MBMeasured on the text that gets saved, after private details are hidden. With gzip, the unpacked size is what counts.

Most lines

30,000A log with one very long line counts as one line. The size limit still applies to it.

Kept for

120 daysEvery log deletes itself after this long. You can't extend it.

Kept for, not hidden

48 hoursA log saved with hidePrivate turned off is deleted after this long instead, because nothing was removed from it.

Delete window

60 minutesThe person who saved a log can delete it with its delete token during this time. After that it stays until it expires.

Uploads

70 per minutePer connection. Counted in the database, so it is exact. Reading a log doesn't count.

Uploads a day

300 per dayPer connection, over the last 24 hours. When you reach it, Retry-After tells you when the oldest of those uploads drops out of the count.

Largest text to analyse

5 MBFor the analyse endpoints, which read text without saving it. The line limit is the same 30,000.

Analyses

30 per minutePer connection. Each of our servers counts on its own, so treat it as a fair-use limit and not an exact number.

Reading findings

60 per minutePer connection, for the findings of a saved log. Answers are cached for a minute, and a cached answer never reaches us, so it doesn't count.

Deleting

60 per minutePer connection. A bulk delete counts on its own limit of 10 calls a minute.

Instead of hard coding these numbers, read them from /v2/limits.

Identify your app

Send your app's name as source with each upload. The log page shows it as a small badge, so a player who opens a link from your app can see it came from there. Any name works, there is nothing to sign up for and no list to be on. Every name is shown exactly as you send it, and none is treated differently from another.

• Up to 32 characters.
• Letters and digits from any language, with spaces or . _ + - between words. Something like MyLauncher or My Launcher 2.1.
• A name that doesn't fit is ignored, and the log is saved without a badge. It is never an error.

You can also send it in an X-Minelog-Client header, which helps when you can't change the body.

The source isn't verified. Anyone can send any name, so treat the badge as a hint about where a link came from, not a guarantee.

Private details

By default, minelog hides IP addresses, user folder names, tokens and email addresses before saving. Player names stay, because you need them for debugging. The server does this on its own copy, so a client that skips it still can't store private details.

To turn it off, send hidePrivate: false. The log is then saved as sent, privacyApplied is false in the response, and the log page shows a warning to everyone who opens it. Because nothing was removed, it is also deleted after 48 hours instead of 120 days, and expiresAt says so. Leave it on unless you have a reason not to.

Save a log

POST/v2/logs

Saves one log and returns its details. You can send it two ways:

• Plain text. Send Content-Type: text/plain with the log as the body. Options go in the query string.
• JSON. Send Content-Type: application/json with an object.

The response is 201 with the fields below. Keep the id if you want to read the log again later.

This can fail with 400, 413, 422 or 429. See Errors.

Read a log

GET/v2/logs/{id}

Returns the same fields as an upload. Add ?content=true to include the log text in a content field. Without it, the response stays small no matter how big the log is.

If the id doesn't exist or the log has expired, you get a 404:

{
  "error": {
    "code": "not_found",
    "message": "This log doesn't exist or has expired."
  }
}

Delete a log

DELETE/v2/logs/{id}

Whoever saved a log can delete it in the first 60 minutes. Saving returns a deleteToken once. Send it back in an Authorization: Bearer header. We keep only a hash of it, so keep the token yourself if you want to offer a delete button.

curl -X DELETE https://api.minelog.org/v2/logs/k7M2xq9D4 \
  -H "Authorization: Bearer Vt3mQ8xZk1cR7pLw0aNe5Yf2HbJdUgS4"

On success you get 200:

{
  "id": "k7M2xq9D4",
  "deleted": true
}

After that the log's page and raw text answer 404. A wrong token gets 403 invalid_token, and once the window is over 403 delete_window_closed. See Errors.

Get the raw text

GET/v2/logs/{id}/raw

Returns the log exactly as saved, as text/plain; charset=utf-8. Useful for piping into other tools. Errors here are still JSON, so check the status code before parsing.

Download as a file

GET/v2/logs/{id}/download

The same text as the raw route, but sent with Content-Disposition: attachment and the file name minelog-{id}.txt. Open it in a browser and the file is saved instead of shown, which is what the Download button on a log page does. The text is the whole log, even for the 15 MB ones, and it is streamed in pieces. Errors are JSON, so check the status code before saving the body.

Read what we found

GET/v2/logs/{id}/insights

Returns what minelog read from a saved log: the game version, loader, Java, launcher and mods, and any known problems with things to try. It works for server logs, client logs, crash reports and Java crash logs. For any other file the lists are empty.

curl https://api.minelog.org/v2/logs/k7M2xq9D4/insights

Here is the answer for a log with a startup line, the Paper banner and an OutOfMemoryError:

{
  "kind": "server",
  "title": "Paper 1.20.1 Server Log",
  "software": {
    "id": "paper",
    "name": "Paper"
  },
  "minecraftVersion": "1.20.1",
  "environment": {
    "gameVersion": {
      "value": "1.20.1",
      "text": "1.20.1",
      "detail": null,
      "confidence": "high",
      "lines": [
        1,
        2
      ],
      "others": []
    },
    "loader": {
      "value": "paper",
      "text": "Paper build 196",
      "detail": "build 196",
      "confidence": "medium",
      "lines": [
        2
      ],
      "others": []
    },
    "java": null,
    "launcher": null,
    "conflicts": []
  },
  "mods": [],
  "bundledMods": 0,
  "problems": [
    {
      "id": "out-of-memory",
      "message": "Java ran out of the memory it was allowed to use.",
      "solutions": [
        "On a hosting panel, raise the RAM setting. On your own machine, raise -Xmx in the start command. For example, -Xmx4G allows 4 GB.",
        "If it comes back after an hour or two of playing, a mod or plugin may be leaking memory. Remove the ones you added last and test again."
      ],
      "count": 1,
      "line": 3
    }
  ]
}

Facts

gameVersion, loader, java and launcher are each null when the log doesn't say, or an object with these fields:

Everything is read from lines the game or server wrote itself. Player chat and console commands are skipped, so a line someone types in chat can't show up as a finding. A log that was edited by hand can still fool it, so treat the answer as what the log says, not as proof.

Problems

The list of known problems is short, and it grows. An empty list doesn't mean the log is healthy. It means none of the known ones showed up. These are the ids today, and an id never changes its meaning:

Answers are cached for a minute, and reading findings has its own limit, listed under Limits. If the id doesn't exist or the log has expired you get the same 404 as when reading a log.

Analyse without saving

POST/v2/analyse

Reads text the same way and returns the same answer, without saving anything. Use it when a tool wants the findings and has no need for a link. Please don't save a log just to read its findings, that stores data nobody needs.

You can send it two ways, like saving a log: plain text with the log as the body, or JSON with an object.

curl --data-binary @latest.log \
  -H "Content-Type: text/plain" \
  https://api.minelog.org/v2/analyse

The answer is 200 with the fields under Read what we found. The text can be up to the analysis size limit in Limits, and a text over it is refused with 413, not cut. Each connection can run 30 a minute. Errors are the ones under Errors.

Read the limits

GET/v2/limits

Returns the current limits, so an app can check a file before trying to upload it:

{
  "retentionDays": 120,
  "unhiddenRetentionHours": 48,
  "maxBytes": 15728640,
  "maxLines": 30000,
  "uploadsPerMinute": 70,
  "uploadsPerDay": 300,
  "maxAnalyseBytes": 5242880,
  "analysesPerMinute": 30
}

Errors

Every /v2 error has the same shape: an error object with a code you can branch on and a message written for people. Show the message to users as is, but don't match on its wording, because it may change.

{
  "error": {
    "code": "too_many_lines",
    "message": "This log has too many lines. The limit is 30,000."
  }
}

Rate limits

Each connection can save 70 logs a minute and 300 a day, and analyse 30 a minute. Reading the findings of a saved log and deleting have limits too, listed under Limits. After that you get a 429 with a Retry-After header, in seconds. We count using a keyed hash of the IP address and never store the address itself. Reading a log, its text or its details isn't counted. Everything except saving is counted by each of our servers on its own, so those numbers are fair-use limits, not exact ones.

An app running on a player's own machine is fine, since each player has their own connection. If your service will upload for many people from one server, contact us before you launch so we can plan for it.

mclo.gs compatibility

If your tool already uploads to mclo.gs, you don't need to rewrite it. Change api.mclo.gs to api.minelog.org and keep the /1 paths:

curl -X POST https://api.mclo.gs/1/log \
  --data-urlencode "content@latest.log"

The response has the shape those tools expect, with a success flag and times in unix seconds:

{
  "success": true,
  "id": "k7M2xq9D4",
  "source": "MyLauncher",
  "created": 1790246455,
  "expires": 1793702455,
  "size": 88012,
  "lines": 1204,
  "errors": 3,
  "url": "https://minelog.org/k7M2xq9D4",
  "raw": "https://api.minelog.org/1/raw/k7M2xq9D4",
  "metadata": [],
  "token": "Vt3mQ8xZk1cR7pLw0aNe5Yf2HbJdUgS4"
}

The findings use mclo.gs's shape too. This is GET /1/insights/{id} and POST /1/analyse, and the same lists come back under content.insights when you add ?insights=1 to GET /1/log/{id}:

{
  "success": true,
  "id": "paper/server",
  "name": "Paper",
  "type": "Server Log",
  "version": "1.20.1",
  "title": "Paper 1.20.1 Server Log",
  "analysis": {
    "problems": [
      {
        "message": "Java ran out of the memory it was allowed to use.",
        "counter": 1,
        "entry": {
          "level": 3,
          "time": null,
          "prefix": "[12:00:01 ERROR]:",
          "lines": [
            {
              "number": 3,
              "content": "[12:00:01 ERROR]: java.lang.OutOfMemoryError: Java heap space"
            }
          ]
        },
        "solutions": [
          {
            "message": "On a hosting panel, raise the RAM setting. On your own machine, raise -Xmx in the start command. For example, -Xmx4G allows 4 GB."
          },
          {
            "message": "If it comes back after an hour or two of playing, a mod or plugin may be leaking memory. Remove the ones you added last and test again."
          }
        ]
      }
    ],
    "information": [
      {
        "message": "Minecraft version: 1.20.1",
        "counter": 1,
        "label": "Minecraft version",
        "value": "1.20.1",
        "entry": {
          "level": 6,
          "time": null,
          "prefix": "[12:00:00 INFO]:",
          "lines": [
            {
              "number": 1,
              "content": "[12:00:00 INFO]: Starting minecraft server version 1.20.1"
            }
          ]
        }
      },
      {
        "message": "Server software: Paper build 196",
        "counter": 1,
        "label": "Server software",
        "value": "Paper build 196",
        "entry": {
          "level": 6,
          "time": null,
          "prefix": "[12:00:00 INFO]:",
          "lines": [
            {
              "number": 2,
              "content": "[12:00:00 INFO]: This server is running Paper version git-Paper-196 (MC: 1.20.1) (Implementing API version 1.20.1-R0.1-SNAPSHOT)"
            }
          ]
        }
      }
    ]
  }
}

Errors use the same flat shape rather than the /v2 one:

{
  "success": false,
  "error": "This log is too large."
}

A few things can't match. This is every mclo.gs endpoint and where it stands:

/1/limits returns our numbers in the units mclo.gs uses:

{
  "storageTime": 10368000,
  "maxLength": 15728640,
  "maxLines": 30000
}

Our limits differ from theirs. A tool that reads /1/limits before uploading picks ours up by itself. One that hard codes the mclo.gs numbers stays inside them, which always fits.

Stability

What you can count on for /v2:

• We can add new fields to a response at any time. If your client ignores fields it doesn't know, nothing breaks.
• Changes that would break a working client go into a new version, /v3. /v2 keeps working alongside it.
• The /1 paths follow mclo.gs. If they add something we'll look at it, but we can't promise the same day.
• Logs are deleted after 120 days, whichever protocol saved them. Only a /v2 log saved with hidePrivate: false is deleted sooner.