Playlyfe API v2.0

The Playlyfe API works over HTTP Secure (HTTPS) connections, and uses the OAuth2.0 protocol for authentication.

If you are looking to use Playlyfe platform to start creating your own gamified apps, have a look at our Getting Started Manual or do it by yourself using one of our SDKs to connect your app with Playlyfe.

Game

Game Examples

Get Game Image

GET/runtime/assets/game

Get the game feature image. The image is returned as a PNG.

Parameters
NameDescription
size

Size of image. Available sizes are original, large, medium, small, icon

Defaults tooriginal
 Query Parameter Request Body Required

Get Game Image

Request
GET https://api.playlyfe.com/v2/runtime/assets/admin/game/theMatrix HTTP/1.1
Response
Binary Image Data of the Game

Player

Player Examples

Get Own Profile

GET/runtime/player

Returns the profile information for the current player. The first_name and last_name is present only on player profiles which are linked to a Playlyfe User account.

Get Own Profile

Request
GET https://api.playlyfe.com/v2/runtime/player HTTP/1.1
Response
{
  "first_name": "Johny",
  "last_name": "Jose",
  "id": "neo",
  "alias": "Neo",
  "created": "2014-03-01T16:22:43.751Z",
  "scores": [
    {
      "metric": {
        "id": "existential_plane",
        "name": "Existential Plane",
        "type": "state"
      },
      "value": {
        "name": "Hell",
        "description": "The plane of demons"
      }
    },
    {
      "metric": {
        "id": "karma",
        "name": "Karma",
        "type": "point"
      },
      "value": "-1000000000"
    },
    {
      "metric": {
        "id": "weapons",
        "name": "Weapons",
        "type": "set"
      },
      "value": {
        "Bhramastra": {
          "description": "The Ultimate Weapon of mass destruction",
          "count": "1"
        }
      }
    }
  ],
  "enabled": true,
  "teams": [
    {
      "id": "53120aea188101a72a668a5e",
      "definition": {
        "id": "immortals",
        "name": "Immortals"
      },
      "roles": [
        "God"
      ],
      "name": "The Gaurdians"
    }
  ]
}
Possible Errors
404player_not_found

Invalid player_id. No player exists with that id.

Update Own Profile

PATCH/runtime/player

Update the profile information for the current player. The alias and email can only be updated.

Update Own Profile

Request
PATCH https://api.playlyfe.com/v2/runtime/player HTTP/1.1
Request Body
{
 "alias": "Johny" 
}
Response
{
 "id": "neo",
  "alias": "Johny",
  "created": "2014-03-01T16:22:43.751Z",
  "scores": [
    {
      "metric": {
        "id": "existential_plane",
        "name": "Existential Plane",
        "type": "state"
      },
      "value": {
        "name": "Hell",
        "description": "The plane of demons"
      }
    },
    {
      "metric": {
        "id": "karma",
        "name": "Karma",
        "type": "point"
      },
      "value": "-1000000000"
    },
    {
      "metric": {
        "id": "weapons",
        "name": "Weapons",
        "type": "set"
      },
      "value": {
        "Bhramastra": {
          "description": "The Ultimate Weapon of mass destruction",
          "count": "1"
        }
      }
    }
  ],
  "enabled": true,
  "teams": [
    {
      "id": "53120aea188101a72a668a5e",
      "definition": {
        "id": "immortals",
        "name": "Immortals"
      },
      "roles": [
        "God"
      ],
      "name": "The Gaurdians"
    }
  ]
}
Possible Errors
404player_not_found

Invalid player_id. No player exists with that id.

Upload Own Profile Image

POST/runtime/player

Upload the profile image for the current player. This request must a mutlti-part form data with the file fieldName as 'file'.

Upload Own Profile Image

Request
POST https://api.playlyfe.com/v2/runtime/player/image HTTP/1.1
Response
{
  "tags": [ "staging", "player" ],
  "album": "g:test",
  "sizes": [
    {
      "height": null,
      "width": null,
      "name": "original"
    },
    {
      "height": 140,
      "width": 140,
      "name": "large"
    },
    {
      "height": 72,
      "width": 72,
      "name": "medium"
    },
    {
      "height": 40,
      "width": 40,
      "name": "small"
    },
    {
      "height": 24,
      "width": 24,
      "name": "icon"
    }
  ],
  "id": "1,10be003d08"
}
Possible Errors
404player_not_found

Invalid player_id. No player exists with that id.

Get Player Profile Image

GET/runtime/assets/players/:player_id

Get a player profile image. The image is returned as a PNG.

Parameters
NameDescription
size

Size of image. Available sizes are original, large, medium, small, icon

Defaults tooriginal
 Query Parameter Request Body Required

Get Player Profile Image

Request
GET https://api.playlyfe.com/v2/runtime/assets/players/neo HTTP/1.1
Response
Binary Image Data of Player Profile

Get Own Activity Feed

GET/runtime/activity

Returns the player's activity feed.

By default, last 24 hour activity is returned. A period can be specified by passing start and end time stamps as query parameters.

Parameters
NameDescription
start

Earliest possible activity time stamp. Unit: UNIX time stamp or ISO time stamp

end

Latest possible activity time stamp. Unit: UNIX time stamp or ISO time stamp

 Query Parameter Request Body Required

Get Own Activity Feed

Request
GET https://api.playlyfe.com/v2/runtime/activity HTTP/1.1
Response
[
  {
    "event": "create",
    "timestamp": "2014-03-01T16:23:06.500Z",
    "process": {
      "id": "neo/5312096a8e1ebb4550a6a6f6",
      "name": "The Matrix"
    },
    "id": "c5465c41-a15d-11e3-84ab-ebaad0c03951"
  },
  {
    "process": {
      "id": "neo/5312096b8e1ebb4550a6a6fc",
      "name": "The Matrix"
    },
    "event": "progress",
    "activity": {
      "id": "destroy_the_world",
      "name": "Destroy the World"
    },
    "changes": [
      {
        "metric": {
          "id": "existential_plane",
          "name": "Existential Plane",
          "type": "state"
        },
        "delta": {
          "old": null,
          "new": "Hell"
        }
      },
      {
        "metric": {
          "id": "karma",
          "name": "Karma",
          "type": "point"
        },
        "delta": {
          "old": "0",
          "new": "-1000000000"
        }
      }
    ],
    "timestamp": "2014-03-01T16:23:29.367Z",
    "id": "d2e79670-a15d-11e3-84ae-ebaad0c03951"
  },
  {
    "process": {
      "id": "neo/5312096b8e1ebb4550a6a6fc",
      "name": "The Matrix"
    },
    "event": "progress",
    "activity": {
      "id": "brahmastra",
      "name": "Brahmastra"
    },
    "changes": [
      {
        "metric": {
          "id": "weapons",
          "name": "Weapons",
          "type": "set"
        },
        "delta": {
          "Bhramastra": {
            "old": "0",
            "new": "1"
          }
        }
      }
    ],
    "timestamp": "2014-03-01T16:23:42.131Z",
    "id": "da833830-a15d-11e3-84ae-ebaad0c03951"
  },
  {
    "event": "create",
    "timestamp": "2014-03-01T16:29:30.088Z",
    "team": {
      "id": "53120aea188101a72a668a5e",
      "name": "The Gaurdians"
    },
    "id": "a9e93e80-a15e-11e3-b581-1b9a3fec215b"
  }
]
Request
GET https://api.playlyfe.com/v2/runtime/activity?start=2014-03-01T10:00:00.000Z&end=2014-03-03T10:00:00.000Z HTTP/1.1
Response
[
  {
    "process": {
      "id": "neo/5312096b8e1ebb4550a6a6fc",
      "name": "The Matrix"
    },
    "event": "progress",
    "activity": {
      "id": "brahmastra",
      "name": "Brahmastra"
    },
    "changes": [
      {
        "metric": {
          "id": "weapons",
          "name": "Weapons",
          "type": "set"
        },
        "delta": {
          "Bhramastra": {
            "old": "0",
            "new": "1"
          }
        }
      }
    ],
    "timestamp": "2014-03-01T16:23:42.131Z",
    "id": "da833830-a15d-11e3-84ae-ebaad0c03951"
  },
  {
    "event": "create",
    "timestamp": "2014-03-01T16:29:30.088Z",
    "team": {
      "id": "53120aea188101a72a668a5e",
      "name": "The Gaurdians"
    },
    "id": "a9e93e80-a15e-11e3-b581-1b9a3fec215b"
  },  
  {
    "event": "create",
    "timestamp": "2014-03-01T16:23:06.500Z",
    "process": {
      "id": "neo/5312096a8e1ebb4550a6a6f6",
      "name": "The Matrix"
    },
    "id": "c5465c41-a15d-11e3-84ab-ebaad0c03951"
  },
  {
    "process": {
      "id": "neo/5312096b8e1ebb4550a6a6fc",
      "name": "The Matrix"
    },
    "event": "progress",
    "activity": {
      "id": "destroy_the_world",
      "name": "Destroy the World"
    },
    "changes": [
      {
        "metric": {
          "id": "existential_plane",
          "name": "Existential Plane",
          "type": "state"
        },
        "delta": {
          "old": null,
          "new": "Hell"
        }
      },
      {
        "metric": {
          "id": "karma",
          "name": "Karma",
          "type": "point"
        },
        "delta": {
          "old": "0",
          "new": "-1000000000"
        }
      }
    ],
    "timestamp": "2014-03-01T16:23:29.367Z",
    "id": "d2e79670-a15d-11e3-84ae-ebaad0c03951"
  },
  {
    "process": {
      "id": "neo/5312096b8e1ebb4550a6a6fc",
      "name": "The Matrix"
    },
    "event": "progress",
    "activity": {
      "id": "brahmastra",
      "name": "Brahmastra"
    },
    "changes": [
      {
        "metric": {
          "id": "weapons",
          "name": "Weapons",
          "type": "set"
        },
        "delta": {
          "Bhramastra": {
            "old": "0",
            "new": "1"
          }
        }
      }
    ],
    "timestamp": "2014-03-01T16:23:42.131Z",
    "id": "da833830-a15d-11e3-84ae-ebaad0c03951"
  },
  {
    "event": "create",
    "timestamp": "2014-03-01T16:29:30.088Z",
    "team": {
      "id": "53120aea188101a72a668a5e",
      "name": "The Gaurdians"
    },
    "id": "a9e93e80-a15e-11e3-b581-1b9a3fec215b"
  },
  {
    "event": "create",
    "timestamp": "2014-03-03T06:24:42.720Z",
    "process": {
      "id": "neo/5312we96ate1ebb4550a6875i",
      "name": "Path of Neo"
    },
    "id": "c5i54q98-a12y-46l3-11lm-e5500c03bbs4"
  }
]

