Revision as of 13:42, 20 August 2022 by Maximouse (talk | contribs) (Undo revision 313824 by Han614698 (talk): the obsolete template is not appropriate in this case because the feature is still "included in the current version of Scratch".)
(diff) ← Older revision | Latest revision (diff) | Newer revision → (diff)

This article or section documents the current version of Scratch (version 3.0). For this article in Scratch 1.4, see Scratch API (1.4).

The Scratch API is an interface which provides access to various instances of data in a mostly programmer-friendly manner. It can be used in many different ways in order to create applications which can send and extract data to and from the Scratch Website. The address of the current Scratch API is https://api.scratch.mit.edu.

Note Caution: Use the API responsibly and in keeping with the Terms of Use. Abuse of the API may result in a ban.[1]

api.scratch.mit.edu Interface

The api.scratch.mit.edu interface is the latest revision of the Scratch API. It can be used to return various types of data regarding the Scratch website. This API can be accessed via the following URL.

https://api.scratch.mit.edu

All endpoints that return an array accept query parameters named limit and offset, except /studios/<studio_id>/activity which only supports limit. limit is the maximum number of items in the response (up to 40). offset is the zero-based index of the first item in the response. For example, /users/mres/projects/142/comments?limit=3&offset=10 returns the 11th, 12th and 13th comment. The default limit is 20 and the default offset is 0.

GET /

The root of the api interface provides basic information regarding the API and the Scratch website.


Example Request
GET https://api.scratch.mit.edu
Example Response


Health

GET /health

Used to return the status of the Scratch website.


Example Request
GET https://api.scratch.mit.edu/health
Example Response


News

GET /news

Returns information regarding the "Scratch News" section of the homepage.


Example Request
GET https://api.scratch.mit.edu/news
Example Response


Projects

GET /projects/count/all

Returns the total number of shared projects on the Scratch website.


Example Request
GET https://api.scratch.mit.edu/projects/count/all
Example Response


GET /projects/<project_id>

Returns information about the project. The response is the same as /users/<username>/projects/<project_id> except that it includes the author's username.


Example Request
GET https://api.scratch.mit.edu/projects/142
Example Response


GET /projects/<project_id>/remixes

Returns an array of the project's remixes.


Example Request
GET https://api.scratch.mit.edu/projects/142/remixes
Example Response


Studios

GET /studios/<studio_id>

Returns information about the studio.


Example Request
GET https://api.scratch.mit.edu/studios/31659696
Example Response


GET /studios/<studio_id>/projects

Returns an array of projects in the studio.


Example Request
GET https://api.scratch.mit.edu/studios/31659696/projects
Example Response


GET /studios/<studio_id>/managers

Returns an array of the studio's managers.


Example Request
GET https://api.scratch.mit.edu/studios/31659696/managers
Example Response


GET /studios/<studio_id>/curators

Returns an array of the studio's curators.


Example Request
GET https://api.scratch.mit.edu/studios/31659696/curators
Example Response


GET /studios/<studio_id>/activity?dateLimit=<date>

Returns an array of events related to the studio's activity. The dateLimit is optional: if specified, the response will contain events at least as old as the limit.


Example Request
GET https://api.scratch.mit.edu/studios/31659696/activity?dateLimit=2022-07-09T13:35:07.000Z
Example Response


GET /studios/<studio_id>/comments

Returns an array of comments posted in the studio. Replies are not included in the response, so a separate request needs to be made for each comment with a "reply_count" greater than 0.


Example Request
GET https://api.scratch.mit.edu/studios/5342/comments
Example Response


GET /studios/<studio_id>/comments/<comment_id>

Returns information about the studio comment.


Example Request
GET https://api.scratch.mit.edu/studios/5342/comments/121123167
Example Response


GET /studios/<studio_id>/comments/<comment_id>/replies

Returns an array of replies to the specified studio comment.


Example Request
GET https://api.scratch.mit.edu/studios/5342/comments/121123167/replies
Example Response


Proxy

GET /proxy/featured

Returns information regarding the projects currently visible on the front page of the website.


Example Request
GET https://api.scratch.mit.edu/proxy/featured
Example Response


Users

GET /users/<username>

Returns information about the specified user.


Example Request
GET https://api.scratch.mit.edu/users/mres
Example Response


GET /users/<username>/favorites

Returns an array of details regarding the projects that a given user has favourited on the website.


