roblox

package module
v0.1.3 Latest Latest
Warning

This package is not in the latest version of its module.

 Go to latest Published: Mar 20, 2026 License: Apache-2.0 Imports: 12 Imported by: 0

README

roblox-go

roblox-go is a Go client library for the Roblox web APIs.

Table of Contents

  1. Installation
  2. Quick Start
  3. Authentication
  4. Pagination
  5. Errors and Rate Limits
  6. Services

Installation

go get github.com/cleesim/roblox-go

Quick Start

package main

import (
	"context"
	"fmt"
	"log"

	"github.com/cleesim/roblox-go"
)

func main() {
	c := roblox.NewClient(nil)

	user, _, err := c.Users.Get(context.Background(), 1)
	if err != nil {
		log.Fatal(err)
	}

	fmt.Printf("%d %s\n", user.ID, user.Name)
}

Authentication

The client supports three authentication methods (highest precedence first):

  1. OAuth bearer token via WithOAuthToken
  2. API key via WithAPIKey
  3. .ROBLOSECURITY cookie via WithCookie
c := roblox.NewClient(
	roblox.WithOAuthToken("oauth-token"),
	roblox.WithAPIKey("api-key"),
	roblox.WithCookie("roblosecurity-cookie")
)

In this case, the OAuth token is used for requests.

Pagination

Many Roblox endpoints are cursor-based. Methods returning lists accept *roblox.ListOptions (or a type embedding it) and return a *roblox.Response with NextPageCursor.

opts := &roblox.ListOptions{Limit: 25}

for {
	members, resp, err := c.Groups.ListMembers(ctx, 1200769, opts)
	if err != nil {
		return err
	}

	for _, m := range members {
		fmt.Println(m.User.Username)
	}

	if resp.NextPageCursor == "" {
		break
	}
	opts.Cursor = resp.NextPageCursor
}

Response also carries rate-limit header data when provided by the API:

  • Response.Rate.Limit
  • Response.Rate.Remaining
  • Response.Rate.Reset

Errors and Rate Limits

Non-2xx responses return *roblox.ErrorResponse. HTTP 429 returns *roblox.RateLimitError.

_, _, err := c.Users.Get(ctx, 0)
if err != nil {
	var apiErr *roblox.ErrorResponse
	if errors.As(err, &apiErr) {
		// inspect apiErr.Errors and apiErr.Response
	}

	var rlErr *roblox.RateLimitError
	if errors.As(err, &rlErr) {
		// inspect rlErr.Rate and rlErr.Response
	}
}

The client also performs one automatic retry when Roblox returns 403 with an x-csrf-token header.

Services

Users
  • Get(ctx, userID)
  • GetAuthenticated(ctx)
  • GetByIDs(ctx, body)
  • GetByUsernames(ctx, body)
  • Search(ctx, opts)
  • ListUsernameHistory(ctx, userID, opts)
Games
  • GetByUniverseIDs(ctx, ids)
  • ListServers(ctx, placeID, serverType, opts)
  • GetFavoritesCount(ctx, universeID)
  • GetVotes(ctx, universeID)
  • ListByUserID(ctx, userID, opts)
  • ListByGroupID(ctx, groupID, opts)
Groups
  • Get(ctx, groupID)
  • GetByIDs(ctx, groupIDs)
  • Search(ctx, opts)
  • ListMembers(ctx, groupID, opts)
  • ListRoles(ctx, groupID)
  • ListUsersInRole(ctx, groupID, roleSetID, opts)
  • ListUserMemberships(ctx, userID)

License

This library is licensed under the Apache License 2.0. See LICENSE for details.

Documentation

Index

Constants

This section is empty.

Variables

This section is empty.

Functions

This section is empty.

Types

type APIError 

type APIError struct {
	Code              int    `json:"code"`
	Message           string `json:"message"`
	UserFacingMessage string `json:"userFacingMessage"`
}

APIError represents a single error object in the Roblox error envelope.

type AuthenticatedUser 

