Spl3 API: Post v3 battle - fetus-hina/stat.ink Wiki

not detailed, for stat.ink API profreshionals:

Request

Endpoint URL: https://stat.ink/api/v3/battle Request Method: POST or PUT Authorization: Required, HTTP Header bearer auth only Content-Type: application/x-msgpack

name type example info
test boolean "no" If "yes", validation only. Defaults to "no"
uuid uuid-string "ca1e4d9d-837f-4c16-853b-570bb1af2b2b" UUIDv5 based on your namespace + SplatNet 3 ID
image_judge image a screenshot image of Judd (referee) and teams' pts
image_result image a screenshot image of scoreboard (8 players shown)
image_gear image a screenshot image of user's gears
lobby key-string "regular" one of regular, bankara_challenge, bankara_open, private
[JSON] https://stat.ink/api/v3/lobby
rule key-string "nawabari" one of nawabari(TW), area(SZ), hoko(RM), yagura(TC), asari(CB)
[JSON] https://stat.ink/api/v3/rule
stage key-string "yunohana" https://stat.ink/api-info/stage3
[JSON] https://stat.ink/api/v3/stage
weapon key-string "wakaba" https://stat.ink/api-info/weapon3
[JSON] https://stat.ink/api/v3/weapon
result key-string "win" one of win, lose, draw, exempted_lose
knockout boolean "no" for TW, set null or not sending
rank_in_team integer [1, 4] 2 position in scoreboard
kill integer [0, 99] 2
assist integer [0, 99] 3
kill_or_assist integer [0, 99] 5 equals to kill + assist if you know them
death integer [0, 99] 4
special integer [0, 99] 6 use count
inked integer 1000 not including bonus
medals array of string ["バトル No.1", "トドメ数 No.1"] localized string, 0-3 elements
our_team_inked integer 2000 TW, not including bonus
their_team_inked integer 1500 TW, not including bonus
our_team_percent decimal [0.0, 100.0] 55.5 TW
their_team_percent decimal [0.0, 100.0] 41.6 TW
our_team_count integer [0, 100] 100 Anarchy
their_team_count integer [0, 100] 5 Anarchy
level_before integer 10 level ("ランク" in JA), before the battle
level_after integer 11 level ("ランク" in JA), after the battle
rank_before key-string "c+" one of c- ... s+, lowercase only
/^[abcs][+-]?$/ except s-
[JSON] https://stat.ink/api/v3/rank
rank_before_s_plus integer 1 S+ n.
i.e., 42 for S+ 42
rank_before_exp integer 100
rank_after key-string
rank_after_s_plus integer
rank_after_exp integer
rank_exp_change integer -2 Set rank_after_exp - rank_before_exp. It can be negative. Set only this value if you don't know their exact values.
rank_up_battle boolean "no" Set "yes" if now "Rank-up Battle" mode.
challenge_win integer [0, 5] Win count for Anarchy (Series)
If rank_up_battle is truthy("yes"), the value range is limited to [0, 3].
challenge_lose integer [0, 3] Lose count for Anarchy (Series)
cash_before integer 10000
cash_after integer 11000
our_team_players array of player struct [{...},{...},{...},{...}] Good guys scoreboard data (1-4 elements)
their_team_players array of player struct Bad guys scoreboard data (1-4 elements)
note string public note
private_note string private note
link_url http-url-string https://example.com/ IDN is not allowed, it will be public
agent string (1 ≤ length ≤ 64) "the super client" your client name *
agent_version string (1 ≤ length ≤ 255) "v1.0.0" its version *
Stat.ink doesn't care the value of this entry. You can send any information to identify the version. Be careful not to be too verbose about the user. Maximum possible information would be OS type ("Windows", "macOS"), browser type ("Chrome", "Firefox"), and/or architecture type ("x64", "ARM").
agent_variables map<string, string>
(1 ≤ len(key) ≤ 63)
(1 ≤ len(value) ≤ 255)
{"foo": "blablabla"} extra data by UA
automated boolean "yes" set "yes" if the client is operating in automatic mode
start_at unix-time 1599577200 the battle starts at
end_at unix-time 1599577380 the battle ends at

player structure

  • For the player themselves, the same data will be sent twice in the main structure and this player structure.
  • See above for description of duplicate items such as kill.
