Talo

https://docs.trytalo.com
Admin
Talo is an open-source backend platform for game developers providing leaderboards, player...
Tokens:78,330
Snippets:919
Trust Score:6.8
Update:2 months ago
Show doc for...
Tokens:
Raw
### GET https://api.trytalo.com/v1/game-config

Source: https://docs.trytalo.com/docs/http/game-config-api

Retrieves the live configuration for the game as a collection of key-value pairs.

```APIDOC
## GET https://api.trytalo.com/v1/game-config

### Description
Retrieves the live configuration for the game. This allows the game to fetch the latest settings defined in the Talo dashboard.

### Method
GET

### Endpoint
https://api.trytalo.com/v1/game-config

### Response
#### Success Response (200)
- **config** (object) - A collection of key-value pairs representing the game configuration.

#### Response Example
{
  "maxLevel": "10",
  "betaEnabled": true
}
```

--------------------------------

### GET /v1/game-stats

Source: https://docs.trytalo.com/docs/http/game-stat-api

Retrieves all game stats.

```APIDOC
## GET /v1/game-stats

### Description
Retrieves all game stats.

### Method
GET

### Endpoint
https://api.trytalo.com/v1/game-stats
```

--------------------------------

### GET https://api.trytalo.com/v1/game-channels/subscriptions

Source: https://docs.trytalo.com/docs/http/game-channel-api

List game channels that the player is currently subscribed to.

```APIDOC
## GET https://api.trytalo.com/v1/game-channels/subscriptions

### Description
List game channels that the player is subscribed to.

### Method
GET

### Endpoint
https://api.trytalo.com/v1/game-channels/subscriptions

### Parameters
#### Headers
- **x-talo-alias** (string) - Required - The ID of the player's alias

#### Query Parameters
- **propKey** (string) - Optional - Only return channels with this prop key
- **propValue** (string) - Optional - Only return channels with a matching prop key and value
```

--------------------------------

### GET https://api.trytalo.com/v1/game-channels/:id/storage/list

Source: https://docs.trytalo.com/docs/http/game-channel-api

Retrieve multiple storage properties from a game channel.

```APIDOC
## GET https://api.trytalo.com/v1/game-channels/:id/storage/list

### Description
Get multiple storage properties from a game channel.

### Method
GET

### Endpoint
https://api.trytalo.com/v1/game-channels/:id/storage/list

### Parameters
#### Headers
- **x-talo-alias** (string) - Required - The ID of the player's alias

#### Path Parameters
- **id** (string) - Required - The ID of the channel

#### Query Parameters
- **propKeys** (array) - Required - An array of storage property keys to retrieve (maximum 50 keys)
```

--------------------------------

### GET https://api.trytalo.com/v1/game-channels

Source: https://docs.trytalo.com/docs/http/game-channel-api

List all game channels, with optional filtering by property keys, values, or search terms.

```APIDOC
## GET https://api.trytalo.com/v1/game-channels

### Description
List game channels. Supports pagination and filtering by property keys, values, or name search.

### Method
GET

### Endpoint
https://api.trytalo.com/v1/game-channels

### Parameters
#### Query Parameters
- **page** (number) - Optional - The current pagination index (starting at 0)
- **propKey** (string) - Optional - Only return channels with this prop key
- **propValue** (string) - Optional - Only return channels with a matching prop key and value
- **search** (string) - Optional - Search term to filter channels by name
```

--------------------------------

### Get Storage Prop Arrays

Source: https://docs.trytalo.com/docs/unity/channels

Fetches all items associated with a specific prop array key.

```csharp
var propKey = "world_items";  

  

// checks the internal cache first  

var arrayItems = await Talo.Channels.GetStoragePropArray(channel.id, propKey, false /* default */);  

  

// fetches the latest data directly from the database  

var freshArrayItems = await Talo.Channels.GetStoragePropArray(channel.id, propKey, true);  

  

foreach (var prop in arrayItems)  

{  

		Debug.Log(prop.value);  

}
```

--------------------------------

### Identify a player response examples

Source: https://docs.trytalo.com/docs/http/player-api

Various response formats for player identification across different authentication services.

```json
{
  ... 
}
```

```json
{
  ... 
}
```

```json
{
  ... 
}
```

```json
{
  ... 
}
```

```json
{
  ... 
}
```

--------------------------------

### Handle session discovery signals

Source: https://docs.trytalo.com/docs/godot/player-authentication

Connects to session_found and session_not_found signals to manage UI flow when starting a session.

```GDScript
func _ready() -> void:  

	# auto_start_session should be disabled  

	Talo.player_auth.session_found.connect(func (): go_to_loading())  

	Talo.player_auth.session_not_found.connect(func (): go_to_login())  

	Talo.player_auth.start_session()
```

--------------------------------

### Send a signed socket message

Source: https://docs.trytalo.com/docs/sockets/request-verification

Example of prepending the generated signature to a JSON message before sending via socket.

```javascript
const message = JSON.stringify({  
	req: 'v1.channels.message',  
	data: { channel: { id: 1 }, message: 'Hello' },  
})  
const signature = buildSignature(message, key, version)  

  

socket.send(`${signature}\n${message}`)
```

--------------------------------

### GET https://api.trytalo.com/v1/game-channels/:id/storage

Source: https://docs.trytalo.com/docs/http/game-channel-api

Retrieve a single storage property from a game channel.

```APIDOC
## GET https://api.trytalo.com/v1/game-channels/:id/storage

### Description
Get a single storage property from a game channel.

### Method
GET

### Endpoint
https://api.trytalo.com/v1/game-channels/:id/storage

### Parameters
#### Headers
- **x-talo-alias** (string) - Required - The ID of the player's alias

#### Path Parameters
- **id** (string) - Required - The ID of the channel

#### Query Parameters
- **propKey** (string) - Required - The key of the storage property to retrieve
```

