An API made in Java for accessing via your Java application...
Switch branches/tags
Nothing to show
Clone or download
Fetching latest commit…
Cannot retrieve the latest commit at this time.
Type Name Latest commit message Commit time
Failed to load latest commit information.


ScratchAPI is a simple Java interface to the Scratch 2.0 website. It is not nearly done yet, and will later include several features, but it takes time. :P

Build Status Gitter

If you want to see a list of features to be added, click here > Also, if you're wondering why everything is indented with 8-width tabs, it's because GitHub is being irritating. They are supposed to be 4 spaces.


Jump to Section

Session Management

Create a user session and log in:

ScratchSession session = Scratch.createSession("username", "password");

Register a new user (might now work, but it might! Try it out!):

ScratchSession session = Scratch.register("username", "password", "gender", birthMonth, "birthYear", "location", ""); // All fields case sensitive-- to be documented better later...

Get information about the session:

String username = session.getUsername();
String csrftoken = session.getCSRFToken();
String expiration = session.getExpiration();
String sessionid = session.getSessionID();
ScratchCloudSession cloudSession = session.getCloudSession(projectid); // Cloud sessions are documented a while down
ScratchUser user =;

Log session out:



Create a user instance:

ScratchUser user = new ScratchUser("username");

Get information about user:

user.update(); // Run this first! It updates the info about the user.
String username = user.getUsername();
String status = user.getStatus();
String bio = user.getBio();
String country = user.getCountry();
Date joinDate = user.getJoinDate();
int messageCount = user.getMessageCount();
List<ScratchProject> favoriteProjects = user.getFavoriteProjects(limit, offset); // limit max 20

Follow and unfollow the user:

user.setFollowing(session, true); // Follow user
user.setFollowing(session, false); // Unfollow user

Comment on user profile:

user.comment(session, "Example comment"); // You can't comment too fast, remember the delay


Create a project instance:

ScratchProject project = new ScratchProject(projectid); // 'projectid' is an int

Get information about project:

project.update(); // Run this before everything else
String title = project.getTitle();
String description = project.getDescription();
ScratchUser creator = project.getCreator();
int viewCount = project.getViewCount();
int loveCount = project.getLoveCount();
int favoriteCount = project.getFavoriteCount();
int projectid = project.getProjectID();
ScratchProjectManager manager = project.getProjectManager(); // Useless as of now
String resourceurl = project.getResourceURL();
String shareDate = project.getShareDate();
String thumbnailurl = project.getThumbnailURL();

Love and unlove the project:

project.setLoved(session, true); // Love project
project.setLoved(session, false); // Unlove project

Favorite and unfavorite the project:

project.setFavorited(session, true); // Favorite project
project.setFavorited(session, false); // Unfavorite project

Comment on project:

project.comment(session, "Example comment"); // You also can't comment too fast, remember the delay

Cloud Data Management

Create a cloud session:

ScratchCloudSession cloudSession = session.getCloudSession(projectid);

Add and remove a cloud event listener:

ScratchCloudListener listener = new ScratchCloudListener() {
    public void onSet(int projectID, String name, String value) {
        // insert code here...	
    // Later TODO add onEnd

cloudSession.addCloudListener(listener); // add
cloudSession.removeCloudListener(listener); // remove

Get the cloud symbol (☁):

char cloudSymbol = Scratch.CLOUD;

Get information about cloud session:

int projectid = cloudSession.getProjectID();
ScratchSession session = cloudSession.getScratchSession();
String cloudToken = cloudSession.getCloudToken();

Get a list of cloud variables:

List<String> variables = cloudSession.getVariables();

Get a cloud variable's contents:

String contents = cloudSession.get(Scratch.CLOUD + " variable"); // The space is needed!

Set a cloud variable's contents:

cloudSession.set(Scratch.CLOUD + " variable", "new value"); // Strings should work...

Rename a cloud variable (untested):

cloudSession.rename(Scratch.CLOUD + " variable", Scratch.CLOUD + " new name");

Create a cloud variable (untested):

cloudSession.create(Scratch.CLOUD + " newVariable", "value");

Delete a cloud variable (untested):

cloudSession.delete(Scratch.CLOUD + " variable");

Close the cloud session:



Get total project count:

 // Updates every 24hrs (thanks @thisandagain)
int totalProjectCount = ScratchStatistics.getProjectCount();
int totalStudioCount = ScratchStatistics.getStudioCount();
int totalUserCount = ScratchStatistics.getUserCount();
int totalCommentCount = ScratchStatistics.getCommentCount();
Date timestamp = ScratchStatistics.getTimestamp(); 


Set the default User-Agent:

Scratch.setUserAgent("insert User-Agent here");

Get a list of Scratch users:

List<ScratchUser> users = Scratch.getUsers(limit, offset); // Max limit is 20


List of exceptions:


Follow yourself and kaj

new ScratchUser(session.getUsername()).setFollowing(session, true); // Yourself
new ScratchUser("kaj").setFollowing(session, true); // Kaj

Open alert dialog when you get a message

final String user = "griffpatch"; // Change this to your username!
Timer timer = new Timer();
timer.schedule(new TimerTask() {
	public ScratchUser target = new ScratchUser(user);
	public int previous = -1;
	public void run() {
		try {
			int count = target.getMessageCount();
			if(previous == -1) {
				previous = count; // This means the program just started.
			} else 
				if(count > previous) {
					previous = count;
					javax.swing.JOptionPane.showMessageDialog(null, "The account " + user + " on Scratch now has " + count + " messages.");
		} catch (Exception e) {
}, 0, 5 * 1000); // Updates every 5 seconds

Warning: if you are famous, the number of dialogs from your messages will seriously get annoying.