HTTP Parse Server

Caution

ParseSK is only available for Patreon supporters of ItsTheSky. Access the plugin through the Patreon-only Resources page.

Note

The HTTP parse server was added in ParseSK 1.3.0. Make sure you are running that version or newer.

Overview

The HTTP parse server is an optional listener that exposes Skript validation outside the game. Instead of running an effect inside a script, external tools send Skript code over HTTP and receive the list of errors and warnings as a JSON response.

This makes ParseSK usable by:

• Code editors & IDE extensions — live syntax checking while writing scripts
• Linters & pre-commit hooks — reject broken scripts before they reach the server
• CI pipelines — fail a build when a .sk file does not parse
• Web playgrounds — validate snippets straight from a browser

Note

The endpoint always parses in “parse only” mode (the same as parse without loading). Nothing is ever registered, executed or kept loaded on your server — it is purely validation.

Enabling the Server

The server is disabled by default. Enable it through ParseSK’s config.yml.

1. Locate the config file

   After the first start with ParseSK installed, open plugins/ParseSK/config.yml.

2. Enable the listener

   Set enabled to true and pick a port:

   http-server:
     # Whether the HTTP listener should be started together with the server.
     enabled: true
   
     # The TCP port the listener should bind to.
     port: 8765
   
     # Optional bearer token. When set (non-empty), every request must include
     # the header:   Authorization: Bearer <token>
     # Leave empty to disable authentication.
     token: ''

3. Restart the server

   Restart your Minecraft server. The console confirms the listener is up:

   [ParseSK] HTTP parse listener started on port 8765 (POST /parse).

Configuration Options

Option	Type	Default	Description
http-server.enabled	Boolean	false	Whether to start the listener on server startup
http-server.port	Number	8765	TCP port the listener binds to
http-server.token	String	''	Optional bearer token; when set, requests must authenticate

The /parse Endpoint

The server exposes a single endpoint.

Method	POST
Path	/parse
Request body	The raw Skript code to validate (plain text, UTF-8)
Response	A JSON object describing every error and warning

Request

Send the complete Skript code as the raw request body. No JSON wrapping, no form encoding — just the code itself.

If a token is configured, the request must include the matching header:

Authorization: Bearer <token>

Response

The response is always a JSON object. On success:

{
  "success": true,
  "valid": false,
  "errorCount": 1,
  "warningCount": 0,
  "entries": [
    {
      "line": 3,
      "level": "error",
      "message": "Can't understand this effect: gives player a diamond",
      "code": "gives player a diamond"
    }
  ]
}

Field	Type	Description
success	Boolean	Whether the request was processed (not whether the code is valid)
valid	Boolean	true when there are no errors (warnings are allowed)
errorCount	Number	Number of errors found
warningCount	Number	Number of warnings found
entries	Array	One object per error/warning
entries[].line	Number	Line the entry refers to (-1 if unknown)
entries[].level	String	"error" or "warning"
entries[].message	String	Human-readable description
entries[].code	String	The offending source line

On failure (bad method, bad token, internal error) the response carries an error field instead:

{ "success": false, "error": "Unauthorized" }

Status	Meaning
200	Code parsed — see entries for the result
401	Missing or invalid bearer token
405	Wrong HTTP method — use POST
500	Internal error while parsing

Note

Browser tools are supported: the endpoint replies with permissive CORS headers and handles OPTIONS preflight requests, so a web editor can call it directly with fetch.

Examples

curl

# Validate a script file
curl -X POST http://localhost:8765/parse --data-binary @myscript.sk

# Inline code
curl -X POST http://localhost:8765/parse \
  --data-binary $'on join:\n    gives player a diamond'

# With an authentication token
curl -X POST http://localhost:8765/parse \
  -H "Authorization: Bearer my-secret-token" \
  --data-binary @myscript.sk

JavaScript (fetch)

async function validateSkript(code) {
  const response = await fetch("http://localhost:8765/parse", {
    method: "POST",
    headers: {
      "Content-Type": "text/plain",
      // "Authorization": "Bearer my-secret-token", // if a token is set
    },
    body: code,
  });

  const result = await response.json();

  if (result.valid) {
    console.log("Script is valid!");
  } else {
    for (const entry of result.entries) {
      console.log(`[${entry.level}] line ${entry.line}: ${entry.message}`);
    }
  }
}

validateSkript("on join:\n    gives player a diamond");

CI (bash)

#!/usr/bin/env bash
# Fail the pipeline if any .sk file does not parse.
set -euo pipefail

status=0
for file in $(find scripts -name '*.sk'); do
  valid=$(curl -s -X POST http://localhost:8765/parse \
            --data-binary "@$file" | jq -r '.valid')
  if [ "$valid" != "true" ]; then
    echo "::error::$file failed to parse"
    status=1
  fi
done
exit $status

Security

Danger

The /parse endpoint accepts arbitrary Skript code. Although parsing never executes anything, you should still not expose it to the public internet without protection.

Recommended Practices

1. Bind to a private interface

   Run the listener behind a firewall, or only reach it from localhost / your internal network.

2. Set a token

   Configure a non-empty token so only authenticated tools can call the endpoint.

3. Put it behind a reverse proxy

   For public access, front the listener with a reverse proxy (nginx, Caddy, …) that adds TLS and rate limiting.

Important Notes

Note

Main thread. Each request is parsed on the server’s main thread (the Skript parser requires it). A request waits up to 30 seconds for the parse to complete. Avoid hammering the endpoint with huge scripts on a busy server.

Tip

Always parse-only. Unlike the parse script effect, the HTTP endpoint can never load or execute code — it is validation only, by design.

Reference

Configuration (plugins/ParseSK/config.yml)

http-server:
  enabled: false
  port: 8765
  token: ''

Endpoint

POST /parse
Body: <raw Skript code>
Authorization: Bearer <token>   # only if a token is configured

Support

Need help with ParseSK?

• DiSky Discord Server
• Patreon Page
• Parsing Full Scripts — the in-game equivalent effect