--------------------------------

### Migrate player account to Steam

Source: https://docs.trytalo.com/docs/godot/player-authentication

Example of migrating a player account to a Steam alias using the Talo player authentication service.

```gdscript
@onready var current_password: TextEdit = %CurrentPassword  

@onready var new_service: OptionButton = %NewService  

@onready var new_identifier: TextEdit = %NewIdentifier  

@onready var validation_label: Label = %ValidationLabel  

  

var ticket_identity := "talo"  

  

func _ready() -> void:  

	Steam.steamInitEx()  

	Steam.get_ticket_for_web_api.connect(_on_get_ticket_for_web_api)  

	Steam.getAuthTicketForWebApi(ticket_identity)  

  

func _on_get_ticket_for_web_api(_auth_ticket: int, _result: int, _ticket_size: int, ticket_buffer: Array) -> void:  

	_migrate_account(PackedByteArray(ticket_buffer).hex_encode())  

  

func _migrate_account(ticket: String) -> void:  

	var res = await Talo.player_auth.migrate_account(current_password.text, "steam", "%s:%s" % [ticket_identity, ticket])  

  

	if res != OK:  

		validation_label.text = Talo.player_auth.last_error.get_string()
```

--------------------------------

### GET https://api.trytalo.com/v1/players/identify

Source: https://docs.trytalo.com/docs/http/player-api

Identifies a player based on a service and unique identifier. You must provide the write:players scope to create a new player if one does not already exist.

```APIDOC
## GET https://api.trytalo.com/v1/players/identify

### Description
Identifies a player based on a service and unique identifier. You must provide the write:players scope to create a new player if one does not already exist.

### Method
GET

### Endpoint
https://api.trytalo.com/v1/players/identify

### Parameters
#### Query Parameters
- **identifier** (string) - Required - The unique identifier of the player. This can be their username, an email or a numeric ID
- **service** (string) - Required - The name of the service where the identity of the player comes from (e.g. "steam", "epic" or "username")
```

--------------------------------

### GET https://api.trytalo.com/v1/leaderboards/:internalName/entries

Source: https://docs.trytalo.com/docs/http/leaderboard-api

Retrieves a paginated list of entries for a specific leaderboard, with support for filtering by player, alias, date range, and properties.

```APIDOC
## GET https://api.trytalo.com/v1/leaderboards/:internalName/entries

### Description
Retrieves 50 results per page for a leaderboard, sorted by the leaderboard's defined order.

### Method
GET

### Endpoint
https://api.trytalo.com/v1/leaderboards/:internalName/entries

### Parameters
#### Path Parameters
- **internalName** (string) - Required - The internal name of the leaderboard

#### Query Parameters
- **aliasId** (string) - Optional - Only return entries for this alias ID
- **aliasService** (string) - Optional - Only return entries for this player alias service
- **endDate** (string) - Optional - A UTC Date, DateTime, or millisecond timestamp
- **page** (integer) - Optional - The current pagination index (starting at 0)
- **playerId** (string) - Optional - Only return entries for this player ID
- **propKey** (string) - Optional - Only return entries with this prop key
- **propValue** (string) - Optional - Only return entries with a matching prop key and value
- **startDate** (string) - Optional - A UTC Date, DateTime, or millisecond timestamp
- **withDeleted** (boolean) - Required - Include entries that were deleted by a refresh interval
```

--------------------------------

### Typical Saved Object Structure

Source: https://docs.trytalo.com/docs/unity/saves

Example of the JSON structure used for saved objects, containing a unique ID, object name, and serialized data fields.

```json
{

	id: "level1cube2",

	name: "Level1.Cubes.Cube2"
	data: [  

		{  

			key: "x",  

			type: "System.Single",  

			value: "0.4036766"  

		},  

		{  

			key: "y",  

			type: "System.Single",  

			value: "0.4561406"  

		},  

		{  

			key: "z",  

			type: "System.Single",  

			value: "0"  

		}  

	],  

},  
```

--------------------------------

### Fetch Live Config in Unity

Source: https://docs.trytalo.com/docs/unity/live-config

Initialize the configuration by subscribing to the OnLiveConfigLoaded event and calling Talo.GameConfig.Get().

```csharp
void Start()  

{  

	Talo.GameConfig.OnLiveConfigLoaded += OnLiveConfigLoaded;  

	// first fetch the config  

	_ = Talo.GameConfig.Get();  

}  

  

void OnLiveConfigLoaded(TaloLiveConfig config)  

{  

	// now you can query the config  

}  
```

--------------------------------

### Fetch and initialize live config in Godot

Source: https://docs.trytalo.com/docs/godot/live-config

Connect to the live_config_loaded signal before requesting the configuration to handle the asynchronous initialization.

```gdscript
func _ready() -> void:  

	Talo.game_config.live_config_loaded.connect(_on_live_config_loaded)  

	# first fetch the config  

	Talo.game_config.get_live_config()  

  

func _on_live_config_loaded(config: TaloLiveConfig):  

	# now you can query the config  

	pass  
```

--------------------------------

### GET /v1/game-stats/:internalName

Source: https://docs.trytalo.com/docs/http/game-stat-api

Retrieves an individual game stat.

```APIDOC
## GET /v1/game-stats/:internalName

### Description
Retrieves an individual game stat.

### Method
GET

### Endpoint
https://api.trytalo.com/v1/game-stats/:internalName

### Parameters
#### Path Parameters
- **internalName** (string) - Required - The internal name of the stat
```

--------------------------------

### Initialize S3mini storage client

Source: https://docs.trytalo.com/docs/selfhosting/configuration

Internal logic used by Talo to map environment variables to the S3mini client.

