# 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 `id`s (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 `id`s. 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 `id`s (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 ```bash curl https://splits.io/api/v3/games?search=sonic ``` ##### Example response *(see the `/games/:id` endpoint for the game format)* ```json { "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 ```bash curl https://splits.io/api/v3/games/sms ``` ##### Example response *(see the `/games/:game_id/categories/:id` endpoint for the category format)* ```json { "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](#pagination). ##### Example request ```bash curl https://splits.io/api/v3/games/sms/runs ``` ##### Example response *(see the `/runs/:id` endpoint for the run format)* ```json { "runs": [ ... ] } ``` #### `GET /games/:game_id/categories/:id` Returns information about a category. ##### Example request ```bash curl https://splits.io/api/v3/games/sms/categories/852 ``` ##### Example response ```json { "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](#pagination). ##### Example request ```bash curl https://splits.io/api/v3/games/sms/categories/70/runs ``` ##### Example response *(see the `/runs/:id` endpoint for the run format)* ```json { "runs": [ ... ] } ``` ### Based on user User ids are Twitch usernames (which we call `name`) or Splits I/O base 10 `id`s. #### `GET /users/:id` Returns information about a user. ##### Example request ```bash curl https://splits.io/api/v3/users/glacials ``` ##### Example response ```json { "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](#pagination). ##### Example request ```bash curl https://splits.io/api/v3/users/glacials/runs ``` ##### Example response *(see the `/runs/:id` endpoint for the run format)* ```json { "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 ```bash curl https://splits.io/api/v3/users/glacials/pbs ``` ##### Example response *(see the `/runs/:id` endpoint for the run format)* ```json { "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](#pagination). ##### Example request ```bash curl https://splits.io/api/v3/users/glacials/games/sms/categories/852/runs ``` ##### Example response *(see the `/runs/:id` endpoint for the run format)* ```json { "runs": [ ... ] } ``` #### `GET /users/:user_id/games/:game_id/categories/:category_id/pb` Returns a user's PB for a game/category. ##### Example request ```bash curl https://splits.io/api/v3/users/glacials/games/sms/categories/852/pb ``` ##### Example response *(see the `/runs/:id` for this format)* ```json { "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 ```bash curl https://splits.io/api/v3/runs/c6 ``` ##### Example response ```json{ "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 ```bash curl -iX POST --form file=@/path/to/splits_file.lss https://splits.io/api/v3/runs ``` ##### Example response ```json { "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" } } ```