🎪

API

🧩 UG Labs API Documentation

🔗 Live API (Staging)

Interact with the API here →
https://pug.stg.uglabs.app/docs#/
 

Interact

To see a list of interact messages - follow this
https://github.com/uglabs/ug-python-sdk/blob/main/pug_protocol/messages.py

🔐 Authentication Overview

UG Labs uses a role- and permission-based authentication system with two types of API keys:
  1. Developer API Key — used by developers to manage accounts and players.
  1. Service Account API Key — used by players to authenticate from your client app.
 
💡
All HTTP requests auth after obtaining a token is done by adding the header: Authorization: Bearer <token>

👨‍💻 Developer Authentication

Developers should log in using Google SSO to access their UG Labs account and retrieve their Developer API Key.
This key allows you to:
  • Create, edit, and delete players within your organization.
  • Generate Service Account API Keys that players will use to authenticate.

1️⃣ Get a Developer Access Token

💡
A quick way to get a developer access token is by logging into here and then navigating to your Profile page
https://pug-playground.stg.uglabs.app/profile
Request
POST /api/auth/login
Content-Type: application/json

{
  "api_key": "{{DEVELOPER_API_KEY}}"
}
Response
{
  "access_token": "{YOUR_ACCESS_TOKEN}"
}
➡️ Save this access_token and include it in the Authorization header for all developer-level requests.

🧑‍🎮 Player Management

Once you have a valid Developer Access Token, you can create new players in your account.
External id could be anything - this endpoint is usually called from within your server (after you validated that this email belongs to the player for example). This could be anything such as phone number or any other identifier.

2️⃣ Create a Player

Request
POST {{baseUrl}}/api/players
Content-Type: application/json
Authorization: Bearer {DEVELOPER_ACCESS_TOKEN}

{
  "external_id": "someemail@gmail.com"
}
Response
{
  "pk": 1,
  "external_id": "someemail@gmail.com",
  "federated_id": "<FEDERATED_ID_UNIQUE_TO_PLAYER>"
}
⚠️ Note:
The federated_id returned here is required for the player’s login process.

🧾 Service Account API Key

The Service Account API Key is used by players to authenticate.
This key should be stored securely on the client side and tied to a specific player.
You can create or retrieve your Service Account API Key from the UG Labs dashboard
Https://pug-playground.stg.uglabs.app

🎮 Player Authentication

Players log in using the Service Account API Key and their federated_id.
Those 2 objects can be stored on the user device.

3️⃣ Get a Player Access Token

Request
POST {{baseUrl}}/api/auth/login
Content-Type: application/json

{
  "api_key": "SERVICE_ACCOUNT_API_KEY",
  "federated_id": "PLAYERS_FEDERATED_ID"
}
Response
{
  "access_token": "{YOUR_ACCESS_TOKEN}"
}
➡️ Use this access_token for the entire duration of the player’s session.
This access token allows you to mainly use the interact endpoint

✅ Summary — Full Authentication Flow

  1. Use Developer API Key → Request a Developer Access Token. Create one here
  1. Login via Google SSO → Access your Developer API Key.
  1. [On your server] Use Developer Access Token → Create a new Player (retrieve federated_id).
  1. Retrieve a Service Account API Key → Store securely on the client side. Create one here.
  1. Player Login → Use SERVICE_ACCOUNT_API_KEY + federated_id → Get Player Access Token.
 

🕹️ Interaction Flow

The interaction endpoint is a websocket that is accessed by players.
After making a call to get an access token (See above) - the player then uses that as the first message to the websocket.
 
URL: wss://pug.stg.uglabs.app/interact
 
List of messages can be found here:
https://github.com/uglabs/ug-python-sdk/blob/main/pug_protocol/messages.py

Message Flow:

1️⃣ Authorization

{
  "type":"request",
  "kind":"authenticate",
  "access_token":"SECRET.ACCESS_TOKEN",
  "uid":"07eb55fb-b094-4407-b957-7f9782a3685a",
  "client_start_time":"2025-10-04T20:27:07.601Z"
}
 
Response:
{
  "type":"response",
  "uid":"07eb55fb-b094-4407-b957-7f9782a3685a",
  "kind":"authenticate",
  "client_start_time":"2025-10-04T20:27:07.601000Z",
  "server_start_time":"2025-10-04T20:27:07.797467Z",
  "server_end_time":"2025-10-04T20:27:07.813188Z"
}
 

2️⃣ Set Configuration

This is where you set your prompt, safety_policy, utilities (Either through strings or through references)
{
  "type":"request",
  "kind":"set_configuration",
  "config": {
    "prompt":"a game of Scattegories where the user needs to say a country that starts with the letter B"
  },
  "uid":"db004255-b063-437d-81fa-6cb2f10e50a8",
  "client_start_time":"2025-10-04T20:27:07.799Z"
 }
Response:
{
  "type":"response",
  "uid":"db004255-b063-437d-81fa-6cb2f10e50a8",
  "kind":"set_configuration",
  "client_start_time":"2025-10-04T20:27:07.799000Z",
  "server_start_time":"2025-10-04T20:27:07.979354Z",
  "server_end_time":"2025-10-04T20:27:07.979614Z"
}

3️⃣ Stream

Sending a message with a “.” is simply a way to tell the ai to send a response back to the user given all the audio that was sent (None in this request) based on the prompt that was given
{
  "type":"stream",
  "kind":"interact",
  "text":".",
  "context":{},
  "audio_output":true,
  "uid":"2abcafa6-f32a-43b2-9fca-17b98dc292c4",
  "client_start_time":"2025-10-04T20:27:07.964Z"
}
{
  "type":"stream",
  "uid":"2abcafa6-f32a-43b2-9fca-17b98dc292c4",
  "kind":"interact",
  "client_start_time":"2025-10-04T20:27:07.964000Z",
  "server_start_time":"2025-10-04T20:27:08.143381Z",
  "server_end_time":"2025-10-04T20:27:08.970967Z",
  "event":"text",
  "text":"Okay"
}
[…] At that point - you should be getting many stream messages of audio and text that will end with this message
{
  "type":"stream",
  "uid":"2abcafa6-f32a-43b2-9fca-17b98dc292c4",
  "kind":"close"
}
 

Me [Developer only token]

GET /api/users/me
Requires authentication
At any point you can call this endpoint with a valid Developer access token and receive a response.
Response:
{
    "pk": 1,
    "name": "Johnny Depp",
    "email": "johnny.depp@somecompany.com",
    "api_key": "MY_API_KEY",
    "teams": [
        {
            "pk": 2,
            "name": "somecompany.com"
        }
    ]
}

Players [Developer only token]

List Players
GET /api/players/
Requires authentication

Returns the list of all the available players in the current user’s team.
{
    "players": [
        {
            "pk": 1,
            "federated_id": "14abcabcabcabc3bbddf19b357ca0dc2"
        },
        {
            "pk": 3,
            "federated_id": "1111ccccdddd037553cc1628f80c6c55"
        }
    ]
}
 

Get Player
GET /api/players/{player_pk}
Requires authentication
 
Returns the full details of a given player in the current user’s team.
Response:
{
    "pk": 3,
    "external_id": "secret2",
    "federated_id": "1111ccccdddd037553cc1628f80c6c55"
}
 
Delete Player
DELETE /api/players/{player_pk}
Requires authentication
 
Deletes a given player in the current user’s team.