NAV Navbar

Using the HTTP API

Introduction

The Trail HTTP API is still mostly a collection of endpoints that are necessary to enable features that require communication between your game's backend and Trail.

Specifically, it allows you to:

But we are also adding more endpoints on a case-by-case basis based on the needs of individual developers, so if you are missing any functionality please reach out to us and we will help you out 👍

Base URL

All requests use the same base URL: https://json.api.beta.trail.gg

Authentication

Requests need to be authenticated using an API token. You can find your API token in the Game Manager by navigating to Your Game > API Token.

You authenticate your requests by passing the API token as a Bearer token in the authorization header of the request, like so: Authorization: Bearer your-api-token

Message format

The API only accepts data sent as JSON and all data returned will also be sent as JSON. So make sure that your content-type header is set to JSON, i.e.

Content-Type: application/json

Example of a JSON-object in a request: 

{
  "key_1": "value_1",
  "key_2": "value_2",
  ...
}

Requests

Data sent in requests should be sent as a plain JSON-object.

Responses

Responses contains either a payload object if the request was successful, and for a failed request the response would contain an error.

Example of a response from a successful request:

{
  "payload": {
    "key_1": "value_1",
    "key_2": "value_2",
    ...
  }
}

Example of a response for a failed request:

{
  "error": "Invalid type",
  "code": 3,
  "message": "Invalid type"
}

or:

{
  "invalid_type_error": {}
}

Example Request

Here is an example request of what it could look like when sending a push notification to your users.

Example Request:

curl -X POST \
  https://json.api.beta.trail.gg/v1/publisher.Notifications/Broadcast \
  -H 'Authorization: Bearer your-api-token' \
  -H 'Content-Type: application/json' \
  -d '{
    "game_id": "your-game-id",
    "type": "match_available",
    "target": {
        "region": "eu"
    }
}'

Example Response:

{
  "payload": {
      "users_targeted": 42
  }
}

Users

GetUser

curl -X POST \
  https://json.api.beta.trail.gg/v1/publisher.Verify/GetUser \
  -H 'Authorization: Bearer your-api-token' \
  -H 'Content-Type: application/json' \
  -d '{
    "play_token": "users-play-token"
  }'

Gives back the user associated with the play token. It also implicitly verifies that the play token is indeed valid and not a forgery.

HTTP Request

POST /v1/publisher.Verify/GetUser

Parameters

Name Type Description
play_token string user's play token

Returns via payload

Name Type Description
user User
game_id bytes

Returned Errors

Name Type Description
invalid_token_error InvalidTokenError

User

Properties

Name Type Description
game_user_id string
username string

Notifications

Broadcast

curl -X POST \
  https://json.api.beta.trail.gg/v1/publisher.Notifications/Broadcast \
  -H 'Authorization: Bearer your-api-token' \
  -H 'Content-Type: application/json' \
  -d '{
    "game_id": "0000-0000-0000-0000",
    "type": "weekend_sale",
    "target": {
      "region": "eu",
      "has_purchased: "true",
    }
  }'

Sends a notification to all users that match the criteria specified by target.

HTTP request

POST /v1/publisher.Notifications/Broadcast

Parameters

Name Type Description
game_id string ID for the game that is sending the notification
type string notification type, e.g. weekend_sale
target object e.g. { "region": "eu", "has_purchased": "true" }

Returns via payload

Name Type Description
users_targeted int32 amount of users targeted by the notification

Returned Errors

Name Type Description
invalid_type_error InvalidTypeError
generic_error GenericError

Payments

GetEntitlements

curl -X POST \
  https://json.api.beta.trail.gg/v1/publisher.Payments/GetEntitlements \
  -H 'Authorization: Bearer your-api-token' \
  -H 'Content-Type: application/json' \
  -d '{
    "game_id": "0000-0000-0000-0000",
    "user_id": "0000-0000-0000-0000"
  }'

Retrieves a list of entitlements for a user.

HTTP request

POST /publisher.Payments/GetEntitlements

Parameters

Name Type Description
game_id string ID of the game you want to retrive entitlements for
user_id string ID of the user you want to retrive entitlements for

Returns via payload

Name Type Description
entitlements Entitlement[]

Returned Errors

Name Type Description
not_found_error NotFoundError

ConsumeEntitlements

curl -X POST \
  https://json.api.beta.trail.gg/v1/publisher.Payments/ConsumeEntitlement \
  -H 'Authorization: Bearer your-api-token' \
  -H 'Content-Type: application/json' \
  -d '{
    "entitlement_id": "0000-0000-0000-0000"
  }'

Consumes an entitlement.

HTTP request

POST /publisher.Payments/ConsumeEntitlement

Parameters

Name Type Description
entitlement_id string ID for the entitlement to be consumed

Returns via payload

Name Type Description
N/A

Returned Errors

Name Type Description
not_found_error NotFoundError

Entitlement

Properties

Name Type Description
entitlement_id string
product_id string ID for the product associated with the entitlement

Errors

Name Description
InvalidTokenError
InvalidTypeError
NotFoundError
GenericError