```javascript
// if S3_ENDPOINT isn't set, use the default S3 URL  

const endpoint = process.env.S3_ENDPOINT ?? 'https://s3.amazonaws.com'  

const bucket = process.env.S3_BUCKET  

const endpointWithBucket = endpoint + bucket  

  

return new S3mini({  

	accessKeyId: process.env.S3_ACCESS_KEY_ID!,  

	secretAccessKey: process.env.S3_SECRET_ACCESS_KEY!,  

	endpoint: endpointWithBucket,  

	region: process.env.S3_REGION,  

})  
```

--------------------------------

### GET /v1/game-stats/:internalName/global-history

Source: https://docs.trytalo.com/docs/http/game-stat-api

Retrieves a history of changes to a global stat.

```APIDOC
## GET /v1/game-stats/:internalName/global-history

### Description
Retrieves a history of changes to a global stat.

### Method
GET

### Endpoint
https://api.trytalo.com/v1/game-stats/:internalName/global-history

### Parameters
#### Path Parameters
- **internalName** (string) - Required - The internal name of the stat

#### Query Parameters
- **endDate** (string) - Optional - A UTC Date (YYYY-MM-DD), DateTime (ISO 8601) or millisecond timestamp
- **page** (number) - Optional - The current pagination index (starting at 0)
- **playerId** (string) - Optional - A player ID to use when filtering snapshots
- **startDate** (string) - Optional - A UTC Date (YYYY-MM-DD), DateTime (ISO 8601) or millisecond timestamp
```

--------------------------------

### GET /v1/game-stats/:internalName/history

Source: https://docs.trytalo.com/docs/http/game-stat-api

Retrieves a history of changes to a player stat.

```APIDOC
## GET /v1/game-stats/:internalName/history

### Description
Retrieves a history of changes to a player stat.

### Method
GET

### Endpoint
https://api.trytalo.com/v1/game-stats/:internalName/history

### Parameters
#### Path Parameters
- **internalName** (string) - Required - The internal name of the stat

#### Headers
- **x-talo-player** (string) - Required - The ID of the player

#### Query Parameters
- **endDate** (string) - Optional - A UTC Date (YYYY-MM-DD), DateTime (ISO 8601) or millisecond timestamp
- **page** (number) - Optional - The current pagination index (starting at 0)
- **startDate** (string) - Optional - A UTC Date (YYYY-MM-DD), DateTime (ISO 8601) or millisecond timestamp
```

--------------------------------

### GET /v1/game-stats/player-stats

Source: https://docs.trytalo.com/docs/http/game-stat-api

Retrieves the current values of all the player's stats.

```APIDOC
## GET /v1/game-stats/player-stats

### Description
Retrieves the current values of all the player's stats.

### Method
GET

### Endpoint
https://api.trytalo.com/v1/game-stats/player-stats

### Parameters
#### Headers
- **x-talo-alias** (string) - Required - The ID of the player's alias
```

--------------------------------

### Register a new player in Unity

Source: https://docs.trytalo.com/docs/unity/player-authentication

Uses Talo.PlayerAuth.Register to create a new account with optional email verification. Handles common registration errors like taken usernames or profanity.

```csharp
private async void OnRegisterClick()  

{  

	var username = root.Q<TextField>("username").text;  

	var password = root.Q<TextField>("password").text;  

	var enableVerification = root.Q<Toggle>("enable-verification").value;  

	var email = root.Q<TextField>("email").text;  

  

	var validationLabel = root.Q<Label>("validation-label");  

  

	if (string.IsNullOrEmpty(username))  

	{  

		validationLabel.text = "Username is required";  

		return;  

	}  

  

	if (string.IsNullOrEmpty(password))  

	{  

		validationLabel.text = "Password is required";  

		return;  

	}  

  

	validationLabel.text = "";  

  

	try  

	{  

		await Talo.PlayerAuth.Register(username, password, email, enableVerification);  

	}  

	catch (PlayerAuthException ex)  

	{  

		validationLabel.text = ex.ErrorCode switch  

		{  

			PlayerAuthErrorCode.IDENTIFIER_TAKEN => "Username is already taken",  

			PlayerAuthErrorCode.IDENTIFIER_PROFANITY => "Username contains profanity",  

			_ => ex.Message  

		};  

	}  

	catch (Exception ex)  

	{  

		validationLabel.text = ex.Message;  

	}  

}  
```

--------------------------------

### GET /v1/players/relationships/subscriptions

Source: https://docs.trytalo.com/docs/http/player-relationships-api

Retrieves a list of subscriptions where the current player is the subscriber.

```APIDOC
## GET https://api.trytalo.com/v1/players/relationships/subscriptions

### Description
Retrieves a list of subscriptions where the current player is the subscriber.

### Method
GET

### Endpoint
https://api.trytalo.com/v1/players/relationships/subscriptions

### Parameters
#### Headers
- **x-talo-alias** (string) - Required - The ID of the player's alias

#### Query Parameters
- **aliasId** (string) - Optional - Filter by a specific subscribed-to alias ID
- **confirmed** (string) - Optional - Filter by confirmation status ("true" or "false")
- **page** (integer) - Optional - Page number for pagination (default: 0)
- **relationshipType** (string) - Optional - Filter by relationship type ("unidirectional" or "bidirectional")
```

--------------------------------

### Query Live Config Properties

Source: https://docs.trytalo.com/docs/unity/live-config

Retrieve specific configuration values by key, optionally providing a default value if the property is missing.

```csharp
var halloweenEventEnabled = Talo.LiveConfig.GetProp<bool>("halloweenEventEnabled");  
```

```csharp
var maxLevel = Talo.LiveConfig.GetProp<int>("maxLevel");  
```

--------------------------------

### GET /v1/game-feedback/categories

Source: https://docs.trytalo.com/docs/http/game-feedback-api

Retrieves a list of available feedback categories for the game.

