Help us shape the future of Go! Take the 2026 Go Developer Survey

public

package
v2.19.1 Latest Latest
Warning

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

 Go to latest Published: Oct 20, 2026 License: Apache-2.0 Imports: 16 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>/v0/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/...

To generate from a specific public-api-server commit, check it out and run the server locally. It serves the spec without a database: 

go run ./cmd/public-api-server --dev --http-port 8000 serve      # in public-api-server
LK_PUBLIC_API_URL=http://localhost:8000 go generate -tags oapigen ./pkg/public/...

Provenance

Nothing in oapi.gen.go records which spec it came from, so the commit that regenerates it names the source in its message: 

Generated from livekit/public-api-server@<full commit sha>

Merged code should point at a public-api-server main commit, never an unmerged branch.

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 (protoc-gen-connect-openapi); ./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 (
	RecordingAudio       = "audio"
	RecordingChatHistory = "chat-history"
)

Recording names accepted by RecordingURLOptions.Recording.

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 /v0 prefix, so this is the host root.

Variables

This section is empty.

Functions

func DownloadRecording added in v2.19.1 

func DownloadRecording(ctx context.Context, signedURL string, w io.Writer) (int64, error)

DownloadRecording copies the recording at a signed URL from GetSessionRecordingURL into w and returns the bytes written. The URL carries its own authorization, so the request sends no credentials: never the user's session token, and no cookie, even across a redirect. Its errors never hold the URL's query string, where the signature is. Chat history is stored gzip-encoded; a gzip body is decompressed whether or not the HTTP transport already did it, so w always gets the plain file.

func EventTypeName added in v2.19.1 

func EventTypeName(apiType string) string

EventTypeName is the friendly name of an API event type, such as "participant_joined" for PARTICIPANT_JOINED.

func EventTypeNames added in v2.19.1 

func EventTypeNames() []string

EventTypeNames lists the friendly event type names EventOptions.Types accepts, sorted: LiveKit's analytics event types in lowercase.

func IsNotFound added in v2.19.1 

func IsNotFound(err error) bool

IsNotFound reports whether err is an APIError signalling that the target doesn't exist (HTTP 404).

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 ObservabilityDisabled added in v2.19.1 

func ObservabilityDisabled(err error) (dashboardURL string, ok bool)

ObservabilityDisabled reports whether err is the Public API's answer to an observability read that found nothing while the project's user data recording is off. dashboardURL is the project's settings page where an admin turns recording on; it can be empty.

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
	// contains filtered or unexported fields
}

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.LivekitPublicapiSimulationsV1SimulationRunsCreateResponse, 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) CreateToken added in v2.19.1 

func (c *Client) CreateToken(ctx context.Context, projectID string, grants *auth.ClaimGrants, ttl time.Duration) (token string, expiresAt time.Time, err error)

CreateToken mints a LiveKit access token for a project carrying grants, valid for ttl (rounded down to whole seconds; 0 means the server default). The token is signed server-side, so no API secret is needed locally.

func (*Client) CreateWebhook added in v2.19.1 

func (c *Client) CreateWebhook(ctx context.Context, projectID string, body oapi.ProjectServiceCreateWebhookJSONRequestBody) (*oapi.LivekitPublicapiProjectsV1Webhook, error)

CreateWebhook adds a webhook destination to a project. An unset filter delivers every event; an unset signing key makes the server pick (and store) the project's oldest API key.

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) DeleteKey added in v2.19.1 

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

DeleteKey revokes an API key on a project.

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) DeleteWebhook added in v2.19.1 

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

DeleteWebhook removes a webhook destination from a project.

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) GenerateKey added in v2.19.1 

func (c *Client) GenerateKey(ctx context.Context, projectID, description string, serviceAccount bool) (*oapi.LivekitPublicapiProjectsV1GenerateKeyResponse, error)

GenerateKey creates a new API key on a project. A service-account key has no owner, so it survives the generating user leaving the project. The returned secret is only ever available from this call.

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) (session *oapi.LivekitPublicapiAnalyticsV1Session, detail *oapi.LivekitPublicapiAnalyticsV1SessionDetail, err error)

GetSession returns a single analytics session by id: its list row and its detail (totals, timelines, and the first page of participants). detail is nil while the server is still finalizing it; the session row is always set.

