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)
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
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)
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}:
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)
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}:
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)
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'
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
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
PlayerGamesResponse:
type: object
properties:
history:
type: array
description: Player's match history
items:
$ref: '#/components/schemas/PlayerSet'
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: string
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
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