Get a Notification Access Token

GET/runtime/notifications/token

Get an access token required for authorization of the notification stream.

Get a Notification Access Token

Request
GET https://api.playlyfe.com/v2/runtime/notifications/token HTTP/1.1
Response
{
  "token": "052de920-a174-11e3-b581-1b9a3fec215b"
}

Get Own Notifications

GET/runtime/notifications

Gets the player notifications for a particular period of time.

If no start and end keys are provided, by default, notifications from the last 24 hours will be returned.

Timestamp values must be either ISO or UNIX time stamp.

Parameters
NameDescription
start

Earliest possible activity timestamp

end

Latest possible activity timestamp.

 Query Parameter Request Body Required

Get Own Notifications

Request
GET https://api.playlyfe.com/v2/runtime/notifications HTTP/1.1
Response
{
  "data": [
    {
      "id": "052de920-a174-11e3-b581-1b9a3fec215b",
      "event": "join",
      "timestamp": "2014-03-02T18:03:59.848Z",
      "actor": {
        "id": "neo",
        "alias": "Neo"
      },
      "process": {
        "id": "matrix",
        "name": "TheMatrix"
      },
      "roles": {
        "matrix": "player"
      },
      "seen": false
    },
    {
      "id": "931dda24-a174-da23-g323-1b9adaec2ds",
      "event": "leave",
      "timestamp": "2013-11-10T16:48:10.570Z",
      "actor": {
        "id": "keymaker",
        "alias": "The Key Maker!"
      },
      "process": {
        "id": "matrix",
        "name": "TheMatrix"
      },
      "seen": false
    }
  ],
  "unseen": 2
}
Possible Errors
400invalid_date

Requested date format is invalid.

Mark Notifications as Read

POST/runtime/notifications

Mark player notifications as read.

Responds with an object containing 2 keys:

  • ok: Total number of notifications that were marked read.
  • unseen: Total number of notifications that are still unseen.
Parameters
NameDescription
ids

An Array containing the IDs of notifications that are to be marked as read.

 Query Parameter Request Body Required

Mark Notifications as Read

Request
POST https://api.playlyfe.com/v2/runtime/notifications HTTP/1.1
Request Body
{
  "ids": ["706db9d2-5756-11e3-a219-b1df8153ecfb"]
}
Response
{
  "ok": 1,
  "unseen": 0
}
Possible Errors
401invalid_notification_id

Invalid notification id

Get Pending Approvals

GET/runtime/approvals

Get the list of pending approvals to join teams/processes for the player.

Parameters
NameDescription
skip

Number of approvals to skip Default: 0

limit

Maximum number of approvals to return Default: 10

 Query Parameter Request Body Required

Get Pending Approvals

Request
GET https://api.playlyfe.com/v2/runtime/approvals HTTP/1.1
Response
{
  "data": [
    {
      "event": "join:request",
      "timestamp": "2014-03-01T18:58:22.142Z",
      "team": {
        "id": "53122d80188101a72a668a63",
        "name": "Titans"
      },
      "roles": {
        "God": true
      },
      "state": "PENDING",
      "id": "75d485e0-a173-11e3-b581-1b9a3fec215b"
    },
    {
      "event": "join:request",
      "timestamp": "2014-03-01T19:02:22.642Z",
      "process": {
        "id": "neo/53122e9a188101a72a668a64",
        "name": "Protected"
      },
      "roles": {
        "~": "player"
      },
      "state": "PENDING",
      "id": "052de920-a174-11e3-b581-1b9a3fec215b"
    }
  ],
  "total": 2
}

Get Pending Invitations

GET/runtime/invites

Get the list of pending invitations to join teams/processes for the player.

Parameters
NameDescription
skip

Number of invites to skip. Default: 0

limit

Maximum number of invites to return. Default: 10

 Query Parameter Request Body Required

Get Pending Invitations

Request
GET https://api.playlyfe.com/v2/runtime/invites HTTP/1.1
Response
{
  "data": [
    {
      "event": "invite",
      "timestamp": "2014-03-01T19:04:33.209Z",
      "actor": {
        "id": "neo",
        "alias": "Neo"
      },
      "team": {
        "id": "53120aea188101a72a668a5e",
        "name": "The Gaurdians"
      },
      "roles": {
        "God": true
      },
      "state": "PENDING",
      "id": "5300da90-a174-11e3-b581-1b9a3fec215b"
    },
    {
      "event": "invite",
      "timestamp": "2014-03-01T19:05:23.452Z",
      "actor": {
        "id": "neo",
        "alias": "Neo"
      },
      "process": {
        "id": "neo/5312096a8e1ebb4550a6a6f9",
        "name": "The Matrix"
      },
      "roles": {
        "~": "player"
      },
      "state": "PENDING",
      "id": "70f353c0-a174-11e3-b581-1b9a3fec215b"
    }
  ],
  "total": 2
}

Accept an Invitation

POST/runtime/invites/:invite_id

Accept an invitation to join a process or a team.

Accept an Invitation

Request
POST https://api.playlyfe.com/v2/runtime/invites/53120aea188101a72a668a5e HTTP/1.1
Response
{
  "event": "invite",
  "process": {
    "id": "gandalf/lotr",
    "name": "lotr"
  },
  "actor": {
    "id": "gandalf",
    "alias": "Gandalf The Grey"
  },
  "invitee": {
    "id": "legolas",
    "alias": "Legolas!"
  },
  "roles": {
    "gondor": "player"
  },
  "state": "ACCEPTED",
  "timestamp": "2014-08-20T05:43:30.062Z",
  "id": "53120aea188101a72a668a5e",
  "accepted_at": "2014-03-21T09:24:34.157Z"
}
Possible Errors
404invalid_invite

Thrown when an invalid invite key is provided.

401team_locked

Thrown when the team is locked.

Reject Invitation

DELETE/runtime/invites/:invite_id

Reject an invitation to join the team or process.

Reject Invitation

Request
DELETE https://api.playlyfe.com/v2/runtime/invites/53120aea188101a72a668a5e HTTP/1.1
Response
{
  "event": "invite",
  "process": {
    "id": "gandalf/lotr",
    "name": "lotr"
  },
  "actor": {
    "id": "gandalf",
    "alias": "Gandalf The Grey!"
  },
  "invitee": {
    "id": "saruman",
    "alias": "Saruman!!"
  },
  "roles": {
    "gondor": "player"
  },
  "state": "REJECTED",
  "timestamp": "2014-08-20T05:43:30.062Z",
  "id": "53120aea188101a72a668a5e",
  "accepted_at": "2014-03-21T09:24:34.157Z"
}
Possible Errors
404invalid_invite

Thrown when an invalid invite key is provided.

Action

Action Examples

List All Actions

GET/runtime/actions

Get a list of all available actions.

List All Actions

Request
GET https://api.playlyfe.com/v2/runtime/actions HTTP/1.1
Response
[
  {
    "id": "collect_coin",
    "name": "collect a coin",
    "description": "Hit the brick and collect a coin",
    "actions": [
      {
        "metric": {
          "id": "coins",
          "type": "point",
          "name": "coins"
        },
        "value": "1",
        "verb": "add",
        "probability": 1
      }
    ]
  },
  {
    "id": "rescue",
    "name": "rescue_princess",
    "description": "Rescue the princess",
    "actions": [
      {
        "metric": {
          "id": "coins",
          "type": "point",
          "name": "coins"
        },
        "value": "300",
        "verb": "add",
        "probability": 1
      }
    ]
  }
]

Play an Action

POST/runtime/actions/:action_id/play

Execute an action with the given id. The response contains the changes that resulted from performing the action along with the currently available actions.

Parameters
NameDescription
count

Number of times the action has to be executed.

variables

Additional variables required by the action. This is a JSON object where each key is the variable name and the value is the variable value

scopes

The Custom Scopes in your Custom Leaderboards in which the scores need to be updated. This is an array of JSON objects where each object contains an id key which is the scope id and an entity_id key which is the player or team instance id

query

Returns available actions after the current action is performed. Disabling query can improve performance.

Defaults totrue
 Query Parameter Request Body Required

Play an Action

Request
POST http://api.playlyfe.com/v2/actions/rescue/play HTTP/1.1
Request Body
{}
Response
{
  "actions": [
    {
      "id": "collect_coin",
      "name": "collect a coin",
      "description": "Hit the brick and collect a coin",
      "rewards": [
        {
          "metric": {
            "id": "coins",
            "type": "point",
            "name": "coins"
          },
          "value": "1",
          "verb": "add",
          "probability": 1
        }
      ]
    },
    {
      "id": "rescue",
      "name": "rescue_princess",
      "description": "Rescue the princess",
      "rewards": [
        {
          "metric": {
            "id": "coins",
            "type": "point",
            "name": "coins"
          },
          "value": "300",
          "verb": "add",
          "probability": 1
        }
      ]
    }
  ],
  "events": {
    "local": [
      {
        "event": "action",
        "actor": {
          "id": "Mario",
          "alias": "SuperM"
        },
        "changes": [
          {
            "metric": {
              "id": "coins",
              "name": "coins",
              "type": "point"
            },
            "delta": {
              "old": "0",
              "new": "300"
            }
          }
        ],
        "timestamp": "2014-03-01T16:29:30.088Z",
        "id": ""
      }
    ],
    "global": [
      {
        "event": "level",
        "actor": {
          "id": "Mario",
          "alias": "SuperM"
        },  
        "changes": [
          {
            "metric": {
              "id": "rescues",
              "name": "badges",
              "type": "set"
            },
            "delta": {
              "novice": {
                "old": null,
                "new": "1"
              }
            }
          }
        ],
        "timestamp": "2014-03-01T16:29:30.088Z",
        "id": ""
      }
    ]
  }
}
Possible Errors
401access_denied