type AuthenticatedUser struct {
	ID          int64  `json:"id"`
	Name        string `json:"name"`
	DisplayName string `json:"displayName"`
}

AuthenticatedUser represents the currently authenticated user.

type Client 

type Client struct {
	UserAgent string

	BaseURLUsers  *url.URL
	BaseURLGames  *url.URL
	BaseURLGroups *url.URL

	Users  *UsersService
	Games  *GamesService
	Groups *GroupsService
	// contains filtered or unexported fields
}

Client manages communication with the Roblox API.

func NewClient 

func NewClient(opts ...ClientOption) *Client

NewClient creates a new Roblox API client with the given options.

func (*Client) Do 

func (c *Client) Do(ctx context.Context, req *http.Request, v any) (*Response, error)

Do sends req and decodes the JSON response into v (if non-nil). On 403 + x-csrf-token header it retries once with the new token. On 429 it returns *RateLimitError. On other non-2xx it returns *ErrorResponse.

func (*Client) NewRequest 

func (c *Client) NewRequest(method string, baseURL *url.URL, urlStr string, body any) (*http.Request, error)

NewRequest creates an API request. urlStr is resolved relative to baseURL. body is JSON-encoded if non-nil.

type ClientOption 

type ClientOption func(*Client)

ClientOption is a functional option for configuring a Client.

func WithAPIKey 

func WithAPIKey(key string) ClientOption

WithAPIKey sets the x-api-key header for all requests.

func WithBaseURLGames 

func WithBaseURLGames(u string) ClientOption

WithBaseURLGames overrides the games API base URL (useful for testing).

func WithBaseURLGroups 

func WithBaseURLGroups(u string) ClientOption

WithBaseURLGroups overrides the groups API base URL (useful for testing).

func WithBaseURLUsers 

func WithBaseURLUsers(u string) ClientOption

WithBaseURLUsers overrides the users API base URL (useful for testing).

func WithCookie 

func WithCookie(cookie string) ClientOption

WithCookie sets the .ROBLOSECURITY cookie for all requests.

func WithHTTPClient 

func WithHTTPClient(hc *http.Client) ClientOption

WithHTTPClient sets the underlying HTTP client.

func WithOAuthToken 

func WithOAuthToken(token string) ClientOption

WithOAuthToken sets the Authorization: Bearer header for all requests.

func WithUserAgent 

func WithUserAgent(ua string) ClientOption

WithUserAgent sets the User-Agent header.

type Creator 

type Creator struct {
	ID               int64  `json:"id"`
	Name             string `json:"name"`
	Type             string `json:"type"`
	IsRNVAccount     bool   `json:"isRNVAccount"`
	HasVerifiedBadge bool   `json:"hasVerifiedBadge"`
}

Creator represents the creator of a game.

type ErrorResponse 

type ErrorResponse struct {
	Response *http.Response
	Errors   []APIError
}

ErrorResponse is returned when the API responds with a non-2xx status.

func (*ErrorResponse) Error 

func (e *ErrorResponse) Error() string

type FavoritesCount 

type FavoritesCount struct {
	FavoritesCount int64 `json:"favoritesCount"`
}

FavoritesCount holds the favorites count for a game.

type Game 

type Game struct {
	ID                        int64    `json:"id"`
	RootPlaceID               int64    `json:"rootPlaceId"`
	Name                      string   `json:"name"`
	Description               string   `json:"description"`
	SourceName                string   `json:"sourceName"`
	SourceDescription         string   `json:"sourceDescription"`
	Creator                   Creator  `json:"creator"`
	Price                     *int64   `json:"price"`
	AllowedGearGenres         []string `json:"allowedGearGenres"`
	AllowedGearCategories     []string `json:"allowedGearCategories"`
	IsGenreEnforced           bool     `json:"isGenreEnforced"`
	CopyingAllowed            bool     `json:"copyingAllowed"`
	Playing                   int64    `json:"playing"`
	Visits                    int64    `json:"visits"`
	MaxPlayers                int      `json:"maxPlayers"`
	Created                   string   `json:"created"`
	Updated                   string   `json:"updated"`
	StudioAccessToApisAllowed bool     `json:"studioAccessToApisAllowed"`
	CreateVipServersAllowed   bool     `json:"createVipServersAllowed"`
	UniverseAvatarType        string   `json:"universeAvatarType"`
	Genre                     string   `json:"genre"`
	IsAllGenre                bool     `json:"isAllGenre"`
	IsFavoritedByUser         bool     `json:"isFavoritedByUser"`
	FavoritedCount            int64    `json:"favoritedCount"`
}