Example Request
GET https://api.scratch.mit.edu/users/mres/favorites
Example Response


GET /users/<username>/followers

Returns a list of a user's most recent followers.


Example Request
GET https://api.scratch.mit.edu/users/mres/followers
Example Response


GET /users/<username>/following

Returns a list of the users that the specified user has most recently followed.


Example Request
GET https://api.scratch.mit.edu/users/mres/following
Example Response


GET /users/<username>/messages/count

This returns the number of unread messages a user currently has. This is what the system looks for showing the message count.


Example Request
GET https://api.scratch.mit.edu/users/mres/messages/count
Example Response


GET /users/<username>/projects

Returns an array with information regarding the projects that a given user has shared on the Scratch website.


Example Request
GET https://api.scratch.mit.edu/users/mres/projects
Example Response


GET /users/<username>/projects/<project_id>

Returns information relevant to the given project.


Example Request
GET https://api.scratch.mit.edu/users/mres/projects/142
Example Response


GET /users/<username>/projects/<project_id>/studios

Returns an array of studios the project is in.


Example Request
GET https://api.scratch.mit.edu/users/mres/projects/142/studios
Example Response


GET /users/<username>/projects/<project_id>/comments

Returns an array of comments posted on the project. Replies are not included in the response, so a separate request needs to be made for each comment with a "reply_count" greater than 0.


Example Request
GET https://api.scratch.mit.edu/users/mres/projects/142/comments
Example Response


GET /users/<username>/projects/<project_id>/comments/<comment_id>

Returns information about the project comment.


Example Request
GET https://api.scratch.mit.edu/users/mres/projects/142/comments/272303677
Example Response


GET /users/<username>/projects/<project_id>/comments/<comment_id>/replies

Returns an array of replies to the specified project comment.


Example Request
GET https://api.scratch.mit.edu/users/mres/projects/142/comments/272303677/replies
Example Response


GET /users/<username>/studios/curate

Returns an array of studios curated by the user.


Example Request
GET https://api.scratch.mit.edu/users/mres/studios/curate
Example Response


Accounts

GET /accounts/checkusername/<username>

Checks if a username can be registered. The "msg" property of the response object is "valid username" if it is available, "invalid username" if it is too short, too long or contains invalid characters, "username exists" if it is taken and "bad username" if it is inappropriate.


Example Request
GET https://api.scratch.mit.edu/accounts/checkusername/mres
Example Response


Explore

GET /explore/projects?q=<query>&mode=<mode>&language=<language_code>

Returns an array of projects displayed on the Projects tab of the Explore page. The query (q parameter) specifies which keywords to search for. It can be set to * or omitted to get all projects. The mode can be popular (default) or trending. A language code can be specified to prefer results in a certain language.


Example Request
GET https://api.scratch.mit.edu/explore/projects?q=games&mode=trending&language=en
Example Response


GET /explore/studios?q=<query>&mode=<mode>&language=<language_code>

Returns an array of studios displayed on the Studios tab of the Explore page. The query (q parameter) specifies which keywords to search for. It can be set to * or omitted to get all studios. The mode can be popular (default) or trending. A language code can be specified to prefer results in a certain language.


Example Request
GET https://api.scratch.mit.edu/explore/studios?q=animations&mode=trending&language=en
Example Response


Search

GET /search/projects?q=<query>&mode=<mode>&language=<language_code>

Searches for projects that match the query (q parameter). The mode can be popular (default) or trending. A language code can be specified but it does not affect the results.[citation needed]


Example Request
GET https://api.scratch.mit.edu/search/projects?q=scratch%203.0&mode=popular&language=en
Example Response


GET /search/studios?q=<query>&mode=<mode>&language=<language_code>

Searches for studios that match the query (q parameter). The mode can be popular (default) or trending. A language code can be specified but it does not affect the results.[citation needed]


Example Request
GET https://api.scratch.mit.edu/search/studios?q=scratch%20welcoming%20committee&mode=popular&language=en
Example Response


Removed endpoints

GET /proxy/users/<user_id>/featured

Returned information regarding the Projects by Scratchers I'm Following, Projects Loved by Scratchers I'm Following and Projects in Studios I'm Following rows on the Front Page. Each row now has its own API endpoint.


Example Request
GET https://api.scratch.mit.edu/proxy/users/167/featured
Example Response


GET /proxy/users/<username>/activity

Returned information regarding the "What's Happening?" section of the homepage for a given user. Moved to /users/<username>/following/users/activity.