Player does not have sufficient permissions to play/trigger the action

Process

Process Examples

List All Process Definitions

GET/runtime/definitions/processes

Get a list of all available process definitions. Process definitions are the blueprints used to create a new process instance.

List All Process Definitions

Request
GET https://api.playlyfe.com/v2/runtime/definitions/processes HTTP/1.1
Response
[
  {
    "id": "destroy_evil",
    "lanes": ["neutral", "good", "evil"],
    "name": "Destroy Evil",
    "access": [
      "PRIVATE"
    ]
  },
  {
    "id": "destroy_good",
    "lanes": ["neutral", "good", "evil"],
    "name": "Destroy Good",
    "access": [
      "PUBLIC"
    ]
  }
]

List Processes

GET/runtime/processes

Get a list of all the processes a player can play/join.

All public and protected processes created by any player in the game will be listed.

Any processes which were bootstrapped will be created and listed here when the player joins the game for the first time.

Parameters
NameDescription
skip

Number of processes to skip

Defaults to0
limit

Maximum number of processes to return.

Defaults to10
state

Comma separated list of process states to filter by. Process states: ACTIVE, COMPLETED

Defaults toACTIVE
 Query Parameter Request Body Required

List Processes

Request
GET https://api.playlyfe.com/v2/runtime/processes?state=ACTIVE,COMPLETED HTTP/1.1
Response
{
  "data": [
    {
      "id": "neo/5312096a8e1ebb4550a6a6f6",
      "name": "Real Life",
      "definition": "boring_stuff",
      "access": "PRIVATE",
      "created": "2014-03-01T16:23:06.500Z",
      "owner": {
        "id": "neo",
        "alias": "Neo"
      },
      "state": "ACTIVE",
      "performers": [
        {
          "id": "neo",
          "alias": "Neo"
        }
      ]
    },
    {
      "id": "neo/5312096a8e1ebb4550a6a6f8",
      "access": "PRIVATE",
      "created": "2014-03-01T16:23:06.501Z",
      "definition": "destroy_evil",
      "name": "The Matrix",
      "state": "ACTIVE",
      "owner": {
        "id": "neo",
        "alias": "Neo"
      },
      "performers": [
        {
          "id": "neo",
          "alias": "Neo"
        },
        {
          "id": "morpheus",
          "alias": "Morpheus"
        }
      ],
    }
  ],
  "total": 2
}

Get a Process

GET/runtime/processes/:process_id

Get details of a process instance with the specified id.

Get a Process

Request
GET https://api.playlyfe.com/v2/runtime/processes/driving_test HTTP/1.1
Response
{
  "id": "driving_test",
  "definition": {
    "id": "test",
    "name": "Simple tests"
  },
  "state": "ACTIVE",
  "created": "2014-03-01T16:34:57.402Z",
  "access": "PROTECTED",
  "performers": [
    {
      "id": "alonso",
      "alias": "Alonso",
      "lanes": [
        {
          "name": "main",
          "role": "observer"
        }
      ]
    },
    {
      "id": "massa",
      "alias": "Massa",
      "lanes": [
        {
          "name": "main",
          "role": "player"
        }
      ]
    }
  ],
  "owner": {
    "id": "clone",
    "alias": "Clonie"
  },
  "lanes": [
    "main"
  ]
}

List All Performers of a Process

GET/runtime/processes/:process_id/performers

List the performers of the process.

Returns an array with objects containing the player id and alias.

List All Performers of a Process

Request
GET https://api.playlyfe.com/v2/runtime/processes/neo/therealmatrix/performers HTTP/1.1
Response
[
  {
    "id": "neo",
    "alias": "The One!"
  },
  {
    "id": "trinity",
    "alias": "Trinity!"
  }
]
Possible Errors
401access_denied

Player not authorized. Only performers can view performer listing in PRIVATE processes.

404process_instance_not_found

Invalid process_id.

Get the Profile of a Process Performer

GET/runtime/processes/:process_id/performers/:performer_id

Get the profile of a performer. In private processes, only existing process performers can view performer profiles.

Returns an object with the player profile information.

Get the Profile of a Process Performer

Request
GET https://api.playlyfe.com/v2/runtime/processes/neo/therealmatrix/performers/trinity HTTP/1.1
Response
{
  "id": "trinity",
  "alias": "Trinity!",
  "created":"2014-03-01T16:22:43.751Z",
  "enabled": true,
  "scores": [
    {
      "metric": {
        "id": "xp",
        "name": "experience",
        "type": "point"
      },
      "value": "50"
    }
  ],
  "teams": []
}
Possible Errors
401access_denied

Player not authorized. Only performers can view performer listing in PRIVATE processes.

404performer_not_found

Invalid performer_id. Requested performer not a part of the process.

Create a Process

POST/runtime/processes

Start a process using a specified process definition. It returns the state of the newly created process.

Parameters
NameDescription
id

The ID of the newly created process instance.

access

The access setting of the process instance. It can be either public, protected or private.

Defaults toStrictest access setting allowed by the definition
 Query Parameter Request Body Required

Create a Process

Request
POST https://api.playlyfe.com/v2/runtime/processes HTTP/1.1
Request Body
{
  "id": "destroy_evil",
  "access":"PROTECTED",
  "definition": "work"
}
Response
{
  "id": "destroy_evil",
  "definition": {
    "id": "work",
    "name": "work"
  },
  "state": "ACTIVE",
  "created": "2014-03-01T16:22:43.751Z",
  "access": "PROTECTED",
  "performers": [
    {
      "id": "clone",
      "alias": "Clonie",
      "lanes": [
        {
          "name": "main",
          "role": "player"
        }
      ]
    }
  ],
  "owner": {
    "id": "clone",
    "alias": "Clonie"
  },
  "lanes": [
    "main"
  ]
}
Possible Errors
403forbidden

player is not authorized to start the process.

400validation_exception

Invalid request body

404process_definition_not_found

definition_id is invalid

408temporary_failure

temporary server error

409process_instance_exists

another process instance exists with the same id

Update Process Settings

PATCH/runtime/processes/:process_id

Update the name or access settings of the process instance.

Parameters
NameDescription
name

The new name of the process.

access

The new access setting for the process. Possible access settings: PUBLIC, PROTECTED, PRIVATE

 Query Parameter Request Body Required

Update Process Settings

Request
PATCH https://api.playlyfe.com/v2/processes/my_process HTTP/1.1
Request Body
{
  "name": "My New Process",
  "access": "PUBLIC"
}
Response
{
  "id": "my_process",
  "definition": {
    "id": "work",
    "name": "work"
  },
  "state": "ACTIVE",
   "created": "2014-03-01T16:23:06.501Z",
  "name": "My New Process",
  "access": "PUBLIC",
  "performers": [
    {
      "id": "clone",
      "alias": "Clonie",
      "lanes": [
        {
          "name": "main",
          "role": "player"
        }
      ]
    }
  ],
  "owner": {
    "id": "clone",
    "alias": "Clonie"
  },
  "lanes": [
    "main"
  ]
}
Possible Errors
400validation_exception

Invalid request

400invalid_access_setting

Access setting not valid

401access_denied

Player not authorized to update the process. Only process owner can perform update.

Delete a Process

DELETE/runtime/processes/:process_id

Delete a process instance.

Delete a Process

Request
DELETE https://api.playlyfe.com/v2/runtime/processes/clone/foo HTTP/1.1
Request Body
{}
Response
{
  "message": "Process 'clone/foo' has been deleted"
}
Possible Errors
401access_denied

Player not authorized to delete the process. Only the process owner can delete the process.

Join a Process

POST/runtime/processes/:process_id/join

Join a process.

You must specify the role and lanes which the player wishes to join in.

There are 2 possible role values :

  • observer - Can only view process state
  • player - Can play a process

The lanes available to join depend on the process definition.

The desired lanes and roles should be specified in the request body, the object keys being the lanes and the values being the desired roles.

If the process is public, then the player's roles are returned. If the process is protected then a generated approval request to join the process is returned. If the process is private, then an error is returned.

Join a Process

Joining a public process.

Request
POST https://api.playlyfe.com/v2/runtime/processes/droid/kill/join HTTP/1.1
Request Body
{
  "war": "player"
}
Response
{
  "war": "player"
}

Joining a protected process.

Request
POST https://api.playlyfe.com/v2/runtime/processes/droid/kill/join HTTP/1.1
Request Body
{
  "war": "observer"
}
Response
{
  "id": "523215efacc4b2f216000034",
  "event": "join:request",
  "timestamp": "2014-03-02T17:47:04.260Z",
  "process": {
    "id": "droid/kill"
  },
  "roles": {
    "war": "observer"
  },
  "state": "PENDING",
  "actor": {
    "id": "droid",
    "alias": "Droid!"
  }
}
Possible Errors
401access_denied

Attempt to join a private process

400validation_exception

Invalid request

409player_exists

Player is already a part of the process.

400invalid_role

Requested role is invalid. It can only be either player or observer.

400invalid_lanes

Requested lane is invalid/does not exist.

Leave a Process

POST/runtime/processes/:process_id/leave

Leave a process.

Its returns a message indicating the result of the operation.

Leave a Process

Request
POST https://api.playlyfe.com/v2/runtime/processes/droid/kill/leave HTTP/1.1
Response
{
  "message": "Player 'clone' has successfully left the process 'droid/kill'"
}
Possible Errors
404performer_not_found

Player is not a performer in the process.

403forbidden

Owner is not allowed to leave the process.

List Process Triggers

GET/runtime/processes/:process_id/triggers

Get a list of all available triggers a player can play in a process instance.

List Process Triggers

