API Files

/files reaches the server folder: server.properties, bukkit.yml, spigot.yml, Paper's config/, every plugin's folder, a world's paper-world.yml, and logs/. Paths are relative, with forward slashes. Every path below starts with /api/v1.

Endpoint	Permission	What it does
GET /files	files:read	List a folder of the server
POST /files/edit	files:write	Replace exact text in a file
GET /files/read	files:read	Read a text file in pages of numbered lines, or grep it
POST /files/set	files:write	Set values in a YAML, .properties, or JSON config by dotted path
PUT /files/write	files:write	Create a file or replace it whole
GET /server/configs	files:read	Where the server's and each plugin's configs are

GET /files and GET /files/read also take logs:read instead of files:read, for files under logs/.

Reading

1. GET /server/configs lists the configs that exist here.
2. GET /files?path=plugins/TAB lists a folder.
3. GET /files/read?path=… returns numbered lines as an editor shows them, <number>\t<text>:
   • 200 at a time from offset, and nextOffset reads on;
   • or the last tail lines;
   • or, with grep (text, or a regular expression with regex=true), the matching lines with context lines around each, -- between groups.

totalLines and matches count the whole file. A grep that runs past 5 seconds stops with 400 grep_timeout; pick a simpler pattern. Lines past 2000 characters are cut, an answer stops at limits.maxReadChars, and gzipped logs read as text.

Writing

Writing needs files:write, which only the owner group has unless you add it elsewhere.

• POST /files/edit replaces exact text. Each oldText must be found once unless replaceAll, and either all edits apply or none.
• POST /files/set sets keys by dotted path in YAML (comments kept), .properties (only the lines it sets change), or JSON; null removes a key.
• PUT /files/write replaces a file whole or creates one.

Send the sha256 from /files/read as expectedSha256, and a write fails with 409 file_changed when someone changed the file since.

What happens to a write

• Every write keeps the previous version in plugins/WorldAPI/backups/, limits.fileBackups per file, and goes to the audit log with the lines added and removed.
• The server and plugins read their configs at start or on their own reload command, so a change takes a restart or that reload.
• ops.json, whitelist.json, banned-players.json, and banned-ips.json go through the server: WorldAPI reads the new content as the list it should become, adds and removes entries to match, and the server saves the file in its own format. Writing ops.json also needs server:console, as PATCH /server/ops does.

Never shared, never written

• Never shared: WorldAPI's own folder (its tokens, database, and backups), hidden files, keys, databases, jars, and anything a link leads to outside the server folder.
• Never written: logs/, usercache.json, and version_history.json, which the server writes by itself. Each file says why it stays read-only in readOnlyReason.

Next: Access control.