├── .gitignore ├── README.md ├── api ├── accounts.md ├── comments.md ├── definitions │ ├── activity_event_object.md │ ├── comment_object.md │ ├── comment_rejection_object.md │ ├── message_object.md │ ├── news_object.md │ ├── project_object.md │ ├── studio_object.md │ └── user_object.md ├── explore_search.md ├── index.md ├── news.md ├── project_data.md ├── projects.md ├── proxy.md ├── studios.md ├── synth_trans.md └── users.md └── etc ├── authentication.md ├── index.md └── limits_and_offsets.md /.gitignore: -------------------------------------------------------------------------------- 1 | .DS_Store 2 | -------------------------------------------------------------------------------- /README.md: -------------------------------------------------------------------------------- 1 | *(Quick links to: [/api/ API reference](https://towerofnix.github.io/scratch-api-unofficial-docs/api/), [/etc/ additional documentation](https://towerofnix.github.io/scratch-api-unofficial-docs/etc/).)* 2 | 3 | Welcome to the Scratch API Unofficial Documentation! This wiki is an organized place to put all the information the community has gathered about the new Scratch API. 4 | 5 | ## Things for you to do: 6 | 7 | **If you have a bunch of information about an API:** Feel free to fork, write documentation, and make a pull request to here! 8 | 9 | **If you know of an API but not a lot about it:** A good idea would be to [make an issue](https://github.com/towerofnix/scratch-api-unofficial-docs/issues/new) about it. Please give us sources of where you got the information about it, and/or any information you have about it. 10 | 11 | **If you're just looking around:** Keep on reading to learn a little bit more about the APIs! You can find the documentation in [/api/](api/) and you can find other API-related things in [/etc/](etc/) (or use the links at the top of this page). 12 | 13 | ## What is the Scratch API? 14 | 15 | The Scratch API is an online API for using information from [Scratch](https://scratch.mit.edu/). It's steadily being developed by the [Scratch Team](https://scratch.mit.edu/info/credits/), and is part of their [upgrade](https://scratch.mit.edu/discuss/topic/163894/) to the Scratch site. There used to be an old API that was fairly well documented, but [it was deprecated](https://scratch.mit.edu/discuss/post/1552554/) on October 26th 2015, and with the new, fresh API coming with the upgrade to the site we (the folk on [the Advanced Topics](http://scratch.mit.edu/discuss/31/) and [everyone who's contributed to this repo!](https://github.com/towerofnix/scratch-api-unofficial-docs/graphs/contributors)) decided to write more up-to-date documentation. 16 | 17 | ## How can you use the Scratch API? 18 | 19 | Simple enough - say you want to get the number of projects currently made. You'd just send a `GET` request to the API page `/projects/count/all`. This can be as simple as opening the API page in your browser: [`https://api.scratch.mit.edu/projects/count/all`](https://api.scratch.mit.edu/projects/count/all). 20 | 21 | Many of the things on the API are going to be more useful to software developers, but it can be fun for anybody just to look around and experiment, too. 22 | 23 | The output of a request is generally (supposed to be) a JSON object. Most programming languages have functions such as [`JSON.parse`](https://developer.mozilla.org/en/docs/Web/JavaScript/Reference/Global_Objects/JSON/parse) to use the data. 24 | 25 | You can also use a built-by-the-community programming library like [scratch-api (Node.js)](https://www.npmjs.com/package/scratch-api) or [scratchapi (Python)](https://github.com/PolyEdge/scratchapi) to connect to the API. 26 | -------------------------------------------------------------------------------- /api/accounts.md: -------------------------------------------------------------------------------- 1 | # `/accounts` API 2 | 3 | The accounts API deals with authentication and username-related operations. 4 | 5 | ## `GET /accounts/checkusername/` 6 | 7 | Gets the status of a _username_, not to be confused with a _user_. Returns: 8 | 9 | ```json 10 | { 11 | "username": String, 12 | "msg": String 13 | } 14 | ``` 15 | 16 | The value of the `msg` property can be "username exists", "valid username", or "bad username". -------------------------------------------------------------------------------- /api/comments.md: -------------------------------------------------------------------------------- 1 | # `/comments` API 2 | 3 | There aren't any endpoints under `/comments` at the time of writing, but you may be looking for these endpoints instead: 4 | 5 | - Getting comments on a project: 6 | - [`GET /users//projects//comments`](users.md#get-usersusernameprojectsidcomments): get top-level comments on a project 7 | - [`GET /users//projects//comments/`](users.md#get-usersusernameprojectsidcommentsid): get a single comment on a project 8 | - [`GET /users//projects//comments//replies`](users.md#get-usersusernameprojectsidcommentsidreplies): get replies to a comment on a project 9 | - Sending & deleting comments on a project: 10 | - [`POST /proxy/comments/project/`](proxy.md#post-proxycommentprojectid): add a comment on a project 11 | - [`DELETE /proxy/comments/project//comment/`](proxy.md#post-proxycommentprojectidcommentid): remove a comment on a project 12 | - Getting comments on a studio: 13 | - [`GET /studios//comments`](studios.md#get-studiosidcomments): get top-level comments on a studio 14 | - [`GET /studios//comments/`](studios.md#get-studiosidcommentsid): get a single comment on a studio 15 | - [`GET /studios//comments//replies`](studios.md#get-studiosidcommentsidreplies): get replies to a comment on a studio 16 | - Sending & deleting comments on a studio: 17 | - [`POST /proxy/comments/studio/`](proxy.md#post-proxycommentsstudioid): add a comment on a studio 18 | - [`DELETE /proxy/comments/studio//comment/`](proxy.md#post-proxycommentsstudioidcommentid): remove a comment on a studio 19 | -------------------------------------------------------------------------------- /api/definitions/activity_event_object.md: -------------------------------------------------------------------------------- 1 | # Activity Event Object 2 | 3 | An activity event object looks like this: 4 | 5 | ``` 6 | { 7 | "actor": { 8 | "admin": /* If the user is an admin or not */ 9 | "pk": /* User's ID */ 10 | "thumbnail_url": /* URL to the user's thumbnail */ 11 | "username": /* User's username */ 12 | } 13 | "datetime_created": /* Date of the event */ 14 | "extra_data": /* Data object specific to the type of event - see below */ 15 | "message": /* HTML display message */ 16 | "obj_id": /* Message ID */ 17 | "pk": /* ??? */ 18 | "type": /* Numeric type of event - see below */ 19 | } ... 20 | ``` 21 | 22 | Note that `actor` isn't a [User Object](user_object.md). 23 | 24 | #### Event Types 25 | 26 | ##### 0 - User follow 27 | 28 | ``` 29 | { 30 | "followee_username": /* Username of the user who was followed */ 31 | } 32 | ``` 33 | 34 | ##### 1 - Studio follow 35 | 36 | ``` 37 | { 38 | "studio_title": /* The title of the studio that was followed */ 39 | } 40 | ``` 41 | 42 | ##### 2 - Project love 43 | 44 | ``` 45 | { 46 | "project_title": /* Title of the loved project */ 47 | } 48 | ``` 49 | 50 | ##### 3 - Project favorite 51 | 52 | ``` 53 | { 54 | "project_title": /* Title of the favorited project */ 55 | } 56 | ``` 57 | 58 | ##### 9 - Studio curation 59 | 60 | ``` 61 | { 62 | "invitor_username": /* Username of the user who invited the new curator */ 63 | "studio_title": /* Title of the studio the new curator was invited to */ 64 | } 65 | ``` 66 | 67 | ##### 10 - Project shared 68 | 69 | ``` 70 | { 71 | "project_title": /* Title of the shared project */ 72 | } 73 | ``` 74 | 75 | ##### 11 - Project remixed 76 | 77 | ``` 78 | { 79 | "parent_id": /* ID of the project that got remixed */ 80 | "parent_title": /* Title of the project that got remixed */ 81 | "project_title": /* Title of the remix project */ 82 | } 83 | ``` 84 | 85 | ##### 22 - Studio promotion 86 | 87 | ``` 88 | { 89 | "invited_username": /* Username of the promoted user */ 90 | "invitor_username": /* Username of the user who promoted the promoted user */ 91 | "studio_title": /* Title of the studio the user was promoted in */ 92 | } 93 | ``` 94 | -------------------------------------------------------------------------------- /api/definitions/comment_object.md: -------------------------------------------------------------------------------- 1 | # Comment Object 2 | 3 | A comment object looks like this: 4 | 5 | ``` 6 | { 7 | "id": /* The comment's ID */ 8 | "author": { 9 | "id": /* The author's user ID */ 10 | "username": /* The author's username */ 11 | "image": /* The URL of the author's profile picure */ 12 | "scratchteam": /* Whether or not the author is a Scratch Team member */ 13 | } 14 | "parent_id": /* The parent comment's ID, or null if a top-level comment */ 15 | "commentee_id": /* The ID of the user replied to, or null if a top-level comment */ 16 | "content": /* The text content of the comment */ 17 | "datetime_created": /* The timestamp when the comment was sent */ 18 | "datetime_modified": /* The timestamp when the comment was last modified */ 19 | "reply_count": /* How many replies the comment has, or 0 for a reply */ 20 | } 21 | ``` 22 | -------------------------------------------------------------------------------- /api/definitions/comment_rejection_object.md: -------------------------------------------------------------------------------- 1 | # Comment Rejection Object 2 | 3 | *Note: Info here isn't 100% complete, since we don't have sample information for what most comment rejection objects actually look like.* 4 | 5 | A comment rejection object looks like this: 6 | 7 | ``` 8 | { 9 | rejected: /* Rejection code - see below */ 10 | status: /* (optional) Status object with rejection details - see below */ 11 | appealId: /* (if IP muted) Case number to contact ST with to appeal block */ 12 | } 13 | ``` 14 | 15 | The `rejected` property will be one of the following: 16 | 17 | - `"isEmpty"`: the comment is empty 18 | - `"isFlood"`: sending too many comments in a short period of time 19 | - `"isBad"`: content was caught by the filter bot 20 | - `"hasChatSite"`: content contained a link to a website with unmoderated chat 21 | - `"isSpam"`: same content has been posted too many times 22 | - `"isMuted"`: posted too many bad comments and account has been muted for the day 23 | - `"isUnconstructive"`: content was detected as being mean or disrespectful 24 | - `"isDisallowed"`: tried to post on a page where comments are disabled 25 | - `"isIPMuted"`: comment sent from a network blocked for breaking the community guidelines too many times 26 | - `"isTooLong"`: content surpasses maximum comment length 27 | - `"isNotPermitted"`: user email address hasn't been confirmed yet 28 | 29 | The `status` property, if present, may have a `mute_status` property. This object will look like this: 30 | 31 | ``` 32 | { 33 | offenses: /* Array of offense objects */ 34 | showWarning: /* Override to always show warning regardless of offense list */ 35 | muteExpiresAt: /* When the user will be unmuted (*1000 to convert to Unix timestamp) */ 36 | currentMessageType: /* Latest(?) offense message type */ 37 | } 38 | ``` 39 | 40 | Offense objects look like this: 41 | 42 | ``` 43 | { 44 | createdAt: /* When the offense was caught (*1000 to convert to Unix timestamp) */ 45 | expiresAt: /* When the offense expires (*1000 to convert to Unix timestamp) */ 46 | messageType: /* What kind of offense was caught */ 47 | } 48 | ``` 49 | 50 | For example, an offense object might indicate it was caught today, expires in one week, and has the message type `"sexual"`. The `mute_status` it is part of may indicate the mute itself expires in only five minutes. 51 | -------------------------------------------------------------------------------- /api/definitions/message_object.md: -------------------------------------------------------------------------------- 1 | # Message Object 2 | 3 | A message object looks like this: 4 | 5 | ``` 6 | { 7 | "id": /* Message ID */ 8 | "datetime_created": /* The date of the notification */ 9 | "actor_username": /* The username of whoever acted (e.g. who loved your project) */ 10 | "actor_id": /* The ID of whoever acted */ 11 | "type": /* A message type */ 12 | /* ..And then type-specific properties; see below. */ 13 | } 14 | ``` 15 | 16 | ## Event Types 17 | 18 | * `followuser`: Somebody followed the user 19 | 20 | * `loveproject`: Somebody loved one of the user's projects 21 | 22 | ``` 23 | { 24 | "project_id": /* The ID of the project which was loved */ 25 | "title": /* The name of the project which was loved */ 26 | } 27 | ``` 28 | 29 | * `favoriteproject`: Somebody favorited one of the user's projects 30 | 31 | ``` 32 | { 33 | "project_id": /* The ID of the project which was favorited */ 34 | "title": /* The name of the project which was favorited */ 35 | } 36 | ``` 37 | 38 | * `remixproject`: Somebody remixed one of the user's projects 39 | 40 | ``` 41 | { 42 | "project_id": /* The ID of the remix */ 43 | "title": /* The name of the remix */ 44 | "parent_id": /* The ID of the project which was remixed */ 45 | "parent_title": /* The name of the project which was remixed */ 46 | } 47 | ``` 48 | 49 | * `addcomment`: Somebody made a comment 50 | 51 | ``` 52 | { 53 | "comment_type": /* A number referring to the type of place where the comment was posted (either 0, 1, or 2) */ 54 | "comment_obj_id": /* The ID of the place where the comment was posted */ 55 | "comment_obj_title": /* The name of where the comment was posted */ 56 | "comment_id": /* The ID of the comment */ 57 | "comment_fragment": /* The text content of the comment */ 58 | "commentee": /* The username of the person which the user replied to (or undefined, if nobody) */ 59 | } 60 | ``` 61 | 62 | The `comment_type` can have one of three values: 63 | 64 | * `0`: the comment was made on a project 65 | * `1`: the comment was made on a profile page 66 | * `2`: the comment was made in a studio's comment section 67 | 68 | `comment_obj_id` is just the ID that shows up in a URL; for example, if `comment_type` is 0, then the full URL for the comment is `https://scratch.mit.edu/projects//#comments-`. 69 | 70 | * `curatorinvite`: Somebody invited the user to a studio 71 | * `becomeownerstudio`: Somebody promoted the user to a manager in a studio 72 | * `studioactivity`: There was activity in a studio that the user is following 73 | 74 | All studio message types (`curatorinvite`, `becomeownerstudio`, and `studioactivity`) have this data: 75 | 76 | ``` 77 | { 78 | "gallery_id": /* The ID of the studio */ 79 | "title": /* The name of the studio */ 80 | } 81 | ``` 82 | 83 | * `forumpost`: Somebody made a new post in a forum thread that the user is following 84 | 85 | ``` 86 | { 87 | "topic_id": /* The ID of the topic */ 88 | "topic_title": /* The name of the topic */ 89 | } 90 | ``` 91 | 92 | * `userjoin` - The user joined Scratch (and was given this welcome notification) 93 | 94 | -------------------------------------------------------------------------------- /api/definitions/news_object.md: -------------------------------------------------------------------------------- 1 | # News Object 2 | 3 | A news object looks like this: 4 | 5 | ``` 6 | { 7 | "id": /* News entry ID */ 8 | "stamp": /* The timestamp at which the news entry was published */ 9 | "headline": /* The headline string */ 10 | "copy": /* The description string */ 11 | "image": /* The URL to the news icon */ 12 | "url": /* The URL to the complete news entry webpage (usually a forum topic or studio) */ 13 | } 14 | ``` 15 | -------------------------------------------------------------------------------- /api/definitions/project_object.md: -------------------------------------------------------------------------------- 1 | # Project Object 2 | 3 | A project object looks like this: 4 | 5 | ``` 6 | { 7 | "id": /* The project's ID */ 8 | "author": { 9 | "id": /* The author's user ID */ 10 | "username": /* The author's username */ 11 | } 12 | "title": /* The title of the project */ 13 | "instructions": /* The project's complete instructions (its Instructions field) */ 14 | "description": /* The project's complete 'description' (its Notes and Credits field) */ 15 | "is_published": /* Whether or not the project is shared */ 16 | "visibility": /* "notvisible" if the project is in the My Stuff trash section; "visible" otherwise */ 17 | "image": /* The URL of the project's thumbnail image */ 18 | "history": { 19 | "created": /* The timestamp when the project was first created (when the 'create' button was pressed) */ 20 | "shared": /* The timestamp when the project was shared */ 21 | "modified": /* The timestamp of the last time the project was modified */ 22 | } 23 | "stats": { 24 | "loves": /* The number of love-its the project has */ 25 | "favorites": /* The number of favorites the project has */ 26 | "views": /* The number of views the project has */ 27 | "remixes": /* The number of remixes the project has */ 28 | } 29 | "remix": { 30 | "root": /* The 'root' project in a remix tree; the top level, which is not a remix (null if this project is not a remix) */ 31 | "parent": /* The 'parent' project in a remix tree, which *may* be a remix (unset if this project is not a remix) */ 32 | } 33 | } 34 | ``` 35 | -------------------------------------------------------------------------------- /api/definitions/studio_object.md: -------------------------------------------------------------------------------- 1 | # Studio Object 2 | 3 | A studio object looks like htis: 4 | 5 | ``` 6 | { 7 | "id": /* The studio's ID */ 8 | "title": /* The title of the studio */ 9 | "host": /* The user ID of the studio's current host */ 10 | "description": /* The studio's complete description */ 11 | "visibility": /* The studio's visibility. */ 12 | "public": /* Whether or not the studio is public */ 13 | "open_to_all": /* Whether or not anyone can add projects to the studio */ 14 | "comments_allowed": /* Whether or not comments are allowed */ 15 | "image": /* The URL of the studio's thumbnail image */ 16 | "history": { 17 | "created": /* The timestamp of when the studio was created */ 18 | "modified": /* The timestamp of when the studio was last updated */ 19 | } 20 | "stats": { 21 | "comments": /* The number of comments on the studio */ 22 | "followers": /* The number of users who are following the studio */ 23 | "managers": /* The number of managers for the studio */ 24 | "projects": /* The number of projects in the studio */ 25 | } 26 | } 27 | ``` 28 | -------------------------------------------------------------------------------- /api/definitions/user_object.md: -------------------------------------------------------------------------------- 1 | # User Object 2 | 3 | A user object looks like this: 4 | 5 | ``` 6 | { 7 | "id": /* User ID */ 8 | "username": /* Username */ 9 | "history": { 10 | "joined": /* Date joined */ 11 | "login": /* Last login date? */ 12 | } 13 | "profile": { 14 | "id": /* Profile ID? */ 15 | "avatar": /* Part of a path to avatar? */ 16 | "status": /* What I'm working on */ 17 | "bio": /* About me */ 18 | } 19 | } 20 | ``` -------------------------------------------------------------------------------- /api/explore_search.md: -------------------------------------------------------------------------------- 1 | # `/explore` and `/search` APIs 2 | 3 | The explore API returns data regarding projects and studios according to a given sort order and optionally a search query. 4 | 5 | The search API returns the results of a search. 6 | 7 | ### `GET /explore/projects` 8 | 9 | Fetches projects according to a tag. Takes [typical `explore` and `search` options](#typical-explore-and-search-options). 10 | 11 | ### `GET /explore/studios` 12 | 13 | Fetches studios according to name. Takes [typical `explore` and `search` options](#typical-explore-and-search-options). 14 | 15 | ### `GET /search/projects` 16 | 17 | Searches for projects. Takes [typical `explore` and `search` options](#typical-explore-and-search-options). 18 | 19 | ### `GET /search/studios` 20 | 21 | Searches for studios. Takes [typical `explore` and `search` options](#typical-explore-and-search-options). 22 | 23 | ### Typical `explore` and `search` options 24 | 25 | All `explore` and `search` endpoints are [limited](../etc/limits_and_offsets.md) to 40 results per request, but return 20 by default. They all take the following options: 26 | 27 | * `?q`: Optional search query, to filter only results which match the query. Usually this means a matching name, but under `/explore/projects` it means a matching project tag. 28 | * `?mode`: "Search mode": how to sort results. Can be one of the following: `popular`, `trending`, `recent`. Defaults to `popular`. 29 | -------------------------------------------------------------------------------- /api/index.md: -------------------------------------------------------------------------------- 1 | # API documentation 2 | 3 | Unofficial documentation for the Scratch API. See [root index](..) for more information. 4 | 5 | ## API pages 6 | 7 | * [`/comments` API](comments.md) - Read comments 8 | * [`/explore` and `/search` APIs](explore_search.md) - View trending and search for projects and studios 9 | * [`/news` API](news.md) - Fetch news entries 10 | * [`/projects` API](projects.md) - Fetch project metadata 11 | * [`/proxy` API](proxy.md) - Miscellaneous utilities 12 | * [`/users` API](users.md) - Fetch user information 13 | * [`projects.` and `assets.` APIs](project_data.md) - Fetch code and assets used in projects 14 | * [`synthesis-service.` and `translation-service.` APIs](synth_trans.md) - Fetch translations and syntheses used by block extensions 15 | 16 | ### Object definitions 17 | 18 | * [Activity Event Object](definitions/activity_event_object.md) 19 | * [Comment Object](definitions/comment_object.md) 20 | * [Comment Rejection Object](definitions/comment_rejection_object.md) 21 | * [Message Object](definitions/message_object.md) 22 | * [News Object](definitions/news_object.md) 23 | * [Project Object](definitions/project_object.md) 24 | * [Studio Object](definitions/studio_object.md) 25 | * [User Object](definitions/user_object.md) 26 | -------------------------------------------------------------------------------- /api/news.md: -------------------------------------------------------------------------------- 1 | # `/news` API 2 | 3 | The news API returns data given to the "Scratch News" box on the homepage. 4 | 5 | ### `GET /news` 6 | 7 | Gets news items. Returns an array of [news objects](definitions/news_object.md). [Limited](../etc/limits_and_offsets.md) to 40 results per request, but returns 20 by default. 8 | -------------------------------------------------------------------------------- /api/project_data.md: -------------------------------------------------------------------------------- 1 | # `projects.` and `assets.` APIs 2 | 3 | These retrieve all of the data and files needed for a scratch project/file. 4 | 5 | ## `https://cdn.projects.scratch.mit.edu/` 6 | 7 | ### `GET //` 8 | 9 | Retrieves the projects JSON data, which is where all of the code for a scratch project is stored. 10 | 11 | ## `https://cdn.assets.scratch.mit.edu/` 12 | 13 | ### `GET /internalapi/asset//get/` 14 | 15 | Retrieves the asset with the given file name. An asset is a costume, sound or other file used in a project. Each asset in each project has a unique md5 id, which is used for referencing and retrieving it. 16 | 17 | The `` is a combination of this `md5 id`, and the file's format. For example: `106798711d0220a08cca12e750468e2b.png` 18 | -------------------------------------------------------------------------------- /api/projects.md: -------------------------------------------------------------------------------- 1 | # `/projects` API 2 | 3 | Returns data related to Scratch projects. 4 | 5 | ### `GET /projects/` 6 | 7 | Gets metadata about the project. Returns a [project object](definitions/project_object.md). If the project has not been shared, this endpoint [requires authentication](../etc/authentication.md). 8 | 9 | ### `GET /projects//remixes` 10 | 11 | Gets a list of remixes of the project. Returns an array of [project objects](definitions/project_object.md). [Limited](../etc/limits_and_offsets.md) to 40 results per request, but returns 20 by default. 12 | 13 | ### `GET /projects//studios` 14 | 15 | Gets a list of studios the project is added to. Returns an array of [studio objects](definitions/studio_object.md). [Limited](../etc/limits_and_offsets.md) to 40 results per request, but returns 20 by default. 16 | 17 | ### `GET /projects//favorites/user/` 18 | 19 | Gets whether or not the project has been loved by the user. [Requires authentication.](../etc/authentication.md) Returns an object that looks like this: 20 | 21 | ``` 22 | { 23 | "projectId": /* The ID of the project */ 24 | "userFavorite": /* True or false */ 25 | } 26 | ``` 27 | 28 | ### `GET /projects//loves/user/` 29 | 30 | Gets whether or not the project has been loved by the user. [Requires authentication.](../etc/authentication.md) Returns an object that looks like this: 31 | 32 | ``` 33 | { 34 | "projectId": /* The ID of the project */ 35 | "userLove": /* True or false */ 36 | } 37 | ``` 38 | 39 | ### `GET /projects/count/all` 40 | 41 | Gets the total number of projects that have been shared on the Scratch site, in this format: 42 | 43 | ``` 44 | { 45 | "count": /* Total number of projects shared */ 46 | } 47 | ``` 48 | -------------------------------------------------------------------------------- /api/proxy.md: -------------------------------------------------------------------------------- 1 | # `/proxy/` API 2 | 3 | The proxy API contains many utilities. The code for each endpoint under the proxy API interacts with the old Scratch API system; essentially, the proxy API is used for parts of the Scratch API which haven't yet been migrated. 4 | 5 | ### `GET /proxy/featured` 6 | 7 | Gets the projects featured on the homepage. Returns an object of which each of its properties' values are arrays of `/proxy`-specific project objects (not [normal project objects](definitions/project_object.md)): 8 | 9 | ``` 10 | { 11 | "community_featured_projects": /* Featured projects */ 12 | "community_featured_studios": /* Featured studios */ 13 | "community_most_loved_projects": /* What the community is loving / top loved projects */ 14 | "community_most_remixed_projects": /* What the community is remixing / top remixed projects */ 15 | "community_newest_projects": /* Recently shared projects */ 16 | "curator_top_projects": /* Curated projects */ 17 | "scratch_design_studio": /* Projects in the Scratch Design Studio */ 18 | } 19 | ``` 20 | 21 | Each item in any of those arrays is a project, and follows this format: 22 | 23 | ``` 24 | { 25 | "creator": /* Username of the user who created the project */ 26 | "id": /* The project's ID */ 27 | "love_count": /* How many people have clicked the love button on the project's page */ 28 | "remixers_count": /* How many people have remixed the project */ 29 | "thumbnail_url": /* URL to the project's thumbnail */ 30 | "title": /* The project's title */ 31 | "type": "project" 32 | } 33 | ``` 34 | 35 | ### `POST /proxy/comments/project/` 36 | 37 | Sends a new comment (top-level or reply) on the project. [Requires authentication.](../etc/authentication.md) The request body should be a JSON string following this format: 38 | 39 | ``` 40 | { 41 | "content": /* Content of the comment */ 42 | "parent_id": /* ID of the comment to reply to, or empty string if top-level */ 43 | "commentee_id": /* ID of the user to mention at the start of the comment, or empty string if none */ 44 | } 45 | ``` 46 | 47 | If successful, returns a [comment object](definitions/comment_object.md). If the comment is rejected, returns a [comment rejection object](definitions/comment_rejection_object.md). (Note this response will still be 200 OK.) 48 | 49 | *(References: [`views/preview/comment/compose-comment.jsx`](https://github.com/scratchfoundation/scratch-www/blob/1534b8938e97bd5bbe2c5bec965545a24ac3202c/src/views/preview/comment/compose-comment.jsx#L80-L149), [`views/preview/presentation.jsx`](https://github.com/scratchfoundation/scratch-www/blob/1534b8938e97bd5bbe2c5bec965545a24ac3202c/src/views/preview/presentation.jsx#L612))* 50 | 51 | ### `DELETE /proxy/comments/project//comment/` 52 | 53 | Deletes an existing comment on the project. [Requires authentication.](../etc/authentication.md) Returns an empty object. 54 | 55 | *(References: [`redux/project-comment-actions.js`](https://github.com/scratchfoundation/scratch-www/blob/1534b8938e97bd5bbe2c5bec965545a24ac3202c/src/redux/project-comment-actions.js#L117-L135))* 56 | 57 | ### `POST /proxy/comments/studio/` 58 | 59 | Sends a new comment (top-level or reply) on the project. [Requires authentication.](../etc/authentication.md) The request body should be a JSON string following this format: 60 | 61 | ``` 62 | { 63 | "content": /* Content of the comment */ 64 | "parent_id": /* ID of the comment to reply to, or empty string if top-level */ 65 | "commentee_id": /* ID of the user to mention at the start of the comment, or empty string if none */ 66 | } 67 | ``` 68 | 69 | If successful, returns a [comment object](definitions/comment_object.md). If the comment is rejected, returns a [comment rejection object](definitions/comment_rejection_object.md). (Note this response will still be 200 OK.) 70 | 71 | *(References: [`views/preview/comment/compose-comment.jsx`](https://github.com/scratchfoundation/scratch-www/blob/1534b8938e97bd5bbe2c5bec965545a24ac3202c/src/views/preview/comment/compose-comment.jsx#L80-L149), [`views/studio/studio-comments.jsx`](https://github.com/scratchfoundation/scratch-www/blob/1534b8938e97bd5bbe2c5bec965545a24ac3202c/src/views/studio/studio-comments.jsx#L216))* 72 | 73 | ### `DELETE /proxy/comments/studio//comment/` 74 | 75 | Deletes an existing comment on the studio. [Requires authentication.](../etc/authentication.md) Returns an empty object. 76 | 77 | *(References: [`redux/studio-comment-actions.js`](https://github.com/scratchfoundation/scratch-www/blob/1534b8938e97bd5bbe2c5bec965545a24ac3202c/src/redux/studio-comment-actions.js#L143-L163))* 78 | -------------------------------------------------------------------------------- /api/studios.md: -------------------------------------------------------------------------------- 1 | # `/studios/` API 2 | 3 | ### `GET /studios//comments` 4 | 5 | Gets a list of top-level comments created on the studio. Returns an array of [comment objects](definitions/comment_object.md). [Limited](../etc/limits_and_offsets.md) to 40 results per request, but returns 20 by default. 6 | 7 | *(References: [`redux/studio-comment-actions.js`](https://github.com/scratchfoundation/scratch-www/blob/1534b8938e97bd5bbe2c5bec965545a24ac3202c/src/redux/studio-comment-actions.js#L70-L106), [`views/studio/studio-comments.jsx`](https://github.com/scratchfoundation/scratch-www/blob/1534b8938e97bd5bbe2c5bec965545a24ac3202c/src/views/studio/studio-comments.jsx#L54-L60))* 8 | 9 | ### `GET /studios//comments/` 10 | 11 | Gets a single comment. Returns a [comment object](definitions/comment_object.md). 12 | 13 | *(References: [`redux/studio-comment-actions.js`](https://github.com/scratchfoundation/scratch-www/blob/1534b8938e97bd5bbe2c5bec965545a24ac3202c/src/redux/studio-comment-actions.js#L108-L141), [`views/studio/studio-comments.jsx`](https://github.com/scratchfoundation/scratch-www/blob/1534b8938e97bd5bbe2c5bec965545a24ac3202c/src/views/studio/studio-comments.jsx#L54-L60))* 14 | 15 | ### `GET /studios//comments//replies` 16 | 17 | Gets a list of replies to a top-level comment on the studio. Returns an array of [comment objects](defintiions/comment_object.md). [Limited](../etc/limits_and_offsets.md) to 40 results per request, but returns 20 by default. 18 | 19 | *(References: [`redux/project-comment-actions.js` #1](https://github.com/scratchfoundation/scratch-www/blob/1534b8938e97bd5bbe2c5bec965545a24ac3202c/src/redux/studio-comment-actions.js#L35-L68), [`redux/project-comment-actions.js` #2](https://github.com/scratchfoundation/scratch-www/blob/1534b8938e97bd5bbe2c5bec965545a24ac3202c/src/redux/studio-comment-actions.js#L94-L97), [`redux/project-comment-actions.js` #3](https://github.com/scratchfoundation/scratch-www/blob/1534b8938e97bd5bbe2c5bec965545a24ac3202c/src/redux/studio-comment-actions.js#L134-L139), [`views/studio/studio-comments.jsx`](https://github.com/scratchfoundation/scratch-www/blob/1534b8938e97bd5bbe2c5bec965545a24ac3202c/src/views/studio/studio-comments.jsx#L160-L167))* 20 | 21 | ### Sending & deleting comments 22 | 23 | Comments are sent and deleted through the [/proxy](proxy.md) API: 24 | 25 | - [`POST /proxy/comments/studio/`](proxy.md#post-proxycommentstudioid) 26 | - [`DELETE /proxy/comments/studio//comment/`](proxy.md#post-proxycommentstudioidcommentid) 27 | -------------------------------------------------------------------------------- /api/synth_trans.md: -------------------------------------------------------------------------------- 1 | # `synthesis-service.` and `translate-service.` APIs 2 | 3 | These retrieve the speech synthesis and translation results for their respective extensions. 4 | 5 | ## `https://translate-service.scratch.mit.edu/` 6 | 7 | ### `GET /translate?language=&text=` 8 | 9 | Retrieves the translation of the input text in the given language. `locale` is generally a two-letter language code. Refer to [this gist](https://gist.github.com/towerofnix/d4369e64604c5a0d7dca94954a83ab35) for a list of supported languages, or check the exports from [`scratch-translate-extension-languages`](https://www.npmjs.com/package/scratch-translate-extension-languages). 10 | 11 | Uses Google Translate [as of Dec. 9, 2019](https://scratch.mit.edu/discuss/post/3778811). 12 | 13 | ### `GET https://translate-service.scratch.mit.edu/supported` 14 | 15 | Retrieves a list of supported language codes for translating text. 16 | 17 | Legacy endpoint - still online, but [no longer used](https://github.com/scratchfoundation/scratch-vm/pull/1159). 18 | 19 | ## `https://synthesis-service.scratch.mit.edu/` 20 | 21 | ### `GET /synth?locale=&gender=&text=` 22 | 23 | Retrieves the synthesis of the input text as an audio file. `gender` is either "male" or "female"; `speech locale` is a "speech synth locale" as described in [the extension's source code](https://github.com/scratchfoundation/scratch-vm/blob/489111f4d74909c2adac40ade1618f966ba30c34/src/extensions/scratch3_text2speech/index.js#L194-L341). 24 | 25 | Likely uses [Amazon Polly](https://aws.amazon.com/polly/). 26 | -------------------------------------------------------------------------------- /api/users.md: -------------------------------------------------------------------------------- 1 | # `/users/` API 2 | 3 | ### `GET /users/` 4 | 5 | Gets metadata about the user. Returns a [user object](definitions/user_object.md). 6 | 7 | ### `GET /users//projects` 8 | 9 | Gets a list of projects that have been shared by the user. Note that it returns oldest projects first; use [`offset`](../etc/limits_and_offsets.md) to find more recent projects. 10 | 11 | Returns an array of [project objects](definitions/project_object.md). [Limited](../etc/limits_and_offsets.md) to 40 results per request, but returns 20 by default. 12 | 13 | ### `GET /users//projects/` 14 | 15 | Gets a specific project created by the user, given its unique project ID. Returns a [project object](definitions/project_object.md). 16 | 17 | ### `GET /users//studios/curate` 18 | 19 | Gets a list of studios that the user curates. Returns an array of [studio objects](definitions/studio_object.md). [Limited](../etc/limits_and_offsets.md) to 40 results per request, but returns 20 by default. 20 | 21 | ### `GET /users//favorites` 22 | 23 | Gets a list of projects that have recently been favorited by the user. Returns an array of [project objects](definitions/project_object.md). [Limited](../etc/limits_and_offsets.md) to 40 results per request, but returns 20 by default. 24 | 25 | ### `GET /users//followers` 26 | 27 | Gets the users that are following the user. Returns an array of [user objects](definitions/user_object.md). [Limited](../etc/limits_and_offsets.md) to 40 results per request, but returns 20 by default. 28 | 29 | ### `GET /users//following` 30 | 31 | Gets the users that the user is following. Returns an array of [user objects](definitions/user_object.md). [Limited](../etc/limits_and_offsets.md) to 40 results per request, but returns 20 by default. 32 | 33 | ### `GET /users//following/studios/projects` 34 | 35 | Gets a list of projects that have recently been added to studios that the given user is following. Returns an array of [project objects](definitions/project_object.md). [Requires authentication.](../etc/authentication.md) 36 | 37 | ### `GET /users//following/users/loves` 38 | 39 | Gets a list of projects that have recently been loved by users that the given user is following. Shows up as "Projects Loved by Scratchers I'm Following" on the front page. Returns an array of [project objects](definitions/project_object.md). [Requires authentication.](../etc/authentication.md) 40 | 41 | ### `GET /users//following/users/projects` 42 | 43 | Gets a list of projects that have recently been shared by users that the given user is following. Returns an array of [project objects](definitions/project_object.md). [Requires authentication.](../etc/authentication.md) 44 | 45 | ### `GET /users//following/users/activity` 46 | 47 | Gets events that show up in the "What's Happening" feed on the front page. Returns an array of [activity event objects](definitions/activity_event_object.md). [Requires authentication.](../etc/authentication.md) 48 | 49 | ### `GET /users//messages` 50 | 51 | Gets the content of all messages the user has (including both read and unread ones). Returns an array of [message objects](definitions/message_object.md). [Limited](../etc/limits_and_offsets.md) to 40 results per request, but returns 20 by default. [Requires authentication.](../etc/authentication.md) 52 | 53 | ### `GET /users//messages/count` 54 | 55 | Gets the number of notifications the user currently has (this is the bubble-number displayed in the navigation bar). 56 | 57 | Returns an object in this format: 58 | 59 | ``` 60 | { 61 | "count": /* Number of messages the user currently has */ 62 | } 63 | ``` 64 | 65 | ### `GET /users//projects//comments` 66 | 67 | Gets a list of top-level comments created on the project. Returns an array of [comment objects](definitions/comment_object.md). [Limited](../etc/limits_and_offsets.md) to 40 results per request, but returns 20 by default. 68 | 69 | *(References: [`redux/project-comment-actions.js`](https://github.com/scratchfoundation/scratch-www/blob/1534b8938e97bd5bbe2c5bec965545a24ac3202c/src/redux/project-comment-actions.js#L54-L84), [`views/preview/project-view.jsx`](https://github.com/scratchfoundation/scratch-www/blob/1534b8938e97bd5bbe2c5bec965545a24ac3202c/src/views/preview/project-view.jsx#L182-L183))* 70 | 71 | ### `GET /users//projects//comments/` 72 | 73 | Gets a single comment. Returns a [comment object](definitions/comment_object.md). 74 | 75 | *(References: [`redux/project-comment-actions.js`](https://github.com/scratchfoundation/scratch-www/blob/1534b8938e97bd5bbe2c5bec965545a24ac3202c/src/redux/project-comment-actions.js#L86-L115), [`views/preview/project-view.jsx`](https://github.com/scratchfoundation/scratch-www/blob/1534b8938e97bd5bbe2c5bec965545a24ac3202c/src/views/preview/project-view.jsx#L179-L180))* 76 | 77 | ### `GET /user//projects//comments//replies` 78 | 79 | Gets a list of replies to a top-level comment on the project. Returns an array of [comment objects](defintiions/comment_object.md). [Limited](../etc/limits_and_offsets.md) to 40 results per request, but returns 20 by default. 80 | 81 | *(References: [`redux/project-comment-actions.js` #1](https://github.com/scratchfoundation/scratch-www/blob/1534b8938e97bd5bbe2c5bec965545a24ac3202c/src/redux/project-comment-actions.js#L25-L52), [`redux/project-comment-actions.js` #2](https://github.com/scratchfoundation/scratch-www/blob/1534b8938e97bd5bbe2c5bec965545a24ac3202c/src/redux/project-comment-actions.js#L73-L76), [`redux/project-comment-actions.js` #3](https://github.com/scratchfoundation/scratch-www/blob/1534b8938e97bd5bbe2c5bec965545a24ac3202c/src/redux/project-comment-actions.js#L108-L113), [`views/preview/project-view.jsx`](https://github.com/scratchfoundation/scratch-www/blob/1534b8938e97bd5bbe2c5bec965545a24ac3202c/src/views/preview/project-view.jsx#L576-L578))* 82 | 83 | ### Sending & deleting comments 84 | 85 | Comments are sent and deleted through the [/proxy](proxy.md) API: 86 | 87 | - [`POST /proxy/comments/project/`](proxy.md#post-proxycommentprojectid) 88 | - [`DELETE /proxy/comments/project//comment/`](proxy.md#post-proxycommentprojectidcommentid) 89 | -------------------------------------------------------------------------------- /etc/authentication.md: -------------------------------------------------------------------------------- 1 | # Authentication 2 | 3 | Some API endpoints require you to authenticate that you are a specific person (for example, when you're trying to access private information, like notifications). 4 | 5 | ## From devtools 6 | Authentication is done by giving a token to the endpoint URL of the API you're using. This token can be accessed from the URL https://scratch.mit.edu/session/ (note that this is on scratch.mit.edu, not the API site) as long as an `X-Requested-With` header is present with a value of `XMLHttpRequest`. The easiest way to fetch the token manually is to go to the Scratch home page in a browser, open developer tools, and locate the request to `/session` in the "Network" tab. The token is given to API endpoints by appending the query `x-token=`; for example `https://api.scratch.mit.edu/users//messages?x-token=`. 7 | 8 | ## With username and password 9 | 10 | > ⚠️ Logging in with a username and password in public applications is _highly_ discouraged since it puts the responsibility on you to prevent man-in-the-middle attacks. Asking for a username and password may also make your app seem suspicious for phishing. 11 | 12 | To log in with a username and password, you need to make a `POST` request to `https://scratch.mit.edu/accounts/login/` and a JSON body containing the `username` and `password` as well as a boolean called [`useMessages`](#what-is-usemessages). The `Referer` and `Origin` headers must be set to `https://scratch.mit.edu`, and a cookie must be passed with containing a [CSRF token](https://en.wikipedia.org/wiki/Cross-site_request_forgery) and a language. This can be a little confusing - below is an example request made with [`node-fetch`](https://npmjs.com/node-fetch) (a common request library for Node.js): 13 | 14 | ```javascript 15 | fetch("https://scratch.mit.edu/accounts/login/", { 16 | credentials: "include", // this ensures that cookies are sent 17 | method: "POST", 18 | headers: { 19 | "Cookie": "scratchcsrftoken=a; scratchlanguage=en", 20 | // ^ this can be anything, as long as it matches the X-CSRFToken header below 21 | "Origin": "https://scratch.mit.edu", 22 | "Referer": "https://scratch.mit.edu/", 23 | "X-CSRFToken": "a", 24 | "X-Requested-With": "XMLHttpRequest", 25 | "Content-Type": "application/json", 26 | }, 27 | body: '{ 28 | "useMessages": true, 29 | "username": "myCoolUsername", 30 | "password": "myPassword", 31 | }', 32 | }); 33 | ``` 34 | 35 | The various implementations of this request will vary based on your chosen language and request library. However, note that credentials (cookies) must be included and you must make the request from a server or native app due to [CORS](https://developer.mozilla.org/en-US/docs/Web/HTTP/CORS) restrictions. 36 | 37 | ### What is `useMessages`? 38 | We don't know for sure what `useMessages` is for since the login API is part of the older [scratchr2](https://scratch.mit.edu/discuss/topic/6865/) version of the Scratch website which is not open-source. However, it's been seen that [requests can fail](https://ocular.jeffalo.net/post/4924768) if the request body doesn't contain it. -------------------------------------------------------------------------------- /etc/index.md: -------------------------------------------------------------------------------- 1 | # Miscellaneous information 2 | 3 | Pages with extra details on behavior of the Scratch API and how to make use of it. See [root index](..) for more information. 4 | 5 | ## Etc. pages 6 | 7 | * [Authentication](authentication.md) - How `x-token` works to authenticate viewing private data or acting on behalf of a user 8 | * [Limits and Offsets](limits_and_offsets.md) - How `limit` and `offset` work to fetch particular data from a large range 9 | -------------------------------------------------------------------------------- /etc/limits_and_offsets.md: -------------------------------------------------------------------------------- 1 | # Limits and Offsets 2 | 3 | Many API endpoints only return a maximum set number of results per request, when often more are wanted. The paramater `limit` can be changed to a number less than or equal to this maximum to decrease the number of users returned in the array, and the paramater `offset` can be set to offset the following selection - for example, `/users/foobar/following?offset=3&limit=2` will get the fourth and fifth most recent users the user foobar is following. 4 | --------------------------------------------------------------------------------