```APIDOC
## GET /v1/game-feedback/categories

### Description
Retrieves a list of available feedback categories.

### Method
GET

### Endpoint
https://api.trytalo.com/v1/game-feedback/categories

### Response
#### Success Response (200)
- **Response** (JSON) - A list of available feedback categories.
```

--------------------------------

### Talo.channels.create()

Source: https://docs.trytalo.com/docs/godot/channels

Creates a new game channel with a name, auto-cleanup settings, and custom properties.

```APIDOC
## Talo.channels.create(options: CreateChannelOptions)

### Description
Creates a new channel. `auto_cleanup` deletes the channel when the owner or last member leaves. `props` allows storing arbitrary string key/value pairs.

### Parameters
- **options** (CreateChannelOptions) - Required - Configuration object including `name` (string), `auto_cleanup` (bool), and `props` (Dictionary).

### Example
```gdscript
var options := Talo.channels.CreateChannelOptions.new()
options.name = "channel name"
options.auto_cleanup = true
options.props = { "prop_key": "prop_value" }
var channel := await Talo.channels.create(options)
```
```

--------------------------------

### Configure verification in settings.cfg

Source: https://docs.trytalo.com/docs/godot/request-verification

Add these settings to the [verification] section of your addons/talo/settings.cfg file to enable request signing.

```ini
[verification]  

enabled=true  

key_version="1"  

key_value="your-secret-key"  
```

--------------------------------

### GET /v1/game-stats/:internalName/player-stat

Source: https://docs.trytalo.com/docs/http/game-stat-api

Retrieves the current value of a player's stat.

```APIDOC
## GET /v1/game-stats/:internalName/player-stat

### Description
Retrieves the current value of a player's stat.

### Method
GET

### Endpoint
https://api.trytalo.com/v1/game-stats/:internalName/player-stat

### Parameters
#### Path Parameters
- **internalName** (string) - Required - The internal name of the stat

#### Headers
- **x-talo-alias** (string) - Required - The ID of the player's alias
```

--------------------------------

### Create a new channel in Unity

Source: https://docs.trytalo.com/docs/unity/channels

Create a channel with a name, auto-cleanup settings, and custom property tuples.

```csharp
var props = new (string, string)[]  

{  

		("propKey", "propValue")  

};

var channel = await Talo.Channels.Create(new CreateChannelOptions() { name = channelName, autoCleanup = true, props = props });
```

--------------------------------

### GET /v1/players/relationships/subscribers

Source: https://docs.trytalo.com/docs/http/player-relationships-api

Retrieves a list of subscriptions from players who have subscribed to the current player.

```APIDOC
## GET https://api.trytalo.com/v1/players/relationships/subscribers

### Description
Retrieves a list of subscriptions from players who have subscribed to the current player.

### Method
GET

### Endpoint
https://api.trytalo.com/v1/players/relationships/subscribers

### Parameters
#### Headers
- **x-talo-alias** (string) - Required - The ID of the player's alias

#### Query Parameters
- **aliasId** (string) - Optional - Filter by a specific subscriber alias ID
- **confirmed** (boolean) - Optional - Filter by confirmation status (true or false)
- **page** (integer) - Optional - Page number for pagination (default: 0)
- **relationshipType** (string) - Optional - Filter by relationship type (unidirectional or bidirectional)
```

--------------------------------

### Create a save request and response

Source: https://docs.trytalo.com/docs/http/game-save-api

Sample JSON structures for creating a new game save.

```json
{
  ... 
}
```

```json
{
  ... 
}
```

--------------------------------

### GET /v1/player-groups/:id

Source: https://docs.trytalo.com/docs/http/player-group-api

Retrieves a specific player group and its associated members.

```APIDOC
## GET /v1/player-groups/:id

### Description
Retrieves the details of a specific player group and its members. Pagination for members can be controlled via query parameters.

### Method
GET

### Endpoint
https://api.trytalo.com/v1/player-groups/:id

### Parameters
#### Path Parameters
- **id** (string) - Required - The ID of the group

#### Query Parameters
- **membersPage** (integer) - Optional - The current pagination index for group members (starting at 0)
```

--------------------------------

### Register a new player in Godot

Source: https://docs.trytalo.com/docs/godot/player-authentication

Uses Talo.player_auth.register to create a new player account and handles potential registration errors.

```GDScript
@onready var username: TextEdit = %Username  

@onready var password: TextEdit = %Password  

@onready var enable_verification: CheckBox = %EnableVerification  

@onready var email: TextEdit = %Email  

@onready var validation_label: Label = %ValidationLabel  

  

...  

  

var res = await Talo.player_auth.register(username.text, password.text, email.text, enable_verification.button_pressed)  

if res != OK:  

	match Talo.player_auth.last_error.get_code():  

		TaloAuthError.ErrorCode.IDENTIFIER_TAKEN:  

			validation_label.text = "Username is already taken"  

		TaloAuthError.ErrorCode.IDENTIFIER_PROFANITY:  

			validation_label.text = "Username contains profanity"  

		_:  

			validation_label.text = Talo.player_auth.last_error.get_string()
```

--------------------------------

### GET https://api.trytalo.com/v1/game-channels/:id

Source: https://docs.trytalo.com/docs/http/game-channel-api

Find a specific game channel by its ID.

```APIDOC
## GET https://api.trytalo.com/v1/game-channels/:id

### Description
Find a game channel.

### Method
GET

### Endpoint
https://api.trytalo.com/v1/game-channels/:id

### Parameters
#### Path Parameters
- **id** (string) - Required - The ID of the channel
```

--------------------------------

### POST https://api.trytalo.com/v1/game-channels

Source: https://docs.trytalo.com/docs/http/game-channel-api

Create a new game channel.

