Introduction

This is the official documentation for Awesome_E's Public HS Tools API.

API Endpoint

The HS Tools API Endpoint is https://hs-tools-api.up.railway.app/. It will be the URL at the start of every request.

Source Code

This project is open-source. You can find the source code on GitHub, where you can file an issue, create PRs, and see the code behind the API.

Getting Hopscotch Data

With this API, you can get hand-created data that the HS Tools website uses. Currently, this includes information about different blocks and objects.

All Hopscotch Blocks

Returns the entire list of blocks being used by HS Tools

To get the list of Hopscotch blocks, you can use this code:

fetch('https://hs-tools-api.up.railway.app/hopscotch-data/blocks')
  .then(r => r.json())
  .then(d => console.log(d))

curl "https://hs-tools-api.up.railway.app/hopscotch-data/blocks"

HTTP Request

GET /hopscotch-data/blocks

Request Parameters

There are no request parameters

This endpoint will return an array of dictionaries that contain info about Hopscotch blocks

200 OK

[
  { ... },
  { ... },
  ...
]

Reponse Data

Info About a Specific Block

Returns information about the block with the specified ID

To get the block with ID -1, you can run the following:

fetch('https://hs-tools-api.up.railway.app/hopscotch-data/blocks/-1')
  .then(r => r.json())
  .then(d => console.log(d))

curl "https://hs-tools-api.up.railway.app/hopscotch-data/blocks/-1"

HTTP Request

GET /hopscotch-data/blocks/:id

Request Parameters

The response will contain JSON with this structure:

200 OK

{
  "about": "Community Description",
  "authors": ["Awesome_E"],
  "availability": "all",
  "blockHTML": "fish <i class=\"ps fa fa-volume-up\"></i> ",
  "collapsible": false,
  "community_links": ["..."],
  "description": "N/A – There is no app description",
  "id": -1,
  "key": "-1",
  "name": "fish",
  "other_info": ["..."],
  "parameters": ["..."],
  "type": "old",
  "useful_for": ["Fishing"]
}

If the block does not exist, it will return this error:

404 Not Found

{
  "status": "error",
  "error": "No block was found with ID -1"
}

Response Data

^*Block Availability

Specific Trait of a Block

All Hopscotch Objects

Returns the entire list of object types tracked in HS Tools.

To get the list of Hopscotch objects, you can use this code:

fetch('https://hs-tools-api.up.railway.app/hopscotch-data/objects')
  .then(r => r.json())
  .then(d => console.log(d))

curl "https://hs-tools-api.up.railway.app/hopscotch-data/objects"

HTTP Request

GET /hopscotch-data/objects

Request Parameters

There are no request parameters

This endpoint will return an array of dictionaries that have information about Hopscotch objects

200 OK

[
  { ... },
  { ... },
  ...
]

Reponse Data

Info About a Specific Object

Returns information about the object with the specified ID

To get the object with ID 1, you can run the following:

fetch('https://hs-tools-api.up.railway.app/hopscotch-data/objects/1')
  .then(r => r.json())
  .then(d => console.log(d))

curl "https://hs-tools-api.up.railway.app/hopscotch-data/objects/1"

HTTP Request

GET /hopscotch-data/objects/:id

Request Parameters

The response will contain JSON with this structure:

200 OK

{
  "codename": "text",
  "description": "An alphabet soup of letters, numbers, symbols, and emoji.",
  "id": 1,
  "key": "1",
  "name": "Text"
}

If the object does not exist, it will return this error:

404 Not Found

{
  "status": "error",
  "error": "No object was found with ID 1"
}

Response Data

Specific Trait of an Object

Retrieving Webplayer Files

Webplayer Metadata

This retrieves the file path, modification date, and version of the latest minor releases under each major webplayer version.

To retrieve information about the latest webplayer release for every major version (1.0, 1.1, 1.2, 1.3, 2.0, etc.):

fetch('https://hs-tools-api.up.railway.app/webplayer/metadata')
  .then(r => r.json())
  .then(d => console.log(d))

curl "https://hs-tools-api.up.railway.app/webplayer/metadata"

HTTP Request

GET /webplayer/metadata/:version

To retrieve information about the latest webplayer release for only 1.5.x webplayers:

fetch('https://hs-tools-api.up.railway.app/webplayer/metadata/1.5')
  .then(r => r.json())
  .then(d => console.log(d))

