public

package
v2.18.7 Latest Latest
Warning

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

 Go to latest Published: Sep 15, 2026 License: Apache-2.0 Imports: 7 Imported by: 0

Documentation

Overview

Package public is the CLI's client for the user-authenticated LiveKit Public API. It is a thin wrapper over the net/http client generated by oapi-codegen from the API's OpenAPI spec (pkg/public/oapi, regenerated via `go generate -tags oapigen`): it adds bearer auth, unwraps the response envelopes, and classifies errors. Its methods return the generated types directly — the API is tightly versioned, so there is no separate domain model to keep in sync. The only value-mapping kept here is role int <-> name (see roles.go), which the wire format (a bare int32) genuinely lacks.

The typed client under ./oapi is generated by oapi-codegen from the LiveKit Public API's OpenAPI spec.

Source of truth

The spec is served by the API itself at <base>/v1/openapi and fetched at generate time — no copy is kept in the repo. The base defaults to production (https://beta-api.livekit.cloud); override it for a local/staging server: 

go generate -tags oapigen ./pkg/public/...                                       # prod
LK_PUBLIC_API_URL=http://localhost:8000 go generate -tags oapigen ./pkg/public/...

The generate directive is gated behind the `oapigen` build tag so a plain `go generate ./...` never reaches the network; the committed ./oapi/oapi.gen.go keeps ordinary build/test offline and reproducible. The spec is OpenAPI 3.1 (grpc-gateway); ./oapi/normalize.go collapses its union `type` arrays to 3.0-style types so oapi-codegen can consume it (see ./oapi/generate.sh).

Index

Constants

View Source 
const DefaultBaseURL = "https://beta-api.livekit.cloud"

DefaultBaseURL is the base URL of the LiveKit Public API. Override it (e.g. to http://localhost:8000) for local development. The generated operation paths already include the /v1 prefix, so this is the host root.

Variables

This section is empty.

Functions

func IsPermissionDenied 

func IsPermissionDenied(err error) bool

IsPermissionDenied reports whether err is an APIError signalling that the authenticated account lacks access to the target project or action (HTTP 403).

func IsUnauthenticated 

func IsUnauthenticated(err error) bool

IsUnauthenticated reports whether err is an APIError signalling a missing or invalid session (HTTP 401), which the CLI surfaces as a prompt to re-run `lk cloud auth`.

func RoleName 

func RoleName(v *int32) string

RoleName renders a wire role value (a *int32) for display. Empty for nil.

Types

type APIError 

type APIError struct {
	Status  int
	Message string
}

APIError is a structured error from the Public API, carrying the HTTP status and the server's message. Callers can errors.As for it — notably via IsUnauthenticated / IsPermissionDenied.

func (*APIError) Error 

func (e *APIError) Error() string

type Client 

type Client struct {
	// contains filtered or unexported fields
}

Client is the CLI's user-authenticated Public API client.

func New 

func New(baseURL, token string, opts ...oapi.ClientOption) (*Client, error)

New builds a Client for the Public API at baseURL, authenticating every request with the given user session token. If baseURL is empty, DefaultBaseURL is used. Extra client options may be passed (e.g. a custom http client).

func (*Client) AddWorkspaceMembersToProject 

func (c *Client) AddWorkspaceMembersToProject(ctx context.Context, projectID string, userIDs []string, role Role) ([]oapi.LivekitPublicapiProjectsV1ProjectMember, error)

AddWorkspaceMembersToProject grants a set of existing workspace members access to a project at the given role, returning the resulting project memberships.

func (*Client) AnswerProjectInvitation 

func (c *Client) AnswerProjectInvitation(ctx context.Context, inviteToken string, accept bool) (*oapi.LivekitPublicapiProjectsV1ProjectMember, error)

AnswerProjectInvitation accepts or declines a project invite by token. On accept the response carries the resulting membership (nil otherwise).

func (*Client) AnswerWorkspaceInvite 

func (c *Client) AnswerWorkspaceInvite(ctx context.Context, inviteToken string, accept bool) (*oapi.LivekitPublicapiWorkspacesV1WorkspaceMember, error)

AnswerWorkspaceInvite accepts or declines a workspace invite by token. On accept the response carries the resulting membership (nil otherwise).

func (*Client) CancelSimulationRun 

func (c *Client) CancelSimulationRun(ctx context.Context, projectID, runID string) error

CancelSimulationRun cancels an in-progress simulation run.

func (*Client) CreateProject 

func (c *Client) CreateProject(ctx context.Context, name string) (*oapi.LivekitPublicapiProjectsV1Project, error)

CreateProject creates a new project with the given name and returns it.

func (*Client) CreateSimulationRun 

func (c *Client) CreateSimulationRun(ctx context.Context, projectID string, opts CreateSimulationOptions) (*oapi.LivekitSimulationRunCreateResponse, error)

CreateSimulationRun starts a new simulation run. The response carries the run id plus a presigned POST target the caller must upload the agent bundle to.

func (*Client) CreateWorkspace 

func (c *Client) CreateWorkspace(ctx context.Context, name, organizationID string) (*oapi.LivekitPublicapiWorkspacesV1Workspace, error)

CreateWorkspace creates a workspace. organizationID is optional.

func (*Client) CreateWorkspaceInvite 

func (c *Client) CreateWorkspaceInvite(ctx context.Context, workspaceID, email string, role Role) (*oapi.LivekitPublicapiWorkspacesV1CreateInviteResponse, error)

CreateWorkspaceInvite invites an email address to a workspace at the given role. The response carries the generated invite token.

func (*Client) CreateWorkspaceProject 

func (c *Client) CreateWorkspaceProject(ctx context.Context, workspaceID, name string) (*oapi.LivekitPublicapiProjectsV1Project, error)

CreateWorkspaceProject creates a project within a workspace.

func (*Client) DeleteProject 

func (c *Client) DeleteProject(ctx context.Context, projectID string) error

DeleteProject deletes a project by id.

func (*Client) DeleteProjectInvite 

func (c *Client) DeleteProjectInvite(ctx context.Context, projectID, email string) error

DeleteProjectInvite revokes a pending invite (keyed by email).

func (*Client) DeleteWorkspace 

func (c *Client) DeleteWorkspace(ctx context.Context, workspaceID string) error

DeleteWorkspace deletes a workspace by id.

func (*Client) DeleteWorkspaceInvite 

func (c *Client) DeleteWorkspaceInvite(ctx context.Context, workspaceID, email string) error

DeleteWorkspaceInvite revokes a pending workspace invite (keyed by email).

func (*Client) DeleteWorkspaceMember 

func (c *Client) DeleteWorkspaceMember(ctx context.Context, workspaceID, userID string) error

DeleteWorkspaceMember removes a member from a workspace.

func (*Client) DeleteWorkspaceProject 

func (c *Client) DeleteWorkspaceProject(ctx context.Context, workspaceID, projectID string) error

DeleteWorkspaceProject deletes a project within a workspace.

func (*Client) GetCurrentUser 

func (c *Client) GetCurrentUser(ctx context.Context) (*oapi.LivekitPublicapiUsersV1User, error)

GetCurrentUser returns the signed-in user.

func (*Client) GetProject 

func (c *Client) GetProject(ctx context.Context, projectID string) (*oapi.LivekitPublicapiProjectsV1Project, error)

GetProject returns a single project by id.

func (*Client) GetProjectInvite 

func (c *Client) GetProjectInvite(ctx context.Context, inviteToken string) (*oapi.LivekitPublicapiProjectsV1ProjectInvite, error)

GetProjectInvite returns a single invite by its token.

func (*Client) GetProjectMember 

func (c *Client) GetProjectMember(ctx context.Context, projectID, userID string) (*oapi.LivekitPublicapiProjectsV1ProjectMember, error)

GetProjectMember returns a single project member by user id.

func (*Client) GetSession 

func (c *Client) GetSession(ctx context.Context, projectID, sessionID string) (*oapi.LivekitPublicapiAnalyticsV1Session, error)

GetSession returns a single analytics session by id.

func (*Client) GetSimulationRun 

func (c *Client) GetSimulationRun(ctx context.Context, projectID, runID string) (*oapi.LivekitSimulationRun, error)

GetSimulationRun returns a single simulation run by id.

func (*Client) GetUser 

func (c *Client) GetUser(ctx context.Context, userID string) (*oapi.LivekitPublicapiUsersV1User, error)

GetUser returns a single user by id.

func (*Client) GetWorkspace 

func (c *Client) GetWorkspace(ctx context.Context, workspaceID string) (*oapi.LivekitPublicapiWorkspacesV1Workspace, error)

GetWorkspace returns a single workspace by id.

func (*Client) GetWorkspaceInvite 

func (c *Client) GetWorkspaceInvite(ctx context.Context, inviteToken string) (*oapi.LivekitPublicapiWorkspacesV1WorkspaceInvite, error)

GetWorkspaceInvite returns a single workspace invite by its token.

func (*Client) GetWorkspaceMember 

func (c *Client) GetWorkspaceMember(ctx context.Context, workspaceID, userID string) (*oapi.LivekitPublicapiWorkspacesV1WorkspaceMember, error)

GetWorkspaceMember returns a single workspace member by user id.

func (*Client) GetWorkspaceProject 

func (c *Client) GetWorkspaceProject(ctx context.Context, workspaceID, projectID string) (*oapi.LivekitPublicapiProjectsV1Project, error)

GetWorkspaceProject returns a project within a workspace.

func (*Client) InviteProjectMember 

func (c *Client) InviteProjectMember(ctx context.Context, projectID, email string, role Role) (*oapi.LivekitPublicapiProjectsV1InviteMemberResponse, error)

InviteProjectMember invites an email address to a project at the given role. The response carries the generated invite token (the server does not echo the email/role back).

func (*Client) ListProjectInvites 

func (c *Client) ListProjectInvites(ctx context.Context, projectID string) ([]oapi.LivekitPublicapiProjectsV1ProjectInvite, error)

ListProjectInvites returns the pending invites for a project.

func (*Client) ListProjectMembers 

func (c *Client) ListProjectMembers(ctx context.Context, projectID string) ([]oapi.LivekitPublicapiProjectsV1ProjectMember, error)

ListProjectMembers returns the members of a project.

func (*Client) ListProjectSessions 

func (c *Client) ListProjectSessions(ctx context.Context, projectID string, limit int32, cursor string) (sessions []oapi.LivekitPublicapiAnalyticsV1Session, nextCursor string, err error)

ListProjectSessions returns one page of a project's analytics sessions. limit caps the page size (0 lets the server choose its default) and cursor requests a specific page (empty starts from the beginning). The operation is cursor-paginated; the returned nextCursor is non-empty when more pages remain (pass it back as cursor to fetch the next page).

func (*Client) ListProjects 

func (c *Client) ListProjects(ctx context.Context) ([]oapi.LivekitPublicapiProjectsV1Project, error)

ListProjects returns the projects the authenticated user can access.

NOTE: this returns only the first page; wire up PageInfo/cursor paging when a command needs the full set.

func (*Client) ListSimulationRuns 

func (c *Client) ListSimulationRuns(ctx context.Context, projectID, status, pageToken string) (runs []oapi.LivekitSimulationRun, nextToken string, err error)

ListSimulationRuns returns one page of the simulation runs for a project, optionally filtered by status name (e.g. "running", "completed"). This operation is token-paginated: pageToken requests a specific page and the returned nextToken is non-empty when more pages remain.

func (*Client) ListUsers 

func (c *Client) ListUsers(ctx context.Context, projectID, workspaceID string, limit int32, cursor string) (users []oapi.LivekitPublicapiUsersV1User, nextCursor string, err error)

ListUsers returns one page of the users in a project or workspace. At least one of projectID or workspaceID must be set. limit caps the page size (0 = server default); cursor requests a specific page. The returned nextCursor is non-empty when more pages remain.

func (*Client) ListWorkspaceInvites 

func (c *Client) ListWorkspaceInvites(ctx context.Context, workspaceID string) ([]oapi.LivekitPublicapiWorkspacesV1WorkspaceInvite, error)

ListWorkspaceInvites returns the pending invites for a workspace.

func (*Client) ListWorkspaceMembers 

func (c *Client) ListWorkspaceMembers(ctx context.Context, workspaceID string) ([]oapi.LivekitPublicapiWorkspacesV1WorkspaceMember, error)

ListWorkspaceMembers returns the members of a workspace.

func (*Client) ListWorkspaceProjects 

func (c *Client) ListWorkspaceProjects(ctx context.Context, workspaceID string, limit int32, cursor string) (projects []oapi.LivekitPublicapiProjectsV1Project, nextCursor string, err error)

ListWorkspaceProjects returns one page of the projects within a workspace.

func (*Client) ListWorkspaces 

func (c *Client) ListWorkspaces(ctx context.Context, limit int32, cursor string) (workspaces []oapi.LivekitPublicapiWorkspacesV1Workspace, nextCursor string, err error)

ListWorkspaces returns one page of the workspaces the authenticated user can access. limit caps the page size (0 = server default); cursor requests a specific page. The returned nextCursor is non-empty when more pages remain.

func (*Client) RemoveProjectMember 

func (c *Client) RemoveProjectMember(ctx context.Context, projectID, userID string) error

RemoveProjectMember removes a member from a project.

func (*Client) UpdateProject 

func (c *Client) UpdateProject(ctx context.Context, projectID, name string) (*oapi.LivekitPublicapiProjectsV1Project, error)

UpdateProject updates a project's name and returns the updated project.

func (*Client) UpdateProjectInvite 

func (c *Client) UpdateProjectInvite(ctx context.Context, projectID, email string, role Role) (*oapi.LivekitPublicapiProjectsV1ProjectInvite, error)

UpdateProjectInvite changes the role of a pending invite (keyed by email).

func (*Client) UpdateProjectMember 

func (c *Client) UpdateProjectMember(ctx context.Context, projectID, userID string, role Role) (*oapi.LivekitPublicapiProjectsV1ProjectMember, error)

UpdateProjectMember changes a project member's role.

func (*Client) UpdateWorkspace 

func (c *Client) UpdateWorkspace(ctx context.Context, workspaceID, name string) (*oapi.LivekitPublicapiWorkspacesV1Workspace, error)

UpdateWorkspace renames a workspace.

func (*Client) UpdateWorkspaceMember 

func (c *Client) UpdateWorkspaceMember(ctx context.Context, workspaceID, userID string, role Role) (*oapi.LivekitPublicapiWorkspacesV1WorkspaceMember, error)

UpdateWorkspaceMember changes a workspace member's role.

func (*Client) UpdateWorkspaceProject 

func (c *Client) UpdateWorkspaceProject(ctx context.Context, workspaceID, projectID, name string) (*oapi.LivekitPublicapiProjectsV1Project, error)

UpdateWorkspaceProject renames a project within a workspace.

type CreateSimulationOptions 

type CreateSimulationOptions struct {
	AgentName      string
	NumSimulations int32
	Concurrency    int32
	Mode           string // "text" (default) or "audio"
	Region         string
}

CreateSimulationOptions configures a new simulation run. When ScenarioGroup is not provided the server generates NumSimulations scenarios from the uploaded agent source.

type Role 

type Role int32

Role is a member/invite access level. It mirrors the server's cloud_protocol.ProjectMemberRole enum, which the Public API represents on the wire as a bare int32 (INVITED=0, READ=1, WRITE=2, ADMIN=3) with no name — so this int <-> name mapping has to live here rather than in the generated code. 

const (
	RoleInvited Role = 0
	RoleRead    Role = 1
	RoleWrite   Role = 2
	RoleAdmin   Role = 3
)

func ParseRole 

func ParseRole(s string) (Role, error)

ParseRole resolves a case-insensitive role name (or its numeric value) to a Role. "member" is accepted as an alias for "write", "viewer" for "read".

func (Role) String 

func (r Role) String() string

String returns the lowercase name of the role, or the numeric value for an unknown role.

Source Files

View all Source files

Directories

Path Synopsis
Package oapi provides primitives to interact with the openapi HTTP API.
 Package oapi provides primitives to interact with the openapi HTTP API.
Package render presents the LiveKit Public API's generated types as tables or JSON for the CLI.
 Package render presents the LiveKit Public API's generated types as tables or JSON for the CLI.

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.