```APIDOC
## POST https://api.trytalo.com/v1/game-channels

### Description
Create a game channel.

### Method
POST

### Endpoint
https://api.trytalo.com/v1/game-channels

### Parameters
#### Headers
- **x-talo-alias** (string) - Required - The ID of the player's alias

#### Request Body
- **autoCleanup** (boolean) - Optional - Whether the channel should be automatically deleted when the owner leaves or the channel is empty (default is false)
- **name** (string) - Required - The name of the channel
- **private** (boolean) - Optional - Private channels require invites to join them (default is false)
- **props** (array) - Optional - An array of Props
- **temporaryMembership** (boolean) - Optional - Whether members should be removed when they disconnect (default is false)
```

--------------------------------

### GET https://api.trytalo.com/v1/game-channels/:id/members

Source: https://docs.trytalo.com/docs/http/game-channel-api

Retrieve the members of a specific game channel.

```APIDOC
## GET https://api.trytalo.com/v1/game-channels/:id/members

### Description
Get the members of a game channel.

### Method
GET

### Endpoint
https://api.trytalo.com/v1/game-channels/:id/members

### Parameters
#### Headers
- **x-talo-alias** (string) - Required - The ID of the player's alias

#### Path Parameters
- **id** (string) - Required - The ID of the channel

#### Query Parameters
- **aliasId** (string) - Optional - Find a member with this player alias ID
- **identifier** (string) - Optional - Find a member with this identifier
- **page** (number) - Optional - The current pagination index (starting at 0)
- **playerGroupId** (string) - Optional - Filter members by players in this group
- **playerId** (string) - Optional - Filter members by this player ID
- **playerPropKey** (string) - Optional - Filter members by players with this prop key
- **playerPropValue** (string) - Optional - Filter members by players with matching prop keys and values
```

--------------------------------

### Talo.channels.create(options)

Source: https://docs.trytalo.com/docs/godot/channels

Creates a new channel.

```APIDOC
## Talo.channels.create(options)

### Description
Creates a new channel using CreateChannelOptions. Supports setting the channel as private.
```

--------------------------------

### POST /v1/players/auth/register

Source: https://docs.trytalo.com/docs/http/player-auth-api

Creates a new player account in the Talo system.

```APIDOC
## POST https://api.trytalo.com/v1/players/auth/register

### Description
Creates a new player account.

### Method
POST

### Endpoint
https://api.trytalo.com/v1/players/auth/register

### Parameters
#### Request Body
- **email** (string) - Optional - Required when verification is enabled. Used for password resets.
- **identifier** (string) - Required - The unique identifier of the player (username, email, or numeric ID).
- **password** (string) - Required - The password the player will login with.
- **verificationEnabled** (boolean) - Optional - When enabled, the player will be sent a verification code to their email address before they can login.
- **withRefresh** (boolean) - Optional - When true, the response will include a refreshToken alongside a short-lived sessionToken.
```

--------------------------------

### GET https://api.trytalo.com/v1/players/:id

Source: https://docs.trytalo.com/docs/http/player-api

Retrieves information for a specific player by their ID.

```APIDOC
## GET https://api.trytalo.com/v1/players/:id

### Description
Retrieves information for a specific player by their ID.

### Method
GET

### Endpoint
https://api.trytalo.com/v1/players/:id
```

--------------------------------

### GET https://api.trytalo.com/v1/game-saves

Source: https://docs.trytalo.com/docs/http/game-save-api

Retrieves a list of all saves associated with a specific player.

```APIDOC
## GET https://api.trytalo.com/v1/game-saves

### Description
Retrieves a list of all saves associated with a specific player.

### Method
GET

### Endpoint
https://api.trytalo.com/v1/game-saves

### Parameters
#### Headers
- **x-talo-player** (string) - Required - The ID of the player
```

--------------------------------

### Create a new channel in Godot

Source: https://docs.trytalo.com/docs/godot/channels

Initialize a channel with a name, auto-cleanup configuration, and custom dictionary properties.

```gdscript
var options := Talo.channels.CreateChannelOptions.new()  

options.name = "channel name"  

options.auto_cleanup = true  

options.props: Dictionary[String, String] = {  

	prop_key = "prop_value"  

}  

var channel := await Talo.channels.create(options)  

  

print(channel.name) # channel name  

print(channel.auto_cleanup) # true  

print(channel.props) # [{ "prop_key": "prop_value" }]  
```

--------------------------------

### Configure HyperDX environment variables

Source: https://docs.trytalo.com/docs/selfhosting/configuration

Required and recommended environment variables for enabling HyperDX observability.

```bash
HYPERDX_API_KEY=[your key]  

OTEL_EXPORTER_OTLP_ENDPOINT=[your opentelemetry collector endpoint]  

HDX_NODE_BETA_MODE=1 # enables trace attributes  

OTEL_NODE_DISABLED_INSTRUMENTATIONS=koa # this instrumentation isn't very helpful  
```

--------------------------------

### GET /v1/players/presence/:id

Source: https://docs.trytalo.com/docs/http/player-presence-api

Retrieves the online status and custom status for a specific player.

```APIDOC
## GET /v1/players/presence/:id

### Description
Retrieves the online status and custom status for a specific player.

### Method
GET

### Endpoint
https://api.trytalo.com/v1/players/presence/:id

### Parameters
#### Path Parameters
- **id** (string) - Required - The ID of the player

### Response
#### Success Response (200)
- **Response** (object) - Returns the player's presence information.
```

--------------------------------

### Login with Talo PlayerAuth

Source: https://docs.trytalo.com/docs/unity/player-authentication

Handles player login by capturing credentials and managing the verification flow if required.