Game represents a Roblox game (universe).

type GameServer 

type GameServer struct {
	ID           string   `json:"id"`
	MaxPlayers   int      `json:"maxPlayers"`
	Playing      int      `json:"playing"`
	PlayerTokens []string `json:"playerTokens"`
	FPS          float64  `json:"fps"`
	Ping         float64  `json:"ping"`
	Name         string   `json:"name"`
	VIPServerId  int64    `json:"vipServerId"`
	AccessCode   string   `json:"accessCode"`
}

GameServer represents an active game server instance.

type GameVotes 

type GameVotes struct {
	ID        int64 `json:"id"`
	UpVotes   int64 `json:"upVotes"`
	DownVotes int64 `json:"downVotes"`
}

GameVotes holds upvote/downvote counts for a game.

type GamesService 

type GamesService service

GamesService handles communication with the Games API. https://games.roblox.com/

func (*GamesService) GetByUniverseIDs 

func (s *GamesService) GetByUniverseIDs(ctx context.Context, ids []int64) ([]*Game, *Response, error)

GetByUniverseIDs returns games for a list of universe IDs (batch, up to 100).

func (*GamesService) GetFavoritesCount 

func (s *GamesService) GetFavoritesCount(ctx context.Context, universeID int64) (*FavoritesCount, *Response, error)

GetFavoritesCount returns the favorites count for a universe.

func (*GamesService) GetVotes 

func (s *GamesService) GetVotes(ctx context.Context, universeID int64) (*GameVotes, *Response, error)

GetVotes returns the vote counts for a universe.

func (*GamesService) ListByGroupID 

func (s *GamesService) ListByGroupID(ctx context.Context, groupID int64, opts *ListOptions) ([]*Game, *Response, error)

ListByGroupID returns games created by a group with cursor-based pagination.

func (*GamesService) ListByUserID 

func (s *GamesService) ListByUserID(ctx context.Context, userID int64, opts *ListOptions) ([]*Game, *Response, error)

ListByUserID returns games created by a user with cursor-based pagination.

func (*GamesService) ListServers 

func (s *GamesService) ListServers(ctx context.Context, placeID int64, serverType string, opts *ServerListOptions) ([]*GameServer, *Response, error)

ListServers returns servers for a place. serverType is "Public" or "Friend".

type GetByIDsRequest 

type GetByIDsRequest struct {
	UserIDs            []int64 `json:"userIds"`
	ExcludeBannedUsers bool    `json:"excludeBannedUsers"`
}

GetByIDsRequest is the request body for GetByIDs.

type GetByUsernamesRequest 

type GetByUsernamesRequest struct {
	Usernames          []string `json:"usernames"`
	ExcludeBannedUsers bool     `json:"excludeBannedUsers"`
}

GetByUsernamesRequest is the request body for GetByUsernames.

type Group 

type Group struct {
	ID                 int64       `json:"id"`
	Name               string      `json:"name"`
	Description        string      `json:"description"`
	Owner              *GroupOwner `json:"owner"`
	MemberCount        int64       `json:"memberCount"`
	IsBuildersClubOnly bool        `json:"isBuildersClubOnly"`
	PublicEntryAllowed bool        `json:"publicEntryAllowed"`
	HasVerifiedBadge   bool        `json:"hasVerifiedBadge"`
}

Group represents a Roblox group.

type GroupMember 

type GroupMember struct {
	User GroupMemberUser `json:"user"`
	Role GroupRole       `json:"role"`
}

GroupMember represents a member of a group.

