splits i/o API #
These docs are for the v3 API.
Jump to section #
Game Endpoints #
User Endpoints #
Run Endpoints #
Uploading Runs on Behalf of a User #
Pagination #
Routes that return array resources are paginated to 20 items per page. To get a specific page of results, add ?page=N
to your API hit. The default page is page 1. You'll find pagination info in the HTTP headers of every paginated response
under the Link, Total, and Per-Page fields.
Overview of routes #
Base URL is https://splits.io/api/v3.
Game Endpoints Overview #
Game ids are SRL shortnames (e.g. sms, oot, etc.) or Splits I/O base 10 ids (which you can discover in other
routes).
GET /games?search=:term
GET /games/:id
GET /games/:game_id/runs
GET /games/:game_id/categories/:id
GET /games/:game_id/categories/:category_id/runs
User Endpoints Overview #
User ids are Twitch usernames or Splits I/O base 10 ids.
GET /users/:id
GET /users/:user_id/runs
GET /users/:user_id/pbs
GET /users/:user_id/games/:game_id/categories/:category_id/runs
GET /users/:user_id/games/:game_id/categories/:category_id/pb
GET /users/:user_id/games/:game_id/categories/:category_id/prediction
Run Endpoints Overview #
Run ids are Splits I/O base 36 ids. These are the strings you see in user-friendly run URLs like splits.io/36s.
GET /runs/:id
DELETE /runs/:id
POST /runs
Route details #
Game Endpoints #
Game ids are SRL shortnames (e.g. sms, oot, etc.) or Splits I/O base 10 ids (which you can discover in other
routes).
GET /games?search=:term #
Returns games with names matching .*:term.* or shortnames exactly equaling :term (in no guaranteed order).
Example request #
curl https://splits.io/api/v3/games?search=sonic
Example response #
(see the /games/:id endpoint for the game format)
{
"games": [
{
"id": 969,
"name": "Sonic 2006",
"shortname": null,
...
},
{
"id": 172,
"name": "Sonic Adventure 2 Battle",
"shortname": "sa2b",
...
},
...
{
"id": 752,
"name": "Sonic Unleashed (360/PS3)",
"shortname": "su360",
...
}
]
}
GET /games/:id #
Returns information about a game.
Example request #
curl https://splits.io/api/v3/games/sms
Example response #
(see the /games/:game_id/categories/:id endpoint for the category format)
{
"game": {
"id": 15,
"name": "Super Mario Sunshine",
"shortname": "sms",
"created_at": "2014-04-18T06:28:59.764Z",
"updated_at": "2015-02-01T21:33:44.460Z",
"categories": [ ... ]
}
}
GET /games/:game_id/runs #
Returns all runs for a game. This route is paginated.
Example request #
curl https://splits.io/api/v3/games/sms/runs
Example response #
(see the /runs/:id endpoint for the run format)
{
"runs": [ ... ]
}
GET /games/:game_id/categories/:id #
Returns information about a category.
Example request #
curl https://splits.io/api/v3/games/sms/categories/852
Example response #
{
"category": {
"id": 852,
"name": "Any%",
"created_at": "2015-01-08T02:53:19.867Z",
"updated_at": "2015-02-01T21:33:44.440Z"
}
GET /games/:game_id/categories/:category_id/runs #
Returns all runs for a category. This route is paginated.
Example request #
curl https://splits.io/api/v3/games/sms/categories/70/runs
Example response #
(see the /runs/:id endpoint for the run format)
{
"runs": [ ... ]
}
User Endpoints #
User ids are Twitch usernames (which we call name) or Splits I/O base 10 ids.
GET /users/:id #
Returns information about a user.
Example request #
curl https://splits.io/api/v3/users/glacials
Example response #
{
"user": {
"id": 1,
"twitch_id": 29798286,
"name": "glacials",
"avatar": "https://static-cdn.jtvnw.net/jtv_user_pictures/glacials-profile_image-dc04543f973cfddc-300x300.png",
"created_at": "2014-03-09T19:00:43.640Z",
"updated_at": "2015-02-01T18:53:03.397Z"
}
}
GET /users/:user_id/runs #
Returns all of a user's runs. This route is paginated.
Example request #
curl https://splits.io/api/v3/users/glacials/runs
Example response #
(see the /runs/:id endpoint for the run format)
{
"runs": [ ... ]
}
GET /users/:user_id/pbs #
Returns all of a user's PBs (one per category). Because of an unnoticed mistake and my desire to not change this endpoint without bumping version, this route is not paginated. You can expect it to be in v4, but v3 will remain unpaginated.
Example request #
curl https://splits.io/api/v3/users/glacials/pbs
Example response #
(see the /runs/:id endpoint for the run format)
{
"pbs": [ ... ]
}
GET /users/:user_id/games/:game_id/categories/:category_id/runs #
Returns all of a user's runs for a game/category. This route is paginated.
Example request #
curl https://splits.io/api/v3/users/glacials/games/sms/categories/852/runs
Example response #
(see the /runs/:id endpoint for the run format)
{
"runs": [ ... ]
}
GET /users/:user_id/games/:game_id/categories/:category_id/pb #
Returns a user's PB for a game/category.
Example request #
curl https://splits.io/api/v3/users/glacials/games/sms/categories/852/pb
Example response #
(see the /runs/:id for this format)
{
"run": { ... }
}
GET /users/:user_id/games/:game_id/categories/:category_id/prediction #
Returns a prediction of this user's next run of this category. Predictions use per-split smoothed moving averages for
all recorded run history of the user for this category. The response for this endpoint looks like a response to a
normal "get run" endpoint, but has a null id.
Run Endpoints #
Run ids are Splits I/O base 36 ids. These are the strings you see in user-friendly run URLs like splits.io/36s.
GET /runs/:id #
Returns a run.
Example request #
curl https://splits.io/api/v3/runs/c6
Example response #
{
"run": {
"id": 438,
"path": "/c6",
"name": "Sonic Colors",
"program": "wsplit",
"image_url": null,
"created_at": "2014-03-09T19:07:46.483Z",
"updated_at": "2016-01-27T15:42:02.834Z",
"video_url": null,
"splits": [
{
"name": "Rotatatron",
"duration": 501.7,
"finish_time": 501.7,
"best": {
"duration": 462.85
},
"history": null,
"gold": false,
"skipped": false,
"reduced": false
},
...
{
"name": "Epilogue",
"duration": 44.719999999999345,
"finish_time": 5083.74,
"best": {
"duration": 44.7199999999993
},
"history": null,
"gold": true,
"skipped": false,
"reduced": false
}
],
"attempts": 9,
"sum_of_best": 5009.42,
"user": { ... }
"game": { ... }
"category": { ... },
"time": 5083.74
}
}
DELETE /runs/:id #
Deletes this run (requires authentication).
POST /runs #
Upload a new run. If you want to allow an account to claim ownership of this run, you should inspect the response for a
uris.claim_uri and send the user who should own the run there. If they're logged in, their account will automatically
claim ownership of the run, then they'll be immediately redirected to the uris.public_uri.
Example request #
curl -iX POST --form file=@/path/to/splits_file.lss https://splits.io/api/v3/runs
Example response #
{
"status": 201,
"message": "Run created.",
"uris": {
"api_uri": "https://splits.io/api/v3/runs/36y",
"public_uri": "https://splits.io/36y",
"claim_uri": "https://splits.io/36y?claim_token=03a1adb08ec85d5b00374a70"
}
}
Uploading Runs on Behalf of a User #
If you want to upload runs for a user (e.g. from within a timer), you have two options.
Simple option #
Upload the run without auth and direct the user to the URL in the response body's uris.claim_uri. If they are logged
in when they visit it, their account will automatically claim the run.
This is the easier method to implement, but has some flaws:
- The user must open the run in their web browser. If you prefer to upload runs in the background, this method isn't for you.
- If there are network or browser issues when the user's browser tries to load the run, it won't be claimed.
- If the user isn't logged in when their browser opens, the run will remain unclaimed. Neither your application nor the user will receive any indication of this.
Advanced option #
The advanced option is a standard OAuth2 flow. You can request permission from the user to upload runs to their account on their behalf. If they accept, you will receive an OAuth token which you can include in your run upload requests in order to create the run as that user.
The following instructions go into naive-case details about implementing this OAuth support in your application. If you want to learn more about OAuth or need general OAuth troubleshooting help, you can research OAuth2 online. Especially if your application is a website, it's likely that the language you're using has well-established libraries that handle much of the below OAuth flow for you.
In all cases, you'll need to first go to your Splits I/O account's settings page and create an application, then refer to the relevant section below.
Note: Once you have an OAuth token, you can use a request like this to retrieve information about it:
GET https://splits.io/oauth/token/info?access_token=YOUR_TOKEN
Example 1: My application is a local program that runs on the user's computer #
If your application runs locally as a program on a user's computer, you should use OAuth's authorization code grant
flow. This means your application will open the Splits I/O authorization page in the user's default browser, and if
the user accepts the authorization, Splits I/O will give your application a code which you should immediately exchange
for an OAuth token using a secure API request.
-
Configure your program to run a small web server on a port of your choosing, and listen for
GETrequests to a path of your choosing. In this example, let's say you're listening on port 8000 for requests to/auth/splitsio. -
On your Splits I/O settings page, set your
redirect_urito something likehttp://localhost:8000/auth/splitsioHint: Set this to "debug" for now if you don't yet have a page to redirect yourself to.
-
When a user wants to grant authorization to your application for their Splits I/O account, send them to a URL like this:
https://splits.io/oauth/authorize?response_type=code&scope=upload_run&redirect_uri=http://localhost:8000/auth/splitsio&client_id=YOUR_CLIENT_IDIf the user authorizes your application, they will be redirected to a URL like
http://localhost:8000/auth/splitsio?code=YOUR_CODEwhich the web server you set up in step 1 should respond to. Give the user a nice-looking HTML page saying to switch back to the application and strip the
codeURL parameter for the next step. -
Use your
codeto make this request:POST https://splits.io/oauth/tokenwith this body:
grant_type=authorization_code client_id=YOUR_CLIENT_ID client_secret=YOUR_CLIENT_SECRET code=YOUR_CODE redirect_uri=http://localhost:8000/auth/splitsiowhich will respond with something like this:
{ "access_token": "0e82e0ac69fed3c6e5044682a9eb94ccded5ace70e84838104a131cb50595cd2", "token_type": "bearer", "expires_in": 7200, "refresh_token": "0e23b095e0d0104ff0642cde71b61d236f3b3865734a0e734714ecd45b25106c", "scope": "upload_run", "created_at": 1499314941 }Success!
access_tokenis your OAuth token for the user. Use it in your API requests to act on behalf of the user by including this header in your requests:Authorization: Bearer YOUR_ACCESS_TOKENThe access token expires after the duration specified in
expires_in(measured in seconds). After it expires, you can retrieve a new one with no user intervention using the returnedrefresh_token:POST https://splits.io/oauth/tokengrant_type=refresh_token refresh_token=YOUR_REFRESH_TOKENThis will return a new access token (and a new refresh token -- update yours!) in a body format identical to original grant (above).
This style of expiring access tokens periodically and using refresh tokens to replace them improves security by making it obvious when a user's stolen credentials are in use. See RFC 6749 for more information on refresh tokens.
Example 2: My application is an all-JavaScript website #
If your application is an in-browser JavaScript application with little or no logic performed by a backend server, you should use OAuth's implicit grant flow.
-
On your Splits I/O settings page, set your
redirect_urito where you want users to land after going through the authorization flow. For this example, we'll usehttps://YOUR_WEBSITE/auth/splitsioHint: Set this to "debug" for now if you don't yet have a page to redirect yourself to.
-
When a user wants to grant authorization to your application for their Splits I/O account, send them to a URL like this:
https://splits.io/oauth/authorize?response_type=token&scope=upload_run&redirect_uri=https://YOUR_WEBSITE/auth/splitsio&client_id=YOUR_CLIENT_IDIf the user authorizes your application, they will be redirected to a URL like
https://YOUR_WEBSITE/auth/splitsio#access_token=YOUR_TOKENSuccess!
access_tokenis your OAuth token for the user. Use it in your API requests to act on behalf of the user by including this header in your requests:Authorization: Bearer YOUR_ACCESS_TOKENThe access token expires after the duration specified in
expires_in(measured in seconds). After it expires, you can retrieve a new one with no user intervention using redirection upon accessing your app, or a hidden iframe to invisibly take the user through the authorization flow. If the user is still authorized, no user interaction will be required and you can strip your new access token from the URL fragment.This style of expiring access tokens periodically improves security by limiting the usability of any stolen credentials.
Example 3: My application is a website #
If your application is a website with a backend component, you should use OAuth's authorization code grant flow.
This means your website will link the user to the Splits I/O authorization page, and if the user accepts the
authorization, Splits I/O will give your application a code which it will immediately exchange for an OAuth token
using a secure API request.
-
On your Splits I/O settings page, set your
redirect_urito where you want users to land after going through the authorization flow. For this example, we'll usehttps://YOUR_WEBSITE/auth/splitsioHint: Set this to "debug" for now if you don't yet have a page to redirect yourself to.
-
When a user wants to grant authorization to your application for their Splits I/O account, send them to a URL like this:
https://splits.io/oauth/authorize?response_type=code&scope=upload_run&redirect_uri=https://YOUR_WEBSITE/auth/splitsio&client_id=YOUR_CLIENT_IDIf the user authorizes your application, they will be redirected to a URL like
https://YOUR_WEBSITE/auth/splitsio?code=YOUR_CODEStrip the
codeURL parameter for the next step. -
Use your
codeto make this request:POST https://splits.io/oauth/tokenwith this body:
grant_type=authorization_code client_id=YOUR_CLIENT_ID client_secret=YOUR_CLIENT_SECRET code=YOUR_CODE redirect_uri=http://localhost:8000/auth/splitsiowhich will respond with something like this:
{ "access_token": "0e82e0ac69fed3c6e5044682a9eb94ccded5ace70e84838104a131cb50595cd2", "token_type": "bearer", "expires_in": 7200, "refresh_token": "0e23b095e0d0104ff0642cde71b61d236f3b3865734a0e734714ecd45b25106c", "scope": "upload_run", "created_at": 1499314941 }Success!
access_tokenis your OAuth token for the user. Use it in your API requests to act on behalf of the user by including this header in your requests:Authorization: Bearer YOUR_ACCESS_TOKENThe access token expires after the duration specified in
expires_in(measured in seconds). After it expires, you can retrieve a new one with no user intervention using the returnedrefresh_token:POST https://splits.io/oauth/tokengrant_type=refresh_token refresh_token=YOUR_REFRESH_TOKENThis will return a new access token (and a new refresh token -- update yours!) in a body format identical to original grant (above).
This style of expiring access tokens periodically and using refresh tokens to replace them improves security by making it obvious when a user's stolen credentials are in use. See RFC 6749 for more information on refresh tokens.