func (*Client) GetSessionLogs added in v2.19.1 

func (c *Client) GetSessionLogs(ctx context.Context, projectID, sessionID string, opts LogOptions) (*LogPage, error)

GetSessionLogs returns one page of the log records a session's agents exported: what the dashboard's logs panel shows, without the chat history GetSessionTranscript reads. An active session returns what its agents have exported so far. An unknown session is NotFound (see IsNotFound); an empty unfiltered first page while the project's user data recording is off is a FailedPrecondition that ObservabilityDisabled recognizes. A read filtered by Levels can come back empty without an error.

func (*Client) GetSessionMetrics added in v2.19.1 

func (c *Client) GetSessionMetrics(ctx context.Context, projectID, sessionID string, opts MetricOptions) (*MetricPage, error)

GetSessionMetrics returns one page of the OpenTelemetry metric points a session's agents exported, such as turn latencies and token usage. They are the raw metrics agents emit, so they won't exactly match the dashboard's metrics panel, which derives its numbers from the transcript and traces; only agents that export OpenTelemetry metrics to LiveKit Cloud produce them. An active session returns what its agents have exported so far. An unknown session is NotFound (see IsNotFound); an empty unfiltered first page while the project's user data recording is off is a FailedPrecondition that ObservabilityDisabled recognizes. A read filtered by Names can come back empty without an error.

func (*Client) GetSessionRecordingURL added in v2.19.1 

func (c *Client) GetSessionRecordingURL(ctx context.Context, projectID, sessionID string, opts RecordingURLOptions) (*oapi.LivekitPublicapiObservabilityV1RecordingGetURLResponse, error)

GetSessionRecordingURL returns a short-lived signed URL for one of a session's recordings, with when it expires and when the recording started. The URL downloads straight from the project's data region (see DownloadRecording). A session with no such recording is NotFound (see IsNotFound), or, while the project's user data recording is off, a FailedPrecondition that ObservabilityDisabled recognizes.

func (*Client) GetSessionTraces added in v2.19.1 

func (c *Client) GetSessionTraces(ctx context.Context, projectID, sessionID string, opts PageOptions) (*TracePage, error)

GetSessionTraces returns one page of the spans a session's agents exported: what the dashboard's trace view shows. A span's attributes are typed, with its resource's and scope's merged in. The pages read the spans the first page found, so a span exported later needs a new read; an active session returns what its agents have exported so far. An unknown session is NotFound (see IsNotFound); an empty first page while the project's user data recording is off is a FailedPrecondition that ObservabilityDisabled recognizes.

func (*Client) GetSessionTranscript added in v2.19.1 

func (c *Client) GetSessionTranscript(ctx context.Context, projectID, sessionID string, opts PageOptions) (*TranscriptPage, error)

GetSessionTranscript returns one page of a session's conversation: messages with their roles and latencies, tool calls and results, agent handoffs and configuration changes. The agent exports its transcript when the session ends, so an active session returns what exists so far, usually nothing, without an error. An unknown session is NotFound (see IsNotFound); an empty first page while the project's user data recording is off is a FailedPrecondition that ObservabilityDisabled recognizes.

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) ListKeys added in v2.19.1 

func (c *Client) ListKeys(ctx context.Context, projectID string, includeAgentKeys bool) ([]oapi.LivekitPublicapiProjectsV1AccessKey, error)

ListKeys returns the API keys of a project. Agent keys (created for cloud agents) are hidden unless includeAgentKeys is set. Secrets are never returned.

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, opts SessionListOptions) (sessions []oapi.LivekitPublicapiAnalyticsV1Session, nextCursor string, err error)

ListProjectSessions returns one page of a project's analytics sessions, narrowed and ordered by opts. The operation is cursor-paginated; the returned nextCursor is non-empty when more pages remain (pass it back as opts.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) ListScopedKeys added in v2.19.1 

func (c *Client) ListScopedKeys(ctx context.Context, projectID string) (personal, other []oapi.LivekitPublicapiProjectsV1AccessKey, err error)

ListScopedKeys returns a project's API keys split into those owned by the authenticated user (personal) and the rest (other).

