Looks like the Great Firewall or something like it is preventing you from completely loading www.skritter.com because it is hosted on Google App Engine, which is periodically blocked. Try instead our mirror:


This might also be caused by an internet filter, such as SafeEyes. If you have such a filter installed, try adding appspot.com to the list of allowed domains.

Request Format

All requests are standard HTTP requests that return JSON strings. There are some GET parameters that any endpoint will accept (whether it's a GET request or not):

  • bearer_token - OAuth2 token. Passing through HTTP headers is preferred
  • gzip - compress the response (default: false)
  • suppress_response_codes - return HTTP 200, no matter what (default: false)

POST and PUT requests sometimes require a JSON formatted entity. These entities should be sent in the HTTP body, but parameters are still GET no matter what.

GZip Encoding

There are two ways to gzip information: the GET parameter listed above, and through headers. To gzip with headers, set User-Agent and Accept-Encoding both to gzip in the request.

It's recommended you use the header system when possible. Response headers will be completely correct, and it's more efficient. The GET method will not have the Content-Encoding header correctly set to 'gzip'.

Why is it set up this way?

Because Skritter is hosted on Google App Engine and they don't allow very much control of the gzip process. But we still want a way for AJAX requests to get compressed content, and AJAX requests can't have the User-Agent or Accept-Encoding headers set. So until there's a better solution, both methods are available.

GET Property Formats

  • Booleans for queries are either 'true' or 'false'. Empty strings revert to the default.
  • Timestamps are Unix epoch floats.
  • Dates are ISO Formatted ('YYYY-MM-DD')
  • Encoded in UTF8

Response Format

Responses are all JSON objects, and include the following parameter:

  • statusCode - the actual HTTP response code, even if suppress_response_codes is on


If something goes awry, responses will use one of the following HTTP codes:

  • 400: Invalid or missing GET parameters or POST input.
  • 401: Invalid or missing OAuth authorization token.
  • 402: Payment required.
  • 403: Unauthorized access.
  • 404: Invalid URL.
  • 408: Timeout (client should retry, perhaps with backoff)
  • 409: Conflict error (client should adjust input)
  • 429: Over quota.
  • 500+: Server error.

The server may return other codes if something happens before the API code even gets started, in which case you probably won't get something JSON formatted, but rather some HTML. Handle all cases!

Error responses will have the following properties:

  • error string name of the error
  • message description of what went wrong.

Response Property Formats

  • Timestamps are Unix epoch floats.
  • Dates are ISO Formatted ('YYYY-MM-DD')
  • Missing or not-found data will be returned as Javascript null.
  • Encoded in UTF8