Request
GET https://api.playlyfe.com/v2/runtime/processes/neo/therealmatrix/triggers HTTP/1.1
Response
[
  {
    "trigger": "destroy_the_world:choose_your_path",
    "name": "Destroy the World",
    "actions": [
      {
        "metric": {
          "id": "existential_plane",
          "type": "state",
          "name": "Existential Plane"
        },
        "value": "Hell",
        "verb": "set"
      },
      {
        "metric": {
          "id": "karma",
          "type": "point",
          "name": "Karma"
        },
        "value": "-1000000000",
        "verb": "add"
      }
    ]
  },
  {
    "trigger": "let_it_burn:choose_your_path",
    "name": "Let it Burn",
    "actions": [
      {
        "metric": {
          "id": "existential_plane",
          "type": "state",
          "name": "Existential Plane"
        },
        "value": "Hell",
        "verb": "set"
      },
      {
        "metric": {
          "id": "karma",
          "type": "point",
          "name": "Karma"
        },
        "value": "1",
        "verb": "add"
      }
    ]
  },
  {
    "trigger": "try_to_save_the_world:choose_your_path",
    "name": "Try to save the World",
    "actions": [
      {
        "metric": {
          "id": "existential_plane",
          "type": "state",
          "name": "Existential Plane"
        },
        "value": "Material",
        "verb": "set"
      },
      {
        "metric": {
          "id": "karma",
          "type": "point",
          "name": "Karma"
        },
        "value": "1000000001",
        "verb": "add"
      }
    ]
  }
]
Possible Errors
401access_denied

Player not authorized. Player not a part of the process.

Play a Process Trigger

POST/runtime/processes/:process_id/play

Play a process. Playing a process causes its state to change.

It returns an array containing:

  • The new triggers that become available
  • The updated scores of the player
  • Any events that occured
Parameters
NameDescription
trigger

The ID of the trigger to be played.

scopes

Scope in which the scores will be counted.

 Query Parameter Request Body Required

Play a Process Trigger

Request
POST https://api.playlyfe.com/v2/runtime/processes/neo/therealmatrix/play HTTP/1.1
Request Body
{
  "trigger": "try_to_save_the_world:choose_your_path"
}
Response
{
  "triggers": [
    {
      "trigger": "brahmastra:choose_your_weapon",
      "name": "Brahmastra",
      "lane": "matrix",
      "locked": "false",
      "rewards": [
        {
          "metric": {
            "id": "weapons",
            "type": "set",
            "name": "Weapons"
          },
          "value": {
            "Bhramastra": "1"
          },
          "verb": "add"
        }
      ]
    },
    {
      "trigger": "excalibur:choose_your_weapon",
      "name": "Excalibur",
      "lane": "matrix",
      "locked": "false",
      "rewards": [
        {
          "metric": {
            "id": "weapons",
            "type": "set",
            "name": "Weapons"
          },
          "value": {
            "Excalibur": "1"
          },
          "verb": "add"
        }
      ]
    },
    {
      "trigger": "mjolinir:choose_your_weapon",
      "name": "Mjolinir",
      "lane": "matrix",
      "locked": "false",
      "rewards": [
        {
          "metric": {
            "id": "weapons",
            "type": "set",
            "name": "Weapons"
          },
          "value": {
            "Mjolinir": "1"
          },
          "verb": "add"
        }
      ]
    }
  ],
  "events": {
    "local": [
      {
        "event": "progress",
        "activity": {
          "id": "try_to_save_the_world",
          "name": "Try to save the World"
        },
        "actor": {
          "id": "neo",
          "alias": "Neo"
        },
        "changes": [
          {
            "metric": {
              "id": "karma",
              "name": "Karma",
              "type": "point"
            },
            "delta": {
              "old": "1000000001",
              "new": "2000000002"
            }
          }
        ],
        "timestamp": "2014-03-02T17:47:04.260Z",
        "id": "aa6d4840-a232-11e3-9af5-753d0e60669a"
      }
    ],
    "global": []
  }
}
Possible Errors
401access_denied

Player not authorized. He is not a performer in the process.

Kick Performer from a Process

POST/runtime/processes/:process_id/performers/:performer_id/kick

Kick out a performer from the process.

This can only be done by the owner of the process and the owner himself cannot be kicked out.

Returns a confirmation message of the event.

Kick Performer from a Process

Request
POST https://api.plalyfe.com/runtime/processes/neo/therealmatrix/performers/morpheus/kick HTTP/1.1
Response
{
  "message": "The player 'morpheus' has been removed from process '/neo/therealmatrix'"
}
Possible Errors
401access_denied

Player not authorized. Only process owners can kick performers.

404performer_not_found

Invalid performer_id. Requested performer is not a part of the process.

403forbidden

Process owner cannot be kicked.

Transfer Process Ownership

POST/runtime/processes/:process_id/transfer

Transfer the ownership of the process to another player.

The new owner can be either an existing performer in the process or any other player in the game.

The lanes and roles assigned to the new owner can be specified in the body of the request. If no lanes are specified, the process default lanes are given to the owner.

The owner transferring ownership will retain his lanes in the process after the transfer.

Parameters
NameDescription
new_owner_id

ID of the new owner

roles

Object that contains the lanes/roles of the new owner

 Query Parameter Request Body Required

Transfer Process Ownership

Request
POST https://api.playlyfe.com/v2/runtime/processes/fury/avengers/transfer HTTP/1.1
Request Body
{
      "new_owner_id": "rogers",
      "roles": {
        "main": "player"
      }
}
Response
{
    "id": "fury/avengers",
    "definition": "work",
    "state": "ACTIVE",
    "created": "april11,2012",
    "access": "PROTECTED",
    "performers": {
        "fury": {
            "main": "player"
        },
        "loki": {
            "main": "observer"
        },
        "stark": {
            "main": "player"
        }
    },
    "keys": {
        "fury/avengers": "work"
    },
    "containers": {
        "work": {
            "key": "fury/avengers",
            "tokens": 1,
            "nodes": {
                "aaa": {
                    "state": "READY",
                    "tokens": 1
                }
            }
        }
    },
    "owner": "rogers"
}
Possible Errors
401access_denied

Player not authorized. Only the instance owner can transfer ownership.

400invalid_lane

Invalid lane specified.

400invalid_role

Roles provided are invalid. Player must have at least one role.

Change Own Roles in Process

POST/runtime/processes/:process_id/roles

If the process is public then the player's roles are updated and the new process state is returned. If the process is protected or private then a generated approval request for role change is returned.

The new roles should be passed as an object in the request body. Keys in the object represent the lane id and the values should be the desired role.

There are 3 possible role values :

  • observer - Can only view process state
  • player - Can play a process
  • false - Removes the player from the lane

The lanes available to join depend on the process definition.

Change Own Roles in Process

In case of a protected or private process.

Request
POST https://api.playlyfe.com/v2/runtime/processes/droid/kill/roles HTTP/1.1
Request Body
{
  "main": "player"
}
Response
{
  "id": "523215efacc4b2f216000034",
  "event": "role:request",
  "timestamp": "2014-03-02T17:47:04.260Z",
  "process": {
    "id": "droid/kill"
  },
  "roles": {
    "main": "player"
  },
  "state": "PENDING",
  "actor": {
    "id": "droid",
    "alias": "Droid!"
  }
}
Possible Errors
401access_denied

Player is not a performer in the process.

400invalid_lane

Requested lane is invalid.

400invalid_role

Invalid role. Roles can only be either player, observer or false.

400role_required

Player must have at least one role.

Get a Process's Activity Feed

GET/runtime/processes/:process_id/activity

Get process activity feed.

By default, if no start and end parameters are provided, the activity feed for the last 24 hours is provided.

Parameters
NameDescription
start

Earliest possible activity timestamp. Timestamp to be provided in either UNIX or ISO timestamp

end

Latest possible activity timestamp. Timestamp to be provided in either UNIX or ISO timestamp

 Query Parameter Request Body Required

Get a Process's Activity Feed

There are no examples yet for this route. You can Try It yourself though!

Possible Errors
400invalid_date

Requested date format is invalid.

Change Roles of a Performer

POST/runtime/processes/:process_id/performers/:performer_id/roles

Change the roles of a performer.

This can only be performed by the owner of the process.

The request body should contain the new roles. The key should be the name of the lane and the value should be the role in the lane. The lane role can be either player, observer or false. false should be provided to remove a performer from the lane.

Returns the updated roles of the process performer.

Change Roles of a Performer

Request
POST https://api.playlyfe.com/v2/runtime/processes/neo/therealmatrix/performers/morpheus/roles HTTP/1.1
Request Body
{
  "matrix": "observer"
}
Response
{
  "matrix": "observer"
}
Possible Errors
401access_denied

Player not authorized. Only process owner can perform role change.

404performer_not_found

Requested performer not a part of the process.

400invalid_lane

Request lane is invalid.

400invalid_role

Requested role is invalid. Roles can only be either player, observer or false and should have a minimum of 1 role in the process.

List Invitations Sent out for a Process

GET/runtime/processes/:process_id/invites

Get a list of invites the player has sent out to join a processes.

Only invitations sent out by the player will be listed.

List Invitations Sent out for a Process

Request
GET https://api.playlyfe.com/v2/runtime/processes/neo/therealmatrix/invites HTTP/1.1
Response
{
  "data": [
    {
      "event": "invite",
      "timestamp": "2014-03-02T17:37:29.371Z",
      "invitee": {
        "id": "trinity",
        "alias": "Trinity"
      }
      "roles": {
        "matrix": "player"
      },
      "state": "PENDING",
      "id": "53c42eb0-a231-11e3-b632-ede196eae44e"
    }
  ],
  "total": 1
}

Send a Process Invitation

POST/runtime/processes/:process_id/invites

Invite a player to join a process.

Only the owner of the process can invite other players.

The roles need to be specified as an object with the key being the lane name and the value is the role in the lane.

It returns the invitation request.

Parameters
NameDescription
id

The ID of the player to whom the invitation has to be sent to.

roles