func (*Client) ListSessionEvents added in v2.19.1 

func (c *Client) ListSessionEvents(ctx context.Context, projectID, sessionID string, opts EventOptions) (*EventPage, error)

ListSessionEvents returns one page of a session's events, such as participants joining and leaving or tracks being published: what the dashboard's events table shows. Each event's payload holds only the fields the server allows, so it carries no participant attributes or metadata. Events are kept for 60 days, so an older session can have none; an active session returns those recorded so far. An unknown session is NotFound (see IsNotFound).

func (*Client) ListSessionParticipants added in v2.19.1 

func (c *Client) ListSessionParticipants(ctx context.Context, projectID, sessionID string, opts ParticipantListOptions) (participants []oapi.LivekitPublicapiAnalyticsV1ParticipantInfo, nextCursor string, err error)

ListSessionParticipants returns one page of a session's participants, one row per identity, ordered by opts. The returned nextCursor is non-empty when more pages remain (pass it back as opts.Cursor to fetch the next page).

func (*Client) ListSimulationRuns 

func (c *Client) ListSimulationRuns(ctx context.Context, projectID, status, cursor string) (runs []oapi.LivekitSimulationRun, nextCursor 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 cursor-paginated: cursor requests a specific page and the returned nextCursor 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) ListWebhookEvents added in v2.19.1 

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

ListWebhookEvents returns the event names a project's webhooks can filter on and send test deliveries of.

func (*Client) ListWebhooks added in v2.19.1 

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

ListWebhooks returns the webhook destinations of a project.

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) SendTestWebhook added in v2.19.1 

func (c *Client) SendTestWebhook(ctx context.Context, projectID, webhookID, event string) (*oapi.LivekitPublicapiProjectsV1SendTestWebhookResponse, error)

SendTestWebhook makes one signed delivery of event, with sample data, to a webhook. A failed delivery is reported in the result, not as an error.

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) UpdateWebhook added in v2.19.1 

func (c *Client) UpdateWebhook(ctx context.Context, projectID, webhookID string, body oapi.ProjectServiceUpdateWebhookJSONRequestBody) (*oapi.LivekitPublicapiProjectsV1Webhook, error)

UpdateWebhook changes the fields set in body and leaves the rest unchanged. A non-nil FilterParams replaces the whole filter; an empty one delivers every event.

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 EventOptions added in v2.19.1 

type EventOptions struct {
	PageOptions
	// Types keeps events of any of these types, by friendly name: the API's
	// type in lowercase, such as "participant_joined" or "track_published"
	// (see EventTypeNames). Empty returns the seven the dashboard's events
	// table shows: participants joining, leaving, going active and resuming,
	// the room created and ended, and API calls. With ParticipantSessionID,
	// empty returns the eleven its participant events table shows: the
	// participant session's joining, leaving, resuming and going active, and
	// its tracks muted, unmuted, published, unpublished, subscribed,
	// subscribe requested and subscribe failed.
	Types []string
	// ParticipantSessionID keeps one participant session's events (PA_...).
	// Room events and API calls name no participant session, so it leaves them
	// out.
	ParticipantSessionID string
	// SortOrder orders by time: "asc" (the server's default) or "desc".
	SortOrder string
}

EventOptions filters, orders and pages ListSessionEvents. Zero values return the server's default types, oldest first, with the server's page size. A cursor pages only a request with the same Types, ParticipantSessionID and SortOrder.

func (EventOptions) Validate added in v2.19.1 

func (o EventOptions) Validate() error

Validate reports a negative limit, an unknown type or sort order name, or a participant session id that isn't one. ListSessionEvents makes the same checks before sending a request; callers can run them earlier.

type EventPage added in v2.19.1 

type EventPage struct {
	// Events are in the requested time order, oldest first by default.
	Events []oapi.LivekitPublicapiAnalyticsV1SessionEvent
	// NextCursor is non-empty when more pages remain (pass it back as
	// EventOptions.Cursor).
	NextCursor string
}

EventPage is one page of a session's events.

type LogOptions added in v2.19.1 

