local universe

Users

Users are the core identity entity in Local Universe. Every user has a profile, relationships, settings, and can be a member of multiple systems.

The user model

Properties

  • Name
    id
    Type
    string
    Description

    Unique identifier for the user.

  • Name
    email
    Type
    string
    Description

    The user's email address.

  • Name
    username
    Type
    string
    Description

    The unique username.

  • Name
    wallet
    Type
    string
    Description

    The user's public wallet address.

  • Name
    display_name
    Type
    string?
    Description

    Optional display name.

  • Name
    avatar
    Type
    string?
    Description

    Avatar image URL.

  • Name
    bio
    Type
    string?
    Description

    User bio text.

  • Name
    created_at
    Type
    timestamp
    Description

    When the account was created.

  • Name
    updated_at
    Type
    timestamp?
    Description

    When the account was last updated.

  • Name
    banned_until
    Type
    timestamp?
    Description

    When the user's ban expires, if banned.

  • Name
    verified
    Type
    boolean
    Description

    Whether the user's email is verified.

  • Name
    public_flags
    Type
    integer
    Description

    Public user flags bitfield. See user flags below.

  • Name
    oid
    Type
    string
    Description

    The user's object identifier.

User flags

ValueName
1STAFF
2PARTNER
8BUG_HUNTER_LEVEL_1
512PREMIUM_EARLY_SUPPORTER
16384BUG_HUNTER_LEVEL_2
131072ACTIVE_DEVELOPER
262144CERTIFIED_MODERATOR

The user balance model

Represents a user's currency balance.

  • Name
    user_id
    Type
    string
    Description

    The user's ID.

  • Name
    currency
    Type
    string
    Description

    The currency type (e.g. bytes).

  • Name
    balance
    Type
    number
    Description

    The current balance.

  • Name
    updated_at
    Type
    string
    Description

    When the balance was last updated.

Currency types

ValueName
bytesBYTES

The relationship model

Relationships represent connections between users — friends, friend requests, and blocks.

  • Name
    type
    Type
    integer
    Description

    The relationship type.

  • Name
    since
    Type
    string
    Description

    When the relationship was created.

  • Name
    user
    Type
    User
    Description

    The other user in the relationship.

Relationship types

ValueName
0NONE
1FRIEND
2OUTGOING_FRIEND_REQUEST
3INCOMING_FRIEND_REQUEST
4OUTGOING_BLOCK
5INCOMING_BLOCK
GET/v1/users

Search users

Search for users. Requires appropriate permissions.

Request

GET
/v1/users
curl https://api.localuniverse.io/v1/users \
  -H "Authorization: Bearer {token}"
GET/v1/users/@me/channels

Get current user's DM channels

Returns all DM and group DM channels for the authenticated user.

Request

GET
/v1/users/@me/channels
curl https://api.localuniverse.io/v1/users/@me/channels \
  -H "Authorization: Bearer {token}"
POST/v1/users/@me/channels

Create a DM channel

Open a DM channel with another user, or create a group DM.

Required attributes

  • Name
    recipient_id
    Type
    string
    Description

    The user ID to open a DM with.

Request

POST
/v1/users/@me/channels
curl -X POST https://api.localuniverse.io/v1/users/@me/channels \
  -H "Authorization: Bearer {token}" \
  -H "Content-Type: application/json" \
  -d '{"recipient_id": "1344387816333399999"}'
GET/v1/users/:userId/channels

Get a user's DM channels

Returns DM channels for a specific user. Used internally by the Wormhole gateway (service auth).

Request

GET
/v1/users/1344387816333352652/channels
curl https://api.localuniverse.io/v1/users/1344387816333352652/channels \
  -H "Authorization: Service {api_key}:{api_secret}"
GET/v1/users/@me/read-states

Get a user's read states

Returns the read state for all channels the user has read. Each read state tracks the last read message and mention count.

Request

GET
/v1/users/@me/read-states
curl https://api.localuniverse.io/v1/users/@me/read-states \
  -H "Authorization: Bearer {token}"
GET/v1/users/:userId

Get a user

Retrieve a user by their ID. Use @me to get the authenticated user.

Request

GET
/v1/users/1344387816333352652
curl https://api.localuniverse.io/v1/users/1344387816333352652 \
  -H "Authorization: Bearer {token}"

Response

{
  "id": "1344387816333352652",
  "email": "tino@localuniverse.gg",
  "username": "tino",
  "wallet": "KtWwxWwQDwoQASN1SrGCWHcqBMfpspRXeccCFauqAPX",
  "display_name": "Tino",
  "avatar": "https://cdn.localuniverse.io/avatars/1344387816333352652/avatar.png",
  "bio": "Building the multiplayer internet",
  "created_at": "2025-02-26T19:17:12.848375Z",
  "updated_at": "2025-02-26T19:17:12.848375Z",
  "banned_until": null,
  "verified": true,
  "public_flags": 0,
  "oid": "obj_abc123"
}
PATCH/v1/users/@me