The roles of the player in the the process.

 Query Parameter Request Body Required

Send a Process Invitation

Request
POST https://api.playlyfe.com/v2/runtime/processes/neo/therealmatrix/invites HTTP/1.1
Request Body
{
  "id": "trinity",
  "roles": {
    "matrix": "player",
    "training": "observer"
  }
}
Response
{
  "id": "aef37730-a233-11e3-9af5-753d0e60669a",
  "event": "invite",
  "timestamp": "2014-03-02T17:54:21.347Z",
  "actor": {
    "id": "neo",
    "alias": "Neo"
  },
  "invitee": {
    "id": "trinity",
    "alias": "Trinity"
  },
  "process": {
    "id": "neo/therealmatrix",
    "name": "Protected"
  },
  "roles": {
    "matrix": "player",
    "training": "observer"
  },
  "state": "PENDING"
}
Possible Errors
400validation_exception

Invalid request

401access_denied

Player not authorized. Only process owner can send invites.

409performer_exists

Requested player already a part of the process.

400invalid_lanes

Requested lane is invalid.

400invalid_role

Requested role is invalid. Can only request player or observer roles.

409already_invited

An invitation is already pending for the requested player.

Cancel a Sent Invitation

DELETE/runtime/processes/:process_id/invites/:invite_id

Cancel a pending invite sent out by the player.

It returns the canceled invitation request.

Cancel a Sent Invitation

Request
DELETE https://api.playlyfe.com/v2/runtime/processes/neo/therealmatrix/invites/052de920-a174-11e3-b581-1b9a3fec215b HTTP/1.1
Response
{
  "event": "invite",
  "timestamp": "2014-03-02T18:03:59.848Z"
  "process": {
    "id": "neo/therealmatrix",
    "name": "The Real Matrix"
  },
  "actor": {
    "id": "neo",
    "name": "Neo"
  },
  "invitee": {
    "id": "trinity",
    "name": "Trinity"
  },
  "roles": {
    "good": "player"
  },
  "state": "CANCELLED",
  "id": "052de920-a174-11e3-b581-1b9a3fec215b"
  "cancelled_at": "2014-03-02T18:04:08.507Z"
}
Possible Errors
404invalid_invite

Invalid invite_id

List Pending Process Join or Role Change Requests

GET/runtime/processes/:process_id/approvals

Get a list of pending player requests in a process.

A pending request can be approved by the owner of the process. Others who try to request the list of approvals will get an error.

List Pending Process Join or Role Change Requests

Request
GET https://api.playlyfe.com/v2/runtime/processes/neo/therealmatrix/approvals HTTP/1.1
Response
{
  "data": [
    {
      "event": "join:request",
      "timestamp": "2014-03-01T19:02:22.642Z",
      "actor": {
        "id": "morpheus",
        "alias": "Morpheus"
      },
      "roles": {
        "matrix": "player"
      },
      "state": "PENDING",
      "id": "052de920-a174-11e3-b581-1b9a3fec215b"
    }
  ],
  "total": 1
}
Possible Errors
401access_denied

When a non owner tries to view approval requests

Approve Process Join or Role Change Request

POST/runtime/processes/:process_id/approvals/:request_id

Accept a player request to join a process or role change.

Only the owner of the process has the right to approve requests.

It returns the accepted approval request.

Approve Process Join or Role Change Request

Request
POST https://api.playlyfe.com/v2/runtime/processes/neo/therealmatrix/approvals/520512b563c67d641e000002 HTTP/1.1
Response
{
  "event": "join:request",
  "timestamp": "2014-03-01T19:02:22.642Z",
  "actor": {
    "id": "morpheus",
    "alias": "Morpheus"
  },
  "process": {
    "id": "neo/therealmatrix",
    "name": "Protected"
  },
  "roles": {
    "matrix": "player"
  },
  "state": "ACCEPTED",
  "id": "052de920-a174-11e3-b581-1b9a3fec215b",
  "accepted_by": {
    "id": "neo",
    "alias": "Neo"
  },
  "accepted_at": "2014-03-02T17:51:42.157Z"
}
Possible Errors
404invalid_approval_request

Invalid request_id

401access_denied

Player not authorized to approve request.

Reject Process Join or Role Change Request

DELETE/runtime/processes/:process_id/approvals/:request_id

Reject a player request to join or change roles in a process.

Only the owner of the process has the rights to reject a request.

It returns the rejected approval request.

Reject Process Join or Role Change Request

Request
DELETE https://api.playlyfe.com/v2/runtime/processes/neo/thefakematrix/approvals/3d183590-a235-11e3-9af5-753d0e60669a HTTP/1.1
Response
{
  "event": "join:request",
  "timestamp": "2014-03-02T18:05:29.321Z",
  "actor": {
    "id": "trinity",
    "alias": "Trinity"
  },
  "process": {
    "id": "neo/thefakematrix",
    "name": "The Fake Matrix"
  },
  "roles": {
    "matrix": "player"
  },
  "state": "REJECTED",
  "id": "3d183590-a235-11e3-9af5-753d0e60669a",
  "rejected_by": {
    "id": "neo",
    "alias": "Neo"
  },
  "rejected_at": "2014-03-02T18:05:43.984Z"
}
Possible Errors
404invalid_approval_request

Invalid request_id

401access_denied

Player not authorized to reject a request. Only process owners can accept/reject requests.

Get Process Image

GET/runtime/assets/definitions/processes/:process_definition_id

Get a process definition image. The image is returned as a PNG.

Parameters
NameDescription
size

Size of image. Available sizes are original, large, medium, small, icon

Defaults tooriginal
 Query Parameter Request Body Required

Get Process Image

Request
GET https://api.playlyfe.com/v2/runtime/assets/definitions/processes/destroy_evil HTTP/1.1
Response
Binary Image Data of Process Definition

Team

Team Examples

List All Team Definitions

GET/runtime/definitions/teams

Get a list of all available team definitions. Team definitions are the blueprints used to create a new team instance.

Only the teams which can be created by the player will be listed.

List All Team Definitions

Request
GET https://api.playlyfe.com/v2/runtime/definitions/teams HTTP/1.1
Response
[
  {
    "id": "immortals",
    "name": "Immortals",
    "roles": [
      "God",
      "Angels"
    ],
    "access": [
      "PRIVATE"
    ]
  },
  {
    "id": "demons",
    "name": "Demons",
    "roles": [
      "Devil",
      "Angels",
      "Monsters"
    ],
    "access": [
      "PRIVATE"
    ]
  }
]

List Teams

GET/runtime/teams

Get a list of all the teams the player can join or is a part of.

All public and protected teams created by any player in the game will be listed.

Any teams which were bootstrapped will be created and listed here when the player joins the game for the first time.

Parameters
NameDescription
skip

Number of teams to skip.

Defaults to0
limit

Maximum number of teams to return.

Defaults to10
 Query Parameter Request Body Required

List Teams

Request
GET https://api.playlyfe.com/v2/runtime/teams HTTP/1.1
Response
{
  "data": [
    {
      "id": "con_artists",
      "name": "The Con Artists",
      "definition": {
        "id": "international",
        "name": "international"
      },
      "access": "PRIVATE",
      "created": "2014-04-03T14:49:00.011Z",
      "owner": {
        "id": "droid",
        "alias": "Droid!"
      },
      "roles": [
        "member",
        "admin",
        "super_admin",
        "owner"
      ],
      "my_roles": [
        "owner"
      ],
      "can_leave": false
    },
    {
      "id": "musicians",
      "name": "The Musicians",
      "definition": {
        "id": "local",
        "name": "local"
      },
      "access": "PRIVATE",
      "created": "2014-03-01T16:29:30.088Z",
      "owner": {
        "id": "droid",
        "alias": "Droid!"
      },
      "roles": [
        "member",
        "admin",
        "super_admin",
        "owner"
      ],
      "my_roles": [
        "owner"
      ],
      "can_leave": false
    }
  ],
  "total": 2
}

Get a Team

GET/runtime/teams/:team_id

Get information about a particular team instance.

Get a Team

Request
GET https://api.playlyfe.com/v2/runtime/teams/globe_trotters HTTP/1.1
Response
{
  "id": "globe_trotters",
  "name": "The Globe Trotters",
  "definition": {
    "id": "local",
    "name": "local"
  },
  "created": "2014-03-01T16:29:30.088Z",
  "access": "PROTECTED",
  "owner": {
    "id": "clone",
    "alias": "Clonie"
  },
  "locked": false,
  "member_count": [
    {
      "name": "member",
      "count": 0
    },
    {
      "name": "admin",
      "count": 0
    },
    {
      "name": "super_admin",
      "count": 0
    },
    {
      "name": "owner",
      "count": 1
    }
  ],
  "total_members": 1,
  "roles": [
    "admin",
    "member",
    "owner",
    "super_admin"
  ],
  "my_roles": [
    "owner"
  ],
  "can_leave": false
}
Possible Errors
401access_denied

Only members can view state of private teams

Create a Team

POST/runtime/teams

Create a team instance by specifying a team definition.

It returns the state of the newly created team.

Parameters
NameDescription
id

The ID of the newly created team instance

Defaults toAuto generated
access

The access setting of the team instance. It can be either public, protected or private

Defaults toStrictest access setting allowed by the definition
name

Name of the team.

definition

ID of the team definition which is to be used.

 Query Parameter Request Body Required

Create a Team

Request
POST https://api.playlyfe.com/v2/runtime/teams HTTP/1.1
Request Body
{
  "id": "globe-trotters",
  "access": "PRIVATE",
  "name": "globe-trotters",
  "definition": "national"
}
Response
{
  "id": "globe-trotters",
  "name": "globe-trotters",
  "definition": "national",
  "created": "2014-03-02T15:11:48.079Z",
  "access": "PRIVATE",
  "owner": "morpheus",
  "locked": false,
  "member_count": {
    "God": 1
  },
  "total_members": 1
}
Possible Errors
403forbidden

Player does not meet requirements to create a team of that definition.

404team_definition_not_found

Invalid team_definition_id.

400invalid_access_setting