type GroupMemberUser 

type GroupMemberUser struct {
	ID               int64  `json:"userId"`
	Username         string `json:"username"`
	DisplayName      string `json:"displayName"`
	HasVerifiedBadge bool   `json:"hasVerifiedBadge"`
}

GroupMemberUser is the user portion of a GroupMember.

type GroupOwner 

type GroupOwner struct {
	ID               int64  `json:"userId"`
	Username         string `json:"username"`
	DisplayName      string `json:"displayName"`
	HasVerifiedBadge bool   `json:"hasVerifiedBadge"`
}

GroupOwner represents the owner of a group.

type GroupRole 

type GroupRole struct {
	ID          int64  `json:"id"`
	Name        string `json:"name"`
	Rank        int    `json:"rank"`
	MemberCount int64  `json:"memberCount"`
}

GroupRole represents a role within a group.

type GroupRolesResponse 

type GroupRolesResponse struct {
	GroupID int64        `json:"groupId"`
	Roles   []*GroupRole `json:"roles"`
}

GroupRolesResponse wraps the roles response from /v1/groups/{groupId}/roles.

type GroupSearchOptions 

type GroupSearchOptions struct {
	ListOptions
	Keyword string `url:"keyword,omitempty"`
}

GroupSearchOptions extends ListOptions with a keyword.

type GroupSearchResult 

type GroupSearchResult struct {
	ID                 int64  `json:"id"`
	Name               string `json:"name"`
	Description        string `json:"description"`
	MemberCount        int64  `json:"memberCount"`
	PublicEntryAllowed bool   `json:"publicEntryAllowed"`
	Created            string `json:"created"`
	Updated            string `json:"updated"`
	HasVerifiedBadge   bool   `json:"hasVerifiedBadge"`
}

GroupSearchResult represents a group returned from search.

type GroupSummary 

type GroupSummary struct {
	ID               int64  `json:"id"`
	Name             string `json:"name"`
	MemberCount      int64  `json:"memberCount"`
	HasVerifiedBadge bool   `json:"hasVerifiedBadge"`
}

GroupSummary is a minimal group representation used in memberships.

type GroupsService 

type GroupsService service

GroupsService handles communication with the Groups API. https://groups.roblox.com/

func (*GroupsService) Get 

func (s *GroupsService) Get(ctx context.Context, groupID int64) (*Group, *Response, error)

Get returns a single group by ID.

func (*GroupsService) GetByIDs 

func (s *GroupsService) GetByIDs(ctx context.Context, groupIDs []int64) ([]*Group, *Response, error)

GetByIDs returns groups for a list of group IDs (batch, up to 100).

func (*GroupsService) ListMembers 

func (s *GroupsService) ListMembers(ctx context.Context, groupID int64, opts *ListOptions) ([]*GroupMember, *Response, error)

ListMembers returns members of a group with cursor-based pagination.

func (*GroupsService) ListRoles 

func (s *GroupsService) ListRoles(ctx context.Context, groupID int64) ([]*GroupRole, *Response, error)

ListRoles returns all roles in a group.

func (*GroupsService) ListUserMemberships 

func (s *GroupsService) ListUserMemberships(ctx context.Context, userID int64) ([]*UserGroupMembership, *Response, error)

ListUserMemberships returns all groups a user belongs to.

func (*GroupsService) ListUsersInRole 

func (s *GroupsService) ListUsersInRole(ctx context.Context, groupID, roleSetID int64, opts *ListOptions) ([]*GroupMember, *Response, error)

ListUsersInRole returns users in a specific role with cursor-based pagination.

func (*GroupsService) Search 

func (s *GroupsService) Search(ctx context.Context, opts *GroupSearchOptions) ([]*GroupSearchResult, *Response, error)

Search searches for groups by keyword with cursor-based pagination.

type ListOptions 

type ListOptions struct {
	Limit     int    `url:"limit,omitempty"`
	Cursor    string `url:"cursor,omitempty"`
	SortOrder string `url:"sortOrder,omitempty"`
}