curl "https://hs-tools-api.up.railway.app/webplayer/metadata/1.5"

Request Parameters

A sample response for getting the latest webplayer metadata for all major releases

200 OK

{
  "1.0": {
    "path": "versions/1.0.14/webplayer.min.js",
    "date": 1593469128976,
    "pixi": "4.8.6",
    "player": "1.0.14"
  },
  "1.1": { ... },
  "1.2": { ... },
  "1.3": { ... },
  "1.4": { ... },
  "1.5": {
    "path": "versions/1.5.20/webplayer.min.js",
    "date": 1637679789463,
    "pixi": "4.8.6",
    "player": "1.5.20"
  }
}

Example response for getting the latest webplayer metadata for only 1.5.x

200 OK

{
  "path": "versions/1.5.20/webplayer.min.js",
  "date": 1637679789463,
  "pixi": "4.8.6",
  "player": "1.5.20"
}

Example Response for a non-existent webplayer version

404 Not Found

null

Response Data

• If a major version is specified in your request, the response will only contain metadata about the latest release under that major version (i.e. only the latest 1.5.x webplayer info).
• If no major version is specified, it will return the latest release for all major webplayer versions.

The metadata of each webplayer follows this structure:

Getting Webplayer Files

Using this API endpoint, you can also get the any Hopscotch webplayer file.

Get the latest 1.5.x webplayer

fetch('https://hs-tools-api.up.railway.app/webplayer/1.5.0')
  .then(r => r.text())
  .then(d => console.log(d))

curl "https://hs-tools-api.up.railway.app/webplayer/1.5.0"

HTTP Request

GET /webplayer/:version

This will also get the latest 1.5.x player, even though a minor version is specified

fetch('https://hs-tools-api.up.railway.app/webplayer/1.5.7')
  .then(r => r.text())
  .then(d => console.log(d))

curl "https://hs-tools-api.up.railway.app/webplayer/1.5.7"

Request Parameters

Get webplayer with exact version 1.5.12

fetch('https://hs-tools-api.up.railway.app/webplayer/1.5.12?newest=0')
  .then(r => r.text())
  .then(d => console.log(d))

curl "https://hs-tools-api.up.railway.app/webplayer/1.5.12?newest=0"

Request Query

For example, if you GET /webplayer/1.5.11 but the latest is 1.5.20, the response will be the 1.5.20 webplayer instead of the version you provided (webplayer 1.5.11). Set the newest flag to 0 if you do not want this behavior.

Sample Response for existing version (truncated for obvious reasons):

200 OK

/**
 * Hopscotch Technologies
 * Webplayer v1.5.20 - 2021/11/23 (production)
 */