Requested access settings are invalid.

409team_instance_exists

A team with the same ID already exists.

Join a Team

POST/runtime/teams/:team_id/join

Join a team.

You must specify the roles with which you want to join the team. The roles available to join depend on the team definition.

If the team is public then he is added to the team and the player's roles are returned. If the team is protected then a generated approval request to join the team is returned. If the team is private an error is returned.

The requested roles should be specified as an object in the request body with the keys being the requested role.

The response returned are the player's roles. The key is the name of the role and the value is the its rank.

Join a Team

In case of a public team.

Request
POST https://api.playlyfe.com/v2/runtime/teams/anonymous/join HTTP/1.1
Request Body
{
   "hacker": true
}
Response
{
   "hacker": 0
}

In case of a protected team.

Request
POST https://api.playlyfe.com/v2/runtime/teams/anonymous/join HTTP/1.1
Request Body
{
   "hacker": true 
}
Response
{
  "id": "520512b563c67d641e000002",
  "event": "join:request",
  "timestamp": "2014-03-02T18:03:59.848Z",
  "actor": {
    "id": "droid",
    "alias": "Droid!"
  },
  "team": {
    "id": "anonymous",
    "name": "Anonymous"
  },
  "roles": {
    "hacker": true
  },
  "state": "PENDING"
}
Request
POST https://api.playlyfe.com/v2/teams/runtime/anonymous/join HTTP/1.1
Request Body
{
   "hacker": true 
}
Response
{
  "error": "access_denied",
  "error_description": "You cannot join the private team 'anonymous'"
}
Possible Errors
409player_exists

Player already a part of the team.

401team_locked

Team is locked. Cannot add new players.

400invalid_role

Requested role is invalid.

401access_denied

Cannot join a private team.

Leave a Team

POST/runtime/teams/:team_id/leave

Leave a team instance who's id is specified.

It returns a confirmation message of the event.

Leave a Team

Request
POST https://api.playlyfe.com/v2/runtime/teams/avengers/leave HTTP/1.1
Response
{
  "message": "The player 'hulk' has been removed from team 'avengers'"
}
Possible Errors
403forbidden

Player cannot leave the team.

404member_not_found

Player not a member of the team.

Change Own Roles in Team

POST/runtime/teams/:team_id/roles

Update player roles in a team.

In a public team, the roles are changed immediately and the new player roles are returned.

In case of a protected and private team, player's roles are updated if he has the required permissions and the updated player roles are returned. If the player does not have permission, it places a request for role change and returns the request.

Each member of the team must have at least 1 role in the team.

The requested roles should be in passed in the body of the request with the keys being the requested roles.

Change Own Roles in Team

In a public team

Request
POST https://api.playlyfe.com/v2/runtime/teams/globe_trotters/roles HTTP/1.1
Request Body
{
  "member": false,
  "admin": true
}
Response
{
  "message": "You have successfully changed member droid roles in team con_artists",
  "roles": [
    "admin"
  ]
}

In case of a protected or private team.

Request
POST https://api.playlyfe.com/v2/runtime/teams/globe_trotters/roles HTTP/1.1
Request Body
{
  "member": false,
  "admin": true
}
Response
{
  "id": "633945c0-29fd-11e4-b2d2-3d471184ea59",
  "event": "role:request",
  "timestamp": "2014-08-22T13:08:19.612Z",
  "team": {
    "id": "globe_trotters",
    "name": "The Globe Trotters"
  },
  "roles": {
    "member": false,
    "admin": true
  },
  "state": "PENDING",
  "actor": {
    "id": "ripley",
    "alias": "The Amazing Mr.Ripley!"
  }
}
Possible Errors
401team_locked

Cannot update roles when the team is locked.

400role_required

Player must have at least 1 role in the team.

List All Members of a Team

GET/runtime/teams/:team_id/members

Get a list of all the players who are members of a team

In case of a private team, only the members of the team can see this list.

List All Members of a Team

Request
GET https://api.playlyfe.com/v2/runtime/teams/hackers/members HTTP/1.1
Response
{
  "data": [
    {
      "alias": "Neo",
      "id": "neo"
    },
    {
      "alias": "Trinity",
      "id": "trinity"
    }
  ],
  "total": 2
}

Get the Profile of a Team Member

GET/runtime/teams/:team_id/members/:member_id

Get a team member's profile. Only fellow team members can see the profile.

Get the Profile of a Team Member

Request
GET https://api.playlyfe.com/v2/runtime/teams/hackers/members/neo HTTP/1.1
Response
{
  "id": "neo",
  "created": "2014-03-02T18:03:59.848Z",
  "enabled": true,
  "alias": "The One",
  "scores": [
    {
      "metric": {
        "id": "xp",
        "name": "experience",
        "type": "point"
      },
      "value": "100"
    }
  ],
  "teams": [
    {
      "id": "hackers",
      "definition": {
        "id": "international",
        "name": "international"
      },
      "roles": [
        "hacker"
      ],
      "name": "TheMatrix"
    }
  ]
}
Possible Errors
401access_denied

Player not authorized. In PRIVATE teams, only team members can view the team.

404player_not_found

Requested player is not a part of that team.

Kick Member From a Team

POST/runtime/teams/:team_id/members/:member_id/kick

Kick a member from the team.

Team owners can not be kicked. Members who kick must have sufficient privileges to do so else an error is returned.

Kick Member From a Team

Request
POST https://api.playlyfe.com/v2/runtime/teams/hackers/members/trinity/kick HTTP/1.1
Response
{
  "message": "The player 'trinity' has been removed from team 'hackers'"
}
Possible Errors
401access_denied

Player does not have sufficient permissions to perform kick.

403forbidden

Cannot kick owner of the team.

404member_not_found

Requested player not a part of the team.

Change Roles of a Team Member

POST/runtime/teams/:team_id/members/:member_id/roles

Update roles of a member.

To perform the role update, the player must have sufficient privileges within the team else an error is returned. All members in the team must have at least 1 role.

The required roles should be specified in the request body.

Response with the new roles and their ranks is returned.

Change Roles of a Team Member

Request
POST https://api.playlyfe.com/v2/runtime/teams/hacker/members/trinity/roles HTTP/1.1
Request Body
{
  "mentor": true,
  "hacker": false
}
Response
{
      "message": "You have successfully changed member trinity roles in team hacker",
      "roles": [
        "mentor"
      ]
    }
Possible Errors
401access_denied

Player does not have required permissions to perform the role update.

404member_not_found

Requested player not found in the team.

400invalid_role

Invalid role requested.

Transfer Team Ownership

POST/runtime/teams/:team_id/transfer

Transfer team ownership to another player.

The new owner can be either an existing member of the team or any other player in the game.

The roles assigned to the new owner can be either specified in the request body or by default, they will be the owner roles of the team.

The original owner will remain a part of the team with older roles in the team after the transfer.

Parameters
NameDescription
id

ID of the new owner.

roles

Object that contains the roles of the new owner.

 Query Parameter Request Body Required

Transfer Team Ownership

Request
POST https://api.playlyfe.com/v2/runtime/teams/globe_trotters/transfer HTTP/1.1
Request Body
{
  "id": "ripley",
  "roles": {
    "member": true
  }
}
Response
{
      "id": "globe_trotters",
      "name": "The Globe Trotters",
      "definition": "local",
      "created": "1937-03-01T16:30:30.088Z",
      "access": "PROTECTED",
      "owner": "ripley",
      "locked": false,
      "member_count": {
        "member": 1,
        "admin": 0,
        "super_admin": 0,
        "owner": 1
      },
      "total_members": 2
  }
Possible Errors
400invalid_role

The roles specified are either non-existent or the player has no roles

401access_denied

Player not authorized to transfer ownership. Only the team owner can perform this action.

Update Team Settings

PATCH/runtime/teams/:team_id

Update team settings.

Only the owner can perform this action.

Only the team name and access setting can be updated. The new values should be sent as an object in the request body.

The updated state of the team is returned.

Parameters
NameDescription
access

The required team access setting. Valid access settings: PUBLIC, PROTECTED, PRIVATE

name

The required team name.

 Query Parameter Request Body Required

Update Team Settings

Request
PATCH https://api.playlyfe.com/v2/runtime/teams/guardians HTTP/1.1
Request Body
{
  "access": "PUBLIC"
}
Response
{
  "id": "guardians",
  "name": "The Gaurdians",
  "definition": "immortals",
  "created": "2014-03-01T16:29:30.088Z",
  "access": "PUBLIC",
  "owner": "star_lord",
  "locked": false,
  "member_count": {
    "God": 2
  },
  "total_members": 2
}
Possible Errors
401access_denied

Player not authorized. Only team owner can update the team.

400invalid_access_setting

Requested access setting is invalid.

Disband a Team

DELETE/runtime/teams/:team_id

Disband a team.

All members of the team will be removed from the team.

A confirmation message for the event is returned.

Disband a Team

Request
DELETE https://api.playlyfe.com/v2/runtime/teams/avengers HTTP/1.1
Response
{
  "message": "Team 'avengers' disbanded successfully"
}
Possible Errors
401access_denied

Player not authorized. Only team owner can disband a team.

Lock a Team

PUT/runtime/teams/:team_id/lock

Lock a team. Locking a team prevents new players from joining/leaving the team.

The player must have the required roles granting the permission to lock/unlock the team.

Lock a Team

Request
PUT https://api.playlyfe.com/v2/runtime/teams/globe-trotters/lock HTTP/1.1
Response
{
  "id": "globe-trotters",
  "name": "The Globe Trotters",
  "definition": {
    "id": "basketball_team",
    "name": "Basketball Team"
  },
  "created": "2013-11-10T16:49:10.570Z",
  "access": "PUBLIC",
  "owner": {
    "id": "clone",
    "alias": "Clonie"
  },
  "locked": true,
  "member_count": [
    {
      "name": "member",
      "count": 10
    },
    {
      "name": "admin",
      "count": 0
    },
    {
      "name": "super_admin",
      "count": 0
    },
    {
      "name": "owner",
      "count": 1
    }
  ],
  "total_members": 11,
  "roles": [
    "admin",
    "member",
    "owner",
    "super_admin"
  ],
  "my_roles": [
    "owner"
  ],
  "can_leave": false
}
Possible Errors
401access_denied