type LogOptions struct {
	PageOptions
	// Levels keeps records at any of these levels: "trace", "debug", "info",
	// "warn", "error" or "fatal" ("warning" and "critical", as Python names
	// them, also work). Empty returns every record, including those with no
	// level, such as a passed evaluation.
	Levels []string
	// SortOrder orders by time: "asc" (the server's default) or "desc".
	SortOrder string
}

LogOptions filters, orders and pages GetSessionLogs. Zero values return every record, oldest first, with the server's page size. A cursor pages only a request with the same Levels and SortOrder.

func (LogOptions) Validate added in v2.19.1 

func (o LogOptions) Validate() error

Validate reports a negative limit or an unknown level or sort order name. GetSessionLogs makes the same checks before sending a request; callers can run them earlier.

type LogPage added in v2.19.1 

type LogPage struct {
	// Records are in the requested time order, oldest first by default.
	Records []oapi.LivekitPublicapiObservabilityV1LogRecord
	// NextCursor is non-empty when more pages remain (pass it back as
	// LogOptions.Cursor).
	NextCursor string
}

LogPage is one page of a session's agent logs.

type MetricOptions added in v2.19.1 

type MetricOptions struct {
	PageOptions
	// Names keeps only the points of these metrics, matched exactly, such as
	// lk.agents.turn.e2e_latency. Empty returns every metric.
	Names []string
}

MetricOptions filters and pages GetSessionMetrics. Zero values return every metric's points, oldest first, with the server's page size. A cursor pages only a request with the same Names.

func (MetricOptions) Validate added in v2.19.1 

func (o MetricOptions) Validate() error

Validate reports a negative limit or a blank metric name. GetSessionMetrics makes the same checks before sending a request; callers can run them earlier.

type MetricPage added in v2.19.1 

type MetricPage struct {
	// Points are by end time, oldest first.
	Points []MetricPoint
	// NextCursor is non-empty when more pages remain (pass it back as
	// MetricOptions.Cursor).
	NextCursor string
}

MetricPage is one page of a session's metric points.

type MetricPoint added in v2.19.1 

type MetricPoint struct {
	// Name is the metric's name, such as lk.agents.turn.e2e_latency.
	Name string `json:"name,omitempty"`
	// Unit is the metric's unit as the agent declared it, such as "s" or
	// "{token}"; empty when it declared none.
	Unit string                                         `json:"unit,omitempty"`
	Kind oapi.LivekitPublicapiObservabilityV1MetricKind `json:"kind,omitempty"`
	// StartTime and EndTime are the interval the point covers; a gauge has no
	// StartTime.
	StartTime *time.Time `json:"startTime,omitempty"`
	EndTime   *time.Time `json:"endTime,omitempty"`
	// Attributes are typed, with the point's resource's and scope's merged in.
	Attributes map[string]*oapi.GoogleProtobufValue                 `json:"attributes,omitempty"`
	Value      *float64                                             `json:"value,omitempty"`
	Histogram  *oapi.LivekitPublicapiObservabilityV1MetricHistogram `json:"histogram,omitempty"`
}

MetricPoint is one OpenTelemetry metric data point a session's agent exported, with the data the API sent decoded: Value for a gauge or sum, Histogram for a histogram or exponential histogram, or neither for a kind newer than this client. It marshals back to the API's own JSON.

type PageOptions added in v2.19.1 

type PageOptions struct {
	// Limit caps how many items a page holds; 0 sends no page size, so the
	// server uses its default. The server also caps a page's size, and a page
	// can hold fewer items than its limit.
	Limit int32
	// Cursor requests a specific page, the NextCursor of the page before it;
	// empty starts from the beginning.
	Cursor string
}

PageOptions pages a read of one of a session's lists: its participants, transcript, agent logs, trace spans, agent metrics or events. Zero values start from the first item with the server's page size.

func (PageOptions) Validate added in v2.19.1 

func (o PageOptions) Validate() error

Validate reports a negative limit. Every read that takes PageOptions makes the same check before sending a request; callers can run it earlier.

type ParticipantListOptions added in v2.19.1 

type ParticipantListOptions struct {
	PageOptions
	// SortBy orders by "joined" (the server's default) or "left".
	SortBy string
	// SortOrder is "asc" or "desc" (the server's default).
	SortOrder string
}

