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

splits i/o API #

These docs are for the v3 API.

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.

Based on game #

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

Based on user #

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

Based on run #

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 #

Based on game #

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": [ ... ]
}

Based on user #

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.

Based on run #

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