Player does not have the required permissions to lock the team

Unlock a Team

DELETE/runtime/teams/:team_id/lock

Unlock a team. Unlocking a previously locked team allows new members to join the team again.

The player must have the required roles granting the permission to lock/unlock the team.

Unlock a Team

Request
DELETE https://api.playlyfe.com/v2/runtime/teams/globe-trotters/lock HTTP/1.1
Response
{
  "id": "globe-trotters",
  "name": "The Globe Trotters",
  "definition": {
    "id": "basketball_team",
    "name": "Basketball Team"
  },
  "created": "2013-11-10T16:49:10.570Z",
  "access": "PUBLIC",
  "owner": {
    "id": "clone",
    "alias": "Clonie"
  },
  "locked": false,
  "member_count": [
    {
      "name": "member",
      "count": 10
    },
    {
      "name": "admin",
      "count": 0
    },
    {
      "name": "super_admin",
      "count": 0
    },
    {
      "name": "owner",
      "count": 1
    }
  ],
  "total_members": 11,
  "roles": [
    "admin",
    "member",
    "owner",
    "super_admin"
  ],
  "my_roles": [
    "owner"
  ],
  "can_leave": false
}
Possible Errors
401access_denied

Player does not have the required permissions to unlock the team

Get a Team's Activity Feed

GET/runtime/teams/:team_id/activity

Get the team activity feed.

By default, if start and end are not defined, the activity feed of the last 24 hours is returned.

The start and end timestamps can be specified as an ISO Timestamp or UNIX timestamp.

Parameters
NameDescription
start

Earliest possible activity timestamp.

end

Latest possible activity timestamp.

 Query Parameter Request Body Required

Get a Team's Activity Feed

Request
GET https://api.playlyfe.com/v2/runtime/teams/hackers/activity HTTP/1.1
Response
[
  {
    "event": "invite:accept",
    "timestamp": "2014-03-02T12:34:34.474Z",
    "actor": {
      "id": "morpheus",
      "alias": "Morpheus"
    },
    "inviter": {
      "id": "neo",
      "alias": "Neo"
    },
    "roles": {
      "Member": true
    },
    "id": "02aefca0-a207-11e3-b0b2-6be1ca7db7ba"
  }
]
Possible Errors
401access_denied

Access denied. In PRIVATE teams, only members of the team can view activity.

400invalid_date

Invalid date format.

List Invitations Sent out for a Team

GET/runtime/teams/:team_id/invites

Get a list of invites the player has sent out to join a team.

Only invitations sent out by the player will be listed.

List Invitations Sent out for a Team

Request
GET https://api.playlyfe.com/v2/teams/hackers/invites HTTP/1.1
Response
{
  "data": [
    {
      "event": "invite",
      "timestamp": "2014-03-02T18:10:08.021Z",
      "invitee": {
        "id": "morpheus",
        "alias": "Morpheus"
      },
      "team": {
        "id": "hackers",
        "name": "The Hackers"
      },
      "roles": {
        "Member": true
      },
      "state": "PENDING",
      "id": "e3367450-a235-11e3-9af5-753d0e60669a"
    }
  ],
  "total": 1
}

Get a Team Member's Activity Feed

GET/runtime/teams/:team_id/members/:member_id/activity

Get the activity feed for a team member.

By default, last 24 hour activity is returned. A period can be specified by passing start and end time stamps as query parameters.

Parameters
NameDescription
start

Earliest possible activity time stamp. Unit: UNIX time stamp or ISO time stamp

end

Latest possible activity time stamp. Unit: UNIX time stamp or ISO time stamp

 Query Parameter Request Body Required

Get a Team Member's Activity Feed

Request
GET https://api.playlyfe.com/v2/runtime/teams/avengers/members/tony/activity HTTP/1.1
Response
[
  {
    "event": "action",
    "action": {
      "id": "rescue",
      "name": "Rescue"
    },
    "count": 1,
    "changes": [
      {
        "metric": {
          "id": "fans",
          "name": "fan count",
          "type": "point"
        },
        "delta": {
          "old": "65000",
          "new": "85000"
        }
      }
    ],
    "timestamp": "2012-04-11T08:00:00.500Z",
    "id": "c5465c41-a15d-11e3-84ab-ebaad0c03951"
  }
]

Send a Team Invitation

POST/runtime/teams/:team_id/invites

Invite a player to join a team.

The player must have a role with peer or assign permissions and the required rank to send the invite.

It returns the invitation request.

Parameters
NameDescription
id

The ID of the player.

roles

The desired roles for the player.

 Query Parameter Request Body Required

Send a Team Invitation

Request
POST https://api.playlyfe.com/v2/runtime/teams/avengers/invites HTTP/1.1
Request Body
{
  "id": "neo",
  "roles": {
    "Member": true
  }
}
Response
{
  "id": "1b669910-a257-11e3-92be-0395a5e3aad0",
  "event": "invite",
  "timestamp": "2014-03-02T22:07:55.681Z",
  "actor": {
    "id": "morpheus",
    "alias": "Morpheus"
  },
  "invitee": {
    "id": "neo",
    "alias": "Neo"
  },
  "team": {
    "id": "5313986386e830697700910c",
    "name": "The Hackers"
  },
  "roles": {
    "Member": true
  },
  "state": "PENDING"
}
Possible Errors
401access_denied

Player not authorized to send an invite.

409member_exists

Request player already a member of the team.

401team_locked

Cannot perform the operation when the team is locked.

400invalid_role

Requested roles are invalid.

409already_invited

An invitation has already been sent to the requested player.

Cancel a Sent Invitation

DELETE/runtime/teams/:team_id/invites/:invite_id

Cancel a pending invite sent out by the player.

It returns the canceled invitation request.

Cancel a Sent Invitation

Request
DELETE https://api.playlyfe.com/v2/runtime/teams/avengers/invites/520512b563c67d641e000003 HTTP/1.1
Response
{
  "event": "invite",
  "timestamp": "2014-03-02T18:03:59.848Z"
  "team": {
    "id": "hackers",
    "name": "Hackers"
  },
  "actor": {
    "id": "neo",
    "name": "Neo"
  },
  "invitee": {
    "id": "trinity",
    "name": "Trinity"
  },
  "roles": {
    "Member": true
  },
  "state": "CANCELLED",
  "id": "052de920-a174-11e3-b581-1b9a3fec215b"
  "cancelled_at": "2014-03-02T18:04:08.507Z"
}
Possible Errors
404invalid_invite

Invalid invite_id.

List Pending Team Join or Role Change Requests

GET/runtime/teams/:team_id/approvals

Get a list of pending player requests in a team.

A pending request can be approved by a player who is already a part of the team with the required permissions.

A player who cannot approve any new player to join the team will get an error when he requests the list of approvals.

List Pending Team Join or Role Change Requests

Request
GET https://api.playlyfe.com/v2/runtime/teams/hackers/approvals HTTP/1.1
Response
{
  "data": [
    {
      "event": "join:request",
      "timestamp": "2014-03-01T18:58:22.142Z",
      "actor": {
        "id": "morpheus",
        "alias": "Morpheus"
      },
      "roles": {
        "Member": true
      },
      "state": "PENDING",
      "id": "75d485e0-a173-11e3-b581-1b9a3fec215b"
    },
    {
      "event": "join:request",
      "timestamp": "2014-03-02T18:11:56.928Z",
      "actor": {
        "id": "trinity",
        "alias": "Trinity"
      },
      "roles": {
        "Member": true
      },
      "state": "PENDING",
      "id": "24205800-a236-11e3-9af5-753d0e60669a"
    }
  ],
  "total": 2
}
Possible Errors
401access_denied

Player does not have sufficient permissions to view team requests.

Approve Team Join or Role Change Request

POST/runtime/teams/:team_id/approvals/:request_id

Accept a player request to join a team.

The player who accepts the request must have sufficient privileges to do so.

It returns the accepted approval request.

Approve Team Join or Role Change Request

Request
POST https://api.playlyfe.com/v2/runtime/teams/hackers/approvals/5f3acfa0-a250-11e3-9af5-753d0e60669a HTTP/1.1
Response
{
  "event": "join:request",
  "timestamp": "2014-03-02T21:19:43.002Z",
  "actor": {
    "id": "trinity",
    "alias": "Trinity"
  },
  "team": {
    "id": "hackers",
    "name": "The Hackers"
  },
  "roles": {
    "God": true
  },
  "state": "ACCEPTED",
  "id": "5f3acfa0-a250-11e3-9af5-753d0e60669a",
  "accepted_by": {
    "id": "morpheus",
    "alias": "Morpheus"
  },
  "accepted_at": "2014-03-02T22:03:06.948Z"
}
Possible Errors
404invalid_approval_request

Invalid request_id. There is no such request.

401team_locked

Cannot perform operation when team is locked.

401access_denied

Player is not authorized to approve the request.

Reject Team Join or Role Change Request

DELETE/runtime/teams/:team_id/approvals/:request_id

Reject a player request to join a team.

The player who rejects the request must have sufficient privileges to do so.

It returns the rejected approval request.

Reject Team Join or Role Change Request

Request
DELETE https://api.playlyfe.com/v2/runtime/teams/hackers/approvals/98548650-a24b-11e3-9af5-753d0e60669a HTTP/1.1
Response
{
  "event": "join:request",
  "timestamp": "2014-03-02T20:45:31.317Z",
  "actor": {
    "id": "neo",
    "alias": "Neo"
  },
  "team": {
    "id": "hackers",
    "name": "The Hackers"
  },
  "roles": {
    "God": true
  },
  "state": "REJECTED",
  "id": "98548650-a24b-11e3-9af5-753d0e60669a",
  "rejected_by": {
    "id": "morpheus",
    "alias": "Morpheus"
  },
  "rejected_at": "2014-03-02T20:45:47.679Z"
}
Possible Errors
404invalid_approval_request