```csharp
private async void OnLoginClick()  

{  

	var username = root.Q<TextField>("username").text;  

	var password = root.Q<TextField>("password").text;  

	var validationLabel = root.Q<Label>("validation-label");  

  

	if (string.IsNullOrEmpty(username))  

	{  

		validationLabel.text = "Username is required";  

		return;  

	}  

  

	if (string.IsNullOrEmpty(password))  

	{  

		validationLabel.text = "Password is required";  

		return;  

	}  

  

	validationLabel.text = "";  

  

	try  

	{  

		if (await Talo.PlayerAuth.Login(username, password))  

		{  

			SendMessageUpwards("GoToVerify", SendMessageOptions.RequireReceiver);  

		}  

	}  

	catch (PlayerAuthException ex)  

	{  

		validationLabel.text = ex.ErrorCode switch  

		{  

			PlayerAuthErrorCode.INVALID_CREDENTIALS => "Username or password is incorrect",  

			_ => ex.Message  

		};  

	}  

	catch (Exception ex)  

	{  

		validationLabel.text = ex.Message;  

	}  

}  
```

--------------------------------

### POST /v1/game-channels/:id/join

Source: https://docs.trytalo.com/docs/http/game-channel-api

Allows a player to join a specific game channel.

```APIDOC
## POST /v1/game-channels/:id/join

### Description
Allows a player to join a specific game channel.

### Method
POST

### Endpoint
https://api.trytalo.com/v1/game-channels/:id/join

### Parameters
#### Path Parameters
- **id** (string) - Required - The ID of the channel

#### Headers
- **x-talo-alias** (string) - Required - The ID of the player's alias
```

--------------------------------

### Talo.Channels.Invite()

Source: https://docs.trytalo.com/docs/unity/channels

Invites a player to a channel, which automatically adds them as a member. Requires write:gameChannels permission.

```APIDOC
## Talo.Channels.Invite()

### Description
Sends an invite to a player alias to join a specific channel.

### Parameters
- **channelId** (string) - Required - The ID of the channel.
- **playerAliasId** (string) - Required - The ID of the player to invite.
```

--------------------------------

### Subscribe to a player in Unity

Source: https://docs.trytalo.com/docs/unity/player-relationships

Creates a relationship subscription with a target player using their alias ID. Requires the write:playerRelationships permission.

```csharp
var searchPage = await Talo.Players.Search("target_player_identifier");  

var targetAliasId = searchPage.players[0].alias.id; // this assumes we found at least one player  

  

// unidirectional relationship  

await Talo.PlayerRelationships.SubscribeTo(targetAliasId, RelationshipType.Unidirectional);  

  

// or, bidirectional relationship  

await Talo.PlayerRelationships.SubscribeTo(targetAliasId, RelationshipType.Bidirectional);
```

--------------------------------

### Get Player Presence

Source: https://docs.trytalo.com/docs/godot/player-presence

Retrieves the presence status of a specific player using their ID.

```GDScript
var presence := await Talo.player_presence.get_presence(player_id)
```

--------------------------------

### Handle Session Events

Source: https://docs.trytalo.com/docs/unity/player-authentication

Subscribes to session discovery events to determine the appropriate UI flow upon game startup.

```csharp
private void Start()  

{  

	// autoStartSession should be disabled  

	Talo.PlayerAuth.OnSessionFound += () => GoToLoading();  

	Talo.PlayerAuth.OnSessionNotFound += () => GoToLogin();  

	Talo.PlayerAuth.StartSession();  

}  
```

--------------------------------

### Query live config properties

Source: https://docs.trytalo.com/docs/godot/live-config

Retrieve configuration values using get_prop, ensuring the returned string is cast to the appropriate data type.

```gdscript
var halloween_event_enabled = bool(Talo.live_config.get_prop("halloween_event_enabled"));  
```

--------------------------------

### Get player presence in Unity

Source: https://docs.trytalo.com/docs/unity/player-presence

Retrieves the current presence status for a specific player using their ID.

```csharp
var presence = await Talo.PlayerPresence.GetPresence(playerId);  
```

--------------------------------

### Create and Invite to Private Channel

Source: https://docs.trytalo.com/docs/unity/channels

Creates a new private channel and invites a player using their alias ID.

```csharp
var channel = await Talo.Channels.Create(new CreateChannelOptions() { name = "channel name", isPrivate = true }  

await Talo.Channels.Invite(channel.id, inviteePlayerAlias.id);  
```

--------------------------------

### v1.live-config.updated

Source: https://docs.trytalo.com/docs/sockets/responses

Sent when live config is updated.

```APIDOC
## v1.live-config.updated

### Description
Notifies all players when the live configuration is updated via the dashboard.

### Response
- **res** (string) - "v1.live-config.updated"
- **data** (object) - Contains the updated configuration props.
```

--------------------------------

### GET https://api.trytalo.com/v1/players/search

Source: https://docs.trytalo.com/docs/http/player-api

Searches for players based on IDs, prop values, alias identifiers, and display names.

```APIDOC
## GET https://api.trytalo.com/v1/players/search

### Description
Searches for players based on IDs, prop values, alias identifiers, and display names.

### Method
GET

### Endpoint
https://api.trytalo.com/v1/players/search

### Parameters
#### Query Parameters
- **query** (string) - Required - Search for players by IDs, prop values, alias identifiers and display names
```

--------------------------------

### POST /v1/players/auth/login

Source: https://docs.trytalo.com/docs/http/player-auth-api

Authenticates a player and returns a session token.

```APIDOC
## POST https://api.trytalo.com/v1/players/auth/login

### Description
Logs a player into their account.

### Method
POST

### Endpoint
https://api.trytalo.com/v1/players/auth/login

### Parameters
#### Request Body
- **identifier** (string) - Required - The unique identifier of the player.
- **password** (string) - Required - The player's password.
- **withRefresh** (boolean) - Optional - When true, the response will include a refreshToken alongside a short-lived sessionToken.
```

--------------------------------

### Talo.GameConfig.Get()

Source: https://docs.trytalo.com/docs/unity/live-config

