Friends endpoints — list and fetch friends

The friends endpoints let you access the current user’s friends list on Nestri. A friend record combines the friend’s Steam account data with their Nestri user profile when one exists. Lookups are scoped to the authenticated user’s linked Steam account — the x-nestri-steam header lets you specify which Steam account to use if more than one is linked.

GET /friends

List all friends associated with the authenticated user’s Steam account.

GET https://api.nestri.io/friends

This endpoint requires a valid Bearer token. The friends list is scoped to the Steam account identified by the x-nestri-steam header, or the first linked account if the header is omitted.

Request headers

Authorization

string

required

Bearer token in the format Bearer <your-jwt-token>.

x-nestri-steam

string

Optional. The Steam ID to scope the friends list to when the user has multiple linked accounts.

Response

Returns a data array of up to 100 Friend objects, ordered by when they were added.

data

Friend[]

required

Hide Friend fields

string

required

The friend’s Steam ID. Example: "74839300282033".

name

string

required

Display name used by this Steam account. Example: "JD The 65th".

realName

string | null

required

Real name set on the Steam profile. Example: "John Doe".

profileUrl

string | null

required

Steam community URL slug or custom URL. Example: "The65thJD".

avatarHash

string

required

Steam avatar hash for constructing the full avatar image URL. Example: "3a5e805fd4c1e04e26a97af0b9c6fab2dee91a19".

status

string

required

Current connection status. One of online, offline, dnd, or playing.

userID

string | null

required

The Nestri user ID linked to this Steam account, if the friend has a Nestri account.

steamMemberSince

string

required

ISO 8601 timestamp of when the Steam account was created. Example: "2010-01-26T21:00:00.000Z".

lastSyncedAt

string

required

ISO 8601 timestamp of the last sync with Steam data. Example: "2025-04-26T20:11:08.155Z".

limitations

object

required

Steam-imposed restrictions on this account.

Show Limitations fields

isLimited

boolean

required

Whether the account has limited status on Steam.

tradeBanState

string

required

Trade ban status. One of none, probation, or banned.

isVacBanned

boolean

required

Whether the account has an active VAC ban.

visibilityState

number

required

Numeric visibility state from the Steam API.

privacyState

string

required

Profile privacy. One of public, private, friendsfriendsonly, or friendsonly.

user

object | null

required

The Nestri user account that owns this Steam account, or null if the friend has not joined Nestri.

Show User fields

string

required

Nestri user ID. Example: "user_XXXXXXXXXXXXXXXXXXXXXXXXX".

name

string

required

Display name. Example: "John Doe".

string

required

Primary email address.

avatarUrl

string | null

required

URL to the user’s profile picture.

ISO 8601 timestamp of the user’s most recent authentication.

polarCustomerID

string | null

required

Associated Polar.sh customer identifier for subscription billing.

Example

curl https://api.nestri.io/friends \
  --header "Authorization: Bearer <your-jwt-token>"

Example response

{
  "data": [
    {
      "id": "74839300282033",
      "name": "JD The 65th",
      "realName": "John Doe",
      "profileUrl": "The65thJD",
      "avatarHash": "3a5e805fd4c1e04e26a97af0b9c6fab2dee91a19",
      "status": "online",
      "userID": "user_XXXXXXXXXXXXXXXXXXXXXXXXX",
      "steamMemberSince": "2010-01-26T21:00:00.000Z",
      "lastSyncedAt": "2025-04-26T20:11:08.155Z",
      "limitations": {
        "isLimited": false,
        "tradeBanState": "none",
        "isVacBanned": false,
        "visibilityState": 3,
        "privacyState": "public"
      },
      "user": {
        "id": "user_XXXXXXXXXXXXXXXXXXXXXXXXX",
        "name": "John Doe",
        "email": "johndoe@example.com",
        "avatarUrl": "https://cdn.discordapp.com/avatars/xxxxxxx/xxxxxxx.png",
        "lastLogin": "2025-04-26T20:11:08.155Z",
        "polarCustomerID": "0bfcb712-df13-4454-81a8-fbee66eddca4"
      }
    }
  ]
}

GET /friends/:id

Fetch a single friend by their Steam ID.

GET https://api.nestri.io/friends/:id

Path parameters

string

required

The Steam ID of the friend to retrieve. Example: "74839300282033".

Request headers

Authorization

string

required

Bearer token in the format Bearer <your-jwt-token>.

x-nestri-steam

string

Optional. The Steam ID of the requesting user’s account to scope the friendship lookup.

Response

Returns a data object with the same Friend field structure as the list endpoint above, or a 404 if the specified Steam ID is not in the user’s friends list.

Example

curl https://api.nestri.io/friends/74839300282033 \
  --header "Authorization: Bearer <your-jwt-token>"

Error responses

Status	Code	Description
`400`	`INVALID_PARAMETER`	Request validation failed
`404`	`RESOURCE_NOT_FOUND`	No friend found with the given Steam ID
`429`	—	Rate limit exceeded

Overview

Endpoints

Friends endpoints — list and fetch friends

GET /friends

Request headers

Response

Example

Example response

GET /friends/:id

Path parameters

Request headers

Response

Example

Error responses

Build docs developers (and LLMs) love

Overview

Endpoints

Documentation Index

​GET /friends

​Request headers

​Response

​Example

​Example response

​GET /friends/:id

​Path parameters

​Request headers

​Response

​Example

​Error responses

Build docs developers (and LLMs) love

GET /friends

Request headers

Response

Example

Example response

GET /friends/:id

Path parameters

Request headers

Response

Example

Error responses