name type example info
me boolean "yes" set "yes" if the player is "current" user. otherwise, set "no".
rank_in_team integer [1, 4] 1 position in scoreboard
name string (1 ≤ length ≤ 10) "なぎさのこあくま" the player's name
number integer (positive) 1112 #1112 in splashtag
splashtag_title string "アゲアゲのルーキー" title in splashtag, localized & joined
weapon key-string "dynamo"
inked integer 903 not including bonus
kill integer 3
assist integer 0
kill_or_assist integer 3
death integer 5
special integer 1
disconnected boolean "no" set "yes" if the player disconnected. otherwise, set "no".

image

types

  • range (like [1, 4]): See this

  • boolean: "yes" or "no". Be careful - it is not a native boolean type, it is a string. (Note: internally, it accepts native boolean value, but the MsgPack library does not support them.)

  • http-url-string: HTTP or HTTPS URL. IDN (Internationalized Domain Names) are not supported. It might work if Punycode encode is done on the client side.

  • unix-time: integer, seconds from 1970-01-01T00:00:00+00:00 without leap seconds. Be careful if the client using JavaScript -- its time unit is milliseconds, so it must be 1/1000.

  • uuid-string: case insensitive string(lowercase recommended), "00000000-0000-M000-N000-000000000000" format, version 1, 3, 4 or 5 is required (M=1, 3, 4, 5). RFC 4122 variant is required (N=8, 9, a, b).

  • image: send image binary as binary-string.

    • filesize limit: up to 3 mebibytes (MiB)
    • width: 100 ≤ width ≤ 3840 (typ. 1280 or 1920)
    • height: 100 ≤ height ≤ 2160 (typ. 720 or 1080)
    • format: JPEG or PNG

agent

The agent parameters must send both or omit both. You cannot send only names.

Response

Successful (test=yes)

Status: HTTP 200 OK Content-Type: application/json Content: {"error": null}

See the 200.

Successful (test=no)

Status: HTTP 201 Created Content-Type: application/json Content: See example below Headers:

  • Location: Public URL, the user can access this URL to view the detail page.
  • X-Api-Location: API URL
  • X-User-Screen-Name: @username (without @)
  • X-Battle-ID: Battle UUID (The ID assigned by the server is set, which is different from the parameter.)

If a battle with the same uuid parameter is submitted within 24 hours (not 1 day; DST related), it will not be created a duplicate data, but will return the same data as before.