Example Request
GET https://api.scratch.mit.edu/proxy/users/mres/activity
Example Response


GET /proxy/users/<username>/activity/count

Was used to return the number of unread messages a user currently has. Moved to /users/<username>/messages/count.


Example Request
GET https://api.scratch.mit.edu/proxy/users/mres/activity/count
Example Response


April Fools' Day, 2018

As an easter egg for April Fools' Day 2018, a counter endpoint was added.

POST /surprise

Increments the counter and returns its current value.


Example Request
POST https://api.scratch.mit.edu/surprise
Example Response


GET /surprise

Returns the counter's current value. This is cached on the server, and so might return an earlier value.


Example Request
GET https://api.scratch.mit.edu/surprise
Example Response


site-api Interface (Deprecated)

The site-api is a legacy interface which was officially deprecated on 25 October 2015, as announced by Scratch Team member, thisandagain.[2] It is still available though, and is used by some parts of the Scratch website. This API can be accessed via the following URL:

https://scratch.mit.edu/site-api/

Comments

GET /comments/gallery/<studio_id>/

Returns the comments on a studio in the form of raw HTML.


Example Request
GET https://scratch.mit.edu/site-api/comments/gallery/5342/
Example Response


GET /comments/project/<project_id>/

Returns the comments on a project in the form of raw HTML.


Example Request
GET https://scratch.mit.edu/site-api/comments/project/142/
Example Response


GET /comments/user/<username>/

Returns the comments on a given user's profile in the form of raw HTML.


Example Request
GET https://scratch.mit.edu/site-api/comments/user/mres/
Example Response


Request Headers

These are the request headers which may be filled out.

Host:
User-Agent:
Accept:
Accept-Language:
Accept-Encoding:
Content-Type:
X-CSRFToken:
X-Requested-With:
Referer:
Content-Length:
Cookie:
Connection:

varserver Interface (Removed)

Archive.png This article or section documents something not included in the current version of Scratch (3.0). It is only useful from a historical perspective.


The varserver API could be utilised to request the values of cloud variables in projects. This API could be accessed via the following URL. It is no longer available, and future requests will return 404 errors.[3]

https://scratch.mit.edu/varserver/

GET /<project_id>

Returned information regarding the cloud data of a given project.


Example Request
GET https://scratch.mit.edu/varserver/10080213
Example Response


api/v1 Interface (Removed)

Archive.png This article or section documents something not included in the current version of Scratch (3.0). It is only useful from a historical perspective.

As of 23 April 2018, the API v1 interface no longer exists queries to this path are immediately met with HTTP 403 errors.

The API v1 interface is a legacy interface which was originally built during the development of Scratch 2.0. It was accessed via the following URL.

https://scratch.mit.edu/api/v1/

GET /

The root of the API v1 interface provides basic information regarding the API.


Example Request
GET https://scratch.mit.edu/api/v1/
Example Response


Projects

GET /project/<project_id>/

Returns information regarding a project and its author.


Example Request
GET https://scratch.mit.edu/api/v1/project/142/
Example Response


GET /project/set/<project_ids>/

Returns information regarding a set of projects and their authors. Project IDs are separated with a semicolon.


Example Request
GET https://scratch.mit.edu/api/v1/project/set/142;864/
Example Response


Users

GET /user/<username>/

Returns information regarding the given user.


Example Request
GET https://scratch.mit.edu/api/v1/user/mres/
Example Response


GET /user/set/<usernames>/

Returns information regarding the given users. Names should be separated with semicolons. The "userprofile" value for each user object is currently empty making this feature of the API effectively useless. One should note that the single user feature remains functional.


Example Request
GET https://scratch.mit.edu/api/v1/user/set/mres;ScratchCat/
Example Response


See Also

External Links

SandCastleIcon.png This section has links to websites or programs not trusted by Scratch or hosted by Wikipedia. Remember to stay safe while using the internet, as we cannot guarantee the safety of other websites.

References

  1. Paddle2See. (15/11/2021). "Accounts have most definitely been blocked for abusing the API." post:5784428
  2. thisandagain. (26/10/2015). "The “site-api” endpoints are all deprecated as of today." post:1552554
  3. thisandagain. (22/5/2018). "Yup. That legacy system has been removed." users:thisandagain/#comments-45728731
Cookies help us deliver our services. By using our services, you agree to our use of cookies.