console.log("Webplayer v1.5.20 - 2021/11/23 (production)");
!function(e){var t={}; ...

Sample Response for non-existent version:

404 Not Found

null

Response Data

The response contains the JavaScript code for the webplayer, exactly as retrieved from Hopscotch's servers.

Project Data Types

This endpoint will retrieve the webplayer file, and from it, determine all of the block, object, and parameter types.

Get data types for the latest 1.5.x webplayer

fetch('https://hs-tools-api.up.railway.app/webplayer/1.5.0/project-datatypes')
  .then(r => r.json())
  .then(d => console.log(d))

curl "https://hs-tools-api.up.railway.app/webplayer/1.5.0/project-datatypes"

200 OK

{
  "blocks": {
    "19": "WaitTilTimestamp",
    "20": "WaitUntilInputIsDone",
    ...
  },
  "objects": {
    "0": "monkey",
    "1": "text",
    ...
  },
  "parameters": {
    "42": "Default",
    "43": "LineWidth",
    ...
  },
  "length": 3
}

HTTP Request

GET /webplayer/:version/project-datatypes

This will return JavaScript that sets a variable to the data types in the latest 1.5.x player (even though a specific version is present):

fetch('https://hs-tools-api.up.railway.app/webplayer/1.5.7/project-datatypes?var=datatypes')
  .then(r => r.text())
  .then(d => console.log(d))

curl "https://hs-tools-api.up.railway.app/webplayer/1.5.7/project-datatypes?var=datatypes"

200 OK

datatypes = {
  "blocks": {
    "19": "WaitTilTimestamp",
    "20": "WaitUntilInputIsDone",
    ...
  },
  ...
  "length": 3
}

Request Parameters

Call a function called foo with the data types as input, based on webplayer 1.5.12 instead of the newest version:

fetch('https://hs-tools-api.up.railway.app/webplayer/1.5.12/project-datatypes?newest=0&callback=foo')
  .then(r => r.text())
  .then(d => console.log(d))

curl "https://hs-tools-api.up.railway.app/webplayer/1.5.12/project-datatypes?newest=0&callback=foo"

Request Query

For example, if you GET /webplayer/1.5.11/project-datatypes but the latest is 1.5.20, the response will be the 1.5.20 data types instead of the version you provided (webplayer 1.5.11). Set the newest flag to 0 if you do not want this behavior.

Sample Response for non-existent version:

404 Not Found

null

Response Data

The response contains the JavaScript code for the webplayer, exactly as retrieved from Hopscotch's servers.

For example, in 19: "waitTilTimestamp", 19 is the ID of the block, and "waitTilTimestamp" is the name. The same applies to objects and parameters.

Modding on the Fly

You can have the power of the modded webplayer anywhere! With this API endpoint, you can choose the mods applied to the latest webplayer and create a completely customized version of it.

HTTP Request

GET /webplayer/:version/project-datatypes

Mod the latest 1.5 webplayer with default settings

fetch('https://hs-tools-api.up.railway.app/webplayer/1.5.0/modded')
  .then(r => r.json())
  .then(d => console.log(d))

curl "https://hs-tools-api.up.railway.app/webplayer/1.5.0/modded"

Request Parameters

Mod webplayer version 1.5.12 with default settings

fetch('https://hs-tools-api.up.railway.app/webplayer/1.5.12/modded?newest=0')
  .then(r => r.text())
  .then(d => console.log(d))

curl "https://hs-tools-api.up.railway.app/webplayer/1.5.12/modded?newest=0"

Sample Response (truncated for obvious reasons):

200 OK

/**
 * Hopscotch Technologies
 * Webplayer v1.5.20 - 2021/11/23 (production)
 */
console.log("Webplayer v1.5.20 - 2021/11/23 (production)");
!function(e){var t={}; ...

Request Query

Note: In a URL, a + is often decoded into a space when put in the URL query. So, decoding include=AE+CS results in include being set to AE CS

Whether or not a certain modification is included is determined in this order:

1. Is it specifically included? If so, include it. If not, continue.
2. Is it specifically excluded? If so, skip it. If not, continue.
3. Is ALL included? If so, include it. If not, continue.
4. Is ALL excluded? If so, exlcude it. If not, continue.
5. Use the default setting for this item.

Mod the latest 1.5 player, but only include the data retriever:

fetch('https://hs-tools-api.up.railway.app/webplayer/1.5.12/modded?exclude=ALL&include=DR')
  .then(r => r.text())
  .then(d => console.log(d))

curl -G "https://hs-tools-api.up.railway.app/webplayer/1.5.2/modded?exclude=ALL&include=DR"

200 OK

/**
 * Hopscotch Technologies
 * Webplayer v1.5.20 - 2021/11/23 (production)
 */
console.log("Webplayer v1.5.20 - 2021/11/23 (production)");
!function(e){var t={}; ...

Modify webplayer 1.2.5, including everything except modded actions, custom sounds, and inclusion of the modded action bundle:

const exclude = ['AE', 'CS', 'IW']
fetch('https://hs-tools-api.up.railway.app/webplayer/1.2.5/modded'
  + '?include=ALL'
  + '&exclude=' + exclude.join('+')
  + '&newest=0'
).then(r => r.text()).then(d => console.log(d))

curl -G "https://hs-tools-api.up.railway.app/webplayer/1.2.5/modded" \
  -d "include=ALL" \
  -d "exclude=AE+CS+IW" \
  -d "newest=0"

200 OK

function sendToApp(a,b,c){void 0===c&&(c="hopscotch");
var d=window.webkit;if(d&&d.messageHandlers){d.messageHandlers[c]
.postMessage((e={},e[a]=b,e));var e}} ...

In the case that the provided webplayer version does not exist:

404 Not Found

null

Available Modifications

Response Data

The webplayer's JavaScript code, modified with either the default settings or your custom configuration.