Fetches the live configuration from the Talo dashboard. This method must be called before querying config properties and triggers the OnLiveConfigLoaded event.

```APIDOC
## Talo.GameConfig.Get()

### Description
Fetches the live configuration from the Talo dashboard. This must be called before querying the config and triggers the OnLiveConfigLoaded event.

### Method
void Talo.GameConfig.Get()

### Events
- **OnLiveConfigLoaded**: Invoked when the config is successfully initialized.
```

--------------------------------

### Talo.PlayerPresence.OnPresenceChanged

Source: https://docs.trytalo.com/docs/unity/player-presence

Event subscription for real-time player presence updates.

```APIDOC
## Talo.PlayerPresence.OnPresenceChanged

### Description
An event that triggers whenever a player's presence is updated. Provides the updated PlayerPresence object and flags indicating which fields changed.

### Signature
`public static event Action<PlayerPresence, bool, bool> OnPresenceChanged`

### Parameters
- **presence** (PlayerPresence) - The updated presence data.
- **onlineChanged** (bool) - Indicates if the online status was modified.
- **customStatusChanged** (bool) - Indicates if the custom status was modified.
```

--------------------------------

### Saved Object Structure

Source: https://docs.trytalo.com/docs/godot/saves

Example of the JSON structure representing a serialized object within a Talo save file.

```json
{

	id: "uuid-uuid-uuid-uuid",  

	name: "/root/MyScene/Player",  

	data: [  

		{  

			key: "stars",  

			type: "2",  

			value: "5"  

		},  

		{  

			key: "spawn_point",  

			type: "5",  

			value: "Vector2(225, 166)"  

		},  

		{  

			key: "spawn_level",  

			type: "4",  

			value: "\"green_zone\""  

		}  

	]  

}
```

--------------------------------

### Track player stats

Source: https://docs.trytalo.com/docs/unity/stats

Updates a stat value by its internal name. These examples demonstrate tracking deaths and healing amounts.

```csharp
public void OnDeath()  

{

	Talo.Stats.Track('deaths')  

}
```

```csharp
private float health;  

  

public void OnHeal(Potion potion)  

{

	health += potion.amount  

	Talo.Stats.Track('health-healed', potion.amount)  

}
```

--------------------------------

### Missing parameter error object

Source: https://docs.trytalo.com/docs/http/common-errors

Example of the error object structure returned when a request body is missing required fields.

```json
errors: {  

	events: ['events is missing from the request body']  

}  
```

--------------------------------

### Talo.game_config.get_live_config()

Source: https://docs.trytalo.com/docs/godot/live-config

Fetches the live configuration from the Talo dashboard. This method triggers the 'Talo.game_config.live_config_loaded' signal upon completion.

```APIDOC
## Talo.game_config.get_live_config()

### Description
Fetches the live configuration from the Talo dashboard. This must be called before querying the config. It emits the `Talo.game_config.live_config_loaded` signal.

### Signature
`void get_live_config()`
```

--------------------------------

### Listen for Live Config Updates

Source: https://docs.trytalo.com/docs/unity/live-config

Subscribe to the OnLiveConfigUpdated event to react to real-time changes pushed from the Talo dashboard.

```csharp
void Start()  

{  

	var textUI = GetComponent<TextMeshProUGUI>();  

  

	Talo.GameConfig.OnLiveConfigUpdated += (liveConfig) =>  

	{  

		textUI.text = liveConfig.GetProp("liveString", "Not set!");  

	};  

}  
```

--------------------------------

### Filter Leaderboard Entries by Player or Alias

Source: https://docs.trytalo.com/docs/godot/leaderboards

Examples for filtering leaderboard results by player ID, alias ID, or alias service.

```gdscript
var options := Talo.leaderboards.GetEntriesOptions.new()  

options.player_id = Talo.current_player.id  

  

var res := await Talo.leaderboards.get_entries(internal_name, options)
```

```gdscript
var options := Talo.leaderboards.GetEntriesOptions.new()  

options.alias_id = Talo.current_alias.id  

  

var res := await Talo.leaderboards.get_entries(internal_name, options)
```

```gdscript
var options := Talo.leaderboards.GetEntriesOptions.new()  

options.alias_service = "steam"  

  

var res := await Talo.leaderboards.get_entries(internal_name, options)
```

--------------------------------

### POST https://api.trytalo.com/v1/players/socket-token

Source: https://docs.trytalo.com/docs/http/player-api

Creates a socket token for a player.

```APIDOC
## POST https://api.trytalo.com/v1/players/socket-token

### Description
Creates a socket token for a player.

### Method
POST

### Endpoint
https://api.trytalo.com/v1/players/socket-token

### Parameters
#### Headers
- **x-talo-alias** (string) - Required - The ID of the player's alias
```

--------------------------------

### Get Storage Property

Source: https://docs.trytalo.com/docs/unity/channels

Retrieves a specific storage property for a channel. Note that fetching immediately after an update may return stale data due to internal caching.

```csharp
var options = new GetSubscribedChannelsOptions() { propKey = "guildId", propValue = "157" };  

var res = await Talo.Channels.GetSubscribedChannels(options);  

  

var channel = res[0];  

var prop = await Talo.Channels.GetStorageProp(channel.id, "shared-gold")  
```

--------------------------------

### Talo.channels.invite(channel_id, player_alias_id)

Source: https://docs.trytalo.com/docs/godot/channels

Invites a player to a channel.

```APIDOC
## Talo.channels.invite(channel_id, player_alias_id)

### Description
Sends an invite to a player to join a channel. Invited players join automatically.
```

--------------------------------

### v1.channels.player-joined

Source: https://docs.trytalo.com/docs/sockets/responses

Sent when a player joins a channel.