Invalid request_id.

401access_denied

Player is not authorized to reject the request.

Get Team Image

GET/runtime/assets/definitions/teams/:team_definition_id

Get a team definition image. The image is returned as a PNG.

Parameters
NameDescription
size

Size of image. Available sizes are original, large, medium, small, icon

Defaults tooriginal
 Query Parameter Request Body Required

Get Team Image

Request
GET https://api.playlyfe.com/v2/runtime/assets/definitions/teams/immortals HTTP/1.1
Response
Binary Image Data of Team Definition

Metric

Metric Examples

List All Metrics

GET/runtime/definitions/metrics

Get a list of all the metrics in the game.

List All Metrics

Request
GET https://api.playlyfe.com/v2/runtime/definitions/metrics HTTP/1.1
Response
[
  {
    "id": "badges",
    "name": "badges",
    "type": "set",
    "items": [
      "expert",
      "novice",
      "seasoned"
    ]
  },
  {
    "id": "rank",
    "name": "rank",
    "type": "state",
    "states": [
      {
        "name": "Brigadier"
      },
      {
        "name": "Colonel"
      },
      {
        "name": "General"
      },
      {
        "name": "Recruit"
      },
      {
        "name": "noob"
      }
    ]
  },
  {
    "items": [],
    "id": "tags",
    "name": "tags",
    "type": "set"
  },
  {
    "id": "xp",
    "name": "experience",
    "type": "point"
  }
]

Get a Metric Image

GET/runtime/assets/definitions/metrics/:metric_id

Get a metric/metric state/metric item image. The image is returned as a PNG.

Parameters
NameDescription
size

Size of image. Available sizes are original, large, medium, small, icon

Defaults tooriginal
state

State name of which to return image. Only valid for metrics of type state

item

Item name of which to return image. Only valid for metrics of type set

 Query Parameter Request Body Required

Get a Metric Image

Request
GET https://api.playlyfe.com/v2/runtime/assets/definitions/metrics/karma?size=icon HTTP/1.1
Response
Binary Image Data of 'karma' metric
Request
GET https://api.playlyfe.com/v2/runtime/assets/definitions/metrics/weapons?item=Excalibur&size=large HTTP/1.1
Response
Binary Image Data of 'Excalibur' item in 'weapons' metric

Leaderboard

Leaderboard Examples

List All Leaderboards

GET/runtime/leaderboards

Get a list of all available leaderboards.

List All Leaderboards

Request
GET https://api.playlyfe.com/v2/runtime/leaderboards HTTP/1.1
Response
[
      {
        "id": "game_leaderboard",
        "name": "GameLeaderboard",
        "entity_type": "players",
        "metric": {
          "id": "xp",
          "type": "point",
          "name": "experience"
        },
        "scope": {
          "type": "game"
        },
        "cycles": [
          "weekly",
          "daily"
        ]
      },
      {
        "id": "team_definition_leaderboard",
        "name": "TeamDefinitionLeaderboard",
        "entity_type": "players",
        "metric": {
          "id": "xp",
          "type": "point",
          "name": "experience"
        },
        "scope": {
          "id": "international",
          "type": "team_definition"
        },
        "cycles": [
          "weekly",
          "daily"
        ]
      },
      {
        "id": "team_leaderboard",
        "name": "TeamLeaderboard",
        "entity_type": "players",
        "metric": {
          "id": "xp",
          "type": "point",
          "name": "experience"
        },
        "scope": {
          "id": "international",
          "type": "team_instance"
        },
        "cycles": [
          "weekly",
          "daily"
        ]
      }
    ]

Get a Leaderboard

GET/runtime/leaderboards/:leaderboard_id

Get the leaderboard for the given leaderboard ID.

Parameters
NameDescription
cycle

Time range of the given leaderboard. Can be one of daily, weekly, monthly, yearly, alltime.

sort

Sorting of the leaderboard. Can be ascending or descending.

Defaults todescending
skip

Number of players to skip.

Defaults to0
limit

Limit the number of players returned in the response. -1 denotes no limit, all players are returned.

Defaults to10
entity_id

Player or Team relative to whom the leaderboard will be.

radius

When the entity_id is provided, players within the requested radius are returned.

Defaults to5
timestamp

Get the latest cycle leaderboard earlier than the given timestamp.

Defaults to<now>
team_instance_id

ID of the team instance. Should be passed when the leaderboard is of type Team Instance.

merge

Merges several leaderboards. The ranking is still based on the original leaderboard, however data of other leaderboards is also sent in the response. Leaderboards being merged can be of any cycle but need to be of the same entity type.

Definition IDs of the leaderboards along with the cycle information are to be sent as comma separated query parameters. The leaderbooard ID and cycle need to be separated by a |, e.g 'overall_leaderboard|alltime`. See manuals for more details.

detailed

Sends details of actions that contributed to the player's leaderboard score. Only available to player leaderboards.

scope_id

Scope of the leaderboard. Available only in custom leaderboards. See manuals for more details.

 Query Parameter Request Body Required

Get a Leaderboard

View leaderboard in ascending order.

Request
GET https://api.playlyfe.com/v2/runtime/leaderboards/game_leaderboard?sort=ascending&cycle=alltime HTTP/1.1
Response
{
      "data": [
        {
          "player": {
            "id": "droid",
            "alias": "Droid!"
          },
          "score": "5",
          "rank": 4
        },
        {
          "player": {
            "id": "clone",
            "alias": "Clonie"
          },
          "score": "12",
          "rank": 3
        },
        {
          "player": {
            "id": "hercules",
            "alias": "hercules"
          },
          "score": "44",
          "rank": 2
        },
        {
          "player": {
            "id": "darky",
            "alias": "darky"
          },
          "score": "87",
          "rank": 1
        }
      ],
      "total": 4
}

View the leaderboard with a particular entity_id and radius.

Request
GET https://api.playlyfe.com/v2/runtime/leaderboards/game_leaderboard?player_id=droid&ranking=relative&radius=1&entity_id=clone&cycle=alltime HTTP/1.1
Response
{
      "data": [
        {
          "player": {
            "id": "droid",
            "alias": "Droid!"
          },
          "score": "5",
          "rank": 4
        },
        {
          "player": {
            "id": "clone",
            "alias": "Clonie"
          },
          "score": "12",
          "rank": 3
        },
        {
          "player": {
            "id": "hercules",
            "alias": "hercules"
          },
          "score": "44",
          "rank": 2
        }
      ],
      "total": 4
}

Merge leaderboards

Request
GET https://api.playlyfe.com/v2/runtime/leaderboards/level_leaderboard?player_id=droid&cycle=alltime&merge_with=kills_leaderboard|alltime,deaths_leaderboard|alltime HTTP/1.1
Response
{
  "data": [
    {
      "player": {
        "id": "ripley",
        "alias": "The Amazing Mr.Ripley!"
      },
      "score": [
        "level_leaderboard",
        "49",
        "kills_leaderboard",
        "10000",
        "deaths_leaderboard",
        "2000"
      ],
      "rank": 1
    },
    {
      "player": {
        "id": "droid",
        "alias": "Droid!"
      },
      "score": [
        "level_leaderboard",
        "37",
        "kill_leaderboard",
        "1700",
        "deaths_leaderboard",
        "180"
      ],
      "rank": 2
    }
  ],
  "total": 2
}

Get a Player or Team Rank Trend

GET/runtime/leaderboard/:leaderboard_id/trend

Get a player or team rank trend. The trend can be viewed at the following cycles:

  • Daily
  • Weekly
  • Monthly
  • Yearly

Trends can be viewed only for those cycles for which the specified leaderboard has been designed. So if a leaderboard has monthly and weekly cycles, you will only be able to view only monthly and weekly trends.

When the leaderboard is of type teams, the team_instance_id is required to specify the team.

The response is an an array of objects. The data key of those objects contains rank information. A rank of -1 is returned when the player was not on the leaderboard at the given time period.

Parameters
NameDescription
cycle

Leaderboard cycle. Possible values : daily, weekly, monthly, yearly

entity_ids

Comma separated string containing IDs of players whose rank trends are required.

start

Valid date string, format - YYYY-mm-dd (eg. 2013-12-13). Specifies the start date for the trend.

end

Valid date string, format - YYYY-mm-dd (eg. 2013-12-13). Specifies the end date for the trend.

team_instance_id

ID of the team instance, required when the leaderboard is of type Team Instance.

 Query Parameter Request Body Required

Get a Player or Team Rank Trend

Request
GET https://api.playlyfe.com/v2/runtime/leaderboard/game_leaderboard/trend?cycle=daily&start=2013-05-01&end=2013-05-07&entity_ids=peter,johny HTTP/1.1
Request Body
{}
Response
[
  {
    "data": [
      {
        "date": "2013-05-01",
        "score": "9",
        "rank": 2
      },
      {
        "date": "2013-05-02",
        "score": "9",
        "rank": 5
      },
      {
        "date": "2013-05-03",
        "score": "11",
        "rank": 6
      },
      {
        "date": "2013-05-04",
        "score": "11",
        "rank": 6
      },
      {
        "date": "2013-05-05",
        "rank": -1
      },
      {
        "date": "2013-05-06",
        "rank": -1
      },
      {
        "date": "2013-05-07",
        "rank": -1
      }
    ],
    "player": {
      "id": "peter",
      "alias": "Peter!!"
    }
  },
  {
    "data": [
      {
        "date": "2013-05-01",
        "rank": -1
      },
      {
        "date": "2013-05-02",
        "rank": -1
      },
      {
        "date": "2013-05-03",
        "score": "111",
        "rank": 1
      },
      {
        "date": "2013-05-04",
        "score": "122",
        "rank": 1
      },
      {
        "date": "2013-05-05",
        "rank": -1
      },
      {
        "date": "2013-05-06",
        "rank": -1
      },
      {
        "date": "2013-05-07",
        "rank": -1
      }
    ],
    "player": {
      "id": "johny",
      "alias": "JohnyJ"
    }
  }
]