openapi: 3.0.0
info:
title: puddle.farm API
version: v1
servers:
- url: https://puddle.farm/api
variables: {}
description: Production
paths:
/player/{id}:
get:
summary: Get player by ID
parameters:
- in: path
name: id
schema:
type: integer
format: int64
required: true
description: ID of the player to get
responses:
"200":
description: Successfully returned player information
content:
application/json:
schema:
$ref: "#/components/schemas/PlayerResponse"
"404":
description: Player not found
/player/{player_id}/{char_id}/history:
get:
summary: Get player's match history for a specific character
parameters:
- in: path
name: player_id
schema:
type: integer
format: int64
required: true
description: ID of the player
- in: path
name: char_id
schema:
type: string
required: true
description: Short name of the character (e.g., "SO" for Sol)
- in: query
name: count
schema:
type: integer
format: int32
default: 100
required: false
description: Number of matches to return (default 100)
- in: query
name: offset
schema:
type: integer
format: int32
default: 0
required: false
description: Number of matches to skip (default 0)
responses:
"200":
description: Successfully returned player's match history
content:
application/json:
schema:
$ref: "#/components/schemas/PlayerGamesResponse"
"404":
description: Player or character not found
/top:
get:
summary: Get top ranked players
parameters:
- in: query
name: count
schema:
type: integer
format: int32
default: 100
required: false
description: Number of players to return (default 100)
- in: query
name: offset
schema:
type: integer
format: int32
default: 0
required: false
description: Number of players to skip (default 0)
responses:
"200":
description: Successfully returned top ranked players
content:
application/json:
schema:
$ref: "#/components/schemas/RankResponse"
/top_char/{char_id}:
get:
summary: Get top ranked players for a specific character
parameters:
- in: path
name: char_id
schema:
type: string
required: true
description: Short name of the character (e.g., "SO" for Sol)
- in: query
name: count
schema:
type: integer
format: int32
default: 100
required: false
description: Number of players to return (default 100)
- in: query
name: offset
schema:
type: integer
format: int32
default: 0
required: false
description: Number of players to skip (default 0)
responses:
"200":
description: Successfully returned top ranked players for the character
content:
application/json:
schema:
$ref: "#/components/schemas/RankResponse"
"404":
description: Character not found
/characters:
get:
summary: Get a list of all characters
responses:
"200":
description: Successfully returned list of characters
content:
application/json:
schema:
type: array
items:
type: array
items:
type: string
/player/search:
get:
summary: Search for players by name
parameters:
- in: query
name: search_string
schema:
type: string
required: true
description: The string to search for in player names
- in: query
name: exact
schema:
type: boolean
required: false
description: Whether to perform an exact match (true) or a partial match (false)
responses:
"200":
description: Successfully returned search results
content:
application/json:
schema:
$ref: "#/components/schemas/SearchResponse"
/claim/{player_id}:
get:
summary: Initiate a claim for a player's profile
parameters:
- in: path
name: player_id
schema:
type: integer
format: int64
required: true
description: ID of the player
responses:
"200":
description: Successfully initiated claim and returned a code
content:
application/json:
schema:
type: string
"404":
description: Player not found
/claim/poll/{player_id}:
get:
summary: Poll for the status of a player's profile claim
parameters:
- in: path
name: player_id
schema:
type: integer
format: int64
required: true
description: ID of the player
responses:
"200":
description: >-
Successfully returned the status of the claim (API key if
successful, "false" otherwise)
content:
application/json:
schema:
type: string
"404":
description: Player or code not found
/settings/{key}:
get:
summary: Get player's settings
parameters:
- in: path
name: key
schema:
type: string
required: true
description: Player's API key
responses:
"200":
description: Successfully returned player's settings
content:
application/json:
schema:
$ref: "#/components/schemas/SettingsResponse"
"404":
description: Player not found
/toggle_private/{key}:
get:
summary: Toggle player's privacy setting
parameters:
- in: path
name: key
schema:
type: string
required: true
description: Player's API key
responses:
"200":
description: >-
Successfully toggled player's privacy setting and returned a
confirmation ("true" if successful, error message otherwise)
content:
application/json:
schema:
type: string
/alias/{player_id}:
get:
summary: Get player's aliases
parameters:
- in: path
name: player_id
schema:
type: integer
format: int64
required: true
description: ID of the player
responses:
"200":
description: Successfully returned player's aliases
content:
application/json:
schema:
type: array
items:
type: string
"404":
description: Player not found
/ratings/{player_id}/{char_id}/{duration}:
get:
summary: Get player's rating history for a specific character
parameters:
- in: path
name: player_id
schema:
type: integer
format: int64
required: true
description: ID of the player
- in: path
name: char_id
schema:
type: string
required: true
description: Short name of the character (e.g., "SO" for Sol)
- in: path
name: duration
schema:
type: integer
format: int32
required: true
description: Duration in days for the rating history
responses:
"200":
description: Successfully returned player's rating history
content:
application/json:
schema:
type: array
items:
$ref: "#/components/schemas/RatingsResponse"
"404":
description: Player or character not found
/stats:
get:
summary: Get global statistics
responses:
"200":
description: Successfully returned global statistics
content:
application/json:
schema:
$ref: "#/components/schemas/StatsResponse"
"404":
description: Stats not found
/popularity:
get:
summary: Get character popularity data
responses:
"200":
description: Successfully returned character popularity data
content:
application/json:
schema:
$ref: "#/components/schemas/PopularityResult"
"404":
description: Popularity data not found
/matchups:
get:
summary: Get character matchup data
responses:
"200":
description: Successfully returned character matchup data
content:
application/json:
schema:
$ref: "#/components/schemas/MatchupResponse"
"404":
description: Matchup data not found
/matchups/{player_id}/{char_id}/{duration}:
get:
summary: Get player's character matchup data
parameters:
- in: path
name: player_id
schema:
type: integer
format: int64
required: true
description: ID of the player
- in: path
name: char_id
schema:
type: string
required: true
description: Short name of the character (e.g., "SO" for Sol)
- in: path
name: duration
schema:
type: integer
format: int32
required: true
description: Duration in days for the matchup data
responses:
"200":
description: Successfully returned player's character matchup data
content:
application/json:
schema:
$ref: "#/components/schemas/MatchupCharResponse"
"404":
description: Player or character not found
/supporters:
get:
summary: Get list of supporters
responses:
"200":
description: Successfully returned list of supporters
content:
application/json:
schema:
type: array
items:
$ref: "#/components/schemas/Supporter"
/distribution:
get:
summary: Get player rating distribution data
responses:
"200":
description: Successfully returned rating distribution data
content:
application/json:
schema:
$ref: "#/components/schemas/DistributionResponse"
"404":
description: Distribution data not found
/health:
get:
summary: Get health status of the system
responses:
"200":
description: System is healthy
content:
text/plain:
schema:
type: string
example: "OK"
"500":
description: System health check failed
content:
text/plain:
schema:
type: string
example: "No New (2m) Replays!"
/calc_rating:
get:
summary: Calculate rating changes for a match
parameters:
- in: query
name: rating_a
schema:
type: number
format: float
required: true
description: Player A's current rating
- in: query
name: drift_a
schema:
type: number
format: float
required: true
description: Player A's current drift (must be > 1.0)
- in: query
name: rating_b
schema:
type: number
format: float
required: true
description: Player B's current rating
- in: query
name: drift_b
schema:
type: number
format: float
required: true
description: Player B's current drift (must be > 1.0)
- in: query
name: a_wins
schema:
type: boolean
required: true
description: Whether player A wins the match
responses:
"200":
description: Successfully calculated rating changes
content:
application/json:
schema:
$ref: "#/components/schemas/CalcRatingResponse"
"400":
description: Bad request - drift values must be greater than 1
/avatar/{player_id}:
get:
summary: Get player's avatar image
parameters:
- in: path
name: player_id
schema:
type: integer
format: int64
required: true
description: ID of the player
responses:
"200":
description: Successfully returned player's avatar
content:
image/png:
schema:
type: string
format: binary
"404":
description: Player not found
"503":
description: GGST is not connected
components:
schemas:
PlayerResponse:
type: object
properties:
id:
type: integer
format: int64
description: Player's ID
name:
type: string
description: Player's name
ratings:
type: array
description: Player's ratings for each character
items:
$ref: "#/components/schemas/PlayerResponsePlayer"
platform:
type: string
description: Player's platform (PS, XB, PC)
status:
type: string
description: Player's status (Public, Private, Cheater)
top_global:
type: integer
format: int32
description: Player's top global rank
tags:
type: array
description: Player's tags (awards, titles, etc.)
items:
$ref: "#/components/schemas/TagResponse"
PlayerResponsePlayer:
type: object
properties:
rating:
type: number
format: float
description: Player's rating for the character
deviation:
type: number
format: float
description: Player's rating deviation for the character
char_short:
type: string
description: Short name of the character (e.g., "SO" for Sol)
character:
type: string
description: Full name of the character
match_count:
type: integer
format: int32
description: Number of matches played with the character
top_char:
type: integer
format: int32
description: Player's top rank for the character
top_defeated:
$ref: "#/components/schemas/TopDefeated"
top_rating:
$ref: "#/components/schemas/TopRating"
PlayerGamesResponse:
type: object
properties:
history:
type: array
description: Player's match history
items:
$ref: "#/components/schemas/PlayerSet"
tags:
type: object
description: Player tags indexed by player ID
additionalProperties:
type: array
items:
$ref: "#/components/schemas/TagResponse"
PlayerSet:
type: object
properties:
timestamp:
type: string
description: Timestamp of the match
own_rating_value:
type: number
format: float
description: Player's rating value at the time of the match
own_rating_deviation:
type: number
format: float
description: Player's rating deviation at the time of the match
floor:
type: string
description: Floor of the match (e.g., "Celestial")
opponent_name:
type: string
description: Opponent's name
opponent_platform:
type: string
description: Opponent's platform (PS, XB, PC)
opponent_id:
type: integer
format: int64
description: Opponent's ID
opponent_character:
type: string
description: Opponent's character (full name)
opponent_character_short:
type: string
description: Opponent's character (short name)
opponent_rating_value:
type: number
format: float
description: Opponent's rating value at the time of the match
opponent_rating_deviation:
type: number
format: float
description: Opponent's rating deviation at the time of the match
result_win:
type: boolean
description: Whether the player won the match
odds:
type: number
format: float
description: Player's odds of winning the match
RankResponse:
type: object
properties:
ranks:
type: array
description: List of player rankings
items:
$ref: "#/components/schemas/PlayerRankResponse"
PlayerRankResponse:
type: object
properties:
rank:
type: integer
format: int32
description: Player's rank
id:
type: integer
format: int64
description: Player's ID
name:
type: string
description: Player's name
rating:
type: number
format: float
description: Player's rating
deviation:
type: number
format: float
description: Player's rating deviation
char_short:
type: string
description: Short name of the character
char_long:
type: string
description: Full name of the character
tags:
type: array
description: Player's tags (awards, titles, etc.)
items:
$ref: "#/components/schemas/TagResponse"
SearchResponse:
type: object
properties:
results:
type: array
description: List of search results
items:
$ref: "#/components/schemas/PlayerSearchResponse"
PlayerSearchResponse:
type: object
properties:
id:
type: integer
format: int64
description: Player's ID
name:
type: string
description: Player's name
rating:
type: number
format: float
description: Player's rating
deviation:
type: number
format: float
description: Player's rating deviation
char_short:
type: string
description: Short name of the character
char_long:
type: string
description: Full name of the character
SettingsResponse:
type: object
properties:
id:
type: integer
format: int64
description: Player's ID
name:
type: string
description: Player's name
status:
type: string
description: Player's status (Public, Private, Cheater)
RatingsResponse:
type: object
properties:
timestamp:
type: string
description: Timestamp of the rating
rating:
type: number
format: float
description: Player's rating at the time
StatsResponse:
type: object
properties:
timestamp:
type: string
description: Timestamp of the last update
total_games:
type: integer
format: int64
description: Total number of games played
one_month_games:
type: integer
format: int64
description: Number of games played in the last month
one_week_games:
type: integer
format: int64
description: Number of games played in the last week
one_day_games:
type: integer
format: int64
description: Number of games played in the last day
one_hour_games:
type: integer
format: int64
description: Number of games played in the last hour
total_players:
type: integer
format: int64
description: Total number of players
one_month_players:
type: integer
format: int64
description: Number of players in the last month
one_week_players:
type: integer
format: int64
description: Number of players in the last week
one_day_players:
type: integer
format: int64
description: Number of players in the last day
one_hour_players:
type: integer
format: int64
description: Number of players in the last hour
PopularityResult:
type: object
properties:
per_player:
type: array
description: Character popularity per player
items:
$ref: "#/components/schemas/PopularityResultChar"
per_character:
type: array
description: Character popularity per character
items:
$ref: "#/components/schemas/PopularityResultChar"
per_player_total:
type: integer
format: int64
description: Total number of players for popularity calculation
per_character_total:
type: integer
format: int64
description: Total number of characters for popularity calculation
last_update:
type: string
description: Timestamp of the last update
PopularityResultChar:
type: object
properties:
name:
type: string
description: Character name
value:
type: integer
format: int64
description: Popularity value
MatchupResponse:
type: object
properties:
last_update:
type: string
format: date-time
data_all:
type: array
items:
$ref: "#/components/schemas/MatchupCharResponse"
data_1700:
type: array
items:
$ref: "#/components/schemas/MatchupCharResponse"
MatchupCharResponse:
type: object
properties:
char_name:
type: string
char_short:
type: string
matchups:
type: array
items:
$ref: "#/components/schemas/MatchupEntry"
MatchupEntry:
type: object
properties:
char_name:
type: string
char_short:
type: string
wins:
type: integer
format: int64
total_games:
type: integer
format: int64
Supporter:
type: object
properties:
id:
type: integer
format: int64
name:
type: string
tags:
type: array
items:
$ref: "#/components/schemas/TagResponse"
TagResponse:
type: object
properties:
tag:
type: string
style:
type: string
DistributionResponse:
type: object
properties:
timestamp:
type: string
description: Timestamp of the distribution data
data:
$ref: "#/components/schemas/DistributionEntry"
DistributionEntry:
type: object
properties:
distribution_floor:
type: array
items:
type: array
items:
type: integer
format: int64
description: Distribution data by floor
one_month_players:
type: integer
format: int64
description: Number of players in the last month
distribution_rating:
type: array
items:
type: object
description: Rating distribution results
CalcRatingResponse:
type: object
properties:
rating_a_new:
type: number
format: float
description: Player A's new rating after the match
drift_a_new:
type: number
format: float
description: Player A's new drift after the match
rating_b_new:
type: number
format: float
description: Player B's new rating after the match
drift_b_new:
type: number
format: float
description: Player B's new drift after the match
win_prob:
type: number
format: float
description: Probability that Player A wins the match
TopDefeated:
type: object
properties:
timestamp:
type: string
description: Timestamp when this opponent was defeated
id:
type: integer
format: int64
description: ID of the defeated opponent
name:
type: string
description: Name of the defeated opponent
char_short:
type: string
description: Character used by the defeated opponent
value:
type: number
format: float
description: Rating of the defeated opponent at the time
deviation:
type: number
format: float
description: Rating deviation of the defeated opponent
TopRating:
type: object
properties:
timestamp:
type: string
description: Timestamp when this rating was achieved
value:
type: number
format: float
description: The top rating value achieved
deviation:
type: number
format: float
description: Rating deviation at the time of top rating