ListOptions specifies cursor-based pagination parameters.

type Rate 

type Rate struct {
	Limit     int
	Remaining int
	Reset     time.Time
}

Rate contains rate-limit information from the API response headers.

type RateLimitError 

type RateLimitError struct {
	Rate     Rate
	Response *http.Response
	Message  string
}

RateLimitError is returned when the API returns 429.

func (*RateLimitError) Error 

func (e *RateLimitError) Error() string

type Response 

type Response struct {
	*http.Response
	NextPageCursor     string
	PreviousPageCursor string
	Rate               Rate
}

Response wraps http.Response with Roblox-specific metadata.

type SearchOptions 

type SearchOptions struct {
	ListOptions
	Keyword string `url:"keyword,omitempty"`
}

SearchOptions extends ListOptions with a search keyword.

type ServerListOptions 

type ServerListOptions struct {
	ListOptions
	ExcludeFullGames bool `url:"excludeFullGames,omitempty"`
}

ServerListOptions extends ListOptions for server listing.

type User 

type User struct {
	ID               int64  `json:"id"`
	Name             string `json:"name"`
	DisplayName      string `json:"displayName"`
	Description      string `json:"description"`
	IsBanned         bool   `json:"isBanned"`
	Created          string `json:"created"`
	HasVerifiedBadge bool   `json:"hasVerifiedBadge"`
}

User represents a Roblox user account.

type UserByUsername 

type UserByUsername struct {
	ID                int64  `json:"id"`
	Name              string `json:"name"`
	DisplayName       string `json:"displayName"`
	RequestedUsername string `json:"requestedUsername"`
	HasVerifiedBadge  bool   `json:"hasVerifiedBadge"`
}

UserByUsername is the result entry from the GetByUsernames batch call.

type UserGroupMembership 

type UserGroupMembership struct {
	Group GroupSummary `json:"group"`
	Role  GroupRole    `json:"role"`
}

UserGroupMembership represents a user's membership in a group.

type UserSearchResult 

type UserSearchResult struct {
	ID                int64    `json:"id"`
	Name              string   `json:"name"`
	DisplayName       string   `json:"displayName"`
	HasVerifiedBadge  bool     `json:"hasVerifiedBadge"`
	PreviousUsernames []string `json:"previousUsernames"`
}

UserSearchResult represents a user returned from search.

type UsernameHistory 

type UsernameHistory struct {
	Name string `json:"name"`
}

UsernameHistory represents a previous username entry.

type UsersService 

type UsersService service

UsersService handles communication with the Users API. https://users.roblox.com/

func (*UsersService) Get 

func (s *UsersService) Get(ctx context.Context, userID int64) (*User, *Response, error)

Get returns a single user by ID.

func (*UsersService) GetAuthenticated 

func (s *UsersService) GetAuthenticated(ctx context.Context) (*AuthenticatedUser, *Response, error)

GetAuthenticated returns the currently authenticated user.

func (*UsersService) GetByIDs 

func (s *UsersService) GetByIDs(ctx context.Context, body *GetByIDsRequest) ([]*User, *Response, error)

GetByIDs returns users matching the given IDs (batch, up to 100).

func (*UsersService) GetByUsernames 

func (s *UsersService) GetByUsernames(ctx context.Context, body *GetByUsernamesRequest) ([]*UserByUsername, *Response, error)

GetByUsernames returns users matching the given usernames (batch, up to 100).

func (*UsersService) ListUsernameHistory 

func (s *UsersService) ListUsernameHistory(ctx context.Context, userID int64, opts *ListOptions) ([]*UsernameHistory, *Response, error)

ListUsernameHistory returns the username history for a user with cursor-based pagination.

func (*UsersService) Search 

func (s *UsersService) Search(ctx context.Context, opts *SearchOptions) ([]*UserSearchResult, *Response, error)

Search searches for users by keyword with cursor-based pagination.

Source Files

View all Source files

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL
go.dev uses cookies from Google to deliver and enhance the quality of its services and to analyze traffic. Learn more.