[READ-ONLY] Mirror of https://github.com/glacials/splits-io. a speedrunning data store and analysis engine splits.io
splits-io docs api_v3.md

splits i/o API #

These docs are for the v3 API.

Jump to section #

Game Endpoints #

User Endpoints #

Run Endpoints #

User Authentication and Authorization #

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"
  }
}

User Authentication and Authorization #

If you want to upload runs for a user (e.g. from within a timer), you have two options. If you only need to know who a user is on Splits I/O, skip to advanced.

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.

  1. Configure your program to run a small web server on a port of your choosing, and listen for GET requests to a path of your choosing. In this example, let's say you're listening on port 8000 for requests to /auth/splitsio.

  2. On your Splits I/O settings page, set your redirect_uri to something like

    http://localhost:8000/auth/splitsio
    

    Hint: Set this to "debug" for now if you don't yet have a page to redirect yourself to.

  3. 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_ID
    

    If the user authorizes your application, they will be redirected to a URL like

    http://localhost:8000/auth/splitsio?code=YOUR_CODE
    

    which 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 code URL parameter for the next step.

  4. Use your code to make this request:

    POST https://splits.io/oauth/token
    

    with 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/splitsio
    

    which 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_token is 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_TOKEN
    

    The 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 returned refresh_token:

    POST https://splits.io/oauth/token
    
    grant_type=refresh_token
    refresh_token=YOUR_REFRESH_TOKEN
    

    This 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.

  1. On your Splits I/O settings page, set your redirect_uri to where you want users to land after going through the authorization flow. For this example, we'll use

    https://YOUR_WEBSITE/auth/splitsio
    

    Hint: Set this to "debug" for now if you don't yet have a page to redirect yourself to.

  2. 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_ID
    

    If the user authorizes your application, they will be redirected to a URL like

    https://YOUR_WEBSITE/auth/splitsio#access_token=YOUR_TOKEN
    

    Success! access_token is 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_TOKEN
    

    The 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.

  1. On your Splits I/O settings page, set your redirect_uri to where you want users to land after going through the authorization flow. For this example, we'll use

    https://YOUR_WEBSITE/auth/splitsio
    

    Hint: Set this to "debug" for now if you don't yet have a page to redirect yourself to.

  2. 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_ID
    

    If the user authorizes your application, they will be redirected to a URL like

    https://YOUR_WEBSITE/auth/splitsio?code=YOUR_CODE
    

    Strip the code URL parameter for the next step.

  3. Use your code to make this request:

    POST https://splits.io/oauth/token
    

    with 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/splitsio
    

    which 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_token is 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_TOKEN
    

    The 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 returned refresh_token:

    POST https://splits.io/oauth/token
    
    grant_type=refresh_token
    refresh_token=YOUR_REFRESH_TOKEN
    

    This 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.