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" }
}| Field | Required | What it is |
|---|---|---|
kind | Yes | What 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. |
at | Yes | When 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. |
subject | Yes | Who 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. |
actor | No | Who did it, in the same shape as subject, plus an optional name to show. |
externalId | No | The old platform's own id for this record. See Uploading twice. At most 200 characters. |
seenBy | No | Where the record came from, which is what the Source column shows. See Where a record came from. |
data | No | Anything 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:
kind | VRChat subject | Discord subject |
|---|---|---|
join | Joined the group | Joined the server |
leave | Left the group | Left the server |
remove | Removed from the group | — |
kick | Kicked from an instance | Kicked from the server |
warn | Warned in an instance | — |
ban | Banned | Banned |
unban | Unbanned | Unbanned |
timeout | — | Timed out |
note | Note added | Note added |
role-add | Role granted | Role granted |
role-remove | Role revoked | Role revoked |
invite | Invite created | — |
join-request | Asked 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:
seenBy | Shown as | Use it for |
|---|---|---|
AuditLog | VRChat | Entries copied out of VRChat's own group audit log. |
Discord | Discord | Things that happened in your Discord server. |
Companion | Companion App | Things a moderator's PC reported, such as an instance join. |
SyncDiff | Sync | Changes an old tool worked out by comparing two checks rather than seeing them happen. |
Manual | Manual | Notes and decisions a person wrote down. |
Modbot | Modbot | Records 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.jsonA 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:
| Key | What it is |
|---|---|
importId | The import that wrote it. |
importSource | The source name you gave the upload, such as old-bot. |
externalId | The 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:
| Count | Meaning |
|---|---|
| Received | Records read from the file, well-formed or not. |
| Imported | Records written. For a dry run, records that would have been. |
| Skipped | Records you had already imported before. See Uploading twice. |
| Already known | Records Modbot already had from somewhere else, such as a ban it read from VRChat's own audit log. See Things Modbot already knows. |
| Rejected | Records 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.jsonThe 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-5f6a7b8c9d0eDrop 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
externalIdwhenever the old platform has one. A record with anexternalIdis imported once, whatever the rest of it says. Without one, correcting a typo indatamakes 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
externalIdor 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.