Update a user

Optional attributes

  • Name
    username
    Type
    string
    Description

    New username.

  • Name
    display_name
    Type
    string
    Description

    New display name.

  • Name
    avatar
    Type
    string
    Description

    New avatar URL.

  • Name
    bio
    Type
    string
    Description

    New bio text.

Request

PATCH
/v1/users/@me
curl -X PATCH https://api.localuniverse.io/v1/users/@me \
  -H "Authorization: Bearer {token}" \
  -H "Content-Type: application/json" \
  -d '{"display_name": "New Name", "bio": "Updated bio"}'
GET/v1/users/@me/settings

Get user settings

Returns the authenticated user's settings.

Request

GET
/v1/users/@me/settings
curl https://api.localuniverse.io/v1/users/@me/settings \
  -H "Authorization: Bearer {token}"
PATCH/v1/users/@me/settings

Update user settings

Update the authenticated user's settings. Send only the fields you want to change.

Request

PATCH
/v1/users/@me/settings
curl -X PATCH https://api.localuniverse.io/v1/users/@me/settings \
  -H "Authorization: Bearer {token}" \
  -H "Content-Type: application/json" \
  -d '{"theme": "dark"}'
GET/v1/users/@me/relationships

List relationships

Returns all relationships (friends, pending requests, blocks) for the authenticated user.

Request

GET
/v1/users/@me/relationships
curl https://api.localuniverse.io/v1/users/@me/relationships \
  -H "Authorization: Bearer {token}"
PUT/v1/users/@me/relationships

Update relationships

Bulk update relationships for the authenticated user.

Request

PUT
/v1/users/@me/relationships
curl -X PUT https://api.localuniverse.io/v1/users/@me/relationships \
  -H "Authorization: Bearer {token}" \
  -H "Content-Type: application/json" \
  -d '{"username": "friend_user"}'
POST/v1/users/@me/relationships

Create a relationship

Send a friend request or create a relationship.

Request

POST
/v1/users/@me/relationships
curl -X POST https://api.localuniverse.io/v1/users/@me/relationships \
  -H "Authorization: Bearer {token}" \
  -H "Content-Type: application/json" \
  -d '{"username": "new_friend"}'
DELETE/v1/users/@me/relationships

Delete all relationships

Remove all relationships for the authenticated user.

Request

DELETE
/v1/users/@me/relationships
curl -X DELETE https://api.localuniverse.io/v1/users/@me/relationships \
  -H "Authorization: Bearer {token}"
PUT/v1/users/@me/relationships/:targetId

Update a relationship

Accept a friend request or update a specific relationship by target user ID.

Request

PUT
/v1/users/@me/relationships/1344387816333399999
curl -X PUT https://api.localuniverse.io/v1/users/@me/relationships/1344387816333399999 \
  -H "Authorization: Bearer {token}" \
  -H "Content-Type: application/json" \
  -d '{"type": 1}'
DELETE/v1/users/@me/relationships/:targetId

Delete a relationship

Remove a specific relationship (unfriend, unblock, cancel request).

Request

DELETE
/v1/users/@me/relationships/1344387816333399999
curl -X DELETE https://api.localuniverse.io/v1/users/@me/relationships/1344387816333399999 \
  -H "Authorization: Bearer {token}"
POST/v1/users/:userId/inventory

Add to user inventory

Add an item instance to a user's inventory. Requires inventory.write permission.

Required attributes

  • Name
    item_id
    Type
    string
    Description

    The ID of the item to add.

Request

POST
/v1/users/1344387816333352652/inventory
curl -X POST https://api.localuniverse.io/v1/users/1344387816333352652/inventory \
  -H "Authorization: Service {api_key}:{api_secret}" \
  -H "Content-Type: application/json" \
  -d '{"item_id": "1344387816333355555"}'
GET/v1/users/@me/balance

Get user balance

Returns the authenticated user's currency balance.

Request

GET
/v1/users/@me/balance
curl https://api.localuniverse.io/v1/users/@me/balance \
  -H "Authorization: Bearer {token}"

Response

{
  "user_id": "1344387816333352652",
  "currency": "bytes",
  "balance": 1250,
  "updated_at": "2025-06-15T12:30:00.000Z"
}
GET/v1/users/@me/systems

Get user's systems

Returns all systems the authenticated user is a member of.

Request

GET
/v1/users/@me/systems
curl https://api.localuniverse.io/v1/users/@me/systems \
  -H "Authorization: Bearer {token}"

Was this page helpful?