Docs

The Nulvio API

Make pastes from a plugin or a script. A plugin can post a crash report and hand the server owner a link; the report lands in your account, where you can read it.

Keys

Anyone can make a paste with no key at all. A key ties the pastes to your account. Make one in your account, and send it with every request:

Authorization: Bearer nul_rk_your_key

Report key nul_rk_

Can only create pastes, and never public ones. This is the one to ship inside a plugin other people run. Anyone can read a key out of a jar; with this one, all they can do is send you a report.

Full key nul_fk_

Can list, read, change and delete every paste in your account. For your own servers and scripts. Never put it in a plugin that leaves your hands.

Make a paste

POST https://nulvio.dev/api/v1/pastes with a JSON body.

curl https://nulvio.dev/api/v1/pastes \
  -H "Authorization: Bearer nul_rk_your_key" \
  -H "Content-Type: application/json" \
  -d '{
    "title": "Crash on startup",
    "files": [{ "name": "latest.log", "content": "[12:00:01] [Server thread/ERROR]: ..." }],
    "meta": { "plugin": "MyPlugin", "version": "2.4.1" }
  }'
files required
One to 10 files, each { "name", "content" } and optionally "language". Each file up to 512 KB, 2.0 MB in all.
title optional
A short name for the paste, up to 120 characters. It is the heading of the paste's page for anyone who opens it and, with a key, its name in your account.
visibility optional
"unlisted" (the default), "public" or "private". Private needs a key. A report key cannot make public pastes.
expires optional
One of "1h", "1d", "7d", "30d", "90d", "1y", "never". The default is "30d". "never" needs a key.
expires_at optional
Instead of "expires": an exact moment, in seconds since 1970, from five minutes to a year away.
max_views optional
Delete the paste after this many opens (1 to 1000). Opening the page or fetching a raw file each count, including by you: the "raw" links in the answer are counted like anyone else's, and only the owner signed in on the paste's page is exempt. Link previewers, and any client whose User-Agent is empty or looks like a bot or crawler, are refused such a paste without using up an open.
meta optional
With a key: { "plugin", "version", "server" }, short labels shown beside the paste in your account.

The answer is 201 with the link to give the user:

{
  "id": "k7q2m9xw4hd8t3bn6vry2c",
  "url": "https://nulvio.dev/p/k7q2m9xw4hd8t3bn6vry2c",
  "raw": ["https://raw.nulvio.dev/k7q2m9xw4hd8t3bn6vry2c/latest.log"]
}

Made with no key, the answer also has a delete_key; send it as the Bearer token to DELETE /api/v1/pastes/{id} to remove the paste. A delete key only works while the paste belongs to no account. A private paste answers with an empty raw list: its files are only handed to people it is shared with.

From a Minecraft plugin

Plain Java 17, no libraries. Run it off the main thread, and show the returned link to whoever ran the command.

import java.net.URI;
import java.net.http.HttpClient;
import java.net.http.HttpRequest;
import java.net.http.HttpResponse;

public final class NulvioReports {
    private static final String KEY = "nul_rk_your_key";
    private static final HttpClient HTTP = HttpClient.newHttpClient();

    /** Sends a report and returns the link to it. Call it off the main thread. */
    public static String send(String title, String fileName, String content, String version) throws Exception {
        String body = "{\"title\":" + quote(title)
            + ",\"files\":[{\"name\":" + quote(fileName) + ",\"content\":" + quote(content) + "}]"
            + ",\"meta\":{\"plugin\":\"MyPlugin\",\"version\":" + quote(version) + "}}";

        HttpRequest request = HttpRequest.newBuilder(URI.create("https://nulvio.dev/api/v1/pastes"))
            .header("Authorization", "Bearer " + KEY)
            .header("Content-Type", "application/json")
            .POST(HttpRequest.BodyPublishers.ofString(body))
            .build();

        HttpResponse<String> response = HTTP.send(request, HttpResponse.BodyHandlers.ofString());
        if (response.statusCode() != 201) throw new IllegalStateException("Nulvio answered " + response.statusCode() + ": " + response.body());

        // The answer is {"id":"...","url":"https://nulvio.dev/p/...", ...}
        String text = response.body();
        int start = text.indexOf("\"url\":\"") + 7;
        return text.substring(start, text.indexOf('"', start));
    }

    private static String quote(String value) {
        StringBuilder out = new StringBuilder("\"");
        for (char c : value.toCharArray()) {
            switch (c) {
                case '"' -> out.append("\\\"");
                case '\\' -> out.append("\\\\");
                case '\n' -> out.append("\\n");
                case '\r' -> out.append("\\r");
                case '\t' -> out.append("\\t");
                default -> { if (c < 0x20) out.append(String.format("\\u%04x", (int) c)); else out.append(c); }
            }
        }
        return out.append('"').toString();
    }
}

Every endpoint

POST /api/v1/pastes none, report or full Make a paste.
GET /api/v1/pastes full List your pastes, newest first. Takes search, visibility, limit and offset.
GET /api/v1/pastes/{id} full One paste with the contents of its files.
PATCH /api/v1/pastes/{id} full Change files, title, visibility or expires. Send only what changes.
DELETE /api/v1/pastes/{id} full, or delete key Delete a paste. Answers 204. A paste made with no key is deleted with its delete_key as the Bearer token.

Limits

  • Report key: 120 pastes per ten minutes and 2,000 per day for the key, and 10 per ten minutes from any one server address. One broken server cannot use up your allowance.
  • Full key: 300 pastes per ten minutes.
  • Per account: 300 pastes per ten minutes and 3,000 per day across all of its keys and the website together, and 500 MB of pastes stored at once.
  • Per paste: 100,000 lines across its files, on top of the size limits above.
  • No key: the same limit as the website, per address.
  • Over a limit the answer is 429 with a Retry-After header. Wait that long; do not retry in a loop.

When something is wrong

Errors from the API are JSON with one field, message, written for a person to read. A few answers come from in front of the API and are plain text or HTML instead: 405 for a method an endpoint does not take, 403 when a request with a body is not sent as Content-Type: application/json, and 413 when the whole request is over 13 MB.

400Something in the request is wrong. The message says what.
401This needs a key and none was sent, or the key is not recognised or has been revoked.
403The key is paused, or the request needs a key (or a kind of key) it does not have. Also a wrong delete key.
404Your account has no paste with that id.
413A file or the whole paste is too large or has too many lines, or the account is at its storage limit.
429Too many requests. Retry-After says how many seconds to wait.
507The server is out of room for new pastes. Try again later.