REST-based service API


All TouchDevelop scripts are stored and analyzed in the cloud. For research purposes, TouchDevelop exposes a set of web services to query scripts, users, comments, screenshots, reviews, leaderboard scores, and tags.


The TouchDevelop Cloud Services Agreement applies for the APIs described below.


The design of the web services is still under heavy development.

The APIs may change at any time without notice.

Recent changes: 2012-02-09: Completely new set of streamlined APIs under /api/ path. 2012-03-15: /api/[scriptid]/text now returns script text formatted according to latest internal language syntax; use optional ?original=true parameter to get old behavior. 2012-04-03: New APIs /api/[...]/subscribers, /api/[...]/subscriptions, /api/[...]/notifications, properties haspicture, subscribers 2012-04-27: New APIs /api/tags, /api/[tagid]/scripts, /api/[scriptid or userid]/tags, /api/[userid]/tagged/[tagid], kind tag, and properties userscore, userhaspicture, screenshots 2012-05-03: Most APIs now support ETag/If-None-Match headers; property now removed from lists; beginning of time redefined 2012-05-07: Renamed &text=... parameter to &q=... which is now supported in several APIs. 2012-06-04: New APIs /api/[userid]/reviewed/[scriptid or commentid] 2012-06-28: New APIs /api/[scriptid]/leaderboardscores, /api/[userid]/leaderboardscored/[scriptid] 2012-07-11: New batch API /api; new optional query parameter for lists: etagsmode 2012-08-02: New API /api/[userid]/tagged/[scriptid] 2012-08-14: Added librarydependencyids and toptagids as script properties 2012-08-16: Added optional return_ssl_resources parameter 2012-10-15: Added optional recent parameter for /api/[userid]/leaderboardscored/[scriptid], /api/[scriptid or userid]/leaderboardscores 2012-11-08: New APIs /api/[artid], /api/art, /api/[userid]/art queries and a new art kind 2012-11-20: New APIs /api/[artid]/scripts, /api/[scriptid]/art; added art as script property 2012-11-29: New APIs /api/documents; new document kind 2012-12-11: Added wavurl and aacurl as art properties 2013-01-31: Added documentation for feature properties 2013-03-08: Added userplatform properties 2013-03-21: Added API /api/stats 2013-07-10: Updated documentation for feature properties; new APIs /api/features, /api/[userid or scriptid]/features 2013-08-01: New APIs /api/runs, /api/runbuckets, /api/[scriptid]/runbuckets, /api/[runbucketid or userid]/runs, /api/[scriptid]/webast, /api/[scriptid]/coverage, /api/[scriptid]/profile; deprecated /api/[scriptid]/ast; new run and runbucket document kinds 2013-10-18: New APIs /api/webapps; webapp document kind 2013-12-05: Removed API /api/[scriptid]/ast 2014-05-20: Added mergeids script property 2014-07-20: Added ids= to /api/[scriptid]/text api. 2014-10-31: Added /api/[scriptid]/progress api. 2014-12-03: Added /api/[scriptid]/canexportapp/[userid] 2014-01-13: Changed /api/[scriptid]/progress to /api/[scriptid]/progressstats to avoid clash in routing 2014-01-27: Added iconArtId, splashArtId to script publication, modified callback API.


http, rest, json

All APIs are exposed as REST services; the APIs return either structured JSON objects, or plain text.


All APIs are exposed via URLs of the form The results of all requests under the /api/ prefix return results which are not meant for direct human consumption.

access restrictions

At this time, no authentication is required to invoke the APIs described below.

search query strings

See here for more documentation on the search query syntax: how to search.

count, continuation

When querying a list, you will get the results in batches. You can add the query parameter &count=[count] with a number between 10 and 1000 to indicate how many items you would like to get returned in each batch. However, the actually returned number of items may be different. You can add the query &applyupdates=true if you want that the latest update of all scripts is returned. The structured JSON response may contain a field called continuation. If this continuation token contains a non-empty string, then there might be more items available, which you can get by performing the exact same query again with the added query parameter &continuation=[continuation].