```APIDOC
## v1.channels.player-joined

### Description
Notifies channel members when a new player joins the channel.

### Response
- **res** (string) - "v1.channels.player-joined"
- **data** (object) - Contains the channel and the player alias of the player who joined.
```

--------------------------------

### Listen for Storage Updates

Source: https://docs.trytalo.com/docs/unity/channels

Subscribes to the OnChannelStoragePropsUpdated event to handle real-time updates to storage properties.

```csharp
void Start()  

{  
		Talo.Channels.OnChannelStoragePropsUpdated += OnChannelStoragePropsUpdated;  

}  

  

void OnChannelStoragePropsUpdated(Channel channel, ChannelStorageProp[] upsertedProps, ChannelStorageProp[] deletedProps)  

{  
		foreach (var prop in upsertedProps)  
		{  
				// e.g. "shared-gold: 80 upserted by jim"  
				Debug.Log($"{prop.key}:{prop.value} upserted by {prop.lastUpdatedBy.identifier}");  
		}  

  

		foreach (var prop in deletedProps)  
		{  
				// e.g. "shared-gold deleted by jim, previous value was 80"  
				Debug.Log($"{prop.key} deleted by {prop.lastUpdatedBy.identifier}, previous value was {prop.value}");  
		}  

}
```

--------------------------------

### Listen for Rejected Player Props in Unity

Source: https://docs.trytalo.com/docs/unity/player-props

Subscribe to the Talo.Players.OnPropsRejected event to handle individual prop update failures.

```csharp
private void OnEnable()  

{  

	Talo.Players.OnPropsRejected += OnPropsRejected;  

}  

  

private void OnDisable()  

{  

	Talo.Players.OnPropsRejected -= OnPropsRejected;  

}  

  

private void OnPropsRejected(RejectedProp[] rejectedProps)  

{  

	foreach (var prop in rejectedProps)  

	{  

		// prop.key: the key of the rejected prop  

		// prop.error: the rejection reason code (e.g. "PROP_VALUE_TOO_LONG")  

		// prop.message: a human-readable description of the rejection  

		Debug.Log($"Rejected prop '{prop.key}': {prop.message} ({prop.error})");  

	}  

}  
```

--------------------------------

### Adding logging configuration to settings.cfg

Source: https://docs.trytalo.com/docs/godot/install

Optional logging configuration to be added to the settings.cfg file for tracking requests and responses.

```ini
...  
  
[logging]  

requests=true  

responses=true  
```

--------------------------------

### Game channel storage requests and response

Source: https://docs.trytalo.com/docs/http/game-channel-api

Samples for creating, updating, or deleting storage properties within a game channel.

```json
{
  ... 
}
```

```json
{
  ... 
}
```

```json
{
  ... 
}
```

--------------------------------

### Talo.Channels.GetChannels()

Source: https://docs.trytalo.com/docs/unity/channels

Retrieves a paginated list of available channels for the game, with optional filtering and searching capabilities.

```APIDOC
## Talo.Channels.GetChannels()

### Description
Retrieves a paginated list of channels. Returns an object containing the list of channels, the total count, and a boolean indicating if it is the last page.

### Parameters
- **options** (GetChannelsOptions) - Required - Configuration object containing:
  - **page** (int) - Required - The page number to retrieve.
  - **propKey** (string) - Optional - Filter channels by a specific property key.
  - **propValue** (string) - Optional - Filter channels by a specific property value (requires propKey).
  - **search** (string) - Optional - Search for channels by name or owner identifier.

### Response
- **channels** (Channel[]) - Array of channel objects.
- **count** (int) - Total number of channels.
- **isLastPage** (bool) - Indicates if the current page is the last one.
```

--------------------------------

### Talo.Channels.Create()

Source: https://docs.trytalo.com/docs/unity/channels

Creates a new channel with specific configuration options like privacy or temporary membership.

```APIDOC
## Talo.Channels.Create()

### Description
Creates a new channel. Supports options for private channels (invite-only) and temporary membership (auto-remove when offline).

### Parameters
- **options** (CreateChannelOptions) - Required - Configuration object including name, isPrivate, and temporaryMembership.
```

--------------------------------

### Bypass internal cache for storage props

Source: https://docs.trytalo.com/docs/godot/channels

Demonstrates how to force a fresh fetch from the database by bypassing the internal cache.

```gdscript
# checks the internal cache first,  

# if the key isn't set, fetches the latest data directly from the database  

var prop := await Talo.channels.get_storage_prop(channel.id, "shared-gold", false) # default  

  

# fetches the latest data directly from the database  

var freshProp := await Talo.channels.get_storage_prop(channel.id, "shared-gold", true)  
```

--------------------------------

### List game channels

Source: https://docs.trytalo.com/docs/unity/channels

Retrieves a paginated list of available channels for the game.

```csharp
var page = 0  

var res = await Talo.Channels.GetChannels(new GetChannelsOptions { page = page })  

  

var channels: Channel[] = res.channels  

var count: int = res.count  

var isLastPage: bool = res.isLastPage  
```

--------------------------------

### Talo.channels.create

Source: https://docs.trytalo.com/docs/godot/channels

Creates a new channel. You can enable temporary_membership to automatically remove players from the channel when they go offline.

```APIDOC
## Talo.channels.create(options)

### Description
Creates a new channel with the specified options. If temporary_membership is enabled, players are removed upon going offline.

### Parameters
- **options** (Talo.channels.CreateChannelOptions) - Required - Configuration object including name and temporary_membership boolean.

### Response
- **channel** (Talo.channels.Channel) - The created channel object.
```

--------------------------------

### Socket connection URL

Source: https://docs.trytalo.com/docs/sockets/intro

Connect to the socket server using the wss protocol and a valid ticket as a query parameter.

```text
wss://api.trytalo.com/socket?ticket=your-ticket-here
```
Tokens:
Raw