ParticipantListOptions orders and pages one page of ListSessionParticipants. Zero values keep the server's defaults: newest join first, with a page size the server picks. To continue from a session detail's first page, pass its participants page cursor with SortBy and SortOrder unset.

func (ParticipantListOptions) Validate added in v2.19.1 

func (o ParticipantListOptions) Validate() error

Validate reports a negative limit or an unknown sort name. ListSessionParticipants makes the same checks before sending a request; callers can run them earlier.

type RecordingURLOptions added in v2.19.1 

type RecordingURLOptions struct {
	// Recording is "audio" (Ogg) or "chat-history" (JSON). Required.
	Recording string
}

RecordingURLOptions chooses which of a session's recordings GetSessionRecordingURL signs a URL for.

func (RecordingURLOptions) Validate added in v2.19.1 

func (o RecordingURLOptions) Validate() error

Validate reports a missing or unknown recording name. GetSessionRecordingURL makes the same check before sending a request; callers can run it earlier.

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.

type SessionListOptions added in v2.19.1 

type SessionListOptions struct {
	// Limit caps the page size; 0 lets the server choose. The server caps pages
	// at 100.
	Limit int32
	// Cursor requests a specific page; empty starts from the beginning.
	Cursor string
	// Start and End bound when a session started, as the half-open window
	// [Start, End). The server fills in a zero side: with neither set it lists
	// the last 24 hours, with only Start it lists up to now, and with only End
	// it lists the 24 hours before End.
	Start, End time.Time
	// Statuses keeps sessions in any of these states: "active" or "closed".
	Statuses []string
	// RoomPrefix keeps sessions whose room name starts with it (case-sensitive).
	RoomPrefix string
	// Tags keeps sessions carrying any of these tags.
	Tags []string
	// SortOrder orders by start time: "asc" or "desc" (the server's default).
	SortOrder string
}

SessionListOptions narrows and orders one page of ListProjectSessions. Zero values keep the server's defaults: any status, newest first, and the window described on Start and End.

func (SessionListOptions) Validate added in v2.19.1 

func (o SessionListOptions) Validate() error

Validate reports an unknown status or sort order name. ListProjectSessions makes the same check before sending a request; callers can run it earlier.

type TracePage added in v2.19.1 

type TracePage struct {
	// Spans are by start time, oldest first, ties broken by span id. Each names
	// its parent, so the pages together rebuild the span tree.
	Spans []oapi.LivekitPublicapiObservabilityV1Span
	// NextCursor is non-empty when more pages remain (pass it back as
	// PageOptions.Cursor).
	NextCursor string
}

TracePage is one page of a session's trace spans.

type TranscriptItem added in v2.19.1 

type TranscriptItem struct {
	ID string `json:"id,omitempty"`
	// Timestamp is when the item happened: for a message, when its speaker
	// started speaking.
	Timestamp    *time.Time                                                      `json:"timestamp,omitempty"`
	Message      *oapi.LivekitPublicapiObservabilityV1TranscriptItemMessage      `json:"message,omitempty"`
	ToolCall     *oapi.LivekitPublicapiObservabilityV1TranscriptItemToolCall     `json:"toolCall,omitempty"`
	ToolResult   *oapi.LivekitPublicapiObservabilityV1TranscriptItemToolResult   `json:"toolResult,omitempty"`
	AgentHandoff *oapi.LivekitPublicapiObservabilityV1TranscriptItemAgentHandoff `json:"agentHandoff,omitempty"`
	ConfigUpdate *oapi.LivekitPublicapiObservabilityV1TranscriptItemConfigUpdate `json:"configUpdate,omitempty"`
}

TranscriptItem is one entry in a session's conversation, with the variant the API sent decoded: exactly one of Message, ToolCall, ToolResult, AgentHandoff and ConfigUpdate is set, or none for a kind newer than this client. It marshals back to the API's own JSON.

type TranscriptPage added in v2.19.1 

type TranscriptPage struct {
	// Items are oldest first, in the order the agent recorded them.
	Items []TranscriptItem
	// NextCursor is non-empty when more pages remain (pass it back as
	// PageOptions.Cursor).
	NextCursor string
	// SkippedRecords counts this page's records the server couldn't read as
	// transcript items and left out.
	SkippedRecords int
}

TranscriptPage is one page of a session's transcript.

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.