Example of result

  • You should not expect order.
  • You should not expect JSON to be pretty printed.
  • You should not expect the time zone is UTC.
  • You should expect that most values can be null.
  • You should expect that keys not listed will be present.
{
    "id": "44bc8e79-cbc2-4de5-a1c3-a17936ab1a5c",
    "url": "https://stat.ink/@fetus_hina/spl3/44bc8e79-cbc2-4de5-a1c3-a17936ab1a5c",
    "images": {
        "judge": "https://img.stat.ink/spl3/f1/f1e0cab7-8543-4ab5-8aa4-58c9a4b78bb1.jpg",
        "results": "https://img.stat.ink/spl3/8f/8f157c67-6dac-4ada-a4ca-a07a33c481d9.jpg",
        "gear": "https://img.stat.ink/spl3/0b/0b33ea0d-0951-4b93-ab2a-c999cd7a1065.jpg"
    },
    "user": {
        "id": 1,
        "name": "ひな",
        "screen_name": "fetus_hina",
        "url": "https://stat.ink/@fetus_hina"
    },
    "lobby": {
        "key": "bankara_open",
        "name": {
            "en_US": "Anarchy Battle (Open)",
            "ja_JP": "バンカラマッチ (オープン)"
        }
    },
    "rule": {
        "key": "hoko",
        "name": {
            "en_US": "Rainmaker",
            "ja_JP": "ガチホコバトル"
        },
        "short_name": {
            "en_US": "RM",
            "ja_JP": "ホコ"
        }
    },
    "stage": {
        "key": "sumeshi",
        "aliases": [
            "wahoo_world",
            "world"
        ],
        "name": {
            "en_US": "Wahoo World",
            "ja_JP": "スメーシーワールド"
        },
        "short_name": {
            "en_US": "World",
            "ja_JP": "スメーシー"
        },
        "area": null,
        "release_at": {
            "time": 1662649200,
            "iso8601": "2022-09-08T15:00:00+00:00"
        }
    },
    "weapon": {
        "key": "dynamo",
        "aliases": [
            "dynamo_roller",
            "1020"
        ],
        "type": {
            "key": "roller",
            "aliases": [],
            "name": {
                "en_US": "Rollers",
                "ja_JP": "ローラー"
            }
        },
        "name": {
            "en_US": "Dynamo Roller",
            "ja_JP": "ダイナモローラー"
        },
        "main": "dynamo",
        "sub": {
            "key": "sprinkler",
            "aliases": [],
            "name": {
                "en_US": "Sprinkler",
                "ja_JP": "スプリンクラー"
            }
        },
        "special": {
            "key": "energystand",
            "aliases": [],
            "name": {
                "en_US": "Tacticooler",
                "ja_JP": "エナジースタンド"
            }
        },
        "reskin_of": "dynamo"
    },
    "result": "win",
    "knockout": false,
    "rank_in_team": 3,
    "kill": 14,
    "assist": 3,
    "kill_or_assist": 17,
    "death": 9,
    "special": 3,
    "inked": 1195,
    "medals": [
        "バトル No.1",
        "トドメ数 No.1",
        "塗りポイント No.1"
    ],
    "our_team_inked": null,
    "their_team_inked": null,
    "our_team_percent": null,
    "their_team_percent": null,
    "our_team_count": 57,
    "their_team_count": 25,
    "level_before": null,
    "level_after": null,
    "rank_before": null,
    "rank_before_s_plus": null,
    "rank_before_exp": null,
    "rank_after": null,
    "rank_after_s_plus": null,
    "rank_after_exp": null
    "rank_up_battle": false,
    "challenge_win": 3,
    "challenge_lose": 2,
    "cash_before": null,
    "cash_after": null,
    "our_team_members": [
        {
            "me": false,
            "rank_in_team": 1,
            "name": "Player",
            "number": 4822,
            "splashtag_title": "自称若者",
            "weapon": {
                "key": "sshooter",
                "aliases": [
                    "splattershot",
                    "40"
                ],
                "type": {
                    "key": "shooter",
                    "aliases": [],
                    "name": {
                        "en_US": "Shooters",
                        "ja_JP": "シューター"
                    }
                },
                "name": {
                    "en_US": "Splattershot",
                    "ja_JP": "スプラシューター"
                },
                "main": "sshooter",
                "sub": {
                    "key": "kyubanbomb",
                    "aliases": [],
                    "name": {
                        "en_US": "Suction Bomb",
                        "ja_JP": "キューバンボム"
                    }
                },
                "special": {
                    "key": "ultrashot",
                    "aliases": [],
                    "name": {
                        "en_US": "Trizooka",
                        "ja_JP": "ウルトラショット"
                    }
                },
                "reskin_of": "sshooter"
            },
            "kill": 16,
            "assist": 1,
            "kill_or_assist": 17,
            "death": 6,
            "special": 3,
            "inked": 1019,
            "disconnected": false
        },
        {
            "me": false,
            "rank_in_team": 2,
            "name": "Player",
            "number": 2720,
            "splashtag_title": "スライドするフリーランス",
            "weapon": {
                "key": "nzap85",
                "aliases": [
                    "n_zap_85",
                    "60"
                ],
                "type": {
                    "key": "shooter",
                    "aliases": [],
                    "name": {
                        "en_US": "Shooters",
                        "ja_JP": "シューター"
                    }
                },
                "name": {
                    "en_US": "N-ZAP '85",
                    "ja_JP": "N-ZAP85"
                },
                "main": "nzap85",
                "sub": {
                    "key": "kyubanbomb",
                    "aliases": [],
                    "name": {
                        "en_US": "Suction Bomb",
                        "ja_JP": "キューバンボム"
                    }
                },
                "special": {
                    "key": "energystand",
                    "aliases": [],
                    "name": {
                        "en_US": "Tacticooler",
                        "ja_JP": "エナジースタンド"
                    }
                },
                "reskin_of": "nzap85"
            },
            "kill": 0,
            "assist": 5,
            "kill_or_assist": 5,
            "death": 7,
            "special": 1,
            "inked": 917,
            "disconnected": false
        },
        {
            "me": true,
            "rank_in_team": 3,
            "name": "なぎさのこあくま",
            "number": 1112,
            "splashtag_title": "アゲアゲのルーキー",
            "weapon": {
                "key": "dynamo",
                "aliases": [
                    "dynamo_roller",
                    "1020"
                ],
                "type": {
                    "key": "roller",
                    "aliases": [],
                    "name": {
                        "en_US": "Rollers",
                        "ja_JP": "ローラー"
                    }
                },
                "name": {
                    "en_US": "Dynamo Roller",
                    "ja_JP": "ダイナモローラー"
                },
                "main": "dynamo",
                "sub": {
                    "key": "sprinkler",
                    "aliases": [],
                    "name": {
                        "en_US": "Sprinkler",
                        "ja_JP": "スプリンクラー"
                    }
                },
                "special": {
                    "key": "energystand",
                    "aliases": [],
                    "name": {
                        "en_US": "Tacticooler",
                        "ja_JP": "エナジースタンド"
                    }
                },
                "reskin_of": "dynamo"
            },
            "kill": 14,
            "assist": 3,
            "kill_or_assist": 17,
            "death": 9,
            "special": 3,
            "inked": 1195,
            "disconnected": false
        },
        {
            "me": false,
            "rank_in_team": 4,
            "name": "Player",
            "number": 2865,
            "splashtag_title": "データで戦うプログラマー",
            "weapon": {
                "key": "tristringer",
                "aliases": [
                    "tri_stringer",
                    "7010"
                ],
                "type": {
                    "key": "stringer",
                    "aliases": [],
                    "name": {
                        "en_US": "Stringers",
                        "ja_JP": "ストリンガー"
                    }
                },
                "name": {
                    "en_US": "Tri-Stringer",
                    "ja_JP": "トライストリンガー"
                },
                "main": "tristringer",
                "sub": {
                    "key": "poisonmist",
                    "aliases": [],
                    "name": {
                        "en_US": "Toxic Mist",
                        "ja_JP": "ポイズンミスト"
                    }
                },
                "special": {
                    "key": "megaphone51",
                    "aliases": [],
                    "name": {
                        "en_US": "Killer Wail 5.1",
                        "ja_JP": "メガホンレーザー5.1ch"
                    }
                },
                "reskin_of": "tristringer"
            },
            "kill": 9,
            "assist": 4,
            "kill_or_assist": 13,
            "death": 4,
            "special": 4,
            "inked": 1205,
            "disconnected": false
        }
    ],
    "their_team_members": [
        {
            "me": false,
            "rank_in_team": 1,
            "name": "Player",
            "number": 4822,
            "splashtag_title": "自称若者",
            "weapon": {
                "key": "sshooter",
                "aliases": [
                    "splattershot",
                    "40"
                ],
                "type": {
                    "key": "shooter",
                    "aliases": [],
                    "name": {
                        "en_US": "Shooters",
                        "ja_JP": "シューター"
                    }
                },
                "name": {
                    "en_US": "Splattershot",
                    "ja_JP": "スプラシューター"
                },
                "main": "sshooter",
                "sub": {
                    "key": "kyubanbomb",
                    "aliases": [],
                    "name": {
                        "en_US": "Suction Bomb",
                        "ja_JP": "キューバンボム"
                    }
                },
                "special": {
                    "key": "ultrashot",
                    "aliases": [],
                    "name": {
                        "en_US": "Trizooka",
                        "ja_JP": "ウルトラショット"
                    }
                },
                "reskin_of": "sshooter"
            },
            "kill": 16,
            "assist": 1,
            "kill_or_assist": 17,
            "death": 6,
            "special": 3,
            "inked": 1019,
            "disconnected": false
        },
        {
            "me": false,
            "rank_in_team": 2,
            "name": "Player",
            "number": 2720,
            "splashtag_title": "スライドするフリーランス",
            "weapon": {
                "key": "nzap85",
                "aliases": [
                    "n_zap_85",
                    "60"
                ],
                "type": {
                    "key": "shooter",
                    "aliases": [],
                    "name": {
                        "en_US": "Shooters",
                        "ja_JP": "シューター"
                    }
                },
                "name": {
                    "en_US": "N-ZAP '85",
                    "ja_JP": "N-ZAP85"
                },
                "main": "nzap85",
                "sub": {
                    "key": "kyubanbomb",
                    "aliases": [],
                    "name": {
                        "en_US": "Suction Bomb",
                        "ja_JP": "キューバンボム"
                    }
                },
                "special": {
                    "key": "energystand",
                    "aliases": [],
                    "name": {
                        "en_US": "Tacticooler",
                        "ja_JP": "エナジースタンド"
                    }
                },
                "reskin_of": "nzap85"
            },
            "kill": 0,
            "assist": 5,
            "kill_or_assist": 5,
            "death": 7,
            "special": 1,
            "inked": 917,
            "disconnected": false
        },
        {
            "me": true,
            "rank_in_team": 3,
            "name": "なぎさのこあくま",
            "number": 1112,
            "splashtag_title": "アゲアゲのルーキー",
            "weapon": {
                "key": "dynamo",
                "aliases": [
                    "dynamo_roller",
                    "1020"
                ],
                "type": {
                    "key": "roller",
                    "aliases": [],
                    "name": {
                        "en_US": "Rollers",
                        "ja_JP": "ローラー"
                    }
                },
                "name": {
                    "en_US": "Dynamo Roller",
                    "ja_JP": "ダイナモローラー"
                },
                "main": "dynamo",
                "sub": {
                    "key": "sprinkler",
                    "aliases": [],
                    "name": {
                        "en_US": "Sprinkler",
                        "ja_JP": "スプリンクラー"
                    }
                },
                "special": {
                    "key": "energystand",
                    "aliases": [],
                    "name": {
                        "en_US": "Tacticooler",
                        "ja_JP": "エナジースタンド"
                    }
                },
                "reskin_of": "dynamo"
            },
            "kill": 14,
            "assist": 3,
            "kill_or_assist": 17,
            "death": 9,
            "special": 3,
            "inked": 1195,
            "disconnected": false
        },
        {
            "me": false,
            "rank_in_team": 4,
            "name": "Player",
            "number": 2865,
            "splashtag_title": "データで戦うプログラマー",
            "weapon": {
                "key": "tristringer",
                "aliases": [
                    "tri_stringer",
                    "7010"
                ],
                "type": {
                    "key": "stringer",
                    "aliases": [],
                    "name": {
                        "en_US": "Stringers",
                        "ja_JP": "ストリンガー"
                    }
                },
                "name": {
                    "en_US": "Tri-Stringer",
                    "ja_JP": "トライストリンガー"
                },
                "main": "tristringer",
                "sub": {
                    "key": "poisonmist",
                    "aliases": [],
                    "name": {
                        "en_US": "Toxic Mist",
                        "ja_JP": "ポイズンミスト"
                    }
                },
                "special": {
                    "key": "megaphone51",
                    "aliases": [],
                    "name": {
                        "en_US": "Killer Wail 5.1",
                        "ja_JP": "メガホンレーザー5.1ch"
                    }
                },
                "reskin_of": "tristringer"
            },
            "kill": 9,
            "assist": 4,
            "kill_or_assist": 13,
            "death": 4,
            "special": 4,
            "inked": 1205,
            "disconnected": false
        }
    ],
    "note": "note",
    "private_note": "private_note",
    "link_url": "https://example.com/",
    "game_version": {
        "tag": "1.1.1",
        "name": {
            "en_US": "v1.1.1",
            "ja_JP": "v1.1.1"
        },
        "release_at": {
            "time": 1663290000,
            "iso8601": "2022-09-16T01:00:00+00:00"
        }
    },
    "user_agent": {
        "name": "dev",
        "version": "1.2.3",
        "variables": {
            "fuga": "bar",
            "hoge": "foo"
        }
    },
    "automated": true,
    "start_at": {
        "time": 1663308935,
        "iso8601": "2022-09-16T06:15:35+00:00"
    },
    "end_at": {
        "time": 1663309235,
        "iso8601": "2022-09-16T06:20:35+00:00"
    },
    "period": {
        "period": 231015,
        "from": "2022-09-16T06:00:00+00:00",
        "to": "2022-09-16T08:00:00+00:00"
    },
    "created_at": {
        "time": 1663309236,
        "iso8601": "2022-09-16T06:20:36+00:00"
    }
}

Error (both test=yes and test=no)

Status: HTTP 400 Bad Request Content-Type: application/json Content: {"error": { /* error information */ }}

⚠️ **GitHub.com Fallback** ⚠️