Modbot Docs
Self-hosting

Importing old data

Bringing bans, warnings, notes and audit entries from an older platform into Modbot as a JSON file, what each record needs, and why uploading the same file twice is safe.

A group moving to Modbot usually has history somewhere else: a Discord bot's ban list, a spreadsheet of warnings, an export from VRCX or from whatever it ran before. Modbot cannot fetch any of that itself. What it can do is take a plain JSON file of records and write each one into the same log everything else goes into.

Imported records show up in the audit log, on a person's profile and in the charts, beside everything Modbot recorded itself. Each one is filed under the source it really came from — VRChat's audit log, Discord, a person — and each one names the import that wrote it. See Where a record came from.

Who can import

Importing needs the Import old data permission (see roles and permissions). It is not part of any built-in role except Administrator, and it is not the same as Change settings: an import writes history that did not happen inside Modbot, so it is given out on purpose.

There is no screen for it. Importing is done with an API key that holds the permission.

The file

A file is either a JSON array of records, or one record per line (newline-delimited JSON). Both are accepted. Modbot tells them apart by the first character: [ is an array, anything else is read line by line. Blank lines are ignored.

Each record looks like this:

{
  "kind": "ban",
  "at": "2024-03-01T18:22:07Z",
  "subject": { "platform": "vrchat", "id": "usr_c1644b5b-3ca4-45b4-97c6-a2a0de70d469" },
  "actor": { "platform": "vrchat", "id": "usr_9a2b7d3e-1f4c-4a8e-b6d2-0c5e7f8a9b1d", "name": "Alice" },
  "externalId": "ban-1042",
  "seenBy": "AuditLog",
  "data": { "reason": "Harassment in the Friday event" }
}
FieldRequiredWhat it is
kindYesWhat happened. One of the words in the kinds table, or a full Modbot event type name. Anything else is kept as it is; see below.
atYesWhen it happened, as an ISO 8601 date and time, for example 2024-03-01T18:22:07Z or 2024-03-01T18:22:07+02:00. Without an offset it is taken as UTC. A time in the future is refused.
subjectYesWho or what it happened to. platform is vrchat or discord; id is that platform's id for them. Modbot never checks what an id looks like. For an entry about the group itself, use the group's id.
actorNoWho did it, in the same shape as subject, plus an optional name to show.
externalIdNoThe old platform's own id for this record. See Uploading twice. At most 200 characters.
seenByNoWhere the record came from, which is what the Source column shows. See Where a record came from.
dataNoAnything else worth keeping, as an object. Stored with the record exactly as given.

Anything else in a record is ignored. Ids are text; do not assume a format for them.

Kinds

The event type a record becomes depends on the kind and on the subject's platform:

kindVRChat subjectDiscord subject
joinJoined the groupJoined the server
leaveLeft the groupLeft the server
removeRemoved from the group—
kickKicked from an instanceKicked from the server
warnWarned in an instance—
banBannedBanned
unbanUnbannedUnbanned
timeout—Timed out
noteNote addedNote added
role-addRole grantedRole granted
role-removeRole revokedRole revoked
inviteInvite created—
join-requestAsked to join the group—

Case does not matter: Ban and ban are the same.

A kind with a dot in it is taken as one of Modbot's own event type names, such as vrchat.group.post.create or vrchat.group.update, and is used as it is when Modbot has that type. The event stream page lists the types.

A kind Modbot does not know is never dropped. A dash in the table, a word not in it, or a type name Modbot does not have is recorded as an event Modbot has no name for, with the kind kept exactly as you wrote it. It appears in the audit log, it is kept forever by default, and it can be given a proper name in a later version of Modbot. Only a malformed record is rejected.

Where a record came from

Every event in Modbot has a Source: the system that said so. The audit log's chips filter on it and every row carries it as a badge.

An import does not have a source of its own. A file is usually a mixture — some of it copied out of VRChat's group audit log, some of it Discord moderation, some of it notes a person typed into a spreadsheet — and calling all of it "imported" would throw away what you know. So each record says where it came from with seenBy:

seenByShown asUse it for
AuditLogVRChatEntries copied out of VRChat's own group audit log.
DiscordDiscordThings that happened in your Discord server.
CompanionCompanion AppThings a moderator's PC reported, such as an instance join.
SyncDiffSyncChanges an old tool worked out by comparing two checks rather than seeing them happen.
ManualManualNotes and decisions a person wrote down.
ModbotModbotRecords of the old tool's own workings, such as a settings change.

Case does not matter. Set seenBy on the upload to give the whole file one source, and on a record to override it for that record:

curl -X POST "https://modbot.example.com/api/imports?source=old-bot&seenBy=AuditLog"   -H "Authorization: Bearer mbk_..."   -H "Content-Type: application/json"   --data-binary @old-bot.json

A record that says nothing is Manual: a person put it in, by hand, from somewhere else.

A seenBy Modbot does not know is rejected with its line number, and an unknown seenBy on the upload is refused before anything is queued. This is the one field checked against a list, because it decides what a column on every row says.

Import used to be a source of its own and is no longer one: it said how a record got here rather than who said so, and it hid the answer. Rows imported before this change still show Import and still filter on it, but nothing new is written under it.

Tracing a record back to its import

Whatever source a record carries, Modbot keeps how it got here on the record itself, in data:

KeyWhat it is
importIdThe import that wrote it.
importSourceThe source name you gave the upload, such as old-bot.
externalIdThe old platform's own id, when the record had one.

So "where did this claim come from" is still answerable for a ban that shows VRChat in the Source column: open the event and read importId.

A full example file

Saved as old-bot.json:

[
  {
    "kind": "join",
    "at": "2023-11-04T20:01:15Z",
    "subject": { "platform": "vrchat", "id": "usr_c1644b5b-3ca4-45b4-97c6-a2a0de70d469" }
  },
  {
    "kind": "warn",
    "at": "2024-01-12T22:40:00Z",
    "subject": { "platform": "vrchat", "id": "usr_c1644b5b-3ca4-45b4-97c6-a2a0de70d469" },
    "actor": { "platform": "vrchat", "id": "usr_9a2b7d3e-1f4c-4a8e-b6d2-0c5e7f8a9b1d", "name": "Alice" },
    "externalId": "warn-88",
    "data": { "reason": "Mic spam", "instance": "wrld_4432ea9b-729c-46e3-8eaf-846aa0a37fdd:12345" }
  },
  {
    "kind": "ban",
    "at": "2024-03-01T18:22:07Z",
    "subject": { "platform": "vrchat", "id": "usr_c1644b5b-3ca4-45b4-97c6-a2a0de70d469" },
    "actor": { "platform": "vrchat", "id": "usr_9a2b7d3e-1f4c-4a8e-b6d2-0c5e7f8a9b1d", "name": "Alice" },
    "externalId": "ban-1042",
    "data": { "reason": "Harassment in the Friday event" }
  },
  {
    "kind": "note",
    "at": "2024-03-02T09:10:00Z",
    "subject": { "platform": "discord", "id": "184982340221485056" },
    "actor": { "platform": "discord", "id": "97124821490135040", "name": "Bob" },
    "data": { "text": "Says they were hacked. Watch for a second account." }
  },
  {
    "kind": "vrchat.group.post.create",
    "at": "2024-04-10T17:00:00Z",
    "subject": { "platform": "vrchat", "id": "grp_a1b2c3d4-e5f6-4a7b-8c9d-0e1f2a3b4c5d" },
    "data": { "title": "Friday event moved to Saturday" }
  },
  {
    "kind": "verified-age",
    "at": "2024-05-20T12:00:00Z",
    "subject": { "platform": "vrchat", "id": "usr_c1644b5b-3ca4-45b4-97c6-a2a0de70d469" },
    "seenBy": "Manual"
  }
]

The last record has a kind Modbot does not know. It is kept, with verified-age as the raw type.

The same file, one record per line, is the same records without the surrounding [, ] and commas.

The counts

Every import reports five counts:

CountMeaning
ReceivedRecords read from the file, well-formed or not.
ImportedRecords written. For a dry run, records that would have been.
SkippedRecords you had already imported before. See Uploading twice.
Already knownRecords Modbot already had from somewhere else, such as a ban it read from VRChat's own audit log. See Things Modbot already knows.
RejectedRecords refused because something was missing or wrong. The first fifty are listed, each with its line number (in a one-record-per-line file) or its position (in an array).

A file that is not JSON at all ends as Failed with the parser's reason.

Importing with curl

With an API key that holds Import old data:

curl -X POST "https://modbot.example.com/api/imports?source=old-bot&fileName=old-bot.json&dryRun=true" \
  -H "Authorization: Bearer mbk_..." \
  -H "Content-Type: application/json" \
  --data-binary @old-bot.json

The answer is the import, with its id and status Queued:

{
  "id": "0199f0d8-4c2e-7a3b-9d1e-5f6a7b8c9d0e",
  "source": "old-bot",
  "fileName": "old-bot.json",
  "dryRun": true,
  "dedup": true,
  "seenBy": "AuditLog",
  "status": "Queued",
  "received": 0, "imported": 0, "skipped": 0, "alreadyKnown": 0, "rejected": 0,
  "rejections": [],
  "error": null,
  "startedBy": "sarah",
  "createdAt": "2026-09-17T10:00:00+00:00",
  "startedAt": null,
  "finishedAt": null
}

Ask for it until status is Done or Failed:

curl -H "Authorization: Bearer mbk_..." \
  https://modbot.example.com/api/imports/0199f0d8-4c2e-7a3b-9d1e-5f6a7b8c9d0e

Drop dryRun=true to import for real. seenBy sets the source for the whole file; see Where a record came from. For a one-record-per-line file send Content-Type: application/x-ndjson; the body is the file either way. A multipart form with a file part and source, dryRun, dedup and fileName fields is accepted too. The body is capped at 64 MB; split a larger export into several files.

GET /api/imports lists the latest fifty. The full detail is in the API reference.

Uploading twice

Uploading the same file again writes nothing new. Each record is filed under the source name you gave, keyed by:

  • its externalId, when it has one;
  • otherwise a fingerprint of the record itself: its kind, time, subject, actor and data.

A record whose key is already there is skipped, counted, and never an error. That makes it safe to re-upload a file after a failed import, or to upload a fresh export every month: only what is new goes in. Re-running the same file reports every record as Skipped and writes nothing at all.

This is about records you have imported before. For records Modbot already knew about from somewhere else, see Things Modbot already knows.

Two things follow from the rule:

  • Give records an externalId whenever the old platform has one. A record with an externalId is imported once, whatever the rest of it says. Without one, correcting a typo in data makes a new record, because Modbot cannot tell a correction from a different event.
  • The same record under two source names is two records. Keep using the same source name for the same platform.

Things Modbot already knows

Uploading twice is one problem. The other is that your file probably overlaps with what Modbot has already recorded itself: if Modbot has been running for a month and your old bot's export covers the same month, those bans are already in the log, read from VRChat's own audit log while they happened.

Modbot skips them. Before writing a record it checks whether it already has that event, and counts the matches as Already known. Nothing is written and nothing is lost.

An event counts as one Modbot already has when the same thing happened to the same person at about the same moment — the same event type, the same subject, and an at within two seconds either way. Nothing else is compared: your old bot's wording of a ban reason will never match VRChat's, and requiring them to match would mean nothing was ever recognised.

Two seconds, because two systems writing down one action rarely agree to the fraction of a second: an export usually keeps whole seconds and Modbot's own record keeps the fraction it saw. It is far less than the time it takes somebody to leave an instance and come back, so two things that really did both happen are never mistaken for one.

Where the action happened is compared only when both sides know it. A record in a file never says which instance a kick was in — there is no field for it — while the kick Modbot read from VRChat's own audit log names one. Those are the same kick, and until this was fixed every kick in an import was written down twice, once with the instance and once without. Two instances that are both known and different are still two events.

Two things this never does:

  • It never collapses records from your own file. Three warnings all dated to the same day are three warnings. Only what Modbot knew before this import began counts. Duplicates inside one file are handled by Uploading twice instead, which tells records apart by externalId or by their contents.
  • It never merges two different kinds of event, or two people, or two moments.

A dry run makes the same check, so its Already known count is what a real import would skip.

Turning that check off

Add dedup=false to the upload and every record is written, whatever Modbot already has. Use it when you have looked at what Modbot matched and decided you want your own records in beside its.

This does not turn off Uploading twice. The two are different questions: dedup is about records Modbot got from somewhere else, and the source-and-key rule is about records you have already imported. That rule always runs, so uploading the same file again still writes nothing, with dedup=false as much as without it.

Every import remembers which way it ran: dedup comes back with the import, so you can see months later how a run was made.

What an import does not do

  • It does not change the member list or the ban list. Those are what VRChat says now; the import is history.
  • It does not make case files. See Bans and case files.
  • It cannot be undone as a whole. Facts are append-only. An import with the wrong data is corrected by purging the people concerned, or by restoring a backup taken before it. Run a dry run first.

Imported records follow the retention windows by their type, like every other fact: see Data and retention. Purging a person removes their imported records with everything else.

Every import writes one entry of its own in the operational log, Import finished, naming who uploaded it, the source, the file and the counts.

Modbot is not endorsed by or affiliated with VRChat Inc. or Discord Inc. VRChat is a trademark of VRChat Inc. Discord is a trademark of Discord Inc. SteamVR is a trademark of Valve Corporation. Windows is a trademark of Microsoft Corporation. Docker is a trademark of Docker, Inc. PostgreSQL is a trademark of the PostgreSQL Community Association of Canada. Railway is a trademark of Railway Corp. Other names are trademarks of their respective owners; see Legal. Modbot and its logo are trademarks of the Modbot project. Open source under AGPL-3.0.

On this page