UG API

UG AI Engine for children

🧩 UG Labs API Documentation

🔗 Live API (Staging)

Interact with the API here →

https://pug.stg.uglabs.app/docs#/

Sign into the platform here

https://pug-playground.stg.uglabs.app/

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:

Developer API Key — used by developers to manage accounts and players.

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

💡

Get a developer API Key by logging into here and then navigating to your Profile page

https://pug-playground.stg.uglabs.app/profile

Then using that API key - you can exchange for an access token

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 - usually this secret is stored on the player’s device for future sign-in (See Player Authentication below)

🧾 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/service-accounts

🎮 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

💡

If you are just testing the system - you can quickly create a demo test player by using this link

https://pug-playground.stg.uglabs.app/players

This should give you some federated_id you can use to test out the system

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 - Testing purposes

Here is a full flow to test out the system

[One time only] Login via Google SSO here

Create a Service Account API Key Create one here.

Create a new test player → Get federated_id here

Player Login → Use Service Account API Key + federated_id → Get Player Access Token.

✅ Summary — Full Authentication Flow

When you are ready to go live - here is how the full flow would look like

[One time only] Login via Google SSO → Access your Developer API Key.

Create a Service Account API Key [With playerCreate permission]

Create a Service Account API Key → Store securely on the client side. Create one here.

Your Server → Login with that service account → Get Service Account Access Token

Player Client → Your server → Use Service Account Access Token → Create a new Player (retrieve federated_id).

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)

[See config full message params here]


{
  "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

(See full message params here)


{
  "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"
}

General endpoints

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.

For the full list of api endpoints - follow this