publication ids

Each script, user, comment, screenshot, review, tag has a unique id, in general referred to as its publication id. Publication ids are sequences of lower-case latin letters, at least four letters long. The ids are randomly assigned by TouchDevelop; the space of possible ids is only used sparcely. Do not try to guess ids; instead, use the APIs to enumerate assigned ids.


main lists

The following queries return lists that enumerate all available objects.

The following queries return lists that enumerate a particular subset of all available objects.


publication properties

Given a publication id, you can query certain properties: You can get the script text, or its compiled abstract syntax tree by querying /api/[scriptid]/text and /api/[scriptid]/webast. As the TouchDevelop language is evolving, the returned script text might changed. Use /text?original=true to obtain the script text as it was originally submitted.


JSON format

Each JSON-formatted response contains a kind field that states the type of the response; depending on the kind, other fields are available. The following kinds and other fields may be returned













run bucket

web app

ETag/If-None-Match headers

Every successful response contains an ETag header representing a stable hash derived form the content of the response. This hash can be passed in as part of a future request via a If-None-Match header. If the content matches the given hash, a 304 Not modified response status code is returned and the unchanged response content is omitted.

Using ETags in list queries

The optional query parameter &etagsmode=[etagsmode] for list queries can be used to reduce the data transfers required to perform queries and responses. The etagsmode can be one of the following.


To further reduce data transfers for requests with rarely changing responses, e.g. featured-scripts, you can indicate in the query that you already have obtained the information about a publication earlier. You do so by appending the etagsmode with a comma followed by a comma-separated list of id:ETag pairs.


If the query string gets long, or you want that it gets compressed, wrap the request in a batch request.

batch requests

You can bundle requests. Bundling involves encoding HTTP requests and responses in JSON form.

To perform a batch request, do a POST request to /api, with a JSON body containing a batch of requests. Unless the JSON body is malformed or there is a fundamental problem with the HTTP request, the main /api call should always return with a 200 OK, while all individual sub-requests have their own status codes embedded in a response JSON object.

At this time, a batch request may include at most 50 individual requests.

batch JSON form of basic HTTP request

An HTTP request similar to

        If-None-Match: $hash

is encoded in JSON as follows.

        { "method": "GET", "relative_url": "$path", "If-None-Match": "$hash" }

The "method" field can be omitted and then "GET" will be assumed as the method. An HTTP response similar to

        200 OK
        ETag: $hash

is encoded in JSON as follows.

        { "code": 200, "body": $json, "ETag": "$hash" }

batch array of requests

You can bundle an array of requests [ $request1, $request2, ..., $requestN ], where each $requestI is given in JSON-encoded form, as follows.

        { "array": [ $request1, $request2, ..., $requestN ], 
          "If-None-Match": "$hash" }

Responses come in array form as well.

        { "code": 200, 
          "array": [ $response1, ..., $responseN ], 
          "ETag": "$hash" }

Note that such array requests and responses work with ETag/If-None-Match just as individual requests.


Not all URLs are supported for batch requests yet. Not yet supported APIs are:

coverage and profile information

You can query aggregated coverage and profile information as follows. The current compilerversion is 0.

Each query returns a JSON array containing objects of one of the following kinds.

coverage for view=union and view=intersection

coverage for view=sum

profile to no view and view=normalized

profile for view=unithistogram


You can query global statistics as follows.

It returns a JSON object with the following fields.


All queries can be performed via either http or https.

By default, all returned resources (redirections, and urls embedded in JSON objects) will refer to the same protocol as the request protocol. This default can be changed by appending either &return_ssl_resources=1 or &return_ssl_resources=0 to the query. In case of a batch request, the parameter must be added to the outer /api batch request, and it then also applies to all nested queries; overriding the default within nested batch queries is not supported.


real-time updates

You can receive realtime updates to your own server whenever publications are created or deleted.

RSS feeds

You can subscribe to RSS feeds to poll for updates.

more information