openapi: 3.1.0
info:
title: LiveKit Public API
version: v0
description: Public HTTP API for LiveKit Cloud. Generated from protobuf.
paths:
/v0/project-invites/{inviteToken}:
get:
tags:
- livekit.publicapi.projects.v1.ProjectService
summary: GetInvite
operationId: ProjectService_GetInvite
parameters:
- name: inviteToken
in: path
required: true
schema:
type: string
title: invite_token
responses:
"200":
description: Success
content:
application/json:
schema:
$ref: '#/components/schemas/livekit.publicapi.projects.v1.GetInviteResponse'
/v0/project-invites/{inviteToken}:answer:
post:
tags:
- livekit.publicapi.projects.v1.ProjectService
summary: AnswerInvitation
operationId: ProjectService_AnswerInvitation
parameters:
- name: inviteToken
in: path
required: true
schema:
type: string
title: invite_token
requestBody:
content:
application/json:
schema:
type: object
properties:
accept:
type: boolean
title: accept
title: AnswerInvitationRequest
additionalProperties: false
required: true
responses:
"200":
description: Success
content:
application/json:
schema:
$ref: '#/components/schemas/livekit.publicapi.projects.v1.AnswerInvitationResponse'
/v0/projects:
get:
tags:
- livekit.publicapi.projects.v1.ProjectService
summary: ListProjects
operationId: ProjectService_ListProjects
parameters:
- name: page.cursor
in: query
description: |-
Opaque cursor returned by a prior page (PageInfo.next_cursor). Empty starts
from the beginning.
schema:
type: string
title: cursor
- name: page.pageSize
in: query
description: Maximum items to return; 0 lets the server pick a default.
schema:
type: integer
title: page_size
format: int32
- name: workspaceId
in: query
description: |-
Mutually exclusive: only one of workspace_id or member_id can be set
if workspace_id is set, list projects for the workspace
schema:
type: string
title: workspace_id
- name: memberId
in: query
description: if member_id is set, list projects for the member
schema:
type: string
title: member_id
responses:
"200":
description: Success
content:
application/json:
schema:
$ref: '#/components/schemas/livekit.publicapi.projects.v1.ListProjectsResponse'
post:
tags:
- livekit.publicapi.projects.v1.ProjectService
summary: CreateProject
operationId: ProjectService_CreateProject
requestBody:
content:
application/json:
schema:
$ref: '#/components/schemas/livekit.publicapi.projects.v1.CreateProjectRequest'
required: true
responses:
"200":
description: Success
content:
application/json:
schema:
$ref: '#/components/schemas/livekit.publicapi.projects.v1.CreateProjectResponse'
/v0/projects/{projectId}:
get:
tags:
- livekit.publicapi.projects.v1.ProjectService
summary: GetProject
operationId: ProjectService_GetProject
parameters:
- name: projectId
in: path
required: true
schema:
type: string
title: project_id
responses:
"200":
description: Success
content:
application/json:
schema:
$ref: '#/components/schemas/livekit.publicapi.projects.v1.GetProjectResponse'
delete:
tags:
- livekit.publicapi.projects.v1.ProjectService
summary: DeleteProject
operationId: ProjectService_DeleteProject
parameters:
- name: projectId
in: path
required: true
schema:
type: string
title: project_id
responses:
"200":
description: Success
content:
application/json:
schema:
$ref: '#/components/schemas/livekit.publicapi.projects.v1.DeleteProjectResponse'
patch:
tags:
- livekit.publicapi.projects.v1.ProjectService
summary: UpdateProject
operationId: ProjectService_UpdateProject
parameters:
- name: projectId
in: path
required: true
schema:
type: string
title: project_id
requestBody:
content:
application/json:
schema:
type: object
properties:
name:
type:
- string
- "null"
title: name
subdomain:
type:
- string
- "null"
title: subdomain
customDomain:
type:
- string
- "null"
title: custom_domain
enableAnalytics:
type:
- boolean
- "null"
title: enable_analytics
enableAutoCreate:
type:
- boolean
- "null"
title: enable_auto_create
enableRemoteUnmute:
type:
- boolean
- "null"
title: enable_remote_unmute
enabledCodecs:
type: array
items:
type: string
title: enabled_codecs
egressClusterId:
type:
- string
- "null"
title: egress_cluster_id
description: LK-admin only
enableHostedAgents:
type:
- boolean
- "null"
title: enable_hosted_agents
description: LK-admin only
enableUserDataRecording:
type:
- boolean
- "null"
title: enable_user_data_recording
requireExplicitDispatch:
type:
- boolean
- "null"
title: require_explicit_dispatch
isPrivate:
type:
- boolean
- "null"
title: is_private
members:
type: array
items:
$ref: '#/components/schemas/livekit.publicapi.projects.v1.CreateProjectMember'
title: members
description: 'Used when becoming private: explicit member set (actor kept as ADMIN).'
enablePiiRedaction:
type:
- boolean
- "null"
title: enable_pii_redaction
piiRedactionCategories:
type: array
items:
$ref: '#/components/schemas/cloud_protocol.PIIRedactionCategory'
title: pii_redaction_categories
description: |-
Non-empty list replaces the stored set (validated via Canonical).
Empty is ignored (cannot clear). When enabling with nothing stored,
defaults are applied server-side — same as cloud-api UpdateProject.
enableInferenceRegionRestriction:
type:
- boolean
- "null"
title: enable_inference_region_restriction
hideOnboarding:
type:
- boolean
- "null"
title: hide_onboarding
description: Preferences (flat, matching cloud-api UpdateProjectRequest).
discoverableByDomain:
type:
- boolean
- "null"
title: discoverable_by_domain
joinableByDomain:
type:
- boolean
- "null"
title: joinable_by_domain
hideSampleAppGallery:
type:
- boolean
- "null"
title: hide_sample_app_gallery
disableTokenEndpoint:
type:
- boolean
- "null"
title: disable_token_endpoint
tokenEndpointKey:
type:
- string
- "null"
title: token_endpoint_key
sfuAllowPause:
type:
- boolean
- "null"
title: sfu_allow_pause
enableEgressBackupStorage:
type:
- boolean
- "null"
title: enable_egress_backup_storage
enableEgressAutoRetry:
type:
- boolean
- "null"
title: enable_egress_auto_retry
featureFlags:
type: object
title: feature_flags
additionalProperties:
type: string
title: value
roomConfigsToUpsert:
type: array
items:
$ref: '#/components/schemas/livekit.RoomConfiguration'
title: room_configs_to_upsert
description: RoomConfiguration management (stored on project preferences).
roomConfigsToDelete:
type: array
items:
type: string
title: room_configs_to_delete
pinnedRegions:
title: pinned_regions
description: |-
SFU/datacenter region pins. Unset leaves them unchanged; a set message
replaces the stored set, so an empty regions list clears the pins (same
shape as cloud AdminPinnedRegions). Distinct from user_data_region.
$ref: '#/components/schemas/livekit.publicapi.projects.v1.PinnedRegions'
title: UpdateProjectRequest
additionalProperties: false
description: |-
UpdateProjectRequest patches a project. Unset optional fields are left
unchanged (proto3 optional). Mirrors cloud-api UpdateProject for local mode;
webhooks are separate RPCs (not included here).
required: true
responses:
"200":
description: Success
content:
application/json:
schema:
$ref: '#/components/schemas/livekit.publicapi.projects.v1.UpdateProjectResponse'
/v0/projects/{projectId}/analytics:
get:
tags:
- livekit.publicapi.analytics.v1.AnalyticsService
summary: GetProjectAnalytics
description: GetProjectAnalytics returns the project overview over a time range.
operationId: AnalyticsService_GetProjectAnalytics
parameters:
- name: projectId
in: path
required: true
schema:
type: string
title: project_id
- name: range.startTime
in: query
description: |-
A Timestamp represents a point in time independent of any time zone or local
calendar, encoded as a count of seconds and fractions of seconds at
nanosecond resolution. The count is relative to an epoch at UTC midnight on
January 1, 1970, in the proleptic Gregorian calendar which extends the
Gregorian calendar backwards to year one.
All minutes are 60 seconds long. Leap seconds are "smeared" so that no leap
second table is needed for interpretation, using a [24-hour linear
smear](https://developers.google.com/time/smear).
The range is from 0001-01-01T00:00:00Z to 9999-12-31T23:59:59.999999999Z. By
restricting to that range, we ensure that we can convert to and from [RFC
3339](https://www.ietf.org/rfc/rfc3339.txt) date strings.
# Examples
Example 1: Compute Timestamp from POSIX `time()`.
Timestamp timestamp;
timestamp.set_seconds(time(NULL));
timestamp.set_nanos(0);
Example 2: Compute Timestamp from POSIX `gettimeofday()`.
struct timeval tv;
gettimeofday(&tv, NULL);
Timestamp timestamp;
timestamp.set_seconds(tv.tv_sec);
timestamp.set_nanos(tv.tv_usec * 1000);
Example 3: Compute Timestamp from Win32 `GetSystemTimeAsFileTime()`.
FILETIME ft;
GetSystemTimeAsFileTime(&ft);
UINT64 ticks = (((UINT64)ft.dwHighDateTime) << 32) | ft.dwLowDateTime;
// A Windows tick is 100 nanoseconds. Windows epoch 1601-01-01T00:00:00Z
// is 11644473600 seconds before Unix epoch 1970-01-01T00:00:00Z.
Timestamp timestamp;
timestamp.set_seconds((INT64) ((ticks / 10000000) - 11644473600LL));
timestamp.set_nanos((INT32) ((ticks % 10000000) * 100));
Example 4: Compute Timestamp from Java `System.currentTimeMillis()`.
long millis = System.currentTimeMillis();
Timestamp timestamp = Timestamp.newBuilder().setSeconds(millis / 1000)
.setNanos((int) ((millis % 1000) * 1000000)).build();
Example 5: Compute Timestamp from Java `Instant.now()`.
Instant now = Instant.now();
Timestamp timestamp =
Timestamp.newBuilder().setSeconds(now.getEpochSecond())
.setNanos(now.getNano()).build();
Example 6: Compute Timestamp from current time in Python.
timestamp = Timestamp()
timestamp.GetCurrentTime()
# JSON Mapping
In JSON format, the Timestamp type is encoded as a string in the
[RFC 3339](https://www.ietf.org/rfc/rfc3339.txt) format. That is, the
format is "{year}-{month}-{day}T{hour}:{min}:{sec}[.{frac_sec}]Z"
where {year} is always expressed using four digits while {month}, {day},
{hour}, {min}, and {sec} are zero-padded to two digits each. The fractional
seconds, which can go up to 9 digits (i.e. up to 1 nanosecond resolution),
are optional. The "Z" suffix indicates the timezone ("UTC"); the timezone
is required. A ProtoJSON serializer should always use UTC (as indicated by
"Z") when printing the Timestamp type and a ProtoJSON parser should be
able to accept both UTC and other timezones (as indicated by an offset).
For example, "2017-01-15T01:30:15.01Z" encodes 15.01 seconds past
01:30 UTC on January 15, 2017.
In JavaScript, one can convert a Date object to this format using the
standard
[toISOString()](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Date/toISOString)
method. In Python, a standard `datetime.datetime` object can be converted
to this format using
[`strftime`](https://docs.python.org/2/library/time.html#time.strftime) with
the time format spec '%Y-%m-%dT%H:%M:%S.%fZ'. Likewise, in Java, one can use
the Joda Time's [`ISODateTimeFormat.dateTime()`](
http://joda-time.sourceforge.net/apidocs/org/joda/time/format/ISODateTimeFormat.html#dateTime()
) to obtain a formatter capable of generating timestamps in this format.
schema:
type: string
examples:
- "2023-01-15T01:30:15.01Z"
- "2024-12-25T12:00:00Z"
format: date-time
- name: range.endTime
in: query
description: |-
A Timestamp represents a point in time independent of any time zone or local
calendar, encoded as a count of seconds and fractions of seconds at
nanosecond resolution. The count is relative to an epoch at UTC midnight on
January 1, 1970, in the proleptic Gregorian calendar which extends the
Gregorian calendar backwards to year one.
All minutes are 60 seconds long. Leap seconds are "smeared" so that no leap
second table is needed for interpretation, using a [24-hour linear
smear](https://developers.google.com/time/smear).
The range is from 0001-01-01T00:00:00Z to 9999-12-31T23:59:59.999999999Z. By
restricting to that range, we ensure that we can convert to and from [RFC
3339](https://www.ietf.org/rfc/rfc3339.txt) date strings.
# Examples
Example 1: Compute Timestamp from POSIX `time()`.
Timestamp timestamp;
timestamp.set_seconds(time(NULL));
timestamp.set_nanos(0);
Example 2: Compute Timestamp from POSIX `gettimeofday()`.
struct timeval tv;
gettimeofday(&tv, NULL);
Timestamp timestamp;
timestamp.set_seconds(tv.tv_sec);
timestamp.set_nanos(tv.tv_usec * 1000);
Example 3: Compute Timestamp from Win32 `GetSystemTimeAsFileTime()`.
FILETIME ft;
GetSystemTimeAsFileTime(&ft);
UINT64 ticks = (((UINT64)ft.dwHighDateTime) << 32) | ft.dwLowDateTime;
// A Windows tick is 100 nanoseconds. Windows epoch 1601-01-01T00:00:00Z
// is 11644473600 seconds before Unix epoch 1970-01-01T00:00:00Z.
Timestamp timestamp;
timestamp.set_seconds((INT64) ((ticks / 10000000) - 11644473600LL));
timestamp.set_nanos((INT32) ((ticks % 10000000) * 100));
Example 4: Compute Timestamp from Java `System.currentTimeMillis()`.
long millis = System.currentTimeMillis();
Timestamp timestamp = Timestamp.newBuilder().setSeconds(millis / 1000)
.setNanos((int) ((millis % 1000) * 1000000)).build();
Example 5: Compute Timestamp from Java `Instant.now()`.
Instant now = Instant.now();
Timestamp timestamp =
Timestamp.newBuilder().setSeconds(now.getEpochSecond())
.setNanos(now.getNano()).build();
Example 6: Compute Timestamp from current time in Python.
timestamp = Timestamp()
timestamp.GetCurrentTime()
# JSON Mapping
In JSON format, the Timestamp type is encoded as a string in the
[RFC 3339](https://www.ietf.org/rfc/rfc3339.txt) format. That is, the
format is "{year}-{month}-{day}T{hour}:{min}:{sec}[.{frac_sec}]Z"
where {year} is always expressed using four digits while {month}, {day},
{hour}, {min}, and {sec} are zero-padded to two digits each. The fractional
seconds, which can go up to 9 digits (i.e. up to 1 nanosecond resolution),
are optional. The "Z" suffix indicates the timezone ("UTC"); the timezone
is required. A ProtoJSON serializer should always use UTC (as indicated by
"Z") when printing the Timestamp type and a ProtoJSON parser should be
able to accept both UTC and other timezones (as indicated by an offset).
For example, "2017-01-15T01:30:15.01Z" encodes 15.01 seconds past
01:30 UTC on January 15, 2017.
In JavaScript, one can convert a Date object to this format using the
standard
[toISOString()](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Date/toISOString)
method. In Python, a standard `datetime.datetime` object can be converted
to this format using
[`strftime`](https://docs.python.org/2/library/time.html#time.strftime) with
the time format spec '%Y-%m-%dT%H:%M:%S.%fZ'. Likewise, in Java, one can use
the Joda Time's [`ISODateTimeFormat.dateTime()`](
http://joda-time.sourceforge.net/apidocs/org/joda/time/format/ISODateTimeFormat.html#dateTime()
) to obtain a formatter capable of generating timestamps in this format.
schema:
type: string
examples:
- "2023-01-15T01:30:15.01Z"
- "2024-12-25T12:00:00Z"
format: date-time
responses:
"200":
description: Success
content:
application/json:
schema:
$ref: '#/components/schemas/livekit.publicapi.analytics.v1.ProjectOverview.Get.Response'
/v0/projects/{projectId}/analytics/agents:
get:
tags:
- livekit.publicapi.analytics.v1.AnalyticsService
summary: ListAgentAnalytics
description: |-
ListAgentAnalytics returns the same per-agent analytics for every agent in
the project, one AgentAnalytics row per agent — so a single agent and the
whole roster share one shape.
operationId: AnalyticsService_ListAgentAnalytics
parameters:
- name: projectId
in: path
required: true
schema:
type: string
title: project_id
- name: range.startTime
in: query
description: |-
A Timestamp represents a point in time independent of any time zone or local
calendar, encoded as a count of seconds and fractions of seconds at
nanosecond resolution. The count is relative to an epoch at UTC midnight on
January 1, 1970, in the proleptic Gregorian calendar which extends the
Gregorian calendar backwards to year one.
All minutes are 60 seconds long. Leap seconds are "smeared" so that no leap
second table is needed for interpretation, using a [24-hour linear
smear](https://developers.google.com/time/smear).
The range is from 0001-01-01T00:00:00Z to 9999-12-31T23:59:59.999999999Z. By
restricting to that range, we ensure that we can convert to and from [RFC
3339](https://www.ietf.org/rfc/rfc3339.txt) date strings.
# Examples
Example 1: Compute Timestamp from POSIX `time()`.
Timestamp timestamp;
timestamp.set_seconds(time(NULL));
timestamp.set_nanos(0);
Example 2: Compute Timestamp from POSIX `gettimeofday()`.
struct timeval tv;
gettimeofday(&tv, NULL);
Timestamp timestamp;
timestamp.set_seconds(tv.tv_sec);
timestamp.set_nanos(tv.tv_usec * 1000);
Example 3: Compute Timestamp from Win32 `GetSystemTimeAsFileTime()`.
FILETIME ft;
GetSystemTimeAsFileTime(&ft);
UINT64 ticks = (((UINT64)ft.dwHighDateTime) << 32) | ft.dwLowDateTime;
// A Windows tick is 100 nanoseconds. Windows epoch 1601-01-01T00:00:00Z
// is 11644473600 seconds before Unix epoch 1970-01-01T00:00:00Z.
Timestamp timestamp;
timestamp.set_seconds((INT64) ((ticks / 10000000) - 11644473600LL));
timestamp.set_nanos((INT32) ((ticks % 10000000) * 100));
Example 4: Compute Timestamp from Java `System.currentTimeMillis()`.
long millis = System.currentTimeMillis();
Timestamp timestamp = Timestamp.newBuilder().setSeconds(millis / 1000)
.setNanos((int) ((millis % 1000) * 1000000)).build();
Example 5: Compute Timestamp from Java `Instant.now()`.
Instant now = Instant.now();
Timestamp timestamp =
Timestamp.newBuilder().setSeconds(now.getEpochSecond())
.setNanos(now.getNano()).build();
Example 6: Compute Timestamp from current time in Python.
timestamp = Timestamp()
timestamp.GetCurrentTime()
# JSON Mapping
In JSON format, the Timestamp type is encoded as a string in the
[RFC 3339](https://www.ietf.org/rfc/rfc3339.txt) format. That is, the
format is "{year}-{month}-{day}T{hour}:{min}:{sec}[.{frac_sec}]Z"
where {year} is always expressed using four digits while {month}, {day},
{hour}, {min}, and {sec} are zero-padded to two digits each. The fractional
seconds, which can go up to 9 digits (i.e. up to 1 nanosecond resolution),
are optional. The "Z" suffix indicates the timezone ("UTC"); the timezone
is required. A ProtoJSON serializer should always use UTC (as indicated by
"Z") when printing the Timestamp type and a ProtoJSON parser should be
able to accept both UTC and other timezones (as indicated by an offset).
For example, "2017-01-15T01:30:15.01Z" encodes 15.01 seconds past
01:30 UTC on January 15, 2017.
In JavaScript, one can convert a Date object to this format using the
standard
[toISOString()](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Date/toISOString)
method. In Python, a standard `datetime.datetime` object can be converted
to this format using
[`strftime`](https://docs.python.org/2/library/time.html#time.strftime) with
the time format spec '%Y-%m-%dT%H:%M:%S.%fZ'. Likewise, in Java, one can use
the Joda Time's [`ISODateTimeFormat.dateTime()`](
http://joda-time.sourceforge.net/apidocs/org/joda/time/format/ISODateTimeFormat.html#dateTime()
) to obtain a formatter capable of generating timestamps in this format.
schema:
type: string
examples:
- "2023-01-15T01:30:15.01Z"
- "2024-12-25T12:00:00Z"
format: date-time
- name: range.endTime
in: query
description: |-
A Timestamp represents a point in time independent of any time zone or local
calendar, encoded as a count of seconds and fractions of seconds at
nanosecond resolution. The count is relative to an epoch at UTC midnight on
January 1, 1970, in the proleptic Gregorian calendar which extends the
Gregorian calendar backwards to year one.
All minutes are 60 seconds long. Leap seconds are "smeared" so that no leap
second table is needed for interpretation, using a [24-hour linear
smear](https://developers.google.com/time/smear).
The range is from 0001-01-01T00:00:00Z to 9999-12-31T23:59:59.999999999Z. By
restricting to that range, we ensure that we can convert to and from [RFC
3339](https://www.ietf.org/rfc/rfc3339.txt) date strings.
# Examples
Example 1: Compute Timestamp from POSIX `time()`.
Timestamp timestamp;
timestamp.set_seconds(time(NULL));
timestamp.set_nanos(0);
Example 2: Compute Timestamp from POSIX `gettimeofday()`.
struct timeval tv;
gettimeofday(&tv, NULL);
Timestamp timestamp;
timestamp.set_seconds(tv.tv_sec);
timestamp.set_nanos(tv.tv_usec * 1000);
Example 3: Compute Timestamp from Win32 `GetSystemTimeAsFileTime()`.
FILETIME ft;
GetSystemTimeAsFileTime(&ft);
UINT64 ticks = (((UINT64)ft.dwHighDateTime) << 32) | ft.dwLowDateTime;
// A Windows tick is 100 nanoseconds. Windows epoch 1601-01-01T00:00:00Z
// is 11644473600 seconds before Unix epoch 1970-01-01T00:00:00Z.
Timestamp timestamp;
timestamp.set_seconds((INT64) ((ticks / 10000000) - 11644473600LL));
timestamp.set_nanos((INT32) ((ticks % 10000000) * 100));
Example 4: Compute Timestamp from Java `System.currentTimeMillis()`.
long millis = System.currentTimeMillis();
Timestamp timestamp = Timestamp.newBuilder().setSeconds(millis / 1000)
.setNanos((int) ((millis % 1000) * 1000000)).build();
Example 5: Compute Timestamp from Java `Instant.now()`.
Instant now = Instant.now();
Timestamp timestamp =
Timestamp.newBuilder().setSeconds(now.getEpochSecond())
.setNanos(now.getNano()).build();
Example 6: Compute Timestamp from current time in Python.
timestamp = Timestamp()
timestamp.GetCurrentTime()
# JSON Mapping
In JSON format, the Timestamp type is encoded as a string in the
[RFC 3339](https://www.ietf.org/rfc/rfc3339.txt) format. That is, the
format is "{year}-{month}-{day}T{hour}:{min}:{sec}[.{frac_sec}]Z"
where {year} is always expressed using four digits while {month}, {day},
{hour}, {min}, and {sec} are zero-padded to two digits each. The fractional
seconds, which can go up to 9 digits (i.e. up to 1 nanosecond resolution),
are optional. The "Z" suffix indicates the timezone ("UTC"); the timezone
is required. A ProtoJSON serializer should always use UTC (as indicated by
"Z") when printing the Timestamp type and a ProtoJSON parser should be
able to accept both UTC and other timezones (as indicated by an offset).
For example, "2017-01-15T01:30:15.01Z" encodes 15.01 seconds past
01:30 UTC on January 15, 2017.
In JavaScript, one can convert a Date object to this format using the
standard
[toISOString()](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Date/toISOString)
method. In Python, a standard `datetime.datetime` object can be converted
to this format using
[`strftime`](https://docs.python.org/2/library/time.html#time.strftime) with
the time format spec '%Y-%m-%dT%H:%M:%S.%fZ'. Likewise, in Java, one can use
the Joda Time's [`ISODateTimeFormat.dateTime()`](
http://joda-time.sourceforge.net/apidocs/org/joda/time/format/ISODateTimeFormat.html#dateTime()
) to obtain a formatter capable of generating timestamps in this format.
schema:
type: string
examples:
- "2023-01-15T01:30:15.01Z"
- "2024-12-25T12:00:00Z"
format: date-time
- name: page.cursor
in: query
description: |-
Opaque cursor returned by a prior page (PageInfo.next_cursor). Empty starts
from the beginning.
schema:
type: string
title: cursor
- name: page.pageSize
in: query
description: Maximum items to return; 0 lets the server pick a default.
schema:
type: integer
title: page_size
format: int32
responses:
"200":
description: Success
content:
application/json:
schema:
$ref: '#/components/schemas/livekit.publicapi.analytics.v1.Agents.List.Response'
/v0/projects/{projectId}/analytics/agents/{agentId}:
get:
tags:
- livekit.publicapi.analytics.v1.AnalyticsService
summary: GetAgentAnalytics
description: GetAgentAnalytics returns the analytics for one agent over a time range.
operationId: AnalyticsService_GetAgentAnalytics
parameters:
- name: projectId
in: path
required: true
schema:
type: string
title: project_id
- name: agentId
in: path
required: true
schema:
type: string
title: agent_id
- name: range.startTime
in: query
description: |-
A Timestamp represents a point in time independent of any time zone or local
calendar, encoded as a count of seconds and fractions of seconds at
nanosecond resolution. The count is relative to an epoch at UTC midnight on
January 1, 1970, in the proleptic Gregorian calendar which extends the
Gregorian calendar backwards to year one.
All minutes are 60 seconds long. Leap seconds are "smeared" so that no leap
second table is needed for interpretation, using a [24-hour linear
smear](https://developers.google.com/time/smear).
The range is from 0001-01-01T00:00:00Z to 9999-12-31T23:59:59.999999999Z. By
restricting to that range, we ensure that we can convert to and from [RFC
3339](https://www.ietf.org/rfc/rfc3339.txt) date strings.
# Examples
Example 1: Compute Timestamp from POSIX `time()`.
Timestamp timestamp;
timestamp.set_seconds(time(NULL));
timestamp.set_nanos(0);
Example 2: Compute Timestamp from POSIX `gettimeofday()`.
struct timeval tv;
gettimeofday(&tv, NULL);
Timestamp timestamp;
timestamp.set_seconds(tv.tv_sec);
timestamp.set_nanos(tv.tv_usec * 1000);
Example 3: Compute Timestamp from Win32 `GetSystemTimeAsFileTime()`.
FILETIME ft;
GetSystemTimeAsFileTime(&ft);
UINT64 ticks = (((UINT64)ft.dwHighDateTime) << 32) | ft.dwLowDateTime;
// A Windows tick is 100 nanoseconds. Windows epoch 1601-01-01T00:00:00Z
// is 11644473600 seconds before Unix epoch 1970-01-01T00:00:00Z.
Timestamp timestamp;
timestamp.set_seconds((INT64) ((ticks / 10000000) - 11644473600LL));
timestamp.set_nanos((INT32) ((ticks % 10000000) * 100));
Example 4: Compute Timestamp from Java `System.currentTimeMillis()`.
long millis = System.currentTimeMillis();
Timestamp timestamp = Timestamp.newBuilder().setSeconds(millis / 1000)
.setNanos((int) ((millis % 1000) * 1000000)).build();
Example 5: Compute Timestamp from Java `Instant.now()`.
Instant now = Instant.now();
Timestamp timestamp =
Timestamp.newBuilder().setSeconds(now.getEpochSecond())
.setNanos(now.getNano()).build();
Example 6: Compute Timestamp from current time in Python.
timestamp = Timestamp()
timestamp.GetCurrentTime()
# JSON Mapping
In JSON format, the Timestamp type is encoded as a string in the
[RFC 3339](https://www.ietf.org/rfc/rfc3339.txt) format. That is, the
format is "{year}-{month}-{day}T{hour}:{min}:{sec}[.{frac_sec}]Z"
where {year} is always expressed using four digits while {month}, {day},
{hour}, {min}, and {sec} are zero-padded to two digits each. The fractional
seconds, which can go up to 9 digits (i.e. up to 1 nanosecond resolution),
are optional. The "Z" suffix indicates the timezone ("UTC"); the timezone
is required. A ProtoJSON serializer should always use UTC (as indicated by
"Z") when printing the Timestamp type and a ProtoJSON parser should be
able to accept both UTC and other timezones (as indicated by an offset).
For example, "2017-01-15T01:30:15.01Z" encodes 15.01 seconds past
01:30 UTC on January 15, 2017.
In JavaScript, one can convert a Date object to this format using the
standard
[toISOString()](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Date/toISOString)
method. In Python, a standard `datetime.datetime` object can be converted
to this format using
[`strftime`](https://docs.python.org/2/library/time.html#time.strftime) with
the time format spec '%Y-%m-%dT%H:%M:%S.%fZ'. Likewise, in Java, one can use
the Joda Time's [`ISODateTimeFormat.dateTime()`](
http://joda-time.sourceforge.net/apidocs/org/joda/time/format/ISODateTimeFormat.html#dateTime()
) to obtain a formatter capable of generating timestamps in this format.
schema:
type: string
examples:
- "2023-01-15T01:30:15.01Z"
- "2024-12-25T12:00:00Z"
format: date-time
- name: range.endTime
in: query
description: |-
A Timestamp represents a point in time independent of any time zone or local
calendar, encoded as a count of seconds and fractions of seconds at
nanosecond resolution. The count is relative to an epoch at UTC midnight on
January 1, 1970, in the proleptic Gregorian calendar which extends the
Gregorian calendar backwards to year one.
All minutes are 60 seconds long. Leap seconds are "smeared" so that no leap
second table is needed for interpretation, using a [24-hour linear
smear](https://developers.google.com/time/smear).
The range is from 0001-01-01T00:00:00Z to 9999-12-31T23:59:59.999999999Z. By
restricting to that range, we ensure that we can convert to and from [RFC
3339](https://www.ietf.org/rfc/rfc3339.txt) date strings.
# Examples
Example 1: Compute Timestamp from POSIX `time()`.
Timestamp timestamp;
timestamp.set_seconds(time(NULL));
timestamp.set_nanos(0);
Example 2: Compute Timestamp from POSIX `gettimeofday()`.
struct timeval tv;
gettimeofday(&tv, NULL);
Timestamp timestamp;
timestamp.set_seconds(tv.tv_sec);
timestamp.set_nanos(tv.tv_usec * 1000);
Example 3: Compute Timestamp from Win32 `GetSystemTimeAsFileTime()`.
FILETIME ft;
GetSystemTimeAsFileTime(&ft);
UINT64 ticks = (((UINT64)ft.dwHighDateTime) << 32) | ft.dwLowDateTime;
// A Windows tick is 100 nanoseconds. Windows epoch 1601-01-01T00:00:00Z
// is 11644473600 seconds before Unix epoch 1970-01-01T00:00:00Z.
Timestamp timestamp;
timestamp.set_seconds((INT64) ((ticks / 10000000) - 11644473600LL));
timestamp.set_nanos((INT32) ((ticks % 10000000) * 100));
Example 4: Compute Timestamp from Java `System.currentTimeMillis()`.
long millis = System.currentTimeMillis();
Timestamp timestamp = Timestamp.newBuilder().setSeconds(millis / 1000)
.setNanos((int) ((millis % 1000) * 1000000)).build();
Example 5: Compute Timestamp from Java `Instant.now()`.
Instant now = Instant.now();
Timestamp timestamp =
Timestamp.newBuilder().setSeconds(now.getEpochSecond())
.setNanos(now.getNano()).build();
Example 6: Compute Timestamp from current time in Python.
timestamp = Timestamp()
timestamp.GetCurrentTime()
# JSON Mapping
In JSON format, the Timestamp type is encoded as a string in the
[RFC 3339](https://www.ietf.org/rfc/rfc3339.txt) format. That is, the
format is "{year}-{month}-{day}T{hour}:{min}:{sec}[.{frac_sec}]Z"
where {year} is always expressed using four digits while {month}, {day},
{hour}, {min}, and {sec} are zero-padded to two digits each. The fractional
seconds, which can go up to 9 digits (i.e. up to 1 nanosecond resolution),
are optional. The "Z" suffix indicates the timezone ("UTC"); the timezone
is required. A ProtoJSON serializer should always use UTC (as indicated by
"Z") when printing the Timestamp type and a ProtoJSON parser should be
able to accept both UTC and other timezones (as indicated by an offset).
For example, "2017-01-15T01:30:15.01Z" encodes 15.01 seconds past
01:30 UTC on January 15, 2017.
In JavaScript, one can convert a Date object to this format using the
standard
[toISOString()](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Date/toISOString)
method. In Python, a standard `datetime.datetime` object can be converted
to this format using
[`strftime`](https://docs.python.org/2/library/time.html#time.strftime) with
the time format spec '%Y-%m-%dT%H:%M:%S.%fZ'. Likewise, in Java, one can use
the Joda Time's [`ISODateTimeFormat.dateTime()`](
http://joda-time.sourceforge.net/apidocs/org/joda/time/format/ISODateTimeFormat.html#dateTime()
) to obtain a formatter capable of generating timestamps in this format.
schema:
type: string
examples:
- "2023-01-15T01:30:15.01Z"
- "2024-12-25T12:00:00Z"
format: date-time
responses:
"200":
description: Success
content:
application/json:
schema:
$ref: '#/components/schemas/livekit.publicapi.analytics.v1.Agents.Get.Response'
/v0/projects/{projectId}/databases:
get:
tags:
- livekit.publicapi.databases.v1.DatabaseService
summary: ListDatabases
description: ListDatabases lists the project's databases, cursor-paginated.
operationId: DatabaseService_ListDatabases
parameters:
- name: projectId
in: path
required: true
schema:
type: string
title: project_id
- name: page.cursor
in: query
description: |-
Opaque cursor returned by a prior page (PageInfo.next_cursor). Empty starts
from the beginning.
schema:
type: string
title: cursor
- name: page.pageSize
in: query
description: Maximum items to return; 0 lets the server pick a default.
schema:
type: integer
title: page_size
format: int32
responses:
"200":
description: Success
content:
application/json:
schema:
$ref: '#/components/schemas/livekit.publicapi.databases.v1.Databases.List.Response'
post:
tags:
- livekit.publicapi.databases.v1.DatabaseService
summary: CreateDatabase
description: |-
CreateDatabase creates an empty database. Not idempotent: a retried
request creates a second database.
operationId: DatabaseService_CreateDatabase
parameters:
- name: projectId
in: path
required: true
schema:
type: string
title: project_id
requestBody:
content:
application/json:
schema:
type: object
properties:
ttl:
title: ttl
description: |-
Unset: never expires. Otherwise clamped to the server cap, and never
extended.
$ref: '#/components/schemas/google.protobuf.Duration'
title: Request
additionalProperties: false
required: true
responses:
"200":
description: Success
content:
application/json:
schema:
$ref: '#/components/schemas/livekit.publicapi.databases.v1.Databases.Create.Response'
/v0/projects/{projectId}/databases/{databaseId}:
get:
tags:
- livekit.publicapi.databases.v1.DatabaseService
summary: GetDatabase
operationId: DatabaseService_GetDatabase
parameters:
- name: projectId
in: path
required: true
schema:
type: string
title: project_id
- name: databaseId
in: path
required: true
schema:
type: string
title: database_id
responses:
"200":
description: Success
content:
application/json:
schema:
$ref: '#/components/schemas/livekit.publicapi.databases.v1.Databases.Get.Response'
delete:
tags:
- livekit.publicapi.databases.v1.DatabaseService
summary: DeleteDatabase
description: DeleteDatabase deletes the stored data, not just the metadata.
operationId: DatabaseService_DeleteDatabase
parameters:
- name: projectId
in: path
required: true
schema:
type: string
title: project_id
- name: databaseId
in: path
required: true
schema:
type: string
title: database_id
responses:
"200":
description: Success
content:
application/json:
schema:
$ref: '#/components/schemas/livekit.publicapi.databases.v1.Databases.Delete.Response'
/v0/projects/{projectId}/databases/{databaseId}:export:
post:
tags:
- livekit.publicapi.databases.v1.DatabaseService
summary: ExportDatabase
description: |-
ExportDatabase exports a consistent SQLite file as a time-limited download
URL.
operationId: DatabaseService_ExportDatabase
parameters:
- name: projectId
in: path
required: true
schema:
type: string
title: project_id
- name: databaseId
in: path
required: true
schema:
type: string
title: database_id
responses:
"200":
description: Success
content:
application/json:
schema:
$ref: '#/components/schemas/livekit.publicapi.databases.v1.Databases.Export.Response'
/v0/projects/{projectId}/invites:
get:
tags:
- livekit.publicapi.projects.v1.ProjectService
summary: ListInvites
operationId: ProjectService_ListInvites
parameters:
- name: projectId
in: path
required: true
schema:
type: string
title: project_id
responses:
"200":
description: Success
content:
application/json:
schema:
$ref: '#/components/schemas/livekit.publicapi.projects.v1.ListInvitesResponse'
post:
tags:
- livekit.publicapi.projects.v1.ProjectService
summary: InviteMember
operationId: ProjectService_InviteMember
parameters:
- name: projectId
in: path
required: true
schema:
type: string
title: project_id
requestBody:
content:
application/json:
schema:
type: object
properties:
email:
type: string
title: email
role:
type: integer
title: role
format: int32
title: InviteMemberRequest
additionalProperties: false
description: InviteMember creates or refreshes a token invite (cloud InviteMember2).
required: true
responses:
"200":
description: Success
content:
application/json:
schema:
$ref: '#/components/schemas/livekit.publicapi.projects.v1.InviteMemberResponse'
/v0/projects/{projectId}/invites/{email}:
delete:
tags:
- livekit.publicapi.projects.v1.ProjectService
summary: DeleteInvite
operationId: ProjectService_DeleteInvite
parameters:
- name: projectId
in: path
required: true
schema:
type: string
title: project_id
- name: email
in: path
required: true
schema:
type: string
title: email
responses:
"200":
description: Success
content:
application/json:
schema:
$ref: '#/components/schemas/livekit.publicapi.projects.v1.DeleteInviteResponse'
patch:
tags:
- livekit.publicapi.projects.v1.ProjectService
summary: UpdateInvite
operationId: ProjectService_UpdateInvite
parameters:
- name: projectId
in: path
required: true
schema:
type: string
title: project_id
- name: email
in: path
required: true
schema:
type: string
title: email
requestBody:
content:
application/json:
schema:
type: object
properties:
role:
type: integer
title: role
format: int32
title: UpdateInviteRequest
additionalProperties: false
required: true
responses:
"200":
description: Success
content:
application/json:
schema:
$ref: '#/components/schemas/livekit.publicapi.projects.v1.UpdateInviteResponse'
/v0/projects/{projectId}/keys:
get:
tags:
- livekit.publicapi.projects.v1.ProjectService
summary: ListKeys
operationId: ProjectService_ListKeys
parameters:
- name: projectId
in: path
required: true
schema:
type: string
title: project_id
- name: includeAgentKeys
in: query
description: Agent keys are hidden by default, matching cloud-api-server.
schema:
type: boolean
title: include_agent_keys
responses:
"200":
description: Success
content:
application/json:
schema:
$ref: '#/components/schemas/livekit.publicapi.projects.v1.ListKeysResponse'
post:
tags:
- livekit.publicapi.projects.v1.ProjectService
summary: GenerateKey
description: |-
Access keys (mirrors cloud ProjectService GenerateKey / ListKeys /
ListScopedKeys / DeleteKey).
operationId: ProjectService_GenerateKey
parameters:
- name: projectId
in: path
required: true
schema:
type: string
title: project_id
requestBody:
content:
application/json:
schema:
type: object
properties:
description:
type: string
title: description
isServiceAccount:
type:
- boolean
- "null"
title: is_service_account
description: |-
When true, the key is created without an owner (project-owned). It is not
listed as anyone's personal key and survives the generating user leaving.
title: GenerateKeyRequest
additionalProperties: false
required: true
responses:
"200":
description: Success
content:
application/json:
schema:
$ref: '#/components/schemas/livekit.publicapi.projects.v1.GenerateKeyResponse'
/v0/projects/{projectId}/keys/{apiKey}:
delete:
tags:
- livekit.publicapi.projects.v1.ProjectService
summary: DeleteKey
operationId: ProjectService_DeleteKey
parameters:
- name: projectId
in: path
required: true
schema:
type: string
title: project_id
- name: apiKey
in: path
required: true
schema:
type: string
title: api_key
responses:
"200":
description: Success
content:
application/json:
schema:
$ref: '#/components/schemas/livekit.publicapi.projects.v1.DeleteKeyResponse'
/v0/projects/{projectId}/members:
get:
tags:
- livekit.publicapi.projects.v1.ProjectService
summary: ListMembers
description: Members & invites (token-based; mirrors cloud ProjectService current flows).
operationId: ProjectService_ListMembers
parameters:
- name: projectId
in: path
required: true
schema:
type: string
title: project_id
responses:
"200":
description: Success
content:
application/json:
schema:
$ref: '#/components/schemas/livekit.publicapi.projects.v1.ListMembersResponse'
/v0/projects/{projectId}/members/{userId}:
get:
tags:
- livekit.publicapi.projects.v1.ProjectService
summary: GetMember
operationId: ProjectService_GetMember
parameters:
- name: projectId
in: path
required: true
schema:
type: string
title: project_id
- name: userId
in: path
required: true
schema:
type: string
title: user_id
responses:
"200":
description: Success
content:
application/json:
schema:
$ref: '#/components/schemas/livekit.publicapi.projects.v1.GetMemberResponse'
delete:
tags:
- livekit.publicapi.projects.v1.ProjectService
summary: RemoveMember
operationId: ProjectService_RemoveMember
parameters:
- name: projectId
in: path
required: true
schema:
type: string
title: project_id
- name: userId
in: path
required: true
schema:
type: string
title: user_id
responses:
"200":
description: Success
content:
application/json:
schema:
$ref: '#/components/schemas/livekit.publicapi.projects.v1.RemoveMemberResponse'
patch:
tags:
- livekit.publicapi.projects.v1.ProjectService
summary: UpdateMember
operationId: ProjectService_UpdateMember
parameters:
- name: projectId
in: path
required: true
schema:
type: string
title: project_id
- name: userId
in: path
required: true
schema:
type: string
title: user_id
requestBody:
content:
application/json:
schema:
type: object
properties:
role:
type: integer
title: role
format: int32
title: UpdateMemberRequest
additionalProperties: false
required: true
responses:
"200":
description: Success
content:
application/json:
schema:
$ref: '#/components/schemas/livekit.publicapi.projects.v1.UpdateMemberResponse'
/v0/projects/{projectId}/members:addWorkspaceMembers:
post:
tags:
- livekit.publicapi.projects.v1.ProjectService
summary: AddWorkspaceMembersToProject
operationId: ProjectService_AddWorkspaceMembersToProject
parameters:
- name: projectId
in: path
required: true
schema:
type: string
title: project_id
requestBody:
content:
application/json:
schema:
type: object
properties:
userIds:
type: array
items:
type: string
title: user_ids
role:
type: integer
title: role
format: int32
title: AddWorkspaceMembersToProjectRequest
additionalProperties: false
required: true
responses:
"200":
description: Success
content:
application/json:
schema:
$ref: '#/components/schemas/livekit.publicapi.projects.v1.AddWorkspaceMembersToProjectResponse'
/v0/projects/{projectId}/scenarios:generateFromSession:
post:
tags:
- livekit.publicapi.simulations.v1.SimulationService
summary: GenerateScenarioFromSession
description: |-
GenerateScenarioFromSession derives a reusable scenario (label,
instructions and expectations) from a recorded room session, for use in a
later run's scenario_group. Nothing is stored; the returned scenario is the
result. The session must have a recorded chat history. Each call runs an
LLM over it, so it counts against the project's scenario-generation quota
and can take up to about a minute.
operationId: SimulationService_GenerateScenarioFromSession
parameters:
- name: projectId
in: path
required: true
schema:
type: string
title: project_id
requestBody:
content:
application/json:
schema:
type: object
properties:
roomId:
type: string
title: room_id
description: Room session (RM_...) to derive the scenario from.
region:
type: string
title: region
description: 'Unused today: the session''s recording is found by project and room.'
title: Request
additionalProperties: false
required: true
responses:
"200":
description: Success
content:
application/json:
schema:
$ref: '#/components/schemas/livekit.publicapi.simulations.v1.Scenarios.GenerateFromSession.Response'
/v0/projects/{projectId}/scoped-keys:
get:
tags:
- livekit.publicapi.projects.v1.ProjectService
summary: ListScopedKeys
operationId: ProjectService_ListScopedKeys
parameters:
- name: projectId
in: path
required: true
schema:
type: string
title: project_id
responses:
"200":
description: Success
content:
application/json:
schema:
$ref: '#/components/schemas/livekit.publicapi.projects.v1.ListScopedKeysResponse'
/v0/projects/{projectId}/sessions:
get:
tags:
- livekit.publicapi.analytics.v1.AnalyticsService
summary: ListProjectSessions
description: |-
ListProjectSessions lists room sessions for a project, newest first,
cursor-paginated. Backed upstream by the ListingService room-sessions list.
operationId: AnalyticsService_ListProjectSessions
parameters:
- name: projectId
in: path
required: true
schema:
type: string
title: project_id
- name: page.cursor
in: query
description: |-
Opaque cursor returned by a prior page (PageInfo.next_cursor). Empty starts
from the beginning.
schema:
type: string
title: cursor
- name: page.pageSize
in: query
description: Maximum items to return; 0 lets the server pick a default.
schema:
type: integer
title: page_size
format: int32
- name: filter.range.startTime
in: query
description: |-
A Timestamp represents a point in time independent of any time zone or local
calendar, encoded as a count of seconds and fractions of seconds at
nanosecond resolution. The count is relative to an epoch at UTC midnight on
January 1, 1970, in the proleptic Gregorian calendar which extends the
Gregorian calendar backwards to year one.
All minutes are 60 seconds long. Leap seconds are "smeared" so that no leap
second table is needed for interpretation, using a [24-hour linear
smear](https://developers.google.com/time/smear).
The range is from 0001-01-01T00:00:00Z to 9999-12-31T23:59:59.999999999Z. By
restricting to that range, we ensure that we can convert to and from [RFC
3339](https://www.ietf.org/rfc/rfc3339.txt) date strings.
# Examples
Example 1: Compute Timestamp from POSIX `time()`.
Timestamp timestamp;
timestamp.set_seconds(time(NULL));
timestamp.set_nanos(0);
Example 2: Compute Timestamp from POSIX `gettimeofday()`.
struct timeval tv;
gettimeofday(&tv, NULL);
Timestamp timestamp;
timestamp.set_seconds(tv.tv_sec);
timestamp.set_nanos(tv.tv_usec * 1000);
Example 3: Compute Timestamp from Win32 `GetSystemTimeAsFileTime()`.
FILETIME ft;
GetSystemTimeAsFileTime(&ft);
UINT64 ticks = (((UINT64)ft.dwHighDateTime) << 32) | ft.dwLowDateTime;
// A Windows tick is 100 nanoseconds. Windows epoch 1601-01-01T00:00:00Z
// is 11644473600 seconds before Unix epoch 1970-01-01T00:00:00Z.
Timestamp timestamp;
timestamp.set_seconds((INT64) ((ticks / 10000000) - 11644473600LL));
timestamp.set_nanos((INT32) ((ticks % 10000000) * 100));
Example 4: Compute Timestamp from Java `System.currentTimeMillis()`.
long millis = System.currentTimeMillis();
Timestamp timestamp = Timestamp.newBuilder().setSeconds(millis / 1000)
.setNanos((int) ((millis % 1000) * 1000000)).build();
Example 5: Compute Timestamp from Java `Instant.now()`.
Instant now = Instant.now();
Timestamp timestamp =
Timestamp.newBuilder().setSeconds(now.getEpochSecond())
.setNanos(now.getNano()).build();
Example 6: Compute Timestamp from current time in Python.
timestamp = Timestamp()
timestamp.GetCurrentTime()
# JSON Mapping
In JSON format, the Timestamp type is encoded as a string in the
[RFC 3339](https://www.ietf.org/rfc/rfc3339.txt) format. That is, the
format is "{year}-{month}-{day}T{hour}:{min}:{sec}[.{frac_sec}]Z"
where {year} is always expressed using four digits while {month}, {day},
{hour}, {min}, and {sec} are zero-padded to two digits each. The fractional
seconds, which can go up to 9 digits (i.e. up to 1 nanosecond resolution),
are optional. The "Z" suffix indicates the timezone ("UTC"); the timezone
is required. A ProtoJSON serializer should always use UTC (as indicated by
"Z") when printing the Timestamp type and a ProtoJSON parser should be
able to accept both UTC and other timezones (as indicated by an offset).
For example, "2017-01-15T01:30:15.01Z" encodes 15.01 seconds past
01:30 UTC on January 15, 2017.
In JavaScript, one can convert a Date object to this format using the
standard
[toISOString()](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Date/toISOString)
method. In Python, a standard `datetime.datetime` object can be converted
to this format using
[`strftime`](https://docs.python.org/2/library/time.html#time.strftime) with
the time format spec '%Y-%m-%dT%H:%M:%S.%fZ'. Likewise, in Java, one can use
the Joda Time's [`ISODateTimeFormat.dateTime()`](
http://joda-time.sourceforge.net/apidocs/org/joda/time/format/ISODateTimeFormat.html#dateTime()
) to obtain a formatter capable of generating timestamps in this format.
schema:
type: string
examples:
- "2023-01-15T01:30:15.01Z"
- "2024-12-25T12:00:00Z"
format: date-time
- name: filter.range.endTime
in: query
description: |-
A Timestamp represents a point in time independent of any time zone or local
calendar, encoded as a count of seconds and fractions of seconds at
nanosecond resolution. The count is relative to an epoch at UTC midnight on
January 1, 1970, in the proleptic Gregorian calendar which extends the
Gregorian calendar backwards to year one.
All minutes are 60 seconds long. Leap seconds are "smeared" so that no leap
second table is needed for interpretation, using a [24-hour linear
smear](https://developers.google.com/time/smear).
The range is from 0001-01-01T00:00:00Z to 9999-12-31T23:59:59.999999999Z. By
restricting to that range, we ensure that we can convert to and from [RFC
3339](https://www.ietf.org/rfc/rfc3339.txt) date strings.
# Examples
Example 1: Compute Timestamp from POSIX `time()`.
Timestamp timestamp;
timestamp.set_seconds(time(NULL));
timestamp.set_nanos(0);
Example 2: Compute Timestamp from POSIX `gettimeofday()`.
struct timeval tv;
gettimeofday(&tv, NULL);
Timestamp timestamp;
timestamp.set_seconds(tv.tv_sec);
timestamp.set_nanos(tv.tv_usec * 1000);
Example 3: Compute Timestamp from Win32 `GetSystemTimeAsFileTime()`.
FILETIME ft;
GetSystemTimeAsFileTime(&ft);
UINT64 ticks = (((UINT64)ft.dwHighDateTime) << 32) | ft.dwLowDateTime;
// A Windows tick is 100 nanoseconds. Windows epoch 1601-01-01T00:00:00Z
// is 11644473600 seconds before Unix epoch 1970-01-01T00:00:00Z.
Timestamp timestamp;
timestamp.set_seconds((INT64) ((ticks / 10000000) - 11644473600LL));
timestamp.set_nanos((INT32) ((ticks % 10000000) * 100));
Example 4: Compute Timestamp from Java `System.currentTimeMillis()`.
long millis = System.currentTimeMillis();
Timestamp timestamp = Timestamp.newBuilder().setSeconds(millis / 1000)
.setNanos((int) ((millis % 1000) * 1000000)).build();
Example 5: Compute Timestamp from Java `Instant.now()`.
Instant now = Instant.now();
Timestamp timestamp =
Timestamp.newBuilder().setSeconds(now.getEpochSecond())
.setNanos(now.getNano()).build();
Example 6: Compute Timestamp from current time in Python.
timestamp = Timestamp()
timestamp.GetCurrentTime()
# JSON Mapping
In JSON format, the Timestamp type is encoded as a string in the
[RFC 3339](https://www.ietf.org/rfc/rfc3339.txt) format. That is, the
format is "{year}-{month}-{day}T{hour}:{min}:{sec}[.{frac_sec}]Z"
where {year} is always expressed using four digits while {month}, {day},
{hour}, {min}, and {sec} are zero-padded to two digits each. The fractional
seconds, which can go up to 9 digits (i.e. up to 1 nanosecond resolution),
are optional. The "Z" suffix indicates the timezone ("UTC"); the timezone
is required. A ProtoJSON serializer should always use UTC (as indicated by
"Z") when printing the Timestamp type and a ProtoJSON parser should be
able to accept both UTC and other timezones (as indicated by an offset).
For example, "2017-01-15T01:30:15.01Z" encodes 15.01 seconds past
01:30 UTC on January 15, 2017.
In JavaScript, one can convert a Date object to this format using the
standard
[toISOString()](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Date/toISOString)
method. In Python, a standard `datetime.datetime` object can be converted
to this format using
[`strftime`](https://docs.python.org/2/library/time.html#time.strftime) with
the time format spec '%Y-%m-%dT%H:%M:%S.%fZ'. Likewise, in Java, one can use
the Joda Time's [`ISODateTimeFormat.dateTime()`](
http://joda-time.sourceforge.net/apidocs/org/joda/time/format/ISODateTimeFormat.html#dateTime()
) to obtain a formatter capable of generating timestamps in this format.
schema:
type: string
examples:
- "2023-01-15T01:30:15.01Z"
- "2024-12-25T12:00:00Z"
format: date-time
- name: filter.statuses
in: query
description: OR semantics; empty matches any status.
schema:
type: array
items:
$ref: '#/components/schemas/livekit.publicapi.analytics.v1.SessionStatus'
title: statuses
- name: filter.roomName
in: query
description: |-
Room-name prefix match (case-sensitive): returns sessions whose room name
starts with this value, e.g. `demo-` matches `demo-1` and `demo-lobby`.
schema:
type: string
title: room_name
- name: filter.sessionId
in: query
description: Exact room-session id match (RM_...).
schema:
type: string
title: session_id
- name: filter.tags
in: query
description: OR semantics.
schema:
type: array
items:
type: string
title: tags
- name: filter.agentId
in: query
description: Cloud agent id (CA_...) — return only sessions this agent served. Duration is not filterable in v1.
schema:
type: string
title: agent_id
- name: sortOrder
in: query
description: |-
Direction of the started_at ordering, the only column sessions sort on.
Defaults to descending (newest first) when unset.
schema:
title: sort_order
$ref: '#/components/schemas/livekit.publicapi.common.v1.SortOrder'
responses:
"200":
description: Success
content:
application/json:
schema:
$ref: '#/components/schemas/livekit.publicapi.analytics.v1.Sessions.List.Response'
/v0/projects/{projectId}/sessions/{sessionId}:
get:
tags:
- livekit.publicapi.analytics.v1.AnalyticsService
summary: GetSession
description: |-
GetSession returns one room session. The response carries both the list-row
`session` and the richer `detail` (participants, per-metric data points).
operationId: AnalyticsService_GetSession
parameters:
- name: projectId
in: path
required: true
schema:
type: string
title: project_id
- name: sessionId
in: path
required: true
schema:
type: string
title: session_id
responses:
"200":
description: Success
content:
application/json:
schema:
$ref: '#/components/schemas/livekit.publicapi.analytics.v1.Sessions.Get.Response'
/v0/projects/{projectId}/sessions/{sessionId}/events:
get:
tags:
- livekit.publicapi.analytics.v1.AnalyticsService
summary: |-
ListSessionEvents lists one room session's events, oldest first by default,
cursor-paginated with no total. With no `types`, it returns the seven the
dashboard's events table shows: PARTICIPANT_JOINED, PARTICIPANT_LEFT,
PARTICIPANT_ACTIVE, PARTICIPANT_RESUMED, ROOM_CREATED, ROOM_ENDED and
API_CALL. `types` asks for others, such as TRACK_PUBLISHED, and
`participant_session_id` keeps one participant session's events. With
`participant_session_id` and no `types`, it returns the eleven the
dashboard's participant events table shows: that participant session's
PARTICIPANT_JOINED, PARTICIPANT_LEFT, PARTICIPANT_RESUMED and
PARTICIPANT_ACTIVE, and its TRACK_MUTED, TRACK_UNMUTED, TRACK_PUBLISHED,
TRACK_UNPUBLISHED, TRACK_SUBSCRIBED, TRACK_SUBSCRIBE_REQUESTED and
TRACK_SUBSCRIBE_FAILED.
description: |-
Unlike the dashboard, on purpose: an unknown type or a malformed
participant session id is InvalidArgument rather than being searched for
as typed, and types match exactly, so TRACK_PUBLISHED doesn't also return
TRACK_PUBLISHED_UPDATE. Each event's payload keeps only an allowlist of
fields, leaving out participants' attributes and metadata and API calls'
request bodies. Each event and participant row still carries the
participant's identity, as the dashboard shows it to every member, and
for a SIP caller that can be a phone number.
Events are kept for 60 days, which can be shorter than the session's other
data, so an older session can list no events. An ACTIVE session lists the
events recorded so far. An unknown session is NotFound.
operationId: AnalyticsService_ListSessionEvents
parameters:
- name: projectId
in: path
required: true
schema:
type: string
title: project_id
- name: sessionId
in: path
required: true
schema:
type: string
title: session_id
- name: page.cursor
in: query
description: |-
Opaque cursor returned by a prior page (PageInfo.next_cursor). Empty starts
from the beginning.
schema:
type: string
title: cursor
- name: page.pageSize
in: query
description: Maximum items to return; 0 lets the server pick a default.
schema:
type: integer
title: page_size
format: int32
- name: types
in: query
description: |-
Event types to return, by name, such as TRACK_PUBLISHED: the names of
LiveKit's AnalyticsEventType. Each matches exactly. Empty returns the
dashboard's seven defaults, or with participant_session_id its eleven
participant defaults, track events included (see ListSessionEvents).
An unknown name is InvalidArgument.
schema:
type: array
items:
type: string
title: types
- name: participantSessionId
in: query
description: |-
Only the events of this participant session (PA_...), as the
participants list's ParticipantSession.participant_session_id names
it. Room events and API calls name no participant session, so they
are left out. Anything but a PA_ id is InvalidArgument.
schema:
type: string
title: participant_session_id
- name: sortOrder
in: query
description: |-
Direction of the timestamp ordering. Defaults to ascending (oldest
first) when unset.
schema:
title: sort_order
$ref: '#/components/schemas/livekit.publicapi.common.v1.SortOrder'
responses:
"200":
description: Success
content:
application/json:
schema:
$ref: '#/components/schemas/livekit.publicapi.analytics.v1.SessionEvents.List.Response'
/v0/projects/{projectId}/sessions/{sessionId}/logs:
get:
tags:
- livekit.publicapi.observability.v1.ObservabilityService
summary: |-
GetSessionLogs returns the log records the session's agents exported, in
time order: what the dashboard's logs panel shows. Their chat history is
left out, since GetSessionTranscript reads it, and their evaluation
results stay in. The session's events, such as participants joining,
come from AnalyticsService's ListSessionEvents.
description: |-
An ACTIVE session returns what its agents have exported so far. A record
exported mid-read with a time this read has already paged past, earlier
than its cursor's when oldest first, is missed until a new read. An
unknown session is NotFound. A read filtered by log_levels can come back
empty because no record is at those levels, so only an unfiltered one is
ObservabilityDisabled.
operationId: ObservabilityService_GetSessionLogs
parameters:
- name: projectId
in: path
required: true
schema:
type: string
title: project_id
- name: sessionId
in: path
description: The session's RM_ id.
required: true
schema:
type: string
title: session_id
- name: page.cursor
in: query
description: |-
Opaque cursor returned by a prior page (PageInfo.next_cursor). Empty starts
from the beginning.
schema:
type: string
title: cursor
- name: page.pageSize
in: query
description: Maximum items to return; 0 lets the server pick a default.
schema:
type: integer
title: page_size
format: int32
- name: logLevels
in: query
description: |-
Only records at these levels, as the dashboard's logs filter selects
them, for example only TRACE and FATAL. Empty returns every record,
including those with no level, such as a passed evaluation.
LOG_LEVEL_UNSPECIFIED is InvalidArgument.
schema:
type: array
items:
$ref: '#/components/schemas/livekit.publicapi.observability.v1.LogLevel'
title: log_levels
- name: sortOrder
in: query
description: |-
Direction of the timestamp ordering. Defaults to ascending (oldest
first) when unset.
schema:
title: sort_order
$ref: '#/components/schemas/livekit.publicapi.common.v1.SortOrder'
responses:
"200":
description: Success
content:
application/json:
schema:
$ref: '#/components/schemas/livekit.publicapi.observability.v1.Logs.Get.Response'
/v0/projects/{projectId}/sessions/{sessionId}/metrics:
get:
tags:
- livekit.publicapi.observability.v1.ObservabilityService
summary: |-
GetSessionMetrics returns the OpenTelemetry metric points the session's
agents exported, by time, typed: turn latencies such as
lk.agents.turn.e2e_latency and lk.agents.turn.llm_ttft, token and duration
usage such as lk.agents.usage.llm_input_tokens, and the gen_ai.*
histograms, along with any metrics the agent's own code recorded.
description: |-
These 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 agent whose code installs its own MeterProvider exports
none to LiveKit Cloud, and its sessions return no points.
Some points aren't labeled as their agent exported them. These are
limitations of the upstream aggregator, which groups a session's series
by their attributes alone and names each group after its first row:
- several metrics can come back under one name, such as an LLM's input,
output and cached token counts, all named
lk.agents.usage.llm_input_tokens;
- points of one series at the same time that recorded equal values
collapse into one point;
- with two agents in one session, a point can carry the other agent's
resource attributes.
An agent exports its metrics every 30 seconds, and its turn latencies
when the session ends, so an ACTIVE session returns what it has exported
so far. An unknown session is NotFound. A read filtered by names can come
back empty because no metric has those names, so only an unfiltered one
is ObservabilityDisabled.
operationId: ObservabilityService_GetSessionMetrics
parameters:
- name: projectId
in: path
required: true
schema:
type: string
title: project_id
- name: sessionId
in: path
description: The session's RM_ id.
required: true
schema:
type: string
title: session_id
- name: page.cursor
in: query
description: |-
Opaque cursor returned by a prior page (PageInfo.next_cursor). Empty starts
from the beginning.
schema:
type: string
title: cursor
- name: page.pageSize
in: query
description: Maximum items to return; 0 lets the server pick a default.
schema:
type: integer
title: page_size
format: int32
- name: names
in: query
description: |-
Only the points of these metrics, matched exactly, such as
lk.agents.turn.e2e_latency. Empty returns every metric. At most 50
names, each 1 to 256 characters.
schema:
type: array
items:
type: string
title: names
responses:
"200":
description: Success
content:
application/json:
schema:
$ref: '#/components/schemas/livekit.publicapi.observability.v1.Metrics.Get.Response'
/v0/projects/{projectId}/sessions/{sessionId}/participants:
get:
tags:
- livekit.publicapi.analytics.v1.AnalyticsService
summary: ListSessionParticipants
description: |-
ListSessionParticipants lists the participants of one room session, one row
per identity, cursor-paginated; newest join first by default. Each row
carries the participant's participant sessions (PA_...), each with the
client it connected from.
operationId: AnalyticsService_ListSessionParticipants
parameters:
- name: projectId
in: path
required: true
schema:
type: string
title: project_id
- name: sessionId
in: path
required: true
schema:
type: string
title: session_id
- name: page.cursor
in: query
description: |-
Opaque cursor returned by a prior page (PageInfo.next_cursor). Empty starts
from the beginning.
schema:
type: string
title: cursor
- name: page.pageSize
in: query
description: Maximum items to return; 0 lets the server pick a default.
schema:
type: integer
title: page_size
format: int32
- name: sortBy
in: query
description: Column to order by. Defaults to joined_at when unset.
schema:
title: sort_by
$ref: '#/components/schemas/livekit.publicapi.analytics.v1.ParticipantSortField'
- name: sortOrder
in: query
description: Direction of sort_by. Defaults to descending (newest first) when unset.
schema:
title: sort_order
$ref: '#/components/schemas/livekit.publicapi.common.v1.SortOrder'
responses:
"200":
description: Success
content:
application/json:
schema:
$ref: '#/components/schemas/livekit.publicapi.analytics.v1.SessionParticipants.List.Response'
/v0/projects/{projectId}/sessions/{sessionId}/recording-url:
get:
tags:
- livekit.publicapi.observability.v1.ObservabilityService
summary: GetSessionRecordingURL
description: |-
GetSessionRecordingURL returns a short-lived signed URL for one of the
session's recordings: its audio or its chat history. A session with no
recording of that type is NotFound. A new recording can be NotFound for
up to a minute after the session ends.
operationId: ObservabilityService_GetSessionRecordingURL
parameters:
- name: projectId
in: path
required: true
schema:
type: string
title: project_id
- name: sessionId
in: path
required: true
schema:
type: string
title: session_id
- name: fileType
in: query
description: Which recording to sign a URL for. UNSPECIFIED is InvalidArgument.
schema:
title: file_type
$ref: '#/components/schemas/livekit.publicapi.observability.v1.RecordingFileType'
- name: expirySeconds
in: query
description: |-
How long the URL stays valid, in seconds. Unset or 0 is 900 (15
minutes), and anything longer is clamped to 900 without an error;
expires_at says what was granted.
schema:
type: integer
title: expiry_seconds
responses:
"200":
description: Success
content:
application/json:
schema:
$ref: '#/components/schemas/livekit.publicapi.observability.v1.Recording.GetURL.Response'
/v0/projects/{projectId}/sessions/{sessionId}/traces:
get:
tags:
- livekit.publicapi.observability.v1.ObservabilityService
summary: |-
GetSessionTraces returns the spans the session's agents exported, by
start time: what the dashboard's trace view shows. Each span names its
parent, so the pages rebuild the span tree, and its attributes carry the
turn and latency fields the dashboard's turn view reads, such as
lk.generation_id and lk.response.ttft.
description: |-
An ACTIVE session returns what its agents have exported so far; a span
exported after the first page waits for a new read. The later pages are
read by offset, so a span exported mid-read can still shift them: a span
can repeat, or be skipped. Dedupe by span_id, and read again from the
first page to pick up a skipped span. An unknown session is NotFound.
operationId: ObservabilityService_GetSessionTraces
parameters:
- name: projectId
in: path
required: true
schema:
type: string
title: project_id
- name: sessionId
in: path
description: The session's RM_ id.
required: true
schema:
type: string
title: session_id
- name: page.cursor
in: query
description: |-
Opaque cursor returned by a prior page (PageInfo.next_cursor). Empty starts
from the beginning.
schema:
type: string
title: cursor
- name: page.pageSize
in: query
description: Maximum items to return; 0 lets the server pick a default.
schema:
type: integer
title: page_size
format: int32
responses:
"200":
description: Success
content:
application/json:
schema:
$ref: '#/components/schemas/livekit.publicapi.observability.v1.Traces.Get.Response'
/v0/projects/{projectId}/sessions/{sessionId}/transcript:
get:
tags:
- livekit.publicapi.observability.v1.ObservabilityService
summary: |-
GetSessionTranscript returns the session's conversation as ordered
transcript items: messages, tool calls and results, agent handoffs and
agent configuration changes. It is the conversation the dashboard's
transcript shows.
description: |-
The agent exports its transcript when the session ends, and it can be
read a minute or two later; on a project with PII redaction, only once
the session's recording has been redacted. So a session that is still
ACTIVE returns what exists so far, usually nothing, without an error:
read it again after the session ends. An unknown session is NotFound.
operationId: ObservabilityService_GetSessionTranscript
parameters:
- name: projectId
in: path
required: true
schema:
type: string
title: project_id
- name: sessionId
in: path
description: The session's RM_ id.
required: true
schema:
type: string
title: session_id
- name: page.cursor
in: query
description: |-
Opaque cursor returned by a prior page (PageInfo.next_cursor). Empty starts
from the beginning.
schema:
type: string
title: cursor
- name: page.pageSize
in: query
description: Maximum items to return; 0 lets the server pick a default.
schema:
type: integer
title: page_size
format: int32
responses:
"200":
description: Success
content:
application/json:
schema:
$ref: '#/components/schemas/livekit.publicapi.observability.v1.Transcript.Get.Response'
/v0/projects/{projectId}/simulation-runs:
get:
tags:
- livekit.publicapi.simulations.v1.SimulationService
summary: ListSimulationRuns
description: |-
ListSimulationRuns lists a project's runs, newest first, cursor-paginated,
optionally narrowed by status, agent, conversation mode and a time window.
Rows carry headline counts (job_count, passed_count, failed_count,
issue_count) but neither jobs nor the summary.
operationId: SimulationService_ListSimulationRuns
parameters:
- name: projectId
in: path
required: true
schema:
type: string
title: project_id
- name: page.cursor
in: query
description: |-
Opaque cursor returned by a prior page (PageInfo.next_cursor). Empty starts
from the beginning.
schema:
type: string
title: cursor
- name: page.pageSize
in: query
description: Maximum items to return; 0 lets the server pick a default.
schema:
type: integer
title: page_size
format: int32
- name: status
in: query
description: Only runs in this status.
schema:
oneOf:
- $ref: '#/components/schemas/livekit.SimulationRun.Status'
- type: "null"
title: status
- name: agentName
in: query
description: Only runs of this agent (exact name).
schema:
type: string
title: agent_name
- name: startTime
in: query
description: |-
A Timestamp represents a point in time independent of any time zone or local
calendar, encoded as a count of seconds and fractions of seconds at
nanosecond resolution. The count is relative to an epoch at UTC midnight on
January 1, 1970, in the proleptic Gregorian calendar which extends the
Gregorian calendar backwards to year one.
All minutes are 60 seconds long. Leap seconds are "smeared" so that no leap
second table is needed for interpretation, using a [24-hour linear
smear](https://developers.google.com/time/smear).
The range is from 0001-01-01T00:00:00Z to 9999-12-31T23:59:59.999999999Z. By
restricting to that range, we ensure that we can convert to and from [RFC
3339](https://www.ietf.org/rfc/rfc3339.txt) date strings.
# Examples
Example 1: Compute Timestamp from POSIX `time()`.
Timestamp timestamp;
timestamp.set_seconds(time(NULL));
timestamp.set_nanos(0);
Example 2: Compute Timestamp from POSIX `gettimeofday()`.
struct timeval tv;
gettimeofday(&tv, NULL);
Timestamp timestamp;
timestamp.set_seconds(tv.tv_sec);
timestamp.set_nanos(tv.tv_usec * 1000);
Example 3: Compute Timestamp from Win32 `GetSystemTimeAsFileTime()`.
FILETIME ft;
GetSystemTimeAsFileTime(&ft);
UINT64 ticks = (((UINT64)ft.dwHighDateTime) << 32) | ft.dwLowDateTime;
// A Windows tick is 100 nanoseconds. Windows epoch 1601-01-01T00:00:00Z
// is 11644473600 seconds before Unix epoch 1970-01-01T00:00:00Z.
Timestamp timestamp;
timestamp.set_seconds((INT64) ((ticks / 10000000) - 11644473600LL));
timestamp.set_nanos((INT32) ((ticks % 10000000) * 100));
Example 4: Compute Timestamp from Java `System.currentTimeMillis()`.
long millis = System.currentTimeMillis();
Timestamp timestamp = Timestamp.newBuilder().setSeconds(millis / 1000)
.setNanos((int) ((millis % 1000) * 1000000)).build();
Example 5: Compute Timestamp from Java `Instant.now()`.
Instant now = Instant.now();
Timestamp timestamp =
Timestamp.newBuilder().setSeconds(now.getEpochSecond())
.setNanos(now.getNano()).build();
Example 6: Compute Timestamp from current time in Python.
timestamp = Timestamp()
timestamp.GetCurrentTime()
# JSON Mapping
In JSON format, the Timestamp type is encoded as a string in the
[RFC 3339](https://www.ietf.org/rfc/rfc3339.txt) format. That is, the
format is "{year}-{month}-{day}T{hour}:{min}:{sec}[.{frac_sec}]Z"
where {year} is always expressed using four digits while {month}, {day},
{hour}, {min}, and {sec} are zero-padded to two digits each. The fractional
seconds, which can go up to 9 digits (i.e. up to 1 nanosecond resolution),
are optional. The "Z" suffix indicates the timezone ("UTC"); the timezone
is required. A ProtoJSON serializer should always use UTC (as indicated by
"Z") when printing the Timestamp type and a ProtoJSON parser should be
able to accept both UTC and other timezones (as indicated by an offset).
For example, "2017-01-15T01:30:15.01Z" encodes 15.01 seconds past
01:30 UTC on January 15, 2017.
In JavaScript, one can convert a Date object to this format using the
standard
[toISOString()](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Date/toISOString)
method. In Python, a standard `datetime.datetime` object can be converted
to this format using
[`strftime`](https://docs.python.org/2/library/time.html#time.strftime) with
the time format spec '%Y-%m-%dT%H:%M:%S.%fZ'. Likewise, in Java, one can use
the Joda Time's [`ISODateTimeFormat.dateTime()`](
http://joda-time.sourceforge.net/apidocs/org/joda/time/format/ISODateTimeFormat.html#dateTime()
) to obtain a formatter capable of generating timestamps in this format.
schema:
type: string
examples:
- "2023-01-15T01:30:15.01Z"
- "2024-12-25T12:00:00Z"
format: date-time
- name: endTime
in: query
description: |-
A Timestamp represents a point in time independent of any time zone or local
calendar, encoded as a count of seconds and fractions of seconds at
nanosecond resolution. The count is relative to an epoch at UTC midnight on
January 1, 1970, in the proleptic Gregorian calendar which extends the
Gregorian calendar backwards to year one.
All minutes are 60 seconds long. Leap seconds are "smeared" so that no leap
second table is needed for interpretation, using a [24-hour linear
smear](https://developers.google.com/time/smear).
The range is from 0001-01-01T00:00:00Z to 9999-12-31T23:59:59.999999999Z. By
restricting to that range, we ensure that we can convert to and from [RFC
3339](https://www.ietf.org/rfc/rfc3339.txt) date strings.
# Examples
Example 1: Compute Timestamp from POSIX `time()`.
Timestamp timestamp;
timestamp.set_seconds(time(NULL));
timestamp.set_nanos(0);
Example 2: Compute Timestamp from POSIX `gettimeofday()`.
struct timeval tv;
gettimeofday(&tv, NULL);
Timestamp timestamp;
timestamp.set_seconds(tv.tv_sec);
timestamp.set_nanos(tv.tv_usec * 1000);
Example 3: Compute Timestamp from Win32 `GetSystemTimeAsFileTime()`.
FILETIME ft;
GetSystemTimeAsFileTime(&ft);
UINT64 ticks = (((UINT64)ft.dwHighDateTime) << 32) | ft.dwLowDateTime;
// A Windows tick is 100 nanoseconds. Windows epoch 1601-01-01T00:00:00Z
// is 11644473600 seconds before Unix epoch 1970-01-01T00:00:00Z.
Timestamp timestamp;
timestamp.set_seconds((INT64) ((ticks / 10000000) - 11644473600LL));
timestamp.set_nanos((INT32) ((ticks % 10000000) * 100));
Example 4: Compute Timestamp from Java `System.currentTimeMillis()`.
long millis = System.currentTimeMillis();
Timestamp timestamp = Timestamp.newBuilder().setSeconds(millis / 1000)
.setNanos((int) ((millis % 1000) * 1000000)).build();
Example 5: Compute Timestamp from Java `Instant.now()`.
Instant now = Instant.now();
Timestamp timestamp =
Timestamp.newBuilder().setSeconds(now.getEpochSecond())
.setNanos(now.getNano()).build();
Example 6: Compute Timestamp from current time in Python.
timestamp = Timestamp()
timestamp.GetCurrentTime()
# JSON Mapping
In JSON format, the Timestamp type is encoded as a string in the
[RFC 3339](https://www.ietf.org/rfc/rfc3339.txt) format. That is, the
format is "{year}-{month}-{day}T{hour}:{min}:{sec}[.{frac_sec}]Z"
where {year} is always expressed using four digits while {month}, {day},
{hour}, {min}, and {sec} are zero-padded to two digits each. The fractional
seconds, which can go up to 9 digits (i.e. up to 1 nanosecond resolution),
are optional. The "Z" suffix indicates the timezone ("UTC"); the timezone
is required. A ProtoJSON serializer should always use UTC (as indicated by
"Z") when printing the Timestamp type and a ProtoJSON parser should be
able to accept both UTC and other timezones (as indicated by an offset).
For example, "2017-01-15T01:30:15.01Z" encodes 15.01 seconds past
01:30 UTC on January 15, 2017.
In JavaScript, one can convert a Date object to this format using the
standard
[toISOString()](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Date/toISOString)
method. In Python, a standard `datetime.datetime` object can be converted
to this format using
[`strftime`](https://docs.python.org/2/library/time.html#time.strftime) with
the time format spec '%Y-%m-%dT%H:%M:%S.%fZ'. Likewise, in Java, one can use
the Joda Time's [`ISODateTimeFormat.dateTime()`](
http://joda-time.sourceforge.net/apidocs/org/joda/time/format/ISODateTimeFormat.html#dateTime()
) to obtain a formatter capable of generating timestamps in this format.
schema:
type: string
examples:
- "2023-01-15T01:30:15.01Z"
- "2024-12-25T12:00:00Z"
format: date-time
- name: mode
in: query
description: Only runs in this conversation mode.
schema:
oneOf:
- $ref: '#/components/schemas/livekit.SimulationMode'
- type: "null"
title: mode
responses:
"200":
description: Success
content:
application/json:
schema:
$ref: '#/components/schemas/livekit.publicapi.simulations.v1.SimulationRuns.List.Response'
post:
tags:
- livekit.publicapi.simulations.v1.SimulationService
summary: CreateSimulationRun
description: |-
CreateSimulationRun registers a new run. With a scenario_group it starts
right away and no upload target is returned. Without one it waits in
PENDING_UPLOAD for the agent source that scenarios are generated from:
upload it to the returned presigned POST, then call
ConfirmSimulationSourceUpload. A run left pending for an hour is failed.
Creating a run is not idempotent: a retried request starts a second run.
operationId: SimulationService_CreateSimulationRun
parameters:
- name: projectId
in: path
required: true
schema:
type: string
title: project_id
requestBody:
content:
application/json:
schema:
type: object
properties:
agentName:
type: string
title: agent_name
description: |-
Name the agent under test is registered under; every job dispatches it
into the simulation room, so it must already be deployed or running as
a worker. Empty uses the project's default agent. Recorded on the run
and usable as a ListSimulationRuns filter.
numSimulations:
type: integer
title: num_simulations
format: int32
description: |-
Number of scenarios to generate from the agent source when
scenario_group is unset.
region:
type: string
title: region
description: 'Reserved: must be empty, and the service chooses where the run happens.'
scenarioGroup:
oneOf:
- $ref: '#/components/schemas/livekit.ScenarioGroup'
- type: "null"
title: scenario_group
description: |-
Run exactly these scenarios (the contents of a scenarios.yaml) instead
of generating num_simulations of them; the run then needs no source
upload and starts immediately.
concurrency:
type:
- integer
- "null"
title: concurrency
format: int32
description: |-
Maximum jobs running in parallel, at most 20; above that the request is
InvalidArgument. The project's concurrency quota can run fewer at once.
Unset uses the server default.
mode:
title: mode
description: Conversation mode for every job; unspecified means TEXT.
$ref: '#/components/schemas/livekit.SimulationMode'
backgroundNoise:
type: boolean
title: background_noise
description: Audio impairments applied to the simulated user; AUDIO mode only.
lowQualityMicrophone:
type: boolean
title: low_quality_microphone
packetLoss:
type: boolean
title: packet_loss
ci:
oneOf:
- $ref: '#/components/schemas/livekit.SimulationRun.CI'
- type: "null"
title: ci
description: |-
The CI pipeline this run came from, so runs can be linked back to
commits.
title: Request
additionalProperties: false
required: true
responses:
"200":
description: Success
content:
application/json:
schema:
$ref: '#/components/schemas/livekit.publicapi.simulations.v1.SimulationRuns.Create.Response'
/v0/projects/{projectId}/simulation-runs/{simulationRunId}:
get:
tags:
- livekit.publicapi.simulations.v1.SimulationService
summary: GetSimulationRun
description: |-
GetSimulationRun returns one run with its jobs and aggregate metrics. The
compressed summary blob (summary_zstd) is omitted; use
GetSimulationRunSummary for the decoded summary.
operationId: SimulationService_GetSimulationRun
parameters:
- name: projectId
in: path
required: true
schema:
type: string
title: project_id
- name: simulationRunId
in: path
required: true
schema:
type: string
title: simulation_run_id
responses:
"200":
description: Success
content:
application/json:
schema:
$ref: '#/components/schemas/livekit.publicapi.simulations.v1.SimulationRuns.Get.Response'
/v0/projects/{projectId}/simulation-runs/{simulationRunId}/summary:
get:
tags:
- livekit.publicapi.simulations.v1.SimulationService
summary: GetSimulationRunSummary
description: |-
GetSimulationRunSummary returns the graded outcome of a finished run:
pass/fail counts, what went well, what to improve, flagged issues with
suggestions, and the per-job chat history. FailedPrecondition while the
run is still going; NotFound if the run finished without a summary.
operationId: SimulationService_GetSimulationRunSummary
parameters:
- name: projectId
in: path
required: true
schema:
type: string
title: project_id
- name: simulationRunId
in: path
required: true
schema:
type: string
title: simulation_run_id
responses:
"200":
description: Success
content:
application/json:
schema:
$ref: '#/components/schemas/livekit.publicapi.simulations.v1.SimulationRuns.GetSummary.Response'
/v0/projects/{projectId}/simulation-runs/{simulationRunId}:cancel:
post:
tags:
- livekit.publicapi.simulations.v1.SimulationService
summary: CancelSimulationRun
description: |-
CancelSimulationRun stops a run that has not finished. Cancelling a run
that already finished succeeds without effect.
operationId: SimulationService_CancelSimulationRun
parameters:
- name: projectId
in: path
required: true
schema:
type: string
title: project_id
- name: simulationRunId
in: path
required: true
schema:
type: string
title: simulation_run_id
responses:
"200":
description: Success
content:
application/json:
schema:
$ref: '#/components/schemas/livekit.publicapi.simulations.v1.SimulationRuns.Cancel.Response'
/v0/projects/{projectId}/simulation-runs/{simulationRunId}:confirmSourceUpload:
post:
tags:
- livekit.publicapi.simulations.v1.SimulationService
summary: ConfirmSimulationSourceUpload
description: |-
ConfirmSimulationSourceUpload marks the agent source as uploaded and starts
scenario generation; the run moves to GENERATING, then RUNNING once the
scenarios exist. Only valid while the run is PENDING_UPLOAD, so a repeated
call fails.
operationId: SimulationService_ConfirmSimulationSourceUpload
parameters:
- name: projectId
in: path
required: true
schema:
type: string
title: project_id
- name: simulationRunId
in: path
required: true
schema:
type: string
title: simulation_run_id
requestBody:
content:
application/json:
schema:
type: object
properties:
codeEntrypoint:
type: string
title: code_entrypoint
description: Entrypoint of the uploaded source, for example "agent.py".
title: Request
additionalProperties: false
required: true
responses:
"200":
description: Success
content:
application/json:
schema:
$ref: '#/components/schemas/livekit.publicapi.simulations.v1.SimulationRuns.ConfirmSourceUpload.Response'
/v0/projects/{projectId}/simulation-runs:counts:
get:
tags:
- livekit.publicapi.simulations.v1.SimulationService
summary: CountSimulationRuns
description: |-
CountSimulationRuns buckets the runs ListSimulationRuns would return over
[start_time, end_time) into a histogram. It takes the same filters over the
same window, so the bars and the rows beneath them always describe one set.
Both bounds are required and end_time must be after start_time.
operationId: SimulationService_CountSimulationRuns
parameters:
- name: projectId
in: path
required: true
schema:
type: string
title: project_id
- name: startTime
in: query
description: |-
A Timestamp represents a point in time independent of any time zone or local
calendar, encoded as a count of seconds and fractions of seconds at
nanosecond resolution. The count is relative to an epoch at UTC midnight on
January 1, 1970, in the proleptic Gregorian calendar which extends the
Gregorian calendar backwards to year one.
All minutes are 60 seconds long. Leap seconds are "smeared" so that no leap
second table is needed for interpretation, using a [24-hour linear
smear](https://developers.google.com/time/smear).
The range is from 0001-01-01T00:00:00Z to 9999-12-31T23:59:59.999999999Z. By
restricting to that range, we ensure that we can convert to and from [RFC
3339](https://www.ietf.org/rfc/rfc3339.txt) date strings.
# Examples
Example 1: Compute Timestamp from POSIX `time()`.
Timestamp timestamp;
timestamp.set_seconds(time(NULL));
timestamp.set_nanos(0);
Example 2: Compute Timestamp from POSIX `gettimeofday()`.
struct timeval tv;
gettimeofday(&tv, NULL);
Timestamp timestamp;
timestamp.set_seconds(tv.tv_sec);
timestamp.set_nanos(tv.tv_usec * 1000);
Example 3: Compute Timestamp from Win32 `GetSystemTimeAsFileTime()`.
FILETIME ft;
GetSystemTimeAsFileTime(&ft);
UINT64 ticks = (((UINT64)ft.dwHighDateTime) << 32) | ft.dwLowDateTime;
// A Windows tick is 100 nanoseconds. Windows epoch 1601-01-01T00:00:00Z
// is 11644473600 seconds before Unix epoch 1970-01-01T00:00:00Z.
Timestamp timestamp;
timestamp.set_seconds((INT64) ((ticks / 10000000) - 11644473600LL));
timestamp.set_nanos((INT32) ((ticks % 10000000) * 100));
Example 4: Compute Timestamp from Java `System.currentTimeMillis()`.
long millis = System.currentTimeMillis();
Timestamp timestamp = Timestamp.newBuilder().setSeconds(millis / 1000)
.setNanos((int) ((millis % 1000) * 1000000)).build();
Example 5: Compute Timestamp from Java `Instant.now()`.
Instant now = Instant.now();
Timestamp timestamp =
Timestamp.newBuilder().setSeconds(now.getEpochSecond())
.setNanos(now.getNano()).build();
Example 6: Compute Timestamp from current time in Python.
timestamp = Timestamp()
timestamp.GetCurrentTime()
# JSON Mapping
In JSON format, the Timestamp type is encoded as a string in the
[RFC 3339](https://www.ietf.org/rfc/rfc3339.txt) format. That is, the
format is "{year}-{month}-{day}T{hour}:{min}:{sec}[.{frac_sec}]Z"
where {year} is always expressed using four digits while {month}, {day},
{hour}, {min}, and {sec} are zero-padded to two digits each. The fractional
seconds, which can go up to 9 digits (i.e. up to 1 nanosecond resolution),
are optional. The "Z" suffix indicates the timezone ("UTC"); the timezone
is required. A ProtoJSON serializer should always use UTC (as indicated by
"Z") when printing the Timestamp type and a ProtoJSON parser should be
able to accept both UTC and other timezones (as indicated by an offset).
For example, "2017-01-15T01:30:15.01Z" encodes 15.01 seconds past
01:30 UTC on January 15, 2017.
In JavaScript, one can convert a Date object to this format using the
standard
[toISOString()](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Date/toISOString)
method. In Python, a standard `datetime.datetime` object can be converted
to this format using
[`strftime`](https://docs.python.org/2/library/time.html#time.strftime) with
the time format spec '%Y-%m-%dT%H:%M:%S.%fZ'. Likewise, in Java, one can use
the Joda Time's [`ISODateTimeFormat.dateTime()`](
http://joda-time.sourceforge.net/apidocs/org/joda/time/format/ISODateTimeFormat.html#dateTime()
) to obtain a formatter capable of generating timestamps in this format.
schema:
type: string
examples:
- "2023-01-15T01:30:15.01Z"
- "2024-12-25T12:00:00Z"
format: date-time
- name: endTime
in: query
description: |-
A Timestamp represents a point in time independent of any time zone or local
calendar, encoded as a count of seconds and fractions of seconds at
nanosecond resolution. The count is relative to an epoch at UTC midnight on
January 1, 1970, in the proleptic Gregorian calendar which extends the
Gregorian calendar backwards to year one.
All minutes are 60 seconds long. Leap seconds are "smeared" so that no leap
second table is needed for interpretation, using a [24-hour linear
smear](https://developers.google.com/time/smear).
The range is from 0001-01-01T00:00:00Z to 9999-12-31T23:59:59.999999999Z. By
restricting to that range, we ensure that we can convert to and from [RFC
3339](https://www.ietf.org/rfc/rfc3339.txt) date strings.
# Examples
Example 1: Compute Timestamp from POSIX `time()`.
Timestamp timestamp;
timestamp.set_seconds(time(NULL));
timestamp.set_nanos(0);
Example 2: Compute Timestamp from POSIX `gettimeofday()`.
struct timeval tv;
gettimeofday(&tv, NULL);
Timestamp timestamp;
timestamp.set_seconds(tv.tv_sec);
timestamp.set_nanos(tv.tv_usec * 1000);
Example 3: Compute Timestamp from Win32 `GetSystemTimeAsFileTime()`.
FILETIME ft;
GetSystemTimeAsFileTime(&ft);
UINT64 ticks = (((UINT64)ft.dwHighDateTime) << 32) | ft.dwLowDateTime;
// A Windows tick is 100 nanoseconds. Windows epoch 1601-01-01T00:00:00Z
// is 11644473600 seconds before Unix epoch 1970-01-01T00:00:00Z.
Timestamp timestamp;
timestamp.set_seconds((INT64) ((ticks / 10000000) - 11644473600LL));
timestamp.set_nanos((INT32) ((ticks % 10000000) * 100));
Example 4: Compute Timestamp from Java `System.currentTimeMillis()`.
long millis = System.currentTimeMillis();
Timestamp timestamp = Timestamp.newBuilder().setSeconds(millis / 1000)
.setNanos((int) ((millis % 1000) * 1000000)).build();
Example 5: Compute Timestamp from Java `Instant.now()`.
Instant now = Instant.now();
Timestamp timestamp =
Timestamp.newBuilder().setSeconds(now.getEpochSecond())
.setNanos(now.getNano()).build();
Example 6: Compute Timestamp from current time in Python.
timestamp = Timestamp()
timestamp.GetCurrentTime()
# JSON Mapping
In JSON format, the Timestamp type is encoded as a string in the
[RFC 3339](https://www.ietf.org/rfc/rfc3339.txt) format. That is, the
format is "{year}-{month}-{day}T{hour}:{min}:{sec}[.{frac_sec}]Z"
where {year} is always expressed using four digits while {month}, {day},
{hour}, {min}, and {sec} are zero-padded to two digits each. The fractional
seconds, which can go up to 9 digits (i.e. up to 1 nanosecond resolution),
are optional. The "Z" suffix indicates the timezone ("UTC"); the timezone
is required. A ProtoJSON serializer should always use UTC (as indicated by
"Z") when printing the Timestamp type and a ProtoJSON parser should be
able to accept both UTC and other timezones (as indicated by an offset).
For example, "2017-01-15T01:30:15.01Z" encodes 15.01 seconds past
01:30 UTC on January 15, 2017.
In JavaScript, one can convert a Date object to this format using the
standard
[toISOString()](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Date/toISOString)
method. In Python, a standard `datetime.datetime` object can be converted
to this format using
[`strftime`](https://docs.python.org/2/library/time.html#time.strftime) with
the time format spec '%Y-%m-%dT%H:%M:%S.%fZ'. Likewise, in Java, one can use
the Joda Time's [`ISODateTimeFormat.dateTime()`](
http://joda-time.sourceforge.net/apidocs/org/joda/time/format/ISODateTimeFormat.html#dateTime()
) to obtain a formatter capable of generating timestamps in this format.
schema:
type: string
examples:
- "2023-01-15T01:30:15.01Z"
- "2024-12-25T12:00:00Z"
format: date-time
- name: status
in: query
description: Only runs in this status.
schema:
oneOf:
- $ref: '#/components/schemas/livekit.SimulationRun.Status'
- type: "null"
title: status
- name: agentName
in: query
description: Only runs of this agent (exact name).
schema:
type: string
title: agent_name
- name: mode
in: query
description: Only runs in this conversation mode.
schema:
oneOf:
- $ref: '#/components/schemas/livekit.SimulationMode'
- type: "null"
title: mode
responses:
"200":
description: Success
content:
application/json:
schema:
$ref: '#/components/schemas/livekit.publicapi.simulations.v1.SimulationRuns.Counts.Response'
/v0/projects/{projectId}/threads:
get:
tags:
- livekit.publicapi.threads.v1.ThreadService
summary: ListThreads
description: ListThreads lists the threads of one scope, newest first.
operationId: ThreadService_ListThreads
parameters:
- name: projectId
in: path
required: true
schema:
type: string
title: project_id
- name: scope
in: query
schema:
type: string
title: scope
- name: page.cursor
in: query
description: |-
Opaque cursor returned by a prior page (PageInfo.next_cursor). Empty starts
from the beginning.
schema:
type: string
title: cursor
- name: page.pageSize
in: query
description: Maximum items to return; 0 lets the server pick a default.
schema:
type: integer
title: page_size
format: int32
responses:
"200":
description: Success
content:
application/json:
schema:
$ref: '#/components/schemas/livekit.publicapi.threads.v1.Threads.List.Response'
post:
tags:
- livekit.publicapi.threads.v1.ThreadService
summary: CreateThread
description: CreateThread creates a thread and its database.
operationId: ThreadService_CreateThread
parameters:
- name: projectId
in: path
required: true
schema:
type: string
title: project_id
requestBody:
content:
application/json:
schema:
type: object
properties:
scope:
type: string
title: scope
description: |-
Optional scope grouping the thread (typically the user's identity),
at most 256 bytes.
attributes:
type: object
title: attributes
additionalProperties:
type: string
title: value
idleTtl:
title: idle_ttl
description: Unset takes the server default.
$ref: '#/components/schemas/google.protobuf.Duration'
title: Request
additionalProperties: false
required: true
responses:
"200":
description: Success
content:
application/json:
schema:
$ref: '#/components/schemas/livekit.publicapi.threads.v1.Threads.Create.Response'
/v0/projects/{projectId}/threads/{threadId}:
get:
tags:
- livekit.publicapi.threads.v1.ThreadService
summary: GetThread
operationId: ThreadService_GetThread
parameters:
- name: projectId
in: path
required: true
schema:
type: string
title: project_id
- name: threadId
in: path
required: true
schema:
type: string
title: thread_id
responses:
"200":
description: Success
content:
application/json:
schema:
$ref: '#/components/schemas/livekit.publicapi.threads.v1.Threads.Get.Response'
delete:
tags:
- livekit.publicapi.threads.v1.ThreadService
summary: DeleteThread
description: DeleteThread deletes the thread and its database.
operationId: ThreadService_DeleteThread
parameters:
- name: projectId
in: path
required: true
schema:
type: string
title: project_id
- name: threadId
in: path
required: true
schema:
type: string
title: thread_id
responses:
"200":
description: Success
content:
application/json:
schema:
$ref: '#/components/schemas/livekit.publicapi.threads.v1.Threads.Delete.Response'
patch:
tags:
- livekit.publicapi.threads.v1.ThreadService
summary: UpdateThread
description: |-
UpdateThread merges attributes (an empty value deletes the entry) and sets
the idle TTL. Every update counts as activity and pushes expires_at out.
operationId: ThreadService_UpdateThread
parameters:
- name: projectId
in: path
required: true
schema:
type: string
title: project_id
- name: threadId
in: path
required: true
schema:
type: string
title: thread_id
requestBody:
content:
application/json:
schema:
type: object
properties:
attributes:
type: object
title: attributes
additionalProperties:
type: string
title: value
idleTtl:
title: idle_ttl
$ref: '#/components/schemas/google.protobuf.Duration'
title: Request
additionalProperties: false
required: true
responses:
"200":
description: Success
content:
application/json:
schema:
$ref: '#/components/schemas/livekit.publicapi.threads.v1.Threads.Update.Response'
/v0/projects/{projectId}/threads/{threadId}/items:
get:
tags:
- livekit.publicapi.threads.v1.ThreadService
summary: GetThreadItems
description: GetThreadItems returns the thread's chat items, oldest first.
operationId: ThreadService_GetThreadItems
parameters:
- name: projectId
in: path
required: true
schema:
type: string
title: project_id
- name: threadId
in: path
required: true
schema:
type: string
title: thread_id
- name: agent
in: query
description: One agent's items; empty for every agent's.
schema:
type: string
title: agent
- name: page.cursor
in: query
description: |-
Opaque cursor returned by a prior page (PageInfo.next_cursor). Empty starts
from the beginning.
schema:
type: string
title: cursor
- name: page.pageSize
in: query
description: Maximum items to return; 0 lets the server pick a default.
schema:
type: integer
title: page_size
format: int32
- name: sortOrder
in: query
description: |-
Direction of the item order. Defaults to ascending (oldest first) when
unset; descending starts from the latest item and pages back.
schema:
title: sort_order
$ref: '#/components/schemas/livekit.publicapi.common.v1.SortOrder'
responses:
"200":
description: Success
content:
application/json:
schema:
$ref: '#/components/schemas/livekit.publicapi.threads.v1.Threads.Items.Response'
/v0/projects/{projectId}/threads/{threadId}/tasks:
get:
tags:
- livekit.publicapi.threads.v1.ThreadService
summary: GetThreadTasks
description: GetThreadTasks returns the thread's background tasks, oldest first.
operationId: ThreadService_GetThreadTasks
parameters:
- name: projectId
in: path
required: true
schema:
type: string
title: project_id
- name: threadId
in: path
required: true
schema:
type: string
title: thread_id
- name: status
in: query
description: Only tasks in this status; unset for every status.
schema:
oneOf:
- $ref: '#/components/schemas/livekit.agent.AgentTask.Status'
- type: "null"
title: status
- name: page.cursor
in: query
description: |-
Opaque cursor returned by a prior page (PageInfo.next_cursor). Empty starts
from the beginning.
schema:
type: string
title: cursor
- name: page.pageSize
in: query
description: Maximum items to return; 0 lets the server pick a default.
schema:
type: integer
title: page_size
format: int32
responses:
"200":
description: Success
content:
application/json:
schema:
$ref: '#/components/schemas/livekit.publicapi.threads.v1.Threads.Tasks.Response'
/v0/projects/{projectId}/tokens:
post:
tags:
- livekit.publicapi.projects.v1.ProjectService
summary: CreateToken
description: |-
CreateToken mints a short-lived LiveKit access token for the project,
signed server-side, so user-authenticated clients can call LiveKit server
APIs (rooms, SIP, egress, …) or join rooms without holding an API secret.
operationId: ProjectService_CreateToken
parameters:
- name: projectId
in: path
required: true
schema:
type: string
title: project_id
requestBody:
content:
application/json:
schema:
type: object
properties:
grants:
title: grants
description: The caller's project role must cover every grant requested.
$ref: '#/components/schemas/livekit.publicapi.projects.v1.TokenGrants'
ttlSeconds:
type: integer
title: ttl_seconds
description: |-
Requested lifetime in seconds. 0 means the default (10 minutes); at most
86400 (24 hours).
title: CreateTokenRequest
additionalProperties: false
required: true
responses:
"200":
description: Success
content:
application/json:
schema:
$ref: '#/components/schemas/livekit.publicapi.projects.v1.CreateTokenResponse'
/v0/users:
get:
tags:
- livekit.publicapi.users.v1.UserService
summary: ListUsers
operationId: UserService_ListUsers
parameters:
- name: page.cursor
in: query
description: |-
Opaque cursor returned by a prior page (PageInfo.next_cursor). Empty starts
from the beginning.
schema:
type: string
title: cursor
- name: page.pageSize
in: query
description: Maximum items to return; 0 lets the server pick a default.
schema:
type: integer
title: page_size
format: int32
- name: projectId
in: query
description: |-
At least one of project_id or workspace_id is required.
If both are set, project_id must belong to workspace_id; members are
the project's members.
schema:
type: string
title: project_id
- name: workspaceId
in: query
schema:
type: string
title: workspace_id
responses:
"200":
description: Success
content:
application/json:
schema:
$ref: '#/components/schemas/livekit.publicapi.users.v1.ListUsersResponse'
/v0/users/me:
get:
tags:
- livekit.publicapi.users.v1.UserService
summary: GetCurrentUser
operationId: UserService_GetCurrentUser
responses:
"200":
description: Success
content:
application/json:
schema:
$ref: '#/components/schemas/livekit.publicapi.users.v1.GetCurrentUserResponse'
/v0/users/{userId}:
get:
tags:
- livekit.publicapi.users.v1.UserService
summary: GetUser
operationId: UserService_GetUser
parameters:
- name: userId
in: path
required: true
schema:
type: string
title: user_id
responses:
"200":
description: Success
content:
application/json:
schema:
$ref: '#/components/schemas/livekit.publicapi.users.v1.GetUserResponse'
/v0/workspace-invites/{inviteToken}:
get:
tags:
- livekit.publicapi.workspaces.v1.WorkspaceService
summary: GetInvite
operationId: WorkspaceService_GetInvite
parameters:
- name: inviteToken
in: path
required: true
schema:
type: string
title: invite_token
responses:
"200":
description: Success
content:
application/json:
schema:
$ref: '#/components/schemas/livekit.publicapi.workspaces.v1.GetInviteResponse'
/v0/workspace-invites/{inviteToken}:answer:
post:
tags:
- livekit.publicapi.workspaces.v1.WorkspaceService
summary: AnswerInvite
operationId: WorkspaceService_AnswerInvite
parameters:
- name: inviteToken
in: path
required: true
schema:
type: string
title: invite_token
requestBody:
content:
application/json:
schema:
type: object
properties:
accept:
type: boolean
title: accept
title: AnswerInviteRequest
additionalProperties: false
required: true
responses:
"200":
description: Success
content:
application/json:
schema:
$ref: '#/components/schemas/livekit.publicapi.workspaces.v1.AnswerInviteResponse'
/v0/workspaces:
get:
tags:
- livekit.publicapi.workspaces.v1.WorkspaceService
summary: ListWorkspaces
operationId: WorkspaceService_ListWorkspaces
parameters:
- name: page.cursor
in: query
description: |-
Opaque cursor returned by a prior page (PageInfo.next_cursor). Empty starts
from the beginning.
schema:
type: string
title: cursor
- name: page.pageSize
in: query
description: Maximum items to return; 0 lets the server pick a default.
schema:
type: integer
title: page_size
format: int32
responses:
"200":
description: Success
content:
application/json:
schema:
$ref: '#/components/schemas/livekit.publicapi.workspaces.v1.ListWorkspacesResponse'
post:
tags:
- livekit.publicapi.workspaces.v1.WorkspaceService
summary: CreateWorkspace
operationId: WorkspaceService_CreateWorkspace
requestBody:
content:
application/json:
schema:
$ref: '#/components/schemas/livekit.publicapi.workspaces.v1.CreateWorkspaceRequest'
required: true
responses:
"200":
description: Success
content:
application/json:
schema:
$ref: '#/components/schemas/livekit.publicapi.workspaces.v1.CreateWorkspaceResponse'
/v0/workspaces/{workspaceId}:
get:
tags:
- livekit.publicapi.workspaces.v1.WorkspaceService
summary: GetWorkspace
operationId: WorkspaceService_GetWorkspace
parameters:
- name: workspaceId
in: path
required: true
schema:
type: string
title: workspace_id
responses:
"200":
description: Success
content:
application/json:
schema:
$ref: '#/components/schemas/livekit.publicapi.workspaces.v1.GetWorkspaceResponse'
delete:
tags:
- livekit.publicapi.workspaces.v1.WorkspaceService
summary: DeleteWorkspace
operationId: WorkspaceService_DeleteWorkspace
parameters:
- name: workspaceId
in: path
required: true
schema:
type: string
title: workspace_id
responses:
"200":
description: Success
content:
application/json:
schema:
$ref: '#/components/schemas/livekit.publicapi.workspaces.v1.DeleteWorkspaceResponse'
patch:
tags:
- livekit.publicapi.workspaces.v1.WorkspaceService
summary: UpdateWorkspace
operationId: WorkspaceService_UpdateWorkspace
parameters:
- name: workspaceId
in: path
required: true
schema:
type: string
title: workspace_id
requestBody:
content:
application/json:
schema:
type: object
properties:
name:
type:
- string
- "null"
title: name
title: UpdateWorkspaceRequest
additionalProperties: false
description: |-
Mirrors cloud-api WorkspaceService.UpdateWorkspace, which only accepts a
name: workspace preferences (hipaa_compliant) cascade to every project in the
workspace and are LK-admin-only there (AdminService.UpdateWorkspace), so they
are deliberately not settable on this path.
required: true
responses:
"200":
description: Success
content:
application/json:
schema:
$ref: '#/components/schemas/livekit.publicapi.workspaces.v1.UpdateWorkspaceResponse'
/v0/workspaces/{workspaceId}/invites:
get:
tags:
- livekit.publicapi.workspaces.v1.WorkspaceService
summary: ListInvites
operationId: WorkspaceService_ListInvites
parameters:
- name: workspaceId
in: path
required: true
schema:
type: string
title: workspace_id
responses:
"200":
description: Success
content:
application/json:
schema:
$ref: '#/components/schemas/livekit.publicapi.workspaces.v1.ListInvitesResponse'
post:
tags:
- livekit.publicapi.workspaces.v1.WorkspaceService
summary: CreateInvite
operationId: WorkspaceService_CreateInvite
parameters:
- name: workspaceId
in: path
required: true
schema:
type: string
title: workspace_id
requestBody:
content:
application/json:
schema:
type: object
properties:
email:
type: string
title: email
role:
type: integer
title: role
format: int32
title: CreateInviteRequest
additionalProperties: false
required: true
responses:
"200":
description: Success
content:
application/json:
schema:
$ref: '#/components/schemas/livekit.publicapi.workspaces.v1.CreateInviteResponse'
/v0/workspaces/{workspaceId}/invites/{email}:
delete:
tags:
- livekit.publicapi.workspaces.v1.WorkspaceService
summary: DeleteInvite
operationId: WorkspaceService_DeleteInvite
parameters:
- name: workspaceId
in: path
required: true
schema:
type: string
title: workspace_id
- name: email
in: path
required: true
schema:
type: string
title: email
responses:
"200":
description: Success
content:
application/json:
schema:
$ref: '#/components/schemas/livekit.publicapi.workspaces.v1.DeleteInviteResponse'
/v0/workspaces/{workspaceId}/members:
get:
tags:
- livekit.publicapi.workspaces.v1.WorkspaceService
summary: ListMembers
description: Members & invites (mirrors cloud WorkspaceService current flows).
operationId: WorkspaceService_ListMembers
parameters:
- name: workspaceId
in: path
required: true
schema:
type: string
title: workspace_id
responses:
"200":
description: Success
content:
application/json:
schema:
$ref: '#/components/schemas/livekit.publicapi.workspaces.v1.ListMembersResponse'
/v0/workspaces/{workspaceId}/members/{userId}:
get:
tags:
- livekit.publicapi.workspaces.v1.WorkspaceService
summary: GetMember
operationId: WorkspaceService_GetMember
parameters:
- name: workspaceId
in: path
required: true
schema:
type: string
title: workspace_id
- name: userId
in: path
required: true
schema:
type: string
title: user_id
responses:
"200":
description: Success
content:
application/json:
schema:
$ref: '#/components/schemas/livekit.publicapi.workspaces.v1.GetMemberResponse'
delete:
tags:
- livekit.publicapi.workspaces.v1.WorkspaceService
summary: DeleteMember
operationId: WorkspaceService_DeleteMember
parameters:
- name: workspaceId
in: path
required: true
schema:
type: string
title: workspace_id
- name: userId
in: path
required: true
schema:
type: string
title: user_id
responses:
"200":
description: Success
content:
application/json:
schema:
$ref: '#/components/schemas/livekit.publicapi.workspaces.v1.DeleteMemberResponse'
patch:
tags:
- livekit.publicapi.workspaces.v1.WorkspaceService
summary: UpdateMember
operationId: WorkspaceService_UpdateMember
parameters:
- name: workspaceId
in: path
required: true
schema:
type: string
title: workspace_id
- name: userId
in: path
required: true
schema:
type: string
title: user_id
requestBody:
content:
application/json:
schema:
type: object
properties:
role:
type: integer
title: role
format: int32
title: UpdateMemberRequest
additionalProperties: false
required: true
responses:
"200":
description: Success
content:
application/json:
schema:
$ref: '#/components/schemas/livekit.publicapi.workspaces.v1.UpdateMemberResponse'
/v0/workspaces/{workspaceId}/projects:
get:
tags:
- livekit.publicapi.workspaces.v1.WorkspaceService
summary: ListProjects
description: Project CRUD scoped to a workspace — responses owned by projects.v1.
operationId: WorkspaceService_ListProjects
parameters:
- name: workspaceId
in: path
required: true
schema:
type: string
title: workspace_id
- name: page.cursor
in: query
description: |-
Opaque cursor returned by a prior page (PageInfo.next_cursor). Empty starts
from the beginning.
schema:
type: string
title: cursor
- name: page.pageSize
in: query
description: Maximum items to return; 0 lets the server pick a default.
schema:
type: integer
title: page_size
format: int32
responses:
"200":
description: Success
content:
application/json:
schema:
$ref: '#/components/schemas/livekit.publicapi.projects.v1.ListProjectsResponse'
post:
tags:
- livekit.publicapi.workspaces.v1.WorkspaceService
summary: CreateProject
operationId: WorkspaceService_CreateProject
parameters:
- name: workspaceId
in: path
required: true
schema:
type: string
title: workspace_id
requestBody:
content:
application/json:
schema:
type: object
properties:
name:
type: string
title: name
subdomain:
type: string
title: subdomain
description: optional; generated from name when empty
isPrivate:
type: boolean
title: is_private
members:
type: array
items:
$ref: '#/components/schemas/livekit.publicapi.projects.v1.CreateProjectMember'
title: members
userDataRegion:
type: string
title: user_data_region
description: create-only; empty keeps the deployment default
title: CreateProjectRequest
additionalProperties: false
required: true
responses:
"200":
description: Success
content:
application/json:
schema:
$ref: '#/components/schemas/livekit.publicapi.projects.v1.CreateProjectResponse'
/v0/workspaces/{workspaceId}/projects/{projectId}:
get:
tags:
- livekit.publicapi.workspaces.v1.WorkspaceService
summary: GetProject
operationId: WorkspaceService_GetProject
parameters:
- name: workspaceId
in: path
required: true
schema:
type: string
title: workspace_id
- name: projectId
in: path
required: true
schema:
type: string
title: project_id
responses:
"200":
description: Success
content:
application/json:
schema:
$ref: '#/components/schemas/livekit.publicapi.projects.v1.GetProjectResponse'
delete:
tags:
- livekit.publicapi.workspaces.v1.WorkspaceService
summary: DeleteProject
operationId: WorkspaceService_DeleteProject
parameters:
- name: workspaceId
in: path
required: true
schema:
type: string
title: workspace_id
- name: projectId
in: path
required: true
schema:
type: string
title: project_id
responses:
"200":
description: Success
content:
application/json:
schema:
$ref: '#/components/schemas/livekit.publicapi.projects.v1.DeleteProjectResponse'
/v0/workspaces/{workspaceId}/projects/{update.projectId}:
patch:
tags:
- livekit.publicapi.workspaces.v1.WorkspaceService
summary: UpdateProject
operationId: WorkspaceService_UpdateProject
parameters:
- name: workspaceId
in: path
required: true
schema:
type: string
title: workspace_id
- name: update.projectId
in: path
required: true
schema:
type: string
title: project_id
requestBody:
description: |-
Nested projects.v1 update; the handler applies this request's workspace_id
as the store constraint.
content:
application/json:
schema:
title: update
description: |-
Nested projects.v1 update; the handler applies this request's workspace_id
as the store constraint.
$ref: '#/components/schemas/livekit.publicapi.projects.v1.UpdateProjectRequest'
responses:
"200":
description: Success
content:
application/json:
schema:
$ref: '#/components/schemas/livekit.publicapi.projects.v1.UpdateProjectResponse'
components:
schemas:
cloud_protocol.PIIRedactionCategory:
type: string
title: PIIRedactionCategory
enum:
- PII_REDACTION_CATEGORY_UNSPECIFIED
- PII_REDACTION_CATEGORY_ACCOUNT_NUMBER
- PII_REDACTION_CATEGORY_AGE
- PII_REDACTION_CATEGORY_BANK_ACCOUNT
- PII_REDACTION_CATEGORY_DATE
- PII_REDACTION_CATEGORY_DOB
- PII_REDACTION_CATEGORY_DRIVER_LICENSE
- PII_REDACTION_CATEGORY_EDUCATION_LEVEL
- PII_REDACTION_CATEGORY_EMAIL_ADDRESS
- PII_REDACTION_CATEGORY_GOVERNMENT_ID
- PII_REDACTION_CATEGORY_HEALTHCARE_NUMBER
- PII_REDACTION_CATEGORY_IP_ADDRESS
- PII_REDACTION_CATEGORY_LICENSE_PLATE
- PII_REDACTION_CATEGORY_LOCATION
- PII_REDACTION_CATEGORY_LOCATION_ADDRESS
- PII_REDACTION_CATEGORY_LOCATION_CITY
- PII_REDACTION_CATEGORY_LOCATION_COORDINATE
- PII_REDACTION_CATEGORY_LOCATION_COUNTRY
- PII_REDACTION_CATEGORY_LOCATION_STATE
- PII_REDACTION_CATEGORY_LOCATION_ZIP
- PII_REDACTION_CATEGORY_NAME
- PII_REDACTION_CATEGORY_NAME_GIVEN
- PII_REDACTION_CATEGORY_NAME_FAMILY
- PII_REDACTION_CATEGORY_NUMERICAL_PII
- PII_REDACTION_CATEGORY_OCCUPATION
- PII_REDACTION_CATEGORY_ORIGIN
- PII_REDACTION_CATEGORY_PASSPORT_NUMBER
- PII_REDACTION_CATEGORY_PASSWORD
- PII_REDACTION_CATEGORY_PHONE_NUMBER
- PII_REDACTION_CATEGORY_ROUTING_NUMBER
- PII_REDACTION_CATEGORY_SSN
- PII_REDACTION_CATEGORY_SWIFT_CODE
- PII_REDACTION_CATEGORY_URL
- PII_REDACTION_CATEGORY_USERNAME
- PII_REDACTION_CATEGORY_VEHICLE_ID
- PII_REDACTION_CATEGORY_CREDIT_CARD
- PII_REDACTION_CATEGORY_CREDIT_CARD_EXPIRATION
- PII_REDACTION_CATEGORY_CVV
- PII_REDACTION_CATEGORY_LANGUAGE
- PII_REDACTION_CATEGORY_ORGANIZATION
- PII_REDACTION_CATEGORY_POLITICAL_AFFILIATION
- PII_REDACTION_CATEGORY_RELIGION
description: |-
PIIRedactionCategory is the canonical taxonomy of PII entity types a project
may select for redaction. It is the shared contract across Cloud, backend,
and the dashboard so none of them need to import the redaction library.
Each value's name maps 1:1 to the snake_case identifier the redaction model
emits: strip the PII_REDACTION_CATEGORY_ prefix and lowercase (see
PIIRedactionCategory.Canonical in Go). A guard test in cloud-observability
asserts this set stays in sync with redact.KnownCategories.
Numbers are permanent and assigned in append order; never renumber or reuse
one. Add a new category with the next free number, then classify it via
PIIRedactionCategory.Class in Go.
google.protobuf.Duration:
type: string
pattern: '^-?(0|[1-9][0-9]*)(\.[0-9]{1,9})?s$'
examples:
- 86400s
- 1.500s
- 0.000000001s
description: |-
A span of time as protobuf JSON encodes it: seconds with an "s" suffix,
e.g. "86400s" for a day. Responses carry 0, 3, 6 or 9 fractional
digits ("1.500s", "0.000000001s"); requests may use 1 to 9. At most
315576000000 seconds either way. Not an ISO 8601 duration ("P1D" is
rejected).
google.protobuf.ListValue:
type: object
properties:
values:
type: array
items:
$ref: '#/components/schemas/google.protobuf.Value'
title: values
description: Repeated field of dynamically typed values.
title: ListValue
additionalProperties: false
description: Represents a JSON array.
google.protobuf.NullValue:
type: string
title: NullValue
enum:
- NULL_VALUE
description: |-
Represents a JSON `null`.
`NullValue` is a sentinel, using an enum with only one value to represent
the null value for the `Value` type union.
A field of type `NullValue` with any value other than `0` is considered
invalid. Most ProtoJSON serializers will emit a Value with a `null_value` set
as a JSON `null` regardless of the integer value, and so will round trip to
a `0` value.
google.protobuf.Struct:
type: object
additionalProperties:
$ref: '#/components/schemas/google.protobuf.Value'
description: |-
Represents a JSON object.
An unordered key-value map, intending to perfectly capture the semantics of a
JSON object. This enables parsing any arbitrary JSON payload as a message
field in ProtoJSON format.
This follows RFC 8259 guidelines for interoperable JSON: notably this type
cannot represent large Int64 values or `NaN`/`Infinity` numbers,
since the JSON format generally does not support those values in its number
type.
If you do not intend to parse arbitrary JSON into your message, a custom
typed message should be preferred instead of using this type.
google.protobuf.Struct.FieldsEntry:
type: object
properties:
key:
type: string
title: key
value:
title: value
$ref: '#/components/schemas/google.protobuf.Value'
title: FieldsEntry
additionalProperties: false
google.protobuf.Timestamp:
type: string
examples:
- "2023-01-15T01:30:15.01Z"
- "2024-12-25T12:00:00Z"
format: date-time
description: |-
A Timestamp represents a point in time independent of any time zone or local
calendar, encoded as a count of seconds and fractions of seconds at
nanosecond resolution. The count is relative to an epoch at UTC midnight on
January 1, 1970, in the proleptic Gregorian calendar which extends the
Gregorian calendar backwards to year one.
All minutes are 60 seconds long. Leap seconds are "smeared" so that no leap
second table is needed for interpretation, using a [24-hour linear
smear](https://developers.google.com/time/smear).
The range is from 0001-01-01T00:00:00Z to 9999-12-31T23:59:59.999999999Z. By
restricting to that range, we ensure that we can convert to and from [RFC
3339](https://www.ietf.org/rfc/rfc3339.txt) date strings.
# Examples
Example 1: Compute Timestamp from POSIX `time()`.
Timestamp timestamp;
timestamp.set_seconds(time(NULL));
timestamp.set_nanos(0);
Example 2: Compute Timestamp from POSIX `gettimeofday()`.
struct timeval tv;
gettimeofday(&tv, NULL);
Timestamp timestamp;
timestamp.set_seconds(tv.tv_sec);
timestamp.set_nanos(tv.tv_usec * 1000);
Example 3: Compute Timestamp from Win32 `GetSystemTimeAsFileTime()`.
FILETIME ft;
GetSystemTimeAsFileTime(&ft);
UINT64 ticks = (((UINT64)ft.dwHighDateTime) << 32) | ft.dwLowDateTime;
// A Windows tick is 100 nanoseconds. Windows epoch 1601-01-01T00:00:00Z
// is 11644473600 seconds before Unix epoch 1970-01-01T00:00:00Z.
Timestamp timestamp;
timestamp.set_seconds((INT64) ((ticks / 10000000) - 11644473600LL));
timestamp.set_nanos((INT32) ((ticks % 10000000) * 100));
Example 4: Compute Timestamp from Java `System.currentTimeMillis()`.
long millis = System.currentTimeMillis();
Timestamp timestamp = Timestamp.newBuilder().setSeconds(millis / 1000)
.setNanos((int) ((millis % 1000) * 1000000)).build();
Example 5: Compute Timestamp from Java `Instant.now()`.
Instant now = Instant.now();
Timestamp timestamp =
Timestamp.newBuilder().setSeconds(now.getEpochSecond())
.setNanos(now.getNano()).build();
Example 6: Compute Timestamp from current time in Python.
timestamp = Timestamp()
timestamp.GetCurrentTime()
# JSON Mapping
In JSON format, the Timestamp type is encoded as a string in the
[RFC 3339](https://www.ietf.org/rfc/rfc3339.txt) format. That is, the
format is "{year}-{month}-{day}T{hour}:{min}:{sec}[.{frac_sec}]Z"
where {year} is always expressed using four digits while {month}, {day},
{hour}, {min}, and {sec} are zero-padded to two digits each. The fractional
seconds, which can go up to 9 digits (i.e. up to 1 nanosecond resolution),
are optional. The "Z" suffix indicates the timezone ("UTC"); the timezone
is required. A ProtoJSON serializer should always use UTC (as indicated by
"Z") when printing the Timestamp type and a ProtoJSON parser should be
able to accept both UTC and other timezones (as indicated by an offset).
For example, "2017-01-15T01:30:15.01Z" encodes 15.01 seconds past
01:30 UTC on January 15, 2017.
In JavaScript, one can convert a Date object to this format using the
standard
[toISOString()](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Date/toISOString)
method. In Python, a standard `datetime.datetime` object can be converted
to this format using
[`strftime`](https://docs.python.org/2/library/time.html#time.strftime) with
the time format spec '%Y-%m-%dT%H:%M:%S.%fZ'. Likewise, in Java, one can use
the Joda Time's [`ISODateTimeFormat.dateTime()`](
http://joda-time.sourceforge.net/apidocs/org/joda/time/format/ISODateTimeFormat.html#dateTime()
) to obtain a formatter capable of generating timestamps in this format.
google.protobuf.Value:
oneOf:
- type: "null"
- type: number
- type: string
- type: boolean
- type: array
- type: object
additionalProperties: true
description: |-
Represents a JSON value.
`Value` represents a dynamically typed value which can be either
null, a number, a string, a boolean, a recursive struct value, or a
list of values. A producer of value is expected to set one of these
variants. Absence of any variant is an invalid state.
livekit.AgentDB.AgentDatabase:
type: object
properties:
databaseId:
type: string
title: database_id
region:
type: string
title: region
createdAt:
title: created_at
$ref: '#/components/schemas/google.protobuf.Timestamp'
expiresAt:
title: expires_at
$ref: '#/components/schemas/google.protobuf.Timestamp'
tip:
type:
- integer
- string
title: tip
format: int64
title: AgentDatabase
additionalProperties: false
description: One database, as get and list both report it.
livekit.AliOSSUpload:
type: object
properties:
accessKey:
type: string
title: access_key
secret:
type: string
title: secret
region:
type: string
title: region
endpoint:
type: string
title: endpoint
bucket:
type: string
title: bucket
title: AliOSSUpload
additionalProperties: false
livekit.AudioCodec:
type: string
title: AudioCodec
enum:
- DEFAULT_AC
- OPUS
- AAC
- AC_MP3
livekit.AudioMixing:
type: string
title: AudioMixing
enum:
- DEFAULT_MIXING
- DUAL_CHANNEL_AGENT
- DUAL_CHANNEL_ALTERNATE
livekit.AutoParticipantEgress:
type: object
allOf:
- properties:
fileOutputs:
type: array
items:
$ref: '#/components/schemas/livekit.EncodedFileOutput'
title: file_outputs
segmentOutputs:
type: array
items:
$ref: '#/components/schemas/livekit.SegmentedFileOutput'
title: segment_outputs
- oneOf:
- type: object
properties:
advanced:
title: advanced
description: (optional)
$ref: '#/components/schemas/livekit.EncodingOptions'
title: advanced
required:
- advanced
- type: object
properties:
preset:
title: preset
description: (default H264_720P_30)
$ref: '#/components/schemas/livekit.EncodingOptionsPreset'
title: preset
required:
- preset
- not:
anyOf:
- required:
- advanced
- required:
- preset
unevaluatedProperties: false
title: AutoParticipantEgress
livekit.AutoTrackEgress:
type: object
allOf:
- properties:
filepath:
type: string
title: filepath
description: see docs for templating (default {track_id}-{time})
disableManifest:
type: boolean
title: disable_manifest
description: disables upload of json manifest file (default false)
- oneOf:
- type: object
properties:
aliOSS:
title: aliOSS
$ref: '#/components/schemas/livekit.AliOSSUpload'
title: aliOSS
required:
- aliOSS
- type: object
properties:
azure:
title: azure
$ref: '#/components/schemas/livekit.AzureBlobUpload'
title: azure
required:
- azure
- type: object
properties:
gcp:
title: gcp
$ref: '#/components/schemas/livekit.GCPUpload'
title: gcp
required:
- gcp
- type: object
properties:
s3:
title: s3
$ref: '#/components/schemas/livekit.S3Upload'
title: s3
required:
- s3
- not:
anyOf:
- required:
- aliOSS
- required:
- azure
- required:
- gcp
- required:
- s3
unevaluatedProperties: false
title: AutoTrackEgress
livekit.AzureBlobUpload:
type: object
properties:
accountName:
type: string
title: account_name
accountKey:
type: string
title: account_key
containerName:
type: string
title: container_name
title: AzureBlobUpload
additionalProperties: false
livekit.EncodedFileOutput:
type: object
allOf:
- properties:
fileType:
title: file_type
$ref: '#/components/schemas/livekit.EncodedFileType'
filepath:
type: string
title: filepath
disableManifest:
type: boolean
title: disable_manifest
- oneOf:
- type: object
properties:
aliOSS:
title: aliOSS
$ref: '#/components/schemas/livekit.AliOSSUpload'
title: aliOSS
required:
- aliOSS
- type: object
properties:
azure:
title: azure
$ref: '#/components/schemas/livekit.AzureBlobUpload'
title: azure
required:
- azure
- type: object
properties:
gcp:
title: gcp
$ref: '#/components/schemas/livekit.GCPUpload'
title: gcp
required:
- gcp
- type: object
properties:
s3:
title: s3
$ref: '#/components/schemas/livekit.S3Upload'
title: s3
required:
- s3
- not:
anyOf:
- required:
- aliOSS
- required:
- azure
- required:
- gcp
- required:
- s3
unevaluatedProperties: false
title: EncodedFileOutput
livekit.EncodedFileType:
type: string
title: EncodedFileType
enum:
- DEFAULT_FILETYPE
- MP4
- OGG
- MP3
livekit.EncodingOptions:
type: object
properties:
width:
type: integer
title: width
format: int32
description: (default 1920)
height:
type: integer
title: height
format: int32
description: (default 1080)
depth:
type: integer
title: depth
format: int32
description: (default 24)
framerate:
type: integer
title: framerate
format: int32
description: (default 30)
audioCodec:
title: audio_codec
description: (default OPUS)
$ref: '#/components/schemas/livekit.AudioCodec'
audioBitrate:
type: integer
title: audio_bitrate
format: int32
description: (default 128)
audioFrequency:
type: integer
title: audio_frequency
format: int32
description: (default 44100)
videoCodec:
title: video_codec
description: (default H264_MAIN)
$ref: '#/components/schemas/livekit.VideoCodec'
videoBitrate:
type: integer
title: video_bitrate
format: int32
description: (default 4500)
keyFrameInterval:
type: number
title: key_frame_interval
format: double
description: in seconds (default 4s for streaming, segment duration for segmented output, encoder default for files)
audioQuality:
type: integer
title: audio_quality
format: int32
description: '--- Deprecated --- quality setting on audio encoder'
deprecated: true
videoQuality:
type: integer
title: video_quality
format: int32
description: quality setting on video encoder
deprecated: true
title: EncodingOptions
additionalProperties: false
livekit.EncodingOptionsPreset:
type: string
title: EncodingOptionsPreset
enum:
- H264_720P_30
- H264_720P_60
- H264_1080P_30
- H264_1080P_60
- PORTRAIT_H264_720P_30
- PORTRAIT_H264_720P_60
- PORTRAIT_H264_1080P_30
- PORTRAIT_H264_1080P_60
- PASSTHROUGH
livekit.FilterParams:
type: object
properties:
includeEvents:
type: array
items:
type: string
title: include_events
excludeEvents:
type: array
items:
type: string
title: exclude_events
title: FilterParams
additionalProperties: false
livekit.GCPUpload:
type: object
properties:
credentials:
type: string
title: credentials
description: service account credentials serialized in JSON "credentials.json"
bucket:
type: string
title: bucket
proxy:
title: proxy
$ref: '#/components/schemas/livekit.ProxyConfig'
title: GCPUpload
additionalProperties: false
livekit.ImageCodec:
type: string
title: ImageCodec
enum:
- IC_DEFAULT
- IC_JPEG
livekit.ImageFileSuffix:
type: string
title: ImageFileSuffix
enum:
- IMAGE_SUFFIX_INDEX
- IMAGE_SUFFIX_TIMESTAMP
- IMAGE_SUFFIX_NONE_OVERWRITE
livekit.ImageOutput:
type: object
allOf:
- properties:
captureInterval:
type: integer
title: capture_interval
description: in seconds (required)
width:
type: integer
title: width
format: int32
description: (optional, defaults to track width)
height:
type: integer
title: height
format: int32
description: (optional, defaults to track height)
filenamePrefix:
type: string
title: filename_prefix
description: (optional)
filenameSuffix:
title: filename_suffix
description: (optional, default INDEX)
$ref: '#/components/schemas/livekit.ImageFileSuffix'
imageCodec:
title: image_codec
description: (optional)
$ref: '#/components/schemas/livekit.ImageCodec'
disableManifest:
type: boolean
title: disable_manifest
description: disable upload of manifest file (default false)
- oneOf:
- type: object
properties:
aliOSS:
title: aliOSS
$ref: '#/components/schemas/livekit.AliOSSUpload'
title: aliOSS
required:
- aliOSS
- type: object
properties:
azure:
title: azure
$ref: '#/components/schemas/livekit.AzureBlobUpload'
title: azure
required:
- azure
- type: object
properties:
gcp:
title: gcp
$ref: '#/components/schemas/livekit.GCPUpload'
title: gcp
required:
- gcp
- type: object
properties:
s3:
title: s3
$ref: '#/components/schemas/livekit.S3Upload'
title: s3
required:
- s3
- not:
anyOf:
- required:
- aliOSS
- required:
- azure
- required:
- gcp
- required:
- s3
unevaluatedProperties: false
title: ImageOutput
description: Capture images at a specified interval
livekit.JobRestartPolicy:
type: string
title: JobRestartPolicy
enum:
- JRP_ON_FAILURE
- JRP_NEVER
livekit.PresignedPostRequest:
type: object
properties:
url:
type: string
title: url
values:
type: object
title: values
additionalProperties:
type: string
title: value
title: PresignedPostRequest
additionalProperties: false
livekit.PresignedPostRequest.ValuesEntry:
type: object
properties:
key:
type: string
title: key
value:
type: string
title: value
title: ValuesEntry
additionalProperties: false
livekit.ProxyConfig:
type: object
properties:
url:
type: string
title: url
username:
type: string
title: username
password:
type: string
title: password
title: ProxyConfig
additionalProperties: false
livekit.RoomAgentDispatch:
type: object
properties:
agentName:
type: string
title: agent_name
metadata:
type: string
title: metadata
restartPolicy:
title: restart_policy
description: cloud only
$ref: '#/components/schemas/livekit.JobRestartPolicy'
deployment:
type: string
title: deployment
attributes:
type: object
title: attributes
additionalProperties:
type: string
title: value
title: RoomAgentDispatch
additionalProperties: false
livekit.RoomAgentDispatch.AttributesEntry:
type: object
properties:
key:
type: string
title: key
value:
type: string
title: value
title: AttributesEntry
additionalProperties: false
livekit.RoomCompositeEgressRequest:
type: object
allOf:
- oneOf:
- type: object
properties:
advanced:
title: advanced
$ref: '#/components/schemas/livekit.EncodingOptions'
title: advanced
required:
- advanced
- type: object
properties:
preset:
title: preset
$ref: '#/components/schemas/livekit.EncodingOptionsPreset'
title: preset
required:
- preset
- not:
anyOf:
- required:
- advanced
- required:
- preset
- oneOf:
- type: object
properties:
file:
title: file
deprecated: true
$ref: '#/components/schemas/livekit.EncodedFileOutput'
title: file
required:
- file
- type: object
properties:
segments:
title: segments
deprecated: true
$ref: '#/components/schemas/livekit.SegmentedFileOutput'
title: segments
required:
- segments
- type: object
properties:
stream:
title: stream
deprecated: true
$ref: '#/components/schemas/livekit.StreamOutput'
title: stream
required:
- stream
- not:
anyOf:
- required:
- file
- required:
- segments
- required:
- stream
unevaluatedProperties: false
properties:
roomName:
type: string
title: room_name
layout:
type: string
title: layout
audioOnly:
type: boolean
title: audio_only
audioMixing:
title: audio_mixing
$ref: '#/components/schemas/livekit.AudioMixing'
videoOnly:
type: boolean
title: video_only
customBaseUrl:
type: string
title: custom_base_url
fileOutputs:
type: array
items:
$ref: '#/components/schemas/livekit.EncodedFileOutput'
title: file_outputs
streamOutputs:
type: array
items:
$ref: '#/components/schemas/livekit.StreamOutput'
title: stream_outputs
segmentOutputs:
type: array
items:
$ref: '#/components/schemas/livekit.SegmentedFileOutput'
title: segment_outputs
imageOutputs:
type: array
items:
$ref: '#/components/schemas/livekit.ImageOutput'
title: image_outputs
webhooks:
type: array
items:
$ref: '#/components/schemas/livekit.WebhookConfig'
title: webhooks
title: RoomCompositeEgressRequest
livekit.RoomConfiguration:
type: object
properties:
name:
type: string
title: name
description: Used as ID, must be unique
emptyTimeout:
type: integer
title: empty_timeout
description: number of seconds to keep the room open if no one joins
departureTimeout:
type: integer
title: departure_timeout
description: number of seconds to keep the room open after everyone leaves
maxParticipants:
type: integer
title: max_participants
description: limit number of participants that can be in a room, excluding Egress and Agent participants
metadata:
type: string
title: metadata
description: metadata of room
egress:
title: egress
description: egress
$ref: '#/components/schemas/livekit.RoomEgress'
minPlayoutDelay:
type: integer
title: min_playout_delay
description: playout delay of subscriber
maxPlayoutDelay:
type: integer
title: max_playout_delay
syncStreams:
type: boolean
title: sync_streams
description: |-
improves A/V sync when playout_delay set to a value larger than 200ms. It will disables transceiver re-use
so not recommended for rooms with frequent subscription changes
agents:
type: array
items:
$ref: '#/components/schemas/livekit.RoomAgentDispatch'
title: agents
description: Define agents that should be dispatched to this room
tags:
type: object
title: tags
additionalProperties:
type: string
title: value
description: Tags to attach to the room
title: RoomConfiguration
additionalProperties: false
livekit.RoomConfiguration.TagsEntry:
type: object
properties:
key:
type: string
title: key
value:
type: string
title: value
title: TagsEntry
additionalProperties: false
livekit.RoomEgress:
type: object
properties:
room:
title: room
$ref: '#/components/schemas/livekit.RoomCompositeEgressRequest'
participant:
title: participant
$ref: '#/components/schemas/livekit.AutoParticipantEgress'
tracks:
title: tracks
$ref: '#/components/schemas/livekit.AutoTrackEgress'
title: RoomEgress
additionalProperties: false
livekit.S3Upload:
type: object
properties:
accessKey:
type: string
title: access_key
secret:
type: string
title: secret
sessionToken:
type: string
title: session_token
assumeRoleArn:
type: string
title: assume_role_arn
description: ARN of the role to assume for file upload. Egress will make an AssumeRole API call using the provided access_key and secret to assume that role. On LiveKit cloud, this is only available on accounts that have the feature enabled
assumeRoleExternalId:
type: string
title: assume_role_external_id
description: ExternalID to use when assuming role for upload
region:
type: string
title: region
endpoint:
type: string
title: endpoint
bucket:
type: string
title: bucket
forcePathStyle:
type: boolean
title: force_path_style
metadata:
type: object
title: metadata
additionalProperties:
type: string
title: value
tagging:
type: string
title: tagging
contentDisposition:
type: string
title: content_disposition
description: Content-Disposition header
proxy:
title: proxy
$ref: '#/components/schemas/livekit.ProxyConfig'
title: S3Upload
additionalProperties: false
livekit.S3Upload.MetadataEntry:
type: object
properties:
key:
type: string
title: key
value:
type: string
title: value
title: MetadataEntry
additionalProperties: false
livekit.Scenario:
type: object
properties:
label:
type: string
title: label
instructions:
type: string
title: instructions
agentExpectations:
type: string
title: agent_expectations
tags:
type: object
title: tags
additionalProperties:
type: string
title: value
description: Set as participant attributes on the simulation participant's access token.
userdata:
type: string
title: userdata
description: |-
Arbitrary JSON-encoded object, surfaced to the agent under test as
SimulationContext userdata (e.g. inputs and benchmark target state).
id:
type: string
title: id
description: |-
SCN_-prefixed guid. Stable across edits to label, instructions, or
expectations, so runs of the same scenario can be correlated over time.
title: Scenario
additionalProperties: false
description: |-
A single scenario, mirroring one entry in a scenarios.yaml file. Scenarios
are no longer stored server-side; the yaml file is the source of truth.
livekit.Scenario.CreateFromSession:
type: object
title: CreateFromSession
additionalProperties: false
livekit.Scenario.CreateFromSession.Request:
type: object
properties:
projectId:
type: string
title: project_id
roomId:
type: string
title: room_id
region:
type: string
title: region
title: Request
additionalProperties: false
livekit.Scenario.CreateFromSession.Response:
type: object
properties:
scenario:
title: scenario
$ref: '#/components/schemas/livekit.Scenario'
title: Response
additionalProperties: false
livekit.Scenario.TagsEntry:
type: object
properties:
key:
type: string
title: key
value:
type: string
title: value
title: TagsEntry
additionalProperties: false
livekit.ScenarioGroup:
type: object
properties:
name:
type: string
title: name
scenarios:
type: array
items:
$ref: '#/components/schemas/livekit.Scenario'
title: scenarios
id:
type: string
title: id
description: |-
SCNG_-prefixed guid. Stable identity of the scenarios file, independent
of its name.
title: ScenarioGroup
additionalProperties: false
description: A named group of scenarios, mirroring a whole scenarios.yaml file.
livekit.SegmentedFileOutput:
type: object
allOf:
- properties:
protocol:
title: protocol
description: (optional)
$ref: '#/components/schemas/livekit.SegmentedFileProtocol'
filenamePrefix:
type: string
title: filename_prefix
description: (optional)
playlistName:
type: string
title: playlist_name
description: (optional)
livePlaylistName:
type: string
title: live_playlist_name
description: (optional, disabled if not provided). Path of a live playlist
segmentDuration:
type: integer
title: segment_duration
description: in seconds (optional)
filenameSuffix:
title: filename_suffix
description: (optional, default INDEX)
$ref: '#/components/schemas/livekit.SegmentedFileSuffix'
disableManifest:
type: boolean
title: disable_manifest
description: disable upload of manifest file (default false)
- oneOf:
- type: object
properties:
aliOSS:
title: aliOSS
$ref: '#/components/schemas/livekit.AliOSSUpload'
title: aliOSS
required:
- aliOSS
- type: object
properties:
azure:
title: azure
$ref: '#/components/schemas/livekit.AzureBlobUpload'
title: azure
required:
- azure
- type: object
properties:
gcp:
title: gcp
$ref: '#/components/schemas/livekit.GCPUpload'
title: gcp
required:
- gcp
- type: object
properties:
s3:
title: s3
$ref: '#/components/schemas/livekit.S3Upload'
title: s3
required:
- s3
- not:
anyOf:
- required:
- aliOSS
- required:
- azure
- required:
- gcp
- required:
- s3
unevaluatedProperties: false
title: SegmentedFileOutput
description: Used to generate HLS segments or other kind of segmented output
livekit.SegmentedFileProtocol:
type: string
title: SegmentedFileProtocol
enum:
- DEFAULT_SEGMENTED_FILE_PROTOCOL
- HLS_PROTOCOL
livekit.SegmentedFileSuffix:
type: string
title: SegmentedFileSuffix
enum:
- INDEX
- TIMESTAMP
livekit.SimulationMode:
type: string
title: SimulationMode
enum:
- SIMULATION_MODE_UNSPECIFIED
- SIMULATION_MODE_TEXT
- SIMULATION_MODE_AUDIO
description: How the simulated user interacts with the agent under test.
livekit.SimulationRun:
type: object
properties:
id:
type: string
title: id
projectId:
type: string
title: project_id
status:
title: status
$ref: '#/components/schemas/livekit.SimulationRun.Status'
agentDescription:
type: string
title: agent_description
error:
type: string
title: error
createdAt:
title: created_at
$ref: '#/components/schemas/google.protobuf.Timestamp'
jobs:
type: array
items:
$ref: '#/components/schemas/livekit.SimulationRun.Job'
title: jobs
agentName:
type: string
title: agent_name
scenarioGroup:
title: scenario_group
$ref: '#/components/schemas/livekit.ScenarioGroup'
endedAt:
title: ended_at
$ref: '#/components/schemas/google.protobuf.Timestamp'
jobCount:
type: integer
title: job_count
format: int32
passedCount:
type: integer
title: passed_count
format: int32
failedCount:
type: integer
title: failed_count
format: int32
numSimulations:
type: integer
title: num_simulations
format: int32
usage:
title: usage
description: Aggregate usage across all jobs in this run (sum of Job.usage).
$ref: '#/components/schemas/livekit.SimulationRun.Usage'
concurrency:
type: integer
title: concurrency
format: int32
description: Maximum simulate jobs running in parallel for this run (0 = server default).
mode:
title: mode
description: Conversation mode for every job in this run; unspecified = TEXT.
$ref: '#/components/schemas/livekit.SimulationMode'
metrics:
title: metrics
description: Run-level aggregates over this run's jobs.
$ref: '#/components/schemas/livekit.SimulationRun.RunMetrics'
summaryZstd:
type: string
title: summary_zstd
format: byte
description: |-
zstd-compressed SimulationRunSummary: decompress, then proto.Unmarshal.
Compressed by default so the blob ships as-is on every hop.
issueCount:
type:
- integer
- "null"
title: issue_count
format: int32
description: |-
How many issues the stored summary flagged. Present only once a summary
landed — absent and 0 differ ("never summarized" vs "no issues") — and
List responses carry it without the summary blob itself.
ci:
oneOf:
- $ref: '#/components/schemas/livekit.SimulationRun.CI'
- type: "null"
title: ci
description: The pipeline this run came from; unset when it did not come from one.
sampling:
oneOf:
- $ref: '#/components/schemas/livekit.SimulationRun.SamplingOptions'
- type: "null"
title: sampling
description: Absent when the run ran each scenario once and required it to pass.
title: SimulationRun
additionalProperties: false
livekit.SimulationRun.CI:
type: object
properties:
provider:
type: string
title: provider
description: e.g. "github_actions"
commitSha:
type: string
title: commit_sha
ref:
type: string
title: ref
description: branch or tag
pullRequest:
type: string
title: pull_request
runUrl:
type: string
title: run_url
description: link back to the CI job
actor:
type: string
title: actor
title: CI
additionalProperties: false
description: |-
The pipeline this run came from. Set by the client from its CI
environment; absent for runs not started by a pipeline.
livekit.SimulationRun.Cancel:
type: object
title: Cancel
additionalProperties: false
livekit.SimulationRun.Cancel.Request:
type: object
properties:
projectId:
type: string
title: project_id
simulationRunId:
type: string
title: simulation_run_id
title: Request
additionalProperties: false
livekit.SimulationRun.Cancel.Response:
type: object
title: Response
additionalProperties: false
livekit.SimulationRun.ConfirmSourceUpload:
type: object
title: ConfirmSourceUpload
additionalProperties: false
livekit.SimulationRun.ConfirmSourceUpload.Request:
type: object
properties:
projectId:
type: string
title: project_id
simulationRunId:
type: string
title: simulation_run_id
codeEntrypoint:
type: string
title: code_entrypoint
title: Request
additionalProperties: false
livekit.SimulationRun.ConfirmSourceUpload.Response:
type: object
title: Response
additionalProperties: false
livekit.SimulationRun.Counts:
type: object
title: Counts
additionalProperties: false
description: |-
Counts of the runs `List` would return over the same window, bucketed by
created_at instead of paginated.
livekit.SimulationRun.Counts.Bucket:
type: object
properties:
bucketStart:
title: bucket_start
$ref: '#/components/schemas/google.protobuf.Timestamp'
count:
type:
- integer
- string
title: count
format: int64
title: Bucket
additionalProperties: false
livekit.SimulationRun.Counts.Request:
type: object
properties:
projectId:
type: string
title: project_id
startTime:
title: start_time
description: |-
Both bounds required: a bucketed scan of a project's whole history is
never what a caller wants.
$ref: '#/components/schemas/google.protobuf.Timestamp'
endTime:
title: end_time
$ref: '#/components/schemas/google.protobuf.Timestamp'
status:
oneOf:
- $ref: '#/components/schemas/livekit.SimulationRun.Status'
- type: "null"
title: status
description: |-
Applied as `List` applies it: a filter the rows honour and the bars
above them drop would make the histogram an answer about a wider set.
agentName:
type:
- string
- "null"
title: agent_name
mode:
oneOf:
- $ref: '#/components/schemas/livekit.SimulationMode'
- type: "null"
title: mode
title: Request
additionalProperties: false
livekit.SimulationRun.Counts.Response:
type: object
properties:
buckets:
type: array
items:
$ref: '#/components/schemas/livekit.SimulationRun.Counts.Bucket'
title: buckets
description: |-
Buckets holding at least one run, ascending by bucket_start. Empty
buckets are omitted; each run lands in exactly one bucket, so the
counts sum to the number of runs in the window.
interval:
title: interval
description: |-
The bucket width the server chose from the window, so the client
zero-fills the omitted buckets on the grid the counts were built on.
$ref: '#/components/schemas/google.protobuf.Duration'
title: Response
additionalProperties: false
livekit.SimulationRun.Create:
type: object
title: Create
additionalProperties: false
livekit.SimulationRun.Create.Request:
type: object
properties:
projectId:
type: string
title: project_id
agentName:
type: string
title: agent_name
numSimulations:
type: integer
title: num_simulations
format: int32
region:
type: string
title: region
scenarioGroup:
oneOf:
- $ref: '#/components/schemas/livekit.ScenarioGroup'
- type: "null"
title: scenario_group
description: |-
When set, run these scenarios (loaded from a scenarios.yaml).
When unset, generate num_simulations scenarios from the uploaded agent source.
concurrency:
type:
- integer
- "null"
title: concurrency
format: int32
description: |-
Maximum simulate jobs running in parallel for this run. Clamped to the
project's concurrency quota; 0/unset uses the server default.
mode:
title: mode
description: Conversation mode for every job in this run; unspecified = TEXT.
$ref: '#/components/schemas/livekit.SimulationMode'
backgroundNoise:
type: boolean
title: background_noise
description: Impairments applied to the simulated user's audio; AUDIO mode only.
lowQualityMicrophone:
type: boolean
title: low_quality_microphone
packetLoss:
type: boolean
title: packet_loss
ci:
oneOf:
- $ref: '#/components/schemas/livekit.SimulationRun.CI'
- type: "null"
title: ci
sampling:
oneOf:
- $ref: '#/components/schemas/livekit.SimulationRun.SamplingOptions'
- type: "null"
title: sampling
description: |-
Absent runs each scenario once and requires it to pass. Requires
scenario_group. The run fails if any scenario fails; pass@k and
pass^k report over scenarios and neither gates.
title: Request
additionalProperties: false
livekit.SimulationRun.Create.Response:
type: object
properties:
simulationRunId:
type: string
title: simulation_run_id
presignedPostRequest:
title: presigned_post_request
$ref: '#/components/schemas/livekit.PresignedPostRequest'
title: Response
additionalProperties: false
livekit.SimulationRun.Get:
type: object
title: Get
additionalProperties: false
livekit.SimulationRun.Get.Request:
type: object
properties:
projectId:
type: string
title: project_id
simulationRunId:
type: string
title: simulation_run_id
title: Request
additionalProperties: false
livekit.SimulationRun.Get.Response:
type: object
properties:
run:
title: run
$ref: '#/components/schemas/livekit.SimulationRun'
title: Response
additionalProperties: false
livekit.SimulationRun.Job:
type: object
properties:
id:
type: string
title: id
status:
title: status
$ref: '#/components/schemas/livekit.SimulationRun.Job.Status'
instructions:
type: string
title: instructions
error:
type: string
title: error
agentExpectations:
type: string
title: agent_expectations
label:
type: string
title: label
tags:
type: array
items:
type: string
title: tags
roomName:
type: string
title: room_name
startedAt:
title: started_at
$ref: '#/components/schemas/google.protobuf.Timestamp'
endedAt:
title: ended_at
$ref: '#/components/schemas/google.protobuf.Timestamp'
roomId:
type: string
title: room_id
usage:
title: usage
$ref: '#/components/schemas/livekit.SimulationRun.Job.Usage'
metrics:
title: metrics
description: Quality metrics for this job's call. Unset when the job produced none.
$ref: '#/components/schemas/livekit.SimulationRun.JobMetrics'
scenarioId:
type: string
title: scenario_id
description: |-
The Scenario.id this job ran; empty for generated runs. Every sample
of one scenario shares it, so a run's jobs group back into scenarios.
sample:
type: integer
title: sample
format: int32
description: |-
1-based sample of that scenario within the run; always 1 when the run's
samples is 1.
title: Job
additionalProperties: false
livekit.SimulationRun.Job.Status:
type: string
title: Status
enum:
- STATUS_PENDING
- STATUS_RUNNING
- STATUS_COMPLETED
- STATUS_FAILED
- STATUS_CANCELLED
livekit.SimulationRun.Job.Usage:
type: object
properties:
textTurnsCount:
type: integer
title: text_turns_count
format: int32
audioTurnsCount:
type: integer
title: audio_turns_count
format: int32
title: Usage
additionalProperties: false
livekit.SimulationRun.JobMetrics:
type: object
properties:
taskCompletion:
type:
- number
- "null"
title: task_completion
format: float
description: the scenario verdict as 1/0
overallScore:
type:
- number
- "null"
title: overall_score
format: float
description: weighted mean of the judged and heard scores
stt:
title: stt
$ref: '#/components/schemas/livekit.SimulationRun.JobMetrics.STT'
llm:
title: llm
$ref: '#/components/schemas/livekit.SimulationRun.JobMetrics.LLM'
tts:
title: tts
$ref: '#/components/schemas/livekit.SimulationRun.JobMetrics.TTS'
conversation:
title: conversation
$ref: '#/components/schemas/livekit.SimulationRun.JobMetrics.Conversation'
turns:
type: array
items:
$ref: '#/components/schemas/livekit.SimulationRun.JobMetrics.Turn'
title: turns
description: One entry per turn, both speakers.
judgeModel:
type: string
title: judge_model
description: text judge for judged scores; "" if none ran
hasRemoteSession:
type: boolean
title: has_remote_session
description: false = waveform-only capture (e.g. SIP)
t0:
title: t0
description: audio only; call start (first speech edge); turn times relative to it
$ref: '#/components/schemas/google.protobuf.Timestamp'
conciseness:
type:
- number
- "null"
title: conciseness
format: float
description: Judged over the authored dialog (text and audio); needs the text judge. judged {0, 0.5, 1} per agent turn; job = mean
unnecessaryToolCalls:
type:
- boolean
- "null"
title: unnecessary_tool_calls
description: Whole-call issue flags; true = present, absent = not judged.
informationLoss:
type:
- boolean
- "null"
title: information_loss
redundantStatements:
type:
- boolean
- "null"
title: redundant_statements
poorQuestionQuality:
type:
- boolean
- "null"
title: poor_question_quality
conversationProgression:
type:
- number
- "null"
title: conversation_progression
format: float
description: 0-1, derived from the flags above
title: JobMetrics
additionalProperties: false
livekit.SimulationRun.JobMetrics.Conversation:
type: object
properties:
turnTakingScore:
type:
- number
- "null"
title: turn_taking_score
format: float
description: 0-1
heardE2eLatencyP50Ms:
type:
- integer
- "null"
title: heard_e2e_latency_p50_ms
format: int32
description: floor-transfer offset; a gap is > 0, an overlap < 0
heardE2eLatencyP95Ms:
type:
- integer
- "null"
title: heard_e2e_latency_p95_ms
format: int32
heardE2eLatencyP99Ms:
type:
- integer
- "null"
title: heard_e2e_latency_p99_ms
format: int32
timeToYieldMs:
type:
- integer
- "null"
title: time_to_yield_ms
description: agent audio continuing past a barge-in
eotMispredictionCount:
type:
- integer
- "null"
title: eot_misprediction_count
description: agent started before the caller's turn ended
overlapRatio:
type:
- number
- "null"
title: overlap_ratio
format: float
description: overlapping speech / total speech
overlapSpeechMs:
type:
- integer
- "null"
title: overlap_speech_ms
description: pooling stats for overlap_ratio
totalSpeechMs:
type:
- integer
- "null"
title: total_speech_ms
awkwardSilenceCount:
type:
- integer
- "null"
title: awkward_silence_count
description: gaps past the natural-pause threshold
unansweredTurns:
type:
- integer
- "null"
title: unanswered_turns
description: the simulated party spoke, the agent never responded
falseInterruptionCount:
type:
- integer
- "null"
title: false_interruption_count
description: needs the RemoteSession; agent paused for a non-interruption
e2eLatencyMs:
type:
- integer
- "null"
title: e2e_latency_ms
description: needs the RemoteSession; the agent's own claim
title: Conversation
additionalProperties: false
description: Audio only.
livekit.SimulationRun.JobMetrics.LLM:
type: object
properties:
ttftMs:
type:
- integer
- "null"
title: ttft_ms
description: needs the RemoteSession; time to first token
ttfsMs:
type:
- integer
- "null"
title: ttfs_ms
description: needs the RemoteSession; time to first sentence, the smallest speakable unit
tokensPerSecond:
type:
- number
- "null"
title: tokens_per_second
format: float
description: needs the RemoteSession
title: LLM
additionalProperties: false
livekit.SimulationRun.JobMetrics.STT:
type: object
properties:
wer:
type:
- number
- "null"
title: wer
format: float
description: needs the RemoteSession; word_errors / words
words:
type:
- integer
- "null"
title: words
description: needs the RemoteSession
wordErrors:
type:
- integer
- "null"
title: word_errors
description: needs the RemoteSession
cer:
type:
- number
- "null"
title: cer
format: float
description: needs the RemoteSession; char_errors / chars
chars:
type:
- integer
- "null"
title: chars
description: needs the RemoteSession
charErrors:
type:
- integer
- "null"
title: char_errors
description: needs the RemoteSession
sttDelayMs:
type:
- integer
- "null"
title: stt_delay_ms
description: needs the RemoteSession; agent-reported STT/endpointing delay
entityRecognition:
type:
- number
- "null"
title: entity_recognition
format: float
description: Key entities (names, IDs, amounts) the caller said. Needs the text judge. recognized / uttered
entitiesUttered:
type:
- integer
- "null"
title: entities_uttered
entitiesRecognized:
type:
- integer
- "null"
title: entities_recognized
entityRecall:
type:
- number
- "null"
title: entity_recall
format: float
description: |-
Retention: an entity is acquired at the first saying heard right, and
these count only the sayings after that, so recall separates keeping an
entity from ever getting it. acquired_recognized / acquired_uttered
entitiesAcquiredUttered:
type:
- integer
- "null"
title: entities_acquired_uttered
entitiesAcquiredRecognized:
type:
- integer
- "null"
title: entities_acquired_recognized
title: STT
additionalProperties: false
description: The agent's perception of the caller. Audio only.
livekit.SimulationRun.JobMetrics.TTS:
type: object
properties:
ttfbMs:
type:
- integer
- "null"
title: ttfb_ms
description: needs the RemoteSession; provider byte-level TTFB
wer:
type:
- number
- "null"
title: wer
format: float
description: needs the RemoteSession; word_errors / words
words:
type:
- integer
- "null"
title: words
description: needs the RemoteSession
wordErrors:
type:
- integer
- "null"
title: word_errors
description: needs the RemoteSession
cer:
type:
- number
- "null"
title: cer
format: float
description: needs the RemoteSession; char_errors / chars
chars:
type:
- integer
- "null"
title: chars
description: needs the RemoteSession
charErrors:
type:
- integer
- "null"
title: char_errors
description: needs the RemoteSession
entityRecognition:
type:
- number
- "null"
title: entity_recognition
format: float
description: Key entities the agent said, as the caller heard them. Needs the text judge. recognized / uttered
entitiesUttered:
type:
- integer
- "null"
title: entities_uttered
entitiesRecognized:
type:
- integer
- "null"
title: entities_recognized
entityRecall:
type:
- number
- "null"
title: entity_recall
format: float
description: acquired_recognized / acquired_uttered
entitiesAcquiredUttered:
type:
- integer
- "null"
title: entities_acquired_uttered
entitiesAcquiredRecognized:
type:
- integer
- "null"
title: entities_acquired_recognized
title: TTS
additionalProperties: false
description: The agent's voice. Audio only.
livekit.SimulationRun.JobMetrics.Turn:
type: object
properties:
index:
type: integer
title: index
description: 1-based, conversation order
role:
title: role
description: ASSISTANT = the agent under test, USER = simulator persona
$ref: '#/components/schemas/livekit.agent.ChatRole'
startMs:
type:
- integer
- "null"
title: start_ms
description: audio only; relative to t0; unset if the turn could not be aligned to the audio
endMs:
type:
- integer
- "null"
title: end_ms
description: audio only
sttDelayMs:
type:
- integer
- "null"
title: stt_delay_ms
description: needs the RemoteSession
llmTtftMs:
type:
- integer
- "null"
title: llm_ttft_ms
description: needs the RemoteSession
llmTtfsMs:
type:
- integer
- "null"
title: llm_ttfs_ms
description: needs the RemoteSession
llmTps:
type:
- number
- "null"
title: llm_tps
format: float
description: needs the RemoteSession
ttsTtfbMs:
type:
- integer
- "null"
title: tts_ttfb_ms
description: needs the RemoteSession
e2eLatencyMs:
type:
- integer
- "null"
title: e2e_latency_ms
description: needs the RemoteSession
heardE2eLatencyMs:
type:
- integer
- "null"
title: heard_e2e_latency_ms
format: int32
timeToYieldMs:
type:
- integer
- "null"
title: time_to_yield_ms
turnTakingScore:
type:
- number
- "null"
title: turn_taking_score
format: float
conciseness:
type:
- number
- "null"
title: conciseness
format: float
description: needs the text judge
eotMisprediction:
type:
- boolean
- "null"
title: eot_misprediction
awkwardSilence:
type:
- boolean
- "null"
title: awkward_silence
unanswered:
type:
- boolean
- "null"
title: unanswered
title: Turn
additionalProperties: false
description: |-
Rows exist for text and audio. The groups above hold the means and pools
over these; anything not measured for a turn stays unset.
livekit.SimulationRun.List:
type: object
title: List
additionalProperties: false
livekit.SimulationRun.List.Request:
type: object
properties:
projectId:
type: string
title: project_id
status:
oneOf:
- $ref: '#/components/schemas/livekit.SimulationRun.Status'
- type: "null"
title: status
pageToken:
oneOf:
- $ref: '#/components/schemas/livekit.TokenPagination'
- type: "null"
title: page_token
startTime:
oneOf:
- $ref: '#/components/schemas/google.protobuf.Timestamp'
- type: "null"
title: start_time
description: |-
Half-open window [start_time, end_time) on created_at, the leading key
of this list's keyset. Unset bounds mean no window, so existing callers
keep their unbounded scan; the histogram's selected range sets both.
endTime:
oneOf:
- $ref: '#/components/schemas/google.protobuf.Timestamp'
- type: "null"
title: end_time
agentName:
type:
- string
- "null"
title: agent_name
description: |-
Exact agent name. Unset means every agent — including the runs whose
name is empty, which a bare string could not tell from no filter.
mode:
oneOf:
- $ref: '#/components/schemas/livekit.SimulationMode'
- type: "null"
title: mode
description: |-
Absent applies no mode filter. TEXT matches runs stored as TEXT or
UNSPECIFIED, which `SimulationRun.mode` defines as the same mode.
title: Request
additionalProperties: false
livekit.SimulationRun.List.Response:
type: object
properties:
runs:
type: array
items:
$ref: '#/components/schemas/livekit.SimulationRun'
title: runs
nextPageToken:
title: next_page_token
$ref: '#/components/schemas/livekit.TokenPagination'
title: Response
additionalProperties: false
livekit.SimulationRun.RunMetrics:
type: object
properties:
scenarioPassRate:
type:
- number
- "null"
title: scenario_pass_rate
format: float
description: share of jobs whose scenario verdict passed
overallScore:
type:
- number
- "null"
title: overall_score
format: float
description: mean over scored jobs
stt:
title: stt
$ref: '#/components/schemas/livekit.SimulationRun.JobMetrics.STT'
llm:
title: llm
$ref: '#/components/schemas/livekit.SimulationRun.JobMetrics.LLM'
tts:
title: tts
$ref: '#/components/schemas/livekit.SimulationRun.JobMetrics.TTS'
conversation:
title: conversation
$ref: '#/components/schemas/livekit.SimulationRun.JobMetrics.Conversation'
conciseness:
type:
- number
- "null"
title: conciseness
format: float
description: Means over the jobs that report them.
conversationProgression:
type:
- number
- "null"
title: conversation_progression
format: float
title: RunMetrics
additionalProperties: false
description: |-
Aggregates over this run's jobs, so a run summary does not have to pull
every job and turn. Reuses the JobMetrics group shapes.
livekit.SimulationRun.SamplingOptions:
type: object
properties:
samples:
type: integer
title: samples
format: int32
description: |-
Samples per scenario, > 1. The run holds scenarios × samples jobs,
subject to the usual job cap.
passRate:
type: number
title: pass_rate
format: double
description: |-
The share of a scenario's samples that must pass for that scenario to
pass, 0-1. A scenario needs round(rate × samples) of them, so 1
requires every sample and 0.67 of 3 requires 2.
title: SamplingOptions
additionalProperties: false
description: |-
Runs each scenario more than once, so a flaky sample is distinguishable
from a broken scenario. Both fields are required when it is present.
livekit.SimulationRun.Status:
type: string
title: Status
enum:
- STATUS_PENDING_UPLOAD
- STATUS_GENERATING
- STATUS_RUNNING
- STATUS_SUMMARIZING
- STATUS_COMPLETED
- STATUS_FAILED
- STATUS_CANCELLED
livekit.SimulationRun.Usage:
type: object
properties:
textTurnsCount:
type: integer
title: text_turns_count
format: int32
audioTurnsCount:
type: integer
title: audio_turns_count
format: int32
title: Usage
additionalProperties: false
livekit.SimulationRunSummary:
type: object
properties:
passed:
type: integer
title: passed
format: int32
failed:
type: integer
title: failed
format: int32
goingWell:
type: string
title: going_well
toImprove:
type: string
title: to_improve
issues:
type: array
items:
$ref: '#/components/schemas/livekit.SimulationRunSummary.Issue'
title: issues
chatHistory:
type: object
title: chat_history
additionalProperties:
title: value
$ref: '#/components/schemas/livekit.agent.ChatContext'
title: SimulationRunSummary
additionalProperties: false
livekit.SimulationRunSummary.ChatHistoryEntry:
type: object
properties:
key:
type: string
title: key
value:
title: value
$ref: '#/components/schemas/livekit.agent.ChatContext'
title: ChatHistoryEntry
additionalProperties: false
livekit.SimulationRunSummary.Issue:
type: object
properties:
description:
type: string
title: description
suggestion:
type: string
title: suggestion
label:
type: string
title: label
title: Issue
additionalProperties: false
livekit.StreamOutput:
type: object
properties:
protocol:
title: protocol
description: required
$ref: '#/components/schemas/livekit.StreamProtocol'
urls:
type: array
items:
type: string
title: urls
description: required
title: StreamOutput
additionalProperties: false
livekit.StreamProtocol:
type: string
title: StreamProtocol
enum:
- DEFAULT_PROTOCOL
- RTMP
- SRT
- WEBSOCKET
livekit.TokenPagination:
type: object
properties:
token:
type: string
title: token
title: TokenPagination
additionalProperties: false
livekit.VideoCodec:
type: string
title: VideoCodec
enum:
- DEFAULT_VC
- H264_BASELINE
- H264_MAIN
- H264_HIGH
- VP8
livekit.WebhookConfig:
type: object
properties:
url:
type: string
title: url
signingKey:
type: string
title: signing_key
filterParams:
title: filter_params
$ref: '#/components/schemas/livekit.FilterParams'
title: WebhookConfig
additionalProperties: false
livekit.agent.AgentConfigUpdate:
type: object
properties:
id:
type: string
title: id
instructions:
type:
- string
- "null"
title: instructions
toolsAdded:
type: array
items:
type: string
title: tools_added
toolsRemoved:
type: array
items:
type: string
title: tools_removed
createdAt:
title: created_at
$ref: '#/components/schemas/google.protobuf.Timestamp'
title: AgentConfigUpdate
additionalProperties: false
livekit.agent.AgentHandoff:
type: object
properties:
id:
type: string
title: id
oldAgentId:
type:
- string
- "null"
title: old_agent_id
newAgentId:
type: string
title: new_agent_id
createdAt:
title: created_at
$ref: '#/components/schemas/google.protobuf.Timestamp'
title: AgentHandoff
additionalProperties: false
livekit.agent.AgentTask.Status:
type: string
title: Status
enum:
- UNSPECIFIED
- RUNNING
- COMPLETED
- FAILED
- CANCELED
description: A task is never UNSPECIFIED.
livekit.agent.AgentTask.Task:
type: object
properties:
taskId:
type: string
title: task_id
threadId:
type: string
title: thread_id
name:
type: string
title: name
description: The task's name, as the agent defines it.
status:
title: status
$ref: '#/components/schemas/livekit.agent.AgentTask.Status'
updatedAt:
title: updated_at
$ref: '#/components/schemas/google.protobuf.Timestamp'
title: Task
additionalProperties: false
livekit.agent.AgentThread.Item:
type: object
properties:
agent:
type: string
title: agent
seq:
type:
- integer
- string
title: seq
format: int64
description: Position in the agent's history.
messageId:
type: string
title: message_id
description: The A2A message the item came from.
item:
title: item
$ref: '#/components/schemas/livekit.agent.ChatContext.ChatItem'
title: Item
additionalProperties: false
description: |-
One chat item of an agent. Stored as the JSON of
ChatContext.ChatItem (items.payload in thread_schema_v1.sql).
livekit.agent.AgentThread.Thread:
type: object
properties:
threadId:
type: string
title: thread_id
scope:
type: string
title: scope
attributes:
type: object
title: attributes
additionalProperties:
type: string
title: value
createdAt:
title: created_at
$ref: '#/components/schemas/google.protobuf.Timestamp'
lastActive:
title: last_active
$ref: '#/components/schemas/google.protobuf.Timestamp'
expiresAt:
title: expires_at
description: |-
last_active + idle_ttl; every update pushes it out. The thread and its
database are deleted once it passes.
$ref: '#/components/schemas/google.protobuf.Timestamp'
idleTtl:
title: idle_ttl
$ref: '#/components/schemas/google.protobuf.Duration'
databaseId:
type: string
title: database_id
description: The thread's database ("DB_..."), created with the thread.
title: Thread
additionalProperties: false
livekit.agent.AgentThread.Thread.AttributesEntry:
type: object
properties:
key:
type: string
title: key
value:
type: string
title: value
title: AttributesEntry
additionalProperties: false
livekit.agent.ChatContext:
type: object
properties:
items:
type: array
items:
$ref: '#/components/schemas/livekit.agent.ChatContext.ChatItem'
title: items
title: ChatContext
additionalProperties: false
livekit.agent.ChatContext.ChatItem:
type: object
oneOf:
- type: object
properties:
agentConfigUpdate:
title: agent_config_update
$ref: '#/components/schemas/livekit.agent.AgentConfigUpdate'
title: agent_config_update
required:
- agentConfigUpdate
- type: object
properties:
agentHandoff:
title: agent_handoff
$ref: '#/components/schemas/livekit.agent.AgentHandoff'
title: agent_handoff
required:
- agentHandoff
- type: object
properties:
functionCall:
title: function_call
$ref: '#/components/schemas/livekit.agent.FunctionCall'
title: function_call
required:
- functionCall
- type: object
properties:
functionCallOutput:
title: function_call_output
$ref: '#/components/schemas/livekit.agent.FunctionCallOutput'
title: function_call_output
required:
- functionCallOutput
- type: object
properties:
message:
title: message
$ref: '#/components/schemas/livekit.agent.ChatMessage'
title: message
required:
- message
- not:
anyOf:
- required:
- agentConfigUpdate
- required:
- agentHandoff
- required:
- functionCall
- required:
- functionCallOutput
- required:
- message
unevaluatedProperties: false
title: ChatItem
livekit.agent.ChatMessage:
type: object
properties:
id:
type: string
title: id
role:
title: role
$ref: '#/components/schemas/livekit.agent.ChatRole'
content:
type: array
items:
$ref: '#/components/schemas/livekit.agent.ChatMessage.ChatContent'
title: content
interrupted:
type: boolean
title: interrupted
transcriptConfidence:
type:
- number
- "null"
title: transcript_confidence
format: double
extra:
type: object
title: extra
additionalProperties:
type: string
title: value
metrics:
title: metrics
$ref: '#/components/schemas/livekit.agent.MetricsReport'
createdAt:
title: created_at
$ref: '#/components/schemas/google.protobuf.Timestamp'
title: ChatMessage
additionalProperties: false
livekit.agent.ChatMessage.ChatContent:
type: object
oneOf:
- type: object
properties:
text:
type: string
title: text
title: text
required:
- text
- not:
anyOf:
- required:
- text
unevaluatedProperties: false
title: ChatContent
livekit.agent.ChatMessage.ExtraEntry:
type: object
properties:
key:
type: string
title: key
value:
type: string
title: value
title: ExtraEntry
additionalProperties: false
livekit.agent.ChatRole:
type: string
title: ChatRole
enum:
- DEVELOPER
- SYSTEM
- USER
- ASSISTANT
livekit.agent.FunctionCall:
type: object
properties:
id:
type: string
title: id
callId:
type: string
title: call_id
arguments:
type: string
title: arguments
name:
type: string
title: name
createdAt:
title: created_at
$ref: '#/components/schemas/google.protobuf.Timestamp'
title: FunctionCall
additionalProperties: false
livekit.agent.FunctionCallOutput:
type: object
properties:
id:
type: string
title: id
name:
type: string
title: name
callId:
type: string
title: call_id
output:
type: string
title: output
isError:
type: boolean
title: is_error
createdAt:
title: created_at
$ref: '#/components/schemas/google.protobuf.Timestamp'
title: FunctionCallOutput
additionalProperties: false
livekit.agent.MetricsReport:
type: object
properties:
startedSpeakingAt:
title: started_speaking_at
$ref: '#/components/schemas/google.protobuf.Timestamp'
stoppedSpeakingAt:
title: stopped_speaking_at
$ref: '#/components/schemas/google.protobuf.Timestamp'
transcriptionDelay:
type:
- number
- "null"
title: transcription_delay
format: double
endOfTurnDelay:
type:
- number
- "null"
title: end_of_turn_delay
format: double
onUserTurnCompletedDelay:
type:
- number
- "null"
title: on_user_turn_completed_delay
format: double
llmNodeTtft:
type:
- number
- "null"
title: llm_node_ttft
format: double
ttsNodeTtfb:
type:
- number
- "null"
title: tts_node_ttfb
format: double
e2eLatency:
type:
- number
- "null"
title: e2e_latency
format: double
llmNodeTps:
type:
- number
- "null"
title: llm_node_tps
format: double
llmNodeTtfs:
type:
- number
- "null"
title: llm_node_ttfs
format: double
title: MetricsReport
additionalProperties: false
livekit.publicapi.analytics.v1.AgentAnalytics:
type: object
properties:
agentId:
type: string
title: agent_id
agentName:
type: string
title: agent_name
region:
type: string
title: region
status:
type: string
title: status
sessions:
title: sessions
$ref: '#/components/schemas/livekit.publicapi.analytics.v1.AgentAnalytics.Sessions'
performance:
title: performance
$ref: '#/components/schemas/livekit.publicapi.analytics.v1.AgentAnalytics.Performance'
usage:
title: usage
$ref: '#/components/schemas/livekit.publicapi.analytics.v1.AgentAnalytics.Usage'
title: AgentAnalytics
additionalProperties: false
description: |-
AgentAnalytics is one agent's analytics over a time range. Common concerns are
grouped so they read the same whether you fetch one agent or the whole roster:
`sessions`, `performance`, and `usage` are always found under those names.
livekit.publicapi.analytics.v1.AgentAnalytics.Performance:
type: object
properties:
interruptedRate:
type: number
title: interrupted_rate
format: double
description: Fraction 0..1 of turns the user interrupted the agent.
turns:
type:
- integer
- string
title: turns
format: int64
latency:
title: latency
$ref: '#/components/schemas/livekit.publicapi.analytics.v1.LatencyBreakdown'
joinLatency:
title: join_latency
$ref: '#/components/schemas/livekit.publicapi.analytics.v1.Percentiles'
title: Performance
additionalProperties: false
livekit.publicapi.analytics.v1.AgentAnalytics.Sessions:
type: object
properties:
total:
type:
- integer
- string
title: total
format: int64
active:
type:
- integer
- string
title: active
format: int64
dispatchErrors:
type:
- integer
- string
title: dispatch_errors
format: int64
estimate:
title: estimate
description: Set when `total` is an approximation; carries its tolerance.
$ref: '#/components/schemas/livekit.publicapi.analytics.v1.Estimate'
title: Sessions
additionalProperties: false
livekit.publicapi.analytics.v1.AgentAnalytics.Usage:
type: object
properties:
avgTokensPerSession:
type:
- integer
- string
title: avg_tokens_per_session
format: int64
models:
type: array
items:
$ref: '#/components/schemas/livekit.publicapi.analytics.v1.ModelUsage'
title: models
title: Usage
additionalProperties: false
livekit.publicapi.analytics.v1.Agents.Get.Request:
type: object
properties:
projectId:
type: string
title: project_id
agentId:
type: string
title: agent_id
range:
title: range
$ref: '#/components/schemas/livekit.publicapi.analytics.v1.TimeRange'
title: Request
additionalProperties: false
livekit.publicapi.analytics.v1.Agents.Get.Response:
type: object
properties:
analytics:
title: analytics
$ref: '#/components/schemas/livekit.publicapi.analytics.v1.AgentAnalytics'
title: Response
additionalProperties: false
livekit.publicapi.analytics.v1.Agents.List.Request:
type: object
properties:
projectId:
type: string
title: project_id
range:
title: range
$ref: '#/components/schemas/livekit.publicapi.analytics.v1.TimeRange'
page:
title: page
$ref: '#/components/schemas/livekit.publicapi.common.v1.PageRequest'
title: Request
additionalProperties: false
livekit.publicapi.analytics.v1.Agents.List.Response:
type: object
properties:
items:
type: array
items:
$ref: '#/components/schemas/livekit.publicapi.analytics.v1.AgentAnalytics'
title: items
pageInfo:
title: page_info
$ref: '#/components/schemas/livekit.publicapi.common.v1.PageInfo'
title: Response
additionalProperties: false
livekit.publicapi.analytics.v1.CountryCount:
type: object
properties:
name:
type: string
title: name
count:
type:
- integer
- string
title: count
format: int64
title: CountryCount
additionalProperties: false
description: CountryCount is a per-country connection count for the top-countries breakdown.
livekit.publicapi.analytics.v1.DataPoint:
type: object
properties:
timestamp:
title: timestamp
$ref: '#/components/schemas/google.protobuf.Timestamp'
value:
type: number
title: value
format: double
title: DataPoint
additionalProperties: false
description: DataPoint is one point of a per-session time series (quality, bandwidth, fps).
livekit.publicapi.analytics.v1.Estimate:
type: object
properties:
isEstimate:
type: boolean
title: is_estimate
errorMargin:
type: number
title: error_margin
format: double
description: Fractional tolerance (e.g. 0.01 for +/-1%). Zero when unknown.
title: Estimate
additionalProperties: false
description: |-
Estimate flags a value that is approximate over large windows, with its
tolerance. A consumer should not treat an estimated value as exact.
livekit.publicapi.analytics.v1.LatencyBreakdown:
type: object
properties:
sttDelayMs:
type: number
title: stt_delay_ms
format: double
eouMs:
type: number
title: eou_ms
format: double
llmTtftMs:
type: number
title: llm_ttft_ms
format: double
ttsTtfbMs:
type: number
title: tts_ttfb_ms
format: double
avgReplyMs:
type: number
title: avg_reply_ms
format: double
title: LatencyBreakdown
additionalProperties: false
description: LatencyBreakdown is where an average agent reply's time goes, in milliseconds.
livekit.publicapi.analytics.v1.ModelUsage:
type: object
properties:
provider:
type: string
title: provider
model:
type: string
title: model
component:
type: string
title: component
requests:
type:
- integer
- string
title: requests
format: int64
sessions:
type:
- integer
- string
title: sessions
format: int64
latencyP50Ms:
type: number
title: latency_p50_ms
format: double
latencyP95Ms:
type: number
title: latency_p95_ms
format: double
inTokens:
type:
- integer
- string
title: in_tokens
format: int64
outTokens:
type:
- integer
- string
title: out_tokens
format: int64
cachedTokens:
type:
- integer
- string
title: cached_tokens
format: int64
ttsChars:
type:
- integer
- string
title: tts_chars
format: int64
title: ModelUsage
additionalProperties: false
description: |-
ModelUsage is per-model usage over the window. `component` is the stage the
model served (llm, tts, realtime); latency is TTFT for llm/realtime rows and
TTFB for tts rows.
livekit.publicapi.analytics.v1.ParticipantInfo:
type: object
properties:
participantIdentity:
type: string
title: participant_identity
participantName:
type: string
title: participant_name
joinedAt:
title: joined_at
description: First join across the identity's connections.
$ref: '#/components/schemas/google.protobuf.Timestamp'
leftAt:
title: left_at
description: |-
Last leave across the identity's connections; unset while no leave is
recorded, so a participant of an active session with no left_at may still
be connected.
$ref: '#/components/schemas/google.protobuf.Timestamp'
publishedSources:
title: published_sources
description: Which track sources the participant published during the session.
$ref: '#/components/schemas/livekit.publicapi.analytics.v1.PublishedSources'
location:
type: string
title: location
description: Country name, e.g. "United States"; "Unknown" when the rollup has none.
region:
type: string
title: region
description: LiveKit region display name; "Unknown" when the region isn't recognized.
sessions:
type: array
items:
$ref: '#/components/schemas/livekit.publicapi.analytics.v1.ParticipantSession'
title: sessions
description: |-
The participant's participant sessions, oldest join first: one per
connection, so each reconnect adds one. At most 50: a participant that
reconnected more often has its oldest 50 here. Empty when they couldn't be
read; the rest of the row still returns.
title: ParticipantInfo
additionalProperties: false
description: |-
ParticipantInfo is one participant identity of a room session, as the
dashboard's participants table shows it.
livekit.publicapi.analytics.v1.ParticipantSession:
type: object
properties:
participantSessionId:
type: string
title: participant_session_id
description: The participant session id (PA_...).
joinedAt:
title: joined_at
description: When this participant session joined.
$ref: '#/components/schemas/google.protobuf.Timestamp'
leftAt:
title: left_at
description: When it left; unset while no leave is recorded.
$ref: '#/components/schemas/google.protobuf.Timestamp'
durationSeconds:
type:
- integer
- string
title: duration_seconds
format: int64
description: |-
Seconds from joined_at to left_at, as the dashboard counts them. While no
leave is recorded, to the session's end once it has one, else to now.
location:
type: string
title: location
description: Country name, e.g. "United States"; "Unknown" when the rollup has none.
region:
type: string
title: region
description: LiveKit region display name; "Unknown" when the region isn't recognized.
connectionType:
type: string
title: connection_type
description: |-
Transport the client connected over: "UDP", "TCP" or "TURN"; empty when
not reported.
connectionTimeMs:
type: integer
title: connection_time_ms
format: int32
description: Milliseconds the client took to connect.
deviceModel:
type: string
title: device_model
description: Client device model, e.g. "iPhone 15".
os:
type: string
title: os
description: |-
Client operating system: "ios", "android", "windows", "mac" or "linux";
empty when not reported.
browser:
type: string
title: browser
description: Client browser, e.g. "chrome".
sdkVersion:
type: string
title: sdk_version
description: LiveKit client SDK version, e.g. "2.6.1". The SDK's name isn't recorded.
title: ParticipantSession
additionalProperties: false
description: |-
ParticipantSession is one participant session of a participant: one
join-to-leave stretch, identified by its participant session id (PA_...),
with the client it connected from. A participant that reconnects, from the
same device or another, has several.
livekit.publicapi.analytics.v1.ParticipantSortField:
type: string
title: ParticipantSortField
enum:
- PARTICIPANT_SORT_FIELD_UNSPECIFIED
- PARTICIPANT_SORT_FIELD_JOINED_AT
- PARTICIPANT_SORT_FIELD_LEFT_AT
description: ParticipantSortField is the column a participant listing is ordered by.
livekit.publicapi.analytics.v1.Percentiles:
type: object
properties:
p50Ms:
type: number
title: p50_ms
format: double
p90Ms:
type: number
title: p90_ms
format: double
p99Ms:
type: number
title: p99_ms
format: double
title: Percentiles
additionalProperties: false
description: Percentiles is a p50/p90/p99 triple in milliseconds.
livekit.publicapi.analytics.v1.PlatformShare:
type: object
properties:
name:
type: string
title: name
share:
type: number
title: share
format: double
title: PlatformShare
additionalProperties: false
description: PlatformShare is a per-platform share of connections (fraction 0..1).
livekit.publicapi.analytics.v1.ProjectAnalytics:
type: object
properties:
sessions:
title: sessions
$ref: '#/components/schemas/livekit.publicapi.analytics.v1.ProjectAnalytics.Sessions'
participants:
title: participants
$ref: '#/components/schemas/livekit.publicapi.analytics.v1.ProjectAnalytics.Participants'
title: ProjectAnalytics
additionalProperties: false
description: |-
ProjectAnalytics is the project overview over a time range, grouped the same
way: `sessions` and `participants`.
livekit.publicapi.analytics.v1.ProjectAnalytics.Participants:
type: object
properties:
total:
type:
- integer
- string
title: total
format: int64
topCountries:
type: array
items:
$ref: '#/components/schemas/livekit.publicapi.analytics.v1.CountryCount'
title: top_countries
platforms:
type: array
items:
$ref: '#/components/schemas/livekit.publicapi.analytics.v1.PlatformShare'
title: platforms
title: Participants
additionalProperties: false
livekit.publicapi.analytics.v1.ProjectAnalytics.Sessions:
type: object
properties:
served:
type:
- integer
- string
title: served
format: int64
withAgents:
type:
- integer
- string
title: with_agents
format: int64
withTelephony:
type:
- integer
- string
title: with_telephony
format: int64
avgDurationSeconds:
type: number
title: avg_duration_seconds
format: double
agentMinutes:
type:
- integer
- string
title: agent_minutes
format: int64
title: Sessions
additionalProperties: false
livekit.publicapi.analytics.v1.ProjectOverview.Get.Request:
type: object
properties:
projectId:
type: string
title: project_id
range:
title: range
$ref: '#/components/schemas/livekit.publicapi.analytics.v1.TimeRange'
title: Request
additionalProperties: false
livekit.publicapi.analytics.v1.ProjectOverview.Get.Response:
type: object
properties:
analytics:
title: analytics
$ref: '#/components/schemas/livekit.publicapi.analytics.v1.ProjectAnalytics'
title: Response
additionalProperties: false
livekit.publicapi.analytics.v1.PublishedSources:
type: object
properties:
cameraTrack:
type: boolean
title: camera_track
microphoneTrack:
type: boolean
title: microphone_track
screenShareTrack:
type: boolean
title: screen_share_track
screenShareAudio:
type: boolean
title: screen_share_audio
title: PublishedSources
additionalProperties: false
description: PublishedSources is which track sources a participant published.
livekit.publicapi.analytics.v1.Session:
type: object
properties:
sessionId:
type: string
title: session_id
roomName:
type: string
title: room_name
status:
title: status
description: |-
ACTIVE until the session's close is recorded, so a session that stopped
reporting can be ACTIVE with an ended_at.
$ref: '#/components/schemas/livekit.publicapi.analytics.v1.SessionStatus'
startedAt:
title: started_at
$ref: '#/components/schemas/google.protobuf.Timestamp'
endedAt:
title: ended_at
description: |-
When the session ended. A session that stopped reporting is given its last
report time, even while its status is still ACTIVE; unset while it is live.
$ref: '#/components/schemas/google.protobuf.Timestamp'
numParticipants:
type: integer
title: num_participants
format: int32
description: |-
Distinct participants (by identity) connected for more than zero seconds
during the session. Not a live count: a closed session keeps its total.
tags:
type: array
items:
type: string
title: tags
hasDetailData:
type: boolean
title: has_detail_data
description: |-
False while the session's full detail (end time, participant counts,
duration) is still being finalized; the detail endpoints are complete once
it is true.
lastActive:
title: last_active
$ref: '#/components/schemas/google.protobuf.Timestamp'
title: Session
additionalProperties: false
description: |-
Session is one room-session list row. Bandwidth and connection time are on
GetSession's detail only.
livekit.publicapi.analytics.v1.SessionDetail:
type: object
properties:
sessionId:
type: string
title: session_id
roomName:
type: string
title: room_name
status:
title: status
$ref: '#/components/schemas/livekit.publicapi.analytics.v1.SessionStatus'
startedAt:
title: started_at
$ref: '#/components/schemas/google.protobuf.Timestamp'
endedAt:
title: ended_at
$ref: '#/components/schemas/google.protobuf.Timestamp'
numParticipants:
type: integer
title: num_participants
format: int32
description: Same count as Session.num_participants.
bandwidthIn:
type:
- integer
- string
title: bandwidth_in
format: int64
description: Bytes participants published, all track types.
bandwidthOut:
type:
- integer
- string
title: bandwidth_out
format: int64
description: Bytes participants subscribed to, all track types.
connectionSeconds:
type:
- integer
- string
title: connection_seconds
format: int64
description: |-
WebRTC connection time in seconds, summed over standard participants and
self-hosted agents (cloud agents excluded), as the dashboard counts it.
participants:
type: array
items:
$ref: '#/components/schemas/livekit.publicapi.analytics.v1.ParticipantInfo'
title: participants
description: |-
The first page of participants, newest join first (at most 50). When
participants_page.has_more, continue with ListSessionParticipants: pass
participants_page.next_cursor as page.cursor, with sort_by and sort_order
unset (or joined_at descending, the same thing).
quality:
type: array
items:
$ref: '#/components/schemas/livekit.publicapi.analytics.v1.DataPoint'
title: quality
description: Average connection quality as a 0-1 fraction of the 0-5 track score.
publishBps:
type: array
items:
$ref: '#/components/schemas/livekit.publicapi.analytics.v1.DataPoint'
title: publish_bps
description: Published audio plus video bitrate, in bits per second.
subscribeBps:
type: array
items:
$ref: '#/components/schemas/livekit.publicapi.analytics.v1.DataPoint'
title: subscribe_bps
description: Subscribed audio plus video bitrate, in bits per second.
publishFps:
type: array
items:
$ref: '#/components/schemas/livekit.publicapi.analytics.v1.DataPoint'
title: publish_fps
description: Published video frame rate.
subscribeFps:
type: array
items:
$ref: '#/components/schemas/livekit.publicapi.analytics.v1.DataPoint'
title: subscribe_fps
description: Subscribed video frame rate.
tags:
type: array
items:
type: string
title: tags
description: The session's tags, as on Session.
participantsPage:
title: participants_page
description: |-
Paging state for participants. Unset when the first page couldn't be
read: the rest of the detail still returns, and ListSessionParticipants
lists the participants.
$ref: '#/components/schemas/livekit.publicapi.common.v1.PageInfo'
title: SessionDetail
additionalProperties: false
description: |-
SessionDetail is the richer per-session view: a superset of Session with the
room id, totals, the first page of participants, and per-metric timelines.
The timelines share one grid sized from the session's length, the
dashboard's: one point per bucket, 0 where a bucket has no data.
livekit.publicapi.analytics.v1.SessionEvent:
type: object
properties:
participantIdentity:
type: string
title: participant_identity
description: |-
The identity of the participant the event is about; empty for a room
event, or an API call that names no participant.
type:
type: string
title: type
description: The event's type, an AnalyticsEventType name such as PARTICIPANT_JOINED.
timestamp:
title: timestamp
$ref: '#/components/schemas/google.protobuf.Timestamp'
payload:
title: payload
description: |-
The event's fields from an allowlist, each present only when the event
has it:
- participant events: participantKind, disconnectReason,
reconnectReason, isMigration and connectionType;
- track events: trackId, trackType, trackSource, mimeType and muted;
- ROOM_ENDED: reason;
- API_CALL: service, method, status, twirpErrorCode and durationNs.
Every other field the event recorded is left out.
$ref: '#/components/schemas/google.protobuf.Struct'
participantSessionId:
type: string
title: participant_session_id
description: |-
The participant session (PA_...) the event is about; empty when
participant_identity is.
title: SessionEvent
additionalProperties: false
description: |-
SessionEvent is one event of a room session, such as a participant joining
or a track being published.
livekit.publicapi.analytics.v1.SessionEvents.List.Request:
type: object
properties:
projectId:
type: string
title: project_id
sessionId:
type: string
title: session_id
page:
title: page
description: |-
page_size counts events, 50 by default and at most 100. A page can
hold fewer events than its size, and the last full page can be
followed by an empty one. A cursor pages only a request with the same
types, participant_session_id and sort_order.
$ref: '#/components/schemas/livekit.publicapi.common.v1.PageRequest'
types:
type: array
items:
type: string
title: types
description: |-
Event types to return, by name, such as TRACK_PUBLISHED: the names of
LiveKit's AnalyticsEventType. Each matches exactly. Empty returns the
dashboard's seven defaults, or with participant_session_id its eleven
participant defaults, track events included (see ListSessionEvents).
An unknown name is InvalidArgument.
participantSessionId:
type: string
title: participant_session_id
description: |-
Only the events of this participant session (PA_...), as the
participants list's ParticipantSession.participant_session_id names
it. Room events and API calls name no participant session, so they
are left out. Anything but a PA_ id is InvalidArgument.
sortOrder:
title: sort_order
description: |-
Direction of the timestamp ordering. Defaults to ascending (oldest
first) when unset.
$ref: '#/components/schemas/livekit.publicapi.common.v1.SortOrder'
title: Request
additionalProperties: false
livekit.publicapi.analytics.v1.SessionEvents.List.Response:
type: object
properties:
items:
type: array
items:
$ref: '#/components/schemas/livekit.publicapi.analytics.v1.SessionEvent'
title: items
pageInfo:
title: page_info
$ref: '#/components/schemas/livekit.publicapi.common.v1.PageInfo'
title: Response
additionalProperties: false
livekit.publicapi.analytics.v1.SessionFilter:
type: object
properties:
range:
title: range
$ref: '#/components/schemas/livekit.publicapi.analytics.v1.TimeRange'
statuses:
type: array
items:
$ref: '#/components/schemas/livekit.publicapi.analytics.v1.SessionStatus'
title: statuses
description: OR semantics; empty matches any status.
roomName:
type: string
title: room_name
description: |-
Room-name prefix match (case-sensitive): returns sessions whose room name
starts with this value, e.g. `demo-` matches `demo-1` and `demo-lobby`.
sessionId:
type: string
title: session_id
description: Exact room-session id match (RM_...).
tags:
type: array
items:
type: string
title: tags
description: OR semantics.
agentId:
type: string
title: agent_id
description: Cloud agent id (CA_...) — return only sessions this agent served. Duration is not filterable in v1.
title: SessionFilter
additionalProperties: false
description: |-
SessionFilter narrows a session listing. Only these fields are filterable
upstream (the rest are rollup-stage values that would break keyset paging).
livekit.publicapi.analytics.v1.SessionParticipants.List.Request:
type: object
properties:
projectId:
type: string
title: project_id
sessionId:
type: string
title: session_id
page:
title: page
$ref: '#/components/schemas/livekit.publicapi.common.v1.PageRequest'
sortBy:
title: sort_by
description: Column to order by. Defaults to joined_at when unset.
$ref: '#/components/schemas/livekit.publicapi.analytics.v1.ParticipantSortField'
sortOrder:
title: sort_order
description: Direction of sort_by. Defaults to descending (newest first) when unset.
$ref: '#/components/schemas/livekit.publicapi.common.v1.SortOrder'
title: Request
additionalProperties: false
livekit.publicapi.analytics.v1.SessionParticipants.List.Response:
type: object
properties:
items:
type: array
items:
$ref: '#/components/schemas/livekit.publicapi.analytics.v1.ParticipantInfo'
title: items
pageInfo:
title: page_info
$ref: '#/components/schemas/livekit.publicapi.common.v1.PageInfo'
title: Response
additionalProperties: false
livekit.publicapi.analytics.v1.SessionStatus:
type: string
title: SessionStatus
enum:
- SESSION_STATUS_UNSPECIFIED
- SESSION_STATUS_ACTIVE
- SESSION_STATUS_CLOSED
description: SessionStatus is the lifecycle state of a session.
livekit.publicapi.analytics.v1.Sessions.Get.Request:
type: object
properties:
projectId:
type: string
title: project_id
sessionId:
type: string
title: session_id
title: Request
additionalProperties: false
livekit.publicapi.analytics.v1.Sessions.Get.Response:
type: object
properties:
session:
title: session
$ref: '#/components/schemas/livekit.publicapi.analytics.v1.Session'
detail:
oneOf:
- $ref: '#/components/schemas/livekit.publicapi.analytics.v1.SessionDetail'
- type: "null"
title: detail
description: |-
Absent while the session's detail is still being finalized (see
Session.has_detail_data on the list row).
title: Response
additionalProperties: false
livekit.publicapi.analytics.v1.Sessions.List.Request:
type: object
properties:
projectId:
type: string
title: project_id
page:
title: page
$ref: '#/components/schemas/livekit.publicapi.common.v1.PageRequest'
filter:
title: filter
$ref: '#/components/schemas/livekit.publicapi.analytics.v1.SessionFilter'
sortOrder:
title: sort_order
description: |-
Direction of the started_at ordering, the only column sessions sort on.
Defaults to descending (newest first) when unset.
$ref: '#/components/schemas/livekit.publicapi.common.v1.SortOrder'
title: Request
additionalProperties: false
livekit.publicapi.analytics.v1.Sessions.List.Response:
type: object
properties:
items:
type: array
items:
$ref: '#/components/schemas/livekit.publicapi.analytics.v1.Session'
title: items
pageInfo:
title: page_info
$ref: '#/components/schemas/livekit.publicapi.common.v1.PageInfo'
title: Response
additionalProperties: false
livekit.publicapi.analytics.v1.TimeRange:
type: object
properties:
startTime:
title: start_time
$ref: '#/components/schemas/google.protobuf.Timestamp'
endTime:
title: end_time
$ref: '#/components/schemas/google.protobuf.Timestamp'
title: TimeRange
additionalProperties: false
description: |-
TimeRange is a half-open window [start_time, end_time). An unset end means
"now"; an unset start means "end minus a service default" (24h for session
lists, 7d for stats). Windows are bounded server-side (stats: 62 days).
livekit.publicapi.common.v1.PageInfo:
type: object
properties:
nextCursor:
type: string
title: next_cursor
description: |-
Pass as `cursor` on the next request to fetch the following page. Empty on
the last page.
hasMore:
type: boolean
title: has_more
title: PageInfo
additionalProperties: false
description: PageInfo is the cursor-pagination metadata shared by every list response.
livekit.publicapi.common.v1.PageRequest:
type: object
properties:
cursor:
type: string
title: cursor
description: |-
Opaque cursor returned by a prior page (PageInfo.next_cursor). Empty starts
from the beginning.
pageSize:
type: integer
title: page_size
format: int32
description: Maximum items to return; 0 lets the server pick a default.
title: PageRequest
additionalProperties: false
description: |-
PageRequest is the shared cursor-pagination request fragment. Embed it in a
list request.
livekit.publicapi.common.v1.SortOrder:
type: string
title: SortOrder
enum:
- SORT_ORDER_UNSPECIFIED
- SORT_ORDER_ASC
- SORT_ORDER_DESC
description: |-
SortOrder is the direction of a list request's sort. A list that lets the
caller pick a direction takes it as `sort_order` and documents its default
column and direction; one that can also sort on more than one column adds
its own `<X>SortField sort_by`.
livekit.publicapi.databases.v1.Databases.Create.Request:
type: object
properties:
projectId:
type: string
title: project_id
ttl:
title: ttl
description: |-
Unset: never expires. Otherwise clamped to the server cap, and never
extended.
$ref: '#/components/schemas/google.protobuf.Duration'
title: Request
additionalProperties: false
livekit.publicapi.databases.v1.Databases.Create.Response:
type: object
properties:
databaseId:
type: string
title: database_id
expiresAt:
title: expires_at
description: Unset when the database never expires.
$ref: '#/components/schemas/google.protobuf.Timestamp'
title: Response
additionalProperties: false
livekit.publicapi.databases.v1.Databases.Delete.Request:
type: object
properties:
projectId:
type: string
title: project_id
databaseId:
type: string
title: database_id
title: Request
additionalProperties: false
livekit.publicapi.databases.v1.Databases.Delete.Response:
type: object
title: Response
additionalProperties: false
livekit.publicapi.databases.v1.Databases.Export.Request:
type: object
properties:
projectId:
type: string
title: project_id
databaseId:
type: string
title: database_id
title: Request
additionalProperties: false
livekit.publicapi.databases.v1.Databases.Export.Response:
type: object
properties:
downloadUrl:
type: string
title: download_url
description: Pre-authenticated object-storage URL.
expiresAt:
title: expires_at
description: Of the URL, not the database.
$ref: '#/components/schemas/google.protobuf.Timestamp'
tip:
type:
- integer
- string
title: tip
format: int64
description: The commit sequence the export is consistent at.
title: Response
additionalProperties: false
livekit.publicapi.databases.v1.Databases.Get.Request:
type: object
properties:
projectId:
type: string
title: project_id
databaseId:
type: string
title: database_id
title: Request
additionalProperties: false
livekit.publicapi.databases.v1.Databases.Get.Response:
type: object
properties:
database:
title: database
$ref: '#/components/schemas/livekit.AgentDB.AgentDatabase'
title: Response
additionalProperties: false
livekit.publicapi.databases.v1.Databases.List.Request:
type: object
properties:
projectId:
type: string
title: project_id
page:
title: page
$ref: '#/components/schemas/livekit.publicapi.common.v1.PageRequest'
title: Request
additionalProperties: false
livekit.publicapi.databases.v1.Databases.List.Response:
type: object
properties:
items:
type: array
items:
$ref: '#/components/schemas/livekit.AgentDB.AgentDatabase'
title: items
pageInfo:
title: page_info
$ref: '#/components/schemas/livekit.publicapi.common.v1.PageInfo'
title: Response
additionalProperties: false
livekit.publicapi.observability.v1.LogLevel:
type: string
title: LogLevel
enum:
- LOG_LEVEL_UNSPECIFIED
- LOG_LEVEL_TRACE
- LOG_LEVEL_DEBUG
- LOG_LEVEL_INFO
- LOG_LEVEL_WARN
- LOG_LEVEL_ERROR
- LOG_LEVEL_FATAL
description: |-
LogLevel is a log record's level, as the dashboard's logs panel shows and
filters it. Agents name levels differently by runtime, such as Python's
CRITICAL and Node's FATAL, so a record's level comes from its OpenTelemetry
severity number, or from its level name when it has none; a level means the
same for Python and Node agents.
livekit.publicapi.observability.v1.LogRecord:
type: object
properties:
id:
type: string
title: id
description: The record's id, the same on every read.
timestamp:
title: timestamp
$ref: '#/components/schemas/google.protobuf.Timestamp'
level:
title: level
$ref: '#/components/schemas/livekit.publicapi.observability.v1.LogLevel'
severityText:
type: string
title: severity_text
description: The level's name as the agent logged it, such as "WARN" or "CRITICAL".
logger:
type: string
title: logger
description: The logger that wrote the record (its logger.name attribute).
message:
type: string
title: message
description: |-
The record's text. A structured logger's body keeps it under its event,
message or msg field; a structured body with none of them is written
here whole, as JSON.
bodyFields:
type: object
title: body_fields
additionalProperties:
title: value
$ref: '#/components/schemas/google.protobuf.Value'
description: |-
A structured logger's body fields other than its message; empty for a
plain text body.
attributes:
type: object
title: attributes
additionalProperties:
title: value
$ref: '#/components/schemas/google.protobuf.Value'
description: |-
The record's attributes, typed and nested as the agent recorded them,
with its resource's and scope's attributes merged in; the record's own
value wins. An integer beyond ±2^53 is its decimal string, and bytes are
base64.
traceId:
type: string
title: trace_id
description: |-
The trace and span the record was logged in, as lowercase hex; empty when
it was logged outside one. They link the record to its span in
GetSessionTraces.
spanId:
type: string
title: span_id
title: LogRecord
additionalProperties: false
description: LogRecord is one log record a session's agent exported.
livekit.publicapi.observability.v1.LogRecord.AttributesEntry:
type: object
properties:
key:
type: string
title: key
value:
title: value
$ref: '#/components/schemas/google.protobuf.Value'
title: AttributesEntry
additionalProperties: false
livekit.publicapi.observability.v1.LogRecord.BodyFieldsEntry:
type: object
properties:
key:
type: string
title: key
value:
title: value
$ref: '#/components/schemas/google.protobuf.Value'
title: BodyFieldsEntry
additionalProperties: false
livekit.publicapi.observability.v1.Logs.Get.Request:
type: object
properties:
projectId:
type: string
title: project_id
sessionId:
type: string
title: session_id
description: The session's RM_ id.
page:
title: page
description: |-
page_size counts records, 50 by default and at most 100. A cursor
pages only a request with the same log_levels and sort_order.
$ref: '#/components/schemas/livekit.publicapi.common.v1.PageRequest'
logLevels:
type: array
items:
$ref: '#/components/schemas/livekit.publicapi.observability.v1.LogLevel'
title: log_levels
description: |-
Only records at these levels, as the dashboard's logs filter selects
them, for example only TRACE and FATAL. Empty returns every record,
including those with no level, such as a passed evaluation.
LOG_LEVEL_UNSPECIFIED is InvalidArgument.
sortOrder:
title: sort_order
description: |-
Direction of the timestamp ordering. Defaults to ascending (oldest
first) when unset.
$ref: '#/components/schemas/livekit.publicapi.common.v1.SortOrder'
title: Request
additionalProperties: false
livekit.publicapi.observability.v1.Logs.Get.Response:
type: object
properties:
records:
type: array
items:
$ref: '#/components/schemas/livekit.publicapi.observability.v1.LogRecord'
title: records
pageInfo:
title: page_info
$ref: '#/components/schemas/livekit.publicapi.common.v1.PageInfo'
title: Response
additionalProperties: false
livekit.publicapi.observability.v1.MetricHistogram:
type: object
properties:
count:
type:
- integer
- string
title: count
format: int64
description: How many values were recorded.
sum:
type:
- number
- "null"
title: sum
format: double
description: Their sum, minimum and maximum; unset when the agent didn't record them.
min:
type:
- number
- "null"
title: min
format: double
max:
type:
- number
- "null"
title: max
format: double
bucketBounds:
type: array
items:
type: number
format: double
title: bucket_bounds
description: |-
A histogram's buckets, with one more count than bounds: bucket_counts[0]
counts the values up to bucket_bounds[0], bucket_counts[i] those in
(bucket_bounds[i-1], bucket_bounds[i]], and the last count those above
the last bound. Both are empty for an exponential histogram.
bucketCounts:
type: array
items:
type:
- integer
- string
format: int64
title: bucket_counts
title: MetricHistogram
additionalProperties: false
description: MetricHistogram summarizes the values a histogram point recorded.
livekit.publicapi.observability.v1.MetricKind:
type: string
title: MetricKind
enum:
- METRIC_KIND_UNSPECIFIED
- METRIC_KIND_GAUGE
- METRIC_KIND_SUM
- METRIC_KIND_HISTOGRAM
- METRIC_KIND_EXPONENTIAL_HISTOGRAM
description: MetricKind is the OpenTelemetry data type a metric point was exported as.
livekit.publicapi.observability.v1.MetricPoint:
type: object
allOf:
- properties:
name:
type: string
title: name
description: |-
The metric's name, such as lk.agents.turn.e2e_latency or
gen_ai.client.token.usage. The upstream aggregator can file several
metrics that share their attributes under one name (GetSessionMetrics).
unit:
type: string
title: unit
description: |-
The metric's unit as the agent declared it, such as "s" or "{token}";
empty when it declared none.
kind:
title: kind
$ref: '#/components/schemas/livekit.publicapi.observability.v1.MetricKind'
startTime:
title: start_time
description: |-
The interval the point covers. An agent exports every 30 seconds, so a
sum or histogram covers the time since its previous export; a gauge has
no start_time.
$ref: '#/components/schemas/google.protobuf.Timestamp'
endTime:
title: end_time
$ref: '#/components/schemas/google.protobuf.Timestamp'
attributes:
type: object
title: attributes
additionalProperties:
title: value
$ref: '#/components/schemas/google.protobuf.Value'
description: |-
The point's attributes, typed and nested as the agent recorded them, with
its resource's and scope's attributes merged in, such as room_id, job_id,
lk.agent_name and the model's model_name; the point's own value wins. With
two agents in one session, the resource's can be the other agent's. An
integer beyond ±2^53 is its decimal string, and bytes are base64.
- oneOf:
- type: object
properties:
histogram:
title: histogram
description: A histogram's or exponential histogram's summary.
$ref: '#/components/schemas/livekit.publicapi.observability.v1.MetricHistogram'
title: histogram
required:
- histogram
- type: object
properties:
value:
type: number
title: value
format: double
description: A gauge's or sum's value.
title: value
required:
- value
- not:
anyOf:
- required:
- histogram
- required:
- value
unevaluatedProperties: false
title: MetricPoint
description: |-
MetricPoint is one OpenTelemetry metric data point a session's agent
exported. It is the raw metric the agent emits, so it 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 points; an agent whose code installs its own MeterProvider exports
none to LiveKit Cloud.
livekit.publicapi.observability.v1.MetricPoint.AttributesEntry:
type: object
properties:
key:
type: string
title: key
value:
title: value
$ref: '#/components/schemas/google.protobuf.Value'
title: AttributesEntry
additionalProperties: false
livekit.publicapi.observability.v1.Metrics.Get.Request:
type: object
properties:
projectId:
type: string
title: project_id
sessionId:
type: string
title: session_id
description: The session's RM_ id.
page:
title: page
description: |-
page_size counts points, 50 by default and at most 100. A cursor pages
only a request with the same names.
$ref: '#/components/schemas/livekit.publicapi.common.v1.PageRequest'
names:
type: array
items:
type: string
title: names
description: |-
Only the points of these metrics, matched exactly, such as
lk.agents.turn.e2e_latency. Empty returns every metric. At most 50
names, each 1 to 256 characters.
title: Request
additionalProperties: false
livekit.publicapi.observability.v1.Metrics.Get.Response:
type: object
properties:
points:
type: array
items:
$ref: '#/components/schemas/livekit.publicapi.observability.v1.MetricPoint'
title: points
description: |-
By end time, oldest first; points that end together are ordered by
start time, a point with none first, then by kind and a hash of what
they recorded, not by name. A page continues
after the previous page's last point, so on an ACTIVE session a point
exported mid-read with a later time comes on a later page, and one
with an earlier time is missed until a new read.
pageInfo:
title: page_info
$ref: '#/components/schemas/livekit.publicapi.common.v1.PageInfo'
title: Response
additionalProperties: false
livekit.publicapi.observability.v1.Recording.GetURL.Request:
type: object
properties:
projectId:
type: string
title: project_id
sessionId:
type: string
title: session_id
fileType:
title: file_type
description: Which recording to sign a URL for. UNSPECIFIED is InvalidArgument.
$ref: '#/components/schemas/livekit.publicapi.observability.v1.RecordingFileType'
expirySeconds:
type: integer
title: expiry_seconds
description: |-
How long the URL stays valid, in seconds. Unset or 0 is 900 (15
minutes), and anything longer is clamped to 900 without an error;
expires_at says what was granted.
title: Request
additionalProperties: false
livekit.publicapi.observability.v1.Recording.GetURL.Response:
type: object
properties:
url:
type: string
title: url
description: |-
A signed URL that downloads the recording straight from the object
store in the project's data region, without credentials, until
expires_at. Audio is Ogg; chat history is JSON served with
Content-Encoding: gzip.
recordingStartedAt:
title: recording_started_at
description: |-
When the recording started, as the agent reported it on upload. Line
the audio up with the transcript by it.
$ref: '#/components/schemas/google.protobuf.Timestamp'
expiresAt:
title: expires_at
description: |-
When the URL stops working: the request's time plus the granted
expiry, after the 15-minute clamp.
$ref: '#/components/schemas/google.protobuf.Timestamp'
title: Response
additionalProperties: false
livekit.publicapi.observability.v1.RecordingFileType:
type: string
title: RecordingFileType
enum:
- RECORDING_FILE_TYPE_UNSPECIFIED
- RECORDING_FILE_TYPE_AUDIO
- RECORDING_FILE_TYPE_CHAT_HISTORY
description: |-
RecordingFileType is the recording requested from GetSessionRecordingURL.
The session's conversation as typed items comes from GetSessionTranscript,
not from a recording.
livekit.publicapi.observability.v1.Role:
type: string
title: Role
enum:
- ROLE_UNSPECIFIED
- ROLE_USER
- ROLE_AGENT
- ROLE_SYSTEM
- ROLE_DEVELOPER
description: Role is who a transcript message is from.
livekit.publicapi.observability.v1.Span:
type: object
properties:
spanId:
type: string
title: span_id
description: The span's ids, as lowercase hex.
traceId:
type: string
title: trace_id
parentSpanId:
type: string
title: parent_span_id
description: |-
Empty for a root span. A span whose parent isn't among the session's
spans is a root too, as the dashboard shows it.
name:
type: string
title: name
startTime:
title: start_time
$ref: '#/components/schemas/google.protobuf.Timestamp'
endTime:
title: end_time
$ref: '#/components/schemas/google.protobuf.Timestamp'
kind:
title: kind
$ref: '#/components/schemas/livekit.publicapi.observability.v1.SpanKind'
status:
title: status
$ref: '#/components/schemas/livekit.publicapi.observability.v1.SpanStatus'
statusMessage:
type: string
title: status_message
attributes:
type: object
title: attributes
additionalProperties:
title: value
$ref: '#/components/schemas/google.protobuf.Value'
description: |-
The span's attributes, typed and nested as the agent recorded them, with
its resource's and scope's attributes merged in, such as lk.agent_name;
the span's own value wins. An integer beyond ±2^53 is its decimal string,
and bytes are base64.
events:
type: array
items:
$ref: '#/components/schemas/livekit.publicapi.observability.v1.SpanEvent'
title: events
title: Span
additionalProperties: false
description: |-
Span is one unit of work in the session's trace, such as an agent turn or
an LLM request.
livekit.publicapi.observability.v1.Span.AttributesEntry:
type: object
properties:
key:
type: string
title: key
value:
title: value
$ref: '#/components/schemas/google.protobuf.Value'
title: AttributesEntry
additionalProperties: false
livekit.publicapi.observability.v1.SpanEvent:
type: object
properties:
timestamp:
title: timestamp
$ref: '#/components/schemas/google.protobuf.Timestamp'
name:
type: string
title: name
attributes:
type: object
title: attributes
additionalProperties:
title: value
$ref: '#/components/schemas/google.protobuf.Value'
description: The event's own attributes, typed and nested as the agent recorded them.
title: SpanEvent
additionalProperties: false
description: |-
SpanEvent is a timestamped event recorded within a Span, such as an
exception.
livekit.publicapi.observability.v1.SpanEvent.AttributesEntry:
type: object
properties:
key:
type: string
title: key
value:
title: value
$ref: '#/components/schemas/google.protobuf.Value'
title: AttributesEntry
additionalProperties: false
livekit.publicapi.observability.v1.SpanKind:
type: string
title: SpanKind
enum:
- SPAN_KIND_UNSPECIFIED
- SPAN_KIND_INTERNAL
- SPAN_KIND_SERVER
- SPAN_KIND_CLIENT
- SPAN_KIND_PRODUCER
- SPAN_KIND_CONSUMER
description: SpanKind is a span's OpenTelemetry kind.
livekit.publicapi.observability.v1.SpanStatus:
type: string
title: SpanStatus
enum:
- SPAN_STATUS_UNSPECIFIED
- SPAN_STATUS_OK
- SPAN_STATUS_ERROR
description: SpanStatus is a span's OpenTelemetry status code.
livekit.publicapi.observability.v1.Traces.Get.Request:
type: object
properties:
projectId:
type: string
title: project_id
sessionId:
type: string
title: session_id
description: The session's RM_ id.
page:
title: page
description: |-
page_size counts spans, 50 by default and at most 100, so a page can
hold fewer spans than its size. A span can be large, since an LLM
span carries the whole chat context so far.
$ref: '#/components/schemas/livekit.publicapi.common.v1.PageRequest'
title: Request
additionalProperties: false
livekit.publicapi.observability.v1.Traces.Get.Response:
type: object
properties:
spans:
type: array
items:
$ref: '#/components/schemas/livekit.publicapi.observability.v1.Span'
title: spans
description: |-
By start time, oldest first. Spans that start together are ordered by
span id as the aggregator stores it: the id's 8 bytes read as a
little-endian unsigned integer, which isn't the order of its hex
string. The pages read the spans the first page found, so a span
exported later waits for a new read. On an ACTIVE session, a span
exported mid-read can still shift the later pages, which are read by
offset, so a span can repeat or be skipped: dedupe by span_id, and
read again from the first page to pick up a skipped span.
pageInfo:
title: page_info
$ref: '#/components/schemas/livekit.publicapi.common.v1.PageInfo'
title: Response
additionalProperties: false
livekit.publicapi.observability.v1.Transcript.Get.Request:
type: object
properties:
projectId:
type: string
title: project_id
sessionId:
type: string
title: session_id
description: The session's RM_ id.
page:
title: page
description: |-
page_size counts the agent's transcript records read, 50 by default
and at most 100, so a page can hold fewer items than its size.
$ref: '#/components/schemas/livekit.publicapi.common.v1.PageRequest'
title: Request
additionalProperties: false
livekit.publicapi.observability.v1.Transcript.Get.Response:
type: object
properties:
items:
type: array
items:
$ref: '#/components/schemas/livekit.publicapi.observability.v1.TranscriptItem'
title: items
description: Oldest first, in the order the agent recorded them.
pageInfo:
title: page_info
$ref: '#/components/schemas/livekit.publicapi.common.v1.PageInfo'
skippedRecords:
type: integer
title: skipped_records
description: |-
How many of this page's records couldn't be read as transcript items
and were left out, such as an item kind newer than this server. Zero
when the page is complete.
title: Response
additionalProperties: false
livekit.publicapi.observability.v1.TranscriptItem:
type: object
allOf:
- properties:
id:
type: string
title: id
description: The item's id, as the agent assigned it (item_...).
timestamp:
title: timestamp
description: |-
When the item happened. For a message, when its speaker started speaking,
else when the agent created it; for any other item, when the agent
recorded it. Items are ordered by when the agent recorded them, so a
message's timestamp can be earlier than the item before it.
$ref: '#/components/schemas/google.protobuf.Timestamp'
- oneOf:
- type: object
properties:
agentHandoff:
title: agent_handoff
$ref: '#/components/schemas/livekit.publicapi.observability.v1.TranscriptItem.AgentHandoff'
title: agent_handoff
required:
- agentHandoff
- type: object
properties:
configUpdate:
title: config_update
$ref: '#/components/schemas/livekit.publicapi.observability.v1.TranscriptItem.ConfigUpdate'
title: config_update
required:
- configUpdate
- type: object
properties:
message:
title: message
$ref: '#/components/schemas/livekit.publicapi.observability.v1.TranscriptItem.Message'
title: message
required:
- message
- type: object
properties:
toolCall:
title: tool_call
$ref: '#/components/schemas/livekit.publicapi.observability.v1.TranscriptItem.ToolCall'
title: tool_call
required:
- toolCall
- type: object
properties:
toolResult:
title: tool_result
$ref: '#/components/schemas/livekit.publicapi.observability.v1.TranscriptItem.ToolResult'
title: tool_result
required:
- toolResult
- not:
anyOf:
- required:
- agentHandoff
- required:
- configUpdate
- required:
- message
- required:
- toolCall
- required:
- toolResult
unevaluatedProperties: false
title: TranscriptItem
description: |-
TranscriptItem is one ordered entry in a session's conversation. Exactly one
of the `item` variants is set.
livekit.publicapi.observability.v1.TranscriptItem.AgentHandoff:
type: object
properties:
fromAgentId:
type: string
title: from_agent_id
description: Unset for the session's first agent.
toAgentId:
type: string
title: to_agent_id
title: AgentHandoff
additionalProperties: false
description: AgentHandoff is the session passing from one agent to another.
livekit.publicapi.observability.v1.TranscriptItem.ConfigUpdate:
type: object
properties:
instructions:
type: string
title: instructions
description: The agent's new instructions; empty when they didn't change.
toolsAdded:
type: array
items:
type: string
title: tools_added
toolsRemoved:
type: array
items:
type: string
title: tools_removed
title: ConfigUpdate
additionalProperties: false
description: |-
ConfigUpdate is a change to the agent's instructions or tools during the
session.
livekit.publicapi.observability.v1.TranscriptItem.Message:
type: object
properties:
role:
title: role
$ref: '#/components/schemas/livekit.publicapi.observability.v1.Role'
text:
type: string
title: text
description: |-
The message's text. Text the agent recorded in several parts is joined
with newlines. When redacted is set, PII in it is replaced with
<redaction type="..."/> markers.
interrupted:
type: boolean
title: interrupted
description: Set on an agent message the user talked over before it finished.
redacted:
type: boolean
title: redacted
description: Set when the project's PII redaction rewrote the text.
transcriptConfidence:
type:
- number
- "null"
title: transcript_confidence
format: double
description: The speech-to-text confidence of a spoken user message, from 0 to 1.
startedSpeakingAt:
title: started_speaking_at
description: |-
When the speaker started and stopped speaking; unset for a message
that wasn't spoken.
$ref: '#/components/schemas/google.protobuf.Timestamp'
stoppedSpeakingAt:
title: stopped_speaking_at
$ref: '#/components/schemas/google.protobuf.Timestamp'
e2eLatencyMs:
type:
- number
- "null"
title: e2e_latency_ms
format: double
description: |-
The turn's latencies in milliseconds, converted from the seconds the
agent recorded; unset when the agent didn't record one. An agent message
carries the first three, a user message the last three.
End-to-end latency: from when the user finished speaking to when the
agent began responding (the agent's e2e_latency).
llmTtftMs:
type:
- number
- "null"
title: llm_ttft_ms
format: double
description: LLM time to first token (llm_node_ttft).
ttsTtfbMs:
type:
- number
- "null"
title: tts_ttfb_ms
format: double
description: TTS time to first byte of audio (tts_node_ttfb).
transcriptionDelayMs:
type:
- number
- "null"
title: transcription_delay_ms
format: double
description: |-
From the end of the user's speech to its final transcript
(transcription_delay).
endOfTurnDelayMs:
type:
- number
- "null"
title: end_of_turn_delay_ms
format: double
description: |-
From the end of the user's speech to the agent deciding the turn ended
(end_of_turn_delay).
onUserTurnCompletedDelayMs:
type:
- number
- "null"
title: on_user_turn_completed_delay_ms
format: double
description: |-
Time spent in the agent's on_user_turn_completed callback
(on_user_turn_completed_delay).
title: Message
additionalProperties: false
description: Message is something said, or added to the conversation as text.
livekit.publicapi.observability.v1.TranscriptItem.ToolCall:
type: object
properties:
name:
type: string
title: name
callId:
type: string
title: call_id
description: Pairs the call with its ToolResult.
arguments:
type: string
title: arguments
description: The call's arguments as a JSON string.
title: ToolCall
additionalProperties: false
description: ToolCall is the agent calling a tool.
livekit.publicapi.observability.v1.TranscriptItem.ToolResult:
type: object
properties:
name:
type: string
title: name
callId:
type: string
title: call_id
description: The call_id of the ToolCall it answers.
output:
type: string
title: output
isError:
type: boolean
title: is_error
description: Set when the tool failed; output then describes the error.
title: ToolResult
additionalProperties: false
description: ToolResult is the output a tool returned for a ToolCall.
livekit.publicapi.projects.v1.AccessKey:
type: object
properties:
apiKey:
type: string
title: api_key
createdAt:
title: created_at
$ref: '#/components/schemas/google.protobuf.Timestamp'
updatedAt:
title: updated_at
$ref: '#/components/schemas/google.protobuf.Timestamp'
description:
type: string
title: description
ownerId:
type: string
title: owner_id
description: Empty for service-account / legacy unowned keys.
ownerEmail:
type: string
title: owner_email
agentId:
type:
- string
- "null"
title: agent_id
description: Set for programmatically-created cloud agent keys.
title: AccessKey
additionalProperties: false
description: |-
AccessKey is project API-key metadata. The secret is never included on list
RPCs; it is returned only from GenerateKey.
livekit.publicapi.projects.v1.AddWorkspaceMembersToProjectRequest:
type: object
properties:
projectId:
type: string
title: project_id
userIds:
type: array
items:
type: string
title: user_ids
role:
type: integer
title: role
format: int32
title: AddWorkspaceMembersToProjectRequest
additionalProperties: false
livekit.publicapi.projects.v1.AddWorkspaceMembersToProjectResponse:
type: object
properties:
items:
type: array
items:
$ref: '#/components/schemas/livekit.publicapi.projects.v1.ProjectMember'
title: items
title: AddWorkspaceMembersToProjectResponse
additionalProperties: false
livekit.publicapi.projects.v1.AnswerInvitationRequest:
type: object
properties:
inviteToken:
type: string
title: invite_token
accept:
type: boolean
title: accept
title: AnswerInvitationRequest
additionalProperties: false
livekit.publicapi.projects.v1.AnswerInvitationResponse:
type: object
properties:
member:
title: member
description: set when accept=true
$ref: '#/components/schemas/livekit.publicapi.projects.v1.ProjectMember'
title: AnswerInvitationResponse
additionalProperties: false
livekit.publicapi.projects.v1.CreateProjectMember:
type: object
properties:
userId:
type: string
title: user_id
role:
type: integer
title: role
format: int32
description: 'Matches cloud_protocol.ProjectMemberRole: INVITED=0, READ=1, WRITE=2, ADMIN=3.'
title: CreateProjectMember
additionalProperties: false
description: 'TODO: Add more parts that allow for a full project creation, not just the name'
livekit.publicapi.projects.v1.CreateProjectRequest:
type: object
properties:
workspaceId:
type: string
title: workspace_id
description: optional; when empty a new workspace is created
name:
type: string
title: name
subdomain:
type: string
title: subdomain
description: optional; generated from name when empty
isPrivate:
type: boolean
title: is_private
members:
type: array
items:
$ref: '#/components/schemas/livekit.publicapi.projects.v1.CreateProjectMember'
title: members
description: private projects only
userDataRegion:
type: string
title: user_data_region
description: create-only; empty keeps the deployment default
title: CreateProjectRequest
additionalProperties: false
livekit.publicapi.projects.v1.CreateProjectResponse:
type: object
properties:
project:
title: project
$ref: '#/components/schemas/livekit.publicapi.projects.v1.Project'
title: CreateProjectResponse
additionalProperties: false
livekit.publicapi.projects.v1.CreateTokenRequest:
type: object
properties:
projectId:
type: string
title: project_id
grants:
title: grants
description: The caller's project role must cover every grant requested.
$ref: '#/components/schemas/livekit.publicapi.projects.v1.TokenGrants'
ttlSeconds:
type: integer
title: ttl_seconds
description: |-
Requested lifetime in seconds. 0 means the default (10 minutes); at most
86400 (24 hours).
title: CreateTokenRequest
additionalProperties: false
livekit.publicapi.projects.v1.CreateTokenResponse:
type: object
properties:
token:
type: string
title: token
description: |-
Signed JWT, sent as `Authorization: Bearer` to the project's server APIs
or used to join a room, depending on the grants.
expiresAt:
title: expires_at
$ref: '#/components/schemas/google.protobuf.Timestamp'
title: CreateTokenResponse
additionalProperties: false
livekit.publicapi.projects.v1.DeleteInviteRequest:
type: object
properties:
projectId:
type: string
title: project_id
email:
type: string
title: email
title: DeleteInviteRequest
additionalProperties: false
livekit.publicapi.projects.v1.DeleteInviteResponse:
type: object
title: DeleteInviteResponse
additionalProperties: false
livekit.publicapi.projects.v1.DeleteKeyRequest:
type: object
properties:
projectId:
type: string
title: project_id
apiKey:
type: string
title: api_key
title: DeleteKeyRequest
additionalProperties: false
livekit.publicapi.projects.v1.DeleteKeyResponse:
type: object
title: DeleteKeyResponse
additionalProperties: false
livekit.publicapi.projects.v1.DeleteProjectRequest:
type: object
properties:
projectId:
type: string
title: project_id
title: DeleteProjectRequest
additionalProperties: false
livekit.publicapi.projects.v1.DeleteProjectResponse:
type: object
title: DeleteProjectResponse
additionalProperties: false
livekit.publicapi.projects.v1.GenerateKeyRequest:
type: object
properties:
projectId:
type: string
title: project_id
description:
type: string
title: description
isServiceAccount:
type:
- boolean
- "null"
title: is_service_account
description: |-
When true, the key is created without an owner (project-owned). It is not
listed as anyone's personal key and survives the generating user leaving.
title: GenerateKeyRequest
additionalProperties: false
livekit.publicapi.projects.v1.GenerateKeyResponse:
type: object
properties:
apiKey:
type: string
title: api_key
secret:
type: string
title: secret
title: GenerateKeyResponse
additionalProperties: false
livekit.publicapi.projects.v1.GetInviteRequest:
type: object
properties:
inviteToken:
type: string
title: invite_token
title: GetInviteRequest
additionalProperties: false
livekit.publicapi.projects.v1.GetInviteResponse:
type: object
properties:
invite:
title: invite
$ref: '#/components/schemas/livekit.publicapi.projects.v1.ProjectInvite'
title: GetInviteResponse
additionalProperties: false
livekit.publicapi.projects.v1.GetMemberRequest:
type: object
properties:
projectId:
type: string
title: project_id
userId:
type: string
title: user_id
title: GetMemberRequest
additionalProperties: false
livekit.publicapi.projects.v1.GetMemberResponse:
type: object
properties:
member:
title: member
$ref: '#/components/schemas/livekit.publicapi.projects.v1.ProjectMember'
title: GetMemberResponse
additionalProperties: false
livekit.publicapi.projects.v1.GetProjectRequest:
type: object
properties:
projectId:
type: string
title: project_id
title: GetProjectRequest
additionalProperties: false
livekit.publicapi.projects.v1.GetProjectResponse:
type: object
properties:
project:
title: project
$ref: '#/components/schemas/livekit.publicapi.projects.v1.Project'
title: GetProjectResponse
additionalProperties: false
livekit.publicapi.projects.v1.InviteMemberRequest:
type: object
properties:
projectId:
type: string
title: project_id
email:
type: string
title: email
role:
type: integer
title: role
format: int32
title: InviteMemberRequest
additionalProperties: false
description: InviteMember creates or refreshes a token invite (cloud InviteMember2).
livekit.publicapi.projects.v1.InviteMemberResponse:
type: object
properties:
projectId:
type: string
title: project_id
inviteToken:
type: string
title: invite_token
title: InviteMemberResponse
additionalProperties: false
livekit.publicapi.projects.v1.ListInvitesRequest:
type: object
properties:
projectId:
type: string
title: project_id
title: ListInvitesRequest
additionalProperties: false
livekit.publicapi.projects.v1.ListInvitesResponse:
type: object
properties:
items:
type: array
items:
$ref: '#/components/schemas/livekit.publicapi.projects.v1.ProjectInvite'
title: items
title: ListInvitesResponse
additionalProperties: false
livekit.publicapi.projects.v1.ListKeysRequest:
type: object
properties:
projectId:
type: string
title: project_id
includeAgentKeys:
type: boolean
title: include_agent_keys
description: Agent keys are hidden by default, matching cloud-api-server.
title: ListKeysRequest
additionalProperties: false
livekit.publicapi.projects.v1.ListKeysResponse:
type: object
properties:
keys:
type: array
items:
$ref: '#/components/schemas/livekit.publicapi.projects.v1.AccessKey'
title: keys
title: ListKeysResponse
additionalProperties: false
livekit.publicapi.projects.v1.ListMembersRequest:
type: object
properties:
projectId:
type: string
title: project_id
title: ListMembersRequest
additionalProperties: false
livekit.publicapi.projects.v1.ListMembersResponse:
type: object
properties:
items:
type: array
items:
$ref: '#/components/schemas/livekit.publicapi.projects.v1.ProjectMember'
title: items
title: ListMembersResponse
additionalProperties: false
livekit.publicapi.projects.v1.ListProjectsRequest:
type: object
properties:
page:
title: page
$ref: '#/components/schemas/livekit.publicapi.common.v1.PageRequest'
workspaceId:
type: string
title: workspace_id
description: |-
Mutually exclusive: only one of workspace_id or member_id can be set
if workspace_id is set, list projects for the workspace
memberId:
type: string
title: member_id
description: if member_id is set, list projects for the member
title: ListProjectsRequest
additionalProperties: false
livekit.publicapi.projects.v1.ListProjectsResponse:
type: object
properties:
items:
type: array
items:
$ref: '#/components/schemas/livekit.publicapi.projects.v1.Project'
title: items
pageInfo:
title: page_info
$ref: '#/components/schemas/livekit.publicapi.common.v1.PageInfo'
title: ListProjectsResponse
additionalProperties: false
livekit.publicapi.projects.v1.ListScopedKeysRequest:
type: object
properties:
projectId:
type: string
title: project_id
title: ListScopedKeysRequest
additionalProperties: false
livekit.publicapi.projects.v1.ListScopedKeysResponse:
type: object
properties:
personalKeys:
type: array
items:
$ref: '#/components/schemas/livekit.publicapi.projects.v1.AccessKey'
title: personal_keys
otherKeys:
type: array
items:
$ref: '#/components/schemas/livekit.publicapi.projects.v1.AccessKey'
title: other_keys
title: ListScopedKeysResponse
additionalProperties: false
livekit.publicapi.projects.v1.PinnedRegions:
type: object
properties:
regions:
type: array
items:
type: string
title: regions
title: PinnedRegions
additionalProperties: false
description: |-
PinnedRegions wraps the region pin set so an explicit empty list can clear
the pins, which a bare repeated field cannot express (mirrors cloud
AdminSetProjectSettingsRequest.pinned_regions).
livekit.publicapi.projects.v1.Project:
type: object
properties:
id:
type: string
title: id
name:
type: string
title: name
workspaceId:
type: string
title: workspace_id
createdAt:
title: created_at
$ref: '#/components/schemas/google.protobuf.Timestamp'
webhooks:
type: array
items:
$ref: '#/components/schemas/livekit.publicapi.projects.v1.Webhook'
title: webhooks
creatorId:
type: string
title: creator_id
subdomain:
type: string
title: subdomain
enableAnalytics:
type: boolean
title: enable_analytics
analyticsAccessKey:
type: string
title: analytics_access_key
enableAutoCreate:
type: boolean
title: enable_auto_create
enableRemoteUnmute:
type: boolean
title: enable_remote_unmute
enableEnhancedNoiseCancellation:
type: boolean
title: enable_enhanced_noise_cancellation
enableHostedAgents:
type: boolean
title: enable_hosted_agents
preferences:
title: preferences
$ref: '#/components/schemas/livekit.publicapi.projects.v1.ProjectPreferences'
enabledCodecs:
type: array
items:
type: string
title: enabled_codecs
pinnedRegions:
type: array
items:
type: string
title: pinned_regions
egressClusterId:
type: string
title: egress_cluster_id
enableSafeMode:
type: boolean
title: enable_safe_mode
enableUserDataRecording:
type: boolean
title: enable_user_data_recording
enableUserDataTraining:
type: boolean
title: enable_user_data_training
userDataRegion:
type: string
title: user_data_region
userDataLifetimeDays:
type: integer
title: user_data_lifetime_days
format: int32
enableSipCustomDomain:
type: boolean
title: enable_sip_custom_domain
requireExplicitDispatch:
type: boolean
title: require_explicit_dispatch
isPrivate:
type: boolean
title: is_private
enablePiiRedaction:
type: boolean
title: enable_pii_redaction
piiRedactionCategories:
type: array
items:
$ref: '#/components/schemas/cloud_protocol.PIIRedactionCategory'
title: pii_redaction_categories
description: |-
Categories to redact when enable_pii_redaction is on. Empty on read means
the stored set (or defaults applied at enable time) — never "redact nothing".
Same taxonomy as cloud-api UpdateProject (cloud_protocol.PIIRedactionCategory).
enableInferenceRegionRestriction:
type: boolean
title: enable_inference_region_restriction
url:
type: string
title: url
description: The project's LiveKit server URL (wss://), derived from its subdomain.
title: Project
additionalProperties: false
description: |-
Project is a LiveKit Cloud project (owned by cloud-api-server).
Field set mirrors backend-common model.Project (most config fields);
members/domains are separate list resources and are not embedded here.
livekit.publicapi.projects.v1.ProjectInvite:
type: object
properties:
projectId:
type: string
title: project_id
email:
type: string
title: email
role:
type: integer
title: role
format: int32
inviteToken:
type: string
title: invite_token
expiresAt:
title: expires_at
$ref: '#/components/schemas/google.protobuf.Timestamp'
title: ProjectInvite
additionalProperties: false
description: ProjectInvite is a pending email invite to a project (token-based, cloud InviteMember2).
livekit.publicapi.projects.v1.ProjectMember:
type: object
properties:
projectId:
type: string
title: project_id
userId:
type: string
title: user_id
email:
type: string
title: email
role:
type: integer
title: role
format: int32
description: 'Matches cloud_protocol.ProjectMemberRole: INVITED=0, READ=1, WRITE=2, ADMIN=3.'
title: ProjectMember
additionalProperties: false
description: ProjectMember is a user's membership on a project.
livekit.publicapi.projects.v1.ProjectPreferences:
type: object
properties:
hideOnboarding:
type: boolean
title: hide_onboarding
discoverableByDomain:
type: boolean
title: discoverable_by_domain
joinableByDomain:
type: boolean
title: joinable_by_domain
hideSampleAppGallery:
type: boolean
title: hide_sample_app_gallery
disableTokenEndpoint:
type: boolean
title: disable_token_endpoint
tokenEndpointKey:
type: string
title: token_endpoint_key
sfuAllowPause:
type: boolean
title: sfu_allow_pause
enableEgressBackupStorage:
type: boolean
title: enable_egress_backup_storage
featureFlags:
type: object
title: feature_flags
additionalProperties:
type: string
title: value
enableEgressAutoRetry:
type: boolean
title: enable_egress_auto_retry
hipaaCompliant:
type: boolean
title: hipaa_compliant
roomConfigurations:
type: object
title: room_configurations
additionalProperties:
title: value
$ref: '#/components/schemas/livekit.RoomConfiguration'
title: ProjectPreferences
additionalProperties: false
description: |-
ProjectPreferences holds per-project UI/feature settings (mirrors
backend-common ProjectPreferences).
livekit.publicapi.projects.v1.ProjectPreferences.FeatureFlagsEntry:
type: object
properties:
key:
type: string
title: key
value:
type: string
title: value
title: FeatureFlagsEntry
additionalProperties: false
livekit.publicapi.projects.v1.ProjectPreferences.RoomConfigurationsEntry:
type: object
properties:
key:
type: string
title: key
value:
title: value
$ref: '#/components/schemas/livekit.RoomConfiguration'
title: RoomConfigurationsEntry
additionalProperties: false
livekit.publicapi.projects.v1.RemoveMemberRequest:
type: object
properties:
projectId:
type: string
title: project_id
userId:
type: string
title: user_id
title: RemoveMemberRequest
additionalProperties: false
livekit.publicapi.projects.v1.RemoveMemberResponse:
type: object
title: RemoveMemberResponse
additionalProperties: false
livekit.publicapi.projects.v1.TokenGrants:
type: object
properties:
identity:
type: string
title: identity
description: Participant identity (the token's subject).
name:
type: string
title: name
description: Participant display name.
kind:
type: string
title: kind
description: 'Participant kind: "standard", "ingress", "egress", "sip", or "agent".'
kindDetails:
type: array
items:
type: string
title: kind_details
video:
title: video
$ref: '#/components/schemas/livekit.publicapi.projects.v1.TokenGrants.Video'
sip:
title: sip
$ref: '#/components/schemas/livekit.publicapi.projects.v1.TokenGrants.Sip'
agent:
title: agent
$ref: '#/components/schemas/livekit.publicapi.projects.v1.TokenGrants.Agent'
inference:
title: inference
$ref: '#/components/schemas/livekit.publicapi.projects.v1.TokenGrants.Inference'
observability:
title: observability
$ref: '#/components/schemas/livekit.publicapi.projects.v1.TokenGrants.Observability'
roomConfig:
title: room_config
description: |-
Configuration for a room this participant creates on join, including
agent dispatches.
$ref: '#/components/schemas/livekit.RoomConfiguration'
roomPreset:
type: string
title: room_preset
description: Cloud room configuration preset; fields in room_config override it.
metadata:
type: string
title: metadata
attributes:
type: object
title: attributes
additionalProperties:
type: string
title: value
agentEndpoint:
title: agent_endpoint
$ref: '#/components/schemas/livekit.publicapi.projects.v1.TokenGrants.AgentEndpoint'
agentThread:
title: agent_thread
$ref: '#/components/schemas/livekit.publicapi.projects.v1.TokenGrants.AgentThread'
title: TokenGrants
additionalProperties: false
description: |-
TokenGrants are the claims of a LiveKit access token. Field names match the
token's JSON claims (protocol auth.ClaimGrants), so a token's claims JSON is
a valid TokenGrants in JSON form.
livekit.publicapi.projects.v1.TokenGrants.Agent:
type: object
properties:
admin:
type: boolean
title: admin
simulationAdmin:
type: boolean
title: simulation_admin
databaseAdmin:
type: boolean
title: database_admin
dispatchAdmin:
type: boolean
title: dispatch_admin
title: Agent
additionalProperties: false
description: Agent server API permissions.
livekit.publicapi.projects.v1.TokenGrants.AgentEndpoint:
type: object
properties:
call:
type: boolean
title: call
agentName:
type: string
title: agent_name
description: One agent; empty for every agent of the project.
deployment:
type: string
title: deployment
description: One deployment; empty for every deployment.
title: AgentEndpoint
additionalProperties: false
description: Calling an agent's non-public HTTP endpoints.
livekit.publicapi.projects.v1.TokenGrants.AgentThread:
type: object
properties:
scope:
type: string
title: scope
threadIds:
type: array
items:
type: string
title: thread_ids
list:
type: boolean
title: list
create:
type: boolean
title: create
write:
type: boolean
title: write
read:
type: boolean
title: read
delete:
type: boolean
title: delete
all:
type: boolean
title: all
title: AgentThread
additionalProperties: false
description: |-
A thread token: list and create in scope; read, write and delete the
threads in thread_ids, e.g. for a frontend rendering one conversation.
all extends it to every thread of the project; the action flags still
apply.
livekit.publicapi.projects.v1.TokenGrants.AttributesEntry:
type: object
properties:
key:
type: string
title: key
value:
type: string
title: value
title: AttributesEntry
additionalProperties: false
livekit.publicapi.projects.v1.TokenGrants.Inference:
type: object
properties:
perform:
type: boolean
title: perform
title: Inference
additionalProperties: false
livekit.publicapi.projects.v1.TokenGrants.Observability:
type: object
properties:
write:
type: boolean
title: write
title: Observability
additionalProperties: false
livekit.publicapi.projects.v1.TokenGrants.Sip:
type: object
properties:
admin:
type: boolean
title: admin
call:
type: boolean
title: call
title: Sip
additionalProperties: false
description: SIP server API permissions.
livekit.publicapi.projects.v1.TokenGrants.Video:
type: object
properties:
roomCreate:
type: boolean
title: room_create
description: 'Server API: create rooms.'
roomList:
type: boolean
title: room_list
description: 'Server API: list rooms.'
roomRecord:
type: boolean
title: room_record
description: 'Server API: start and manage egress.'
roomAdmin:
type: boolean
title: room_admin
description: 'Server API: manage `room` (or any room when unset).'
roomJoin:
type: boolean
title: room_join
description: Join `room`.
room:
type: string
title: room
canPublish:
type:
- boolean
- "null"
title: can_publish
description: Unset means allowed.
canSubscribe:
type:
- boolean
- "null"
title: can_subscribe
canPublishData:
type:
- boolean
- "null"
title: can_publish_data
canPublishSources:
type: array
items:
type: string
title: can_publish_sources
description: Restrict publishing to these sources ("camera", "microphone", …).
canUpdateOwnMetadata:
type:
- boolean
- "null"
title: can_update_own_metadata
ingressAdmin:
type: boolean
title: ingress_admin
description: 'Server API: manage ingress.'
hidden:
type: boolean
title: hidden
recorder:
type: boolean
title: recorder
agent:
type: boolean
title: agent
canSubscribeMetrics:
type:
- boolean
- "null"
title: can_subscribe_metrics
canManageAgentSession:
type:
- boolean
- "null"
title: can_manage_agent_session
destinationRoom:
type: string
title: destination_room
description: Room to move or forward participants to.
title: Video
additionalProperties: false
description: Room and participant permissions.
livekit.publicapi.projects.v1.UpdateInviteRequest:
type: object
properties:
projectId:
type: string
title: project_id
email:
type: string
title: email
role:
type: integer
title: role
format: int32
title: UpdateInviteRequest
additionalProperties: false
livekit.publicapi.projects.v1.UpdateInviteResponse:
type: object
properties:
invite:
title: invite
$ref: '#/components/schemas/livekit.publicapi.projects.v1.ProjectInvite'
title: UpdateInviteResponse
additionalProperties: false
livekit.publicapi.projects.v1.UpdateMemberRequest:
type: object
properties:
projectId:
type: string
title: project_id
userId:
type: string
title: user_id
role:
type: integer
title: role
format: int32
title: UpdateMemberRequest
additionalProperties: false
livekit.publicapi.projects.v1.UpdateMemberResponse:
type: object
properties:
member:
title: member
$ref: '#/components/schemas/livekit.publicapi.projects.v1.ProjectMember'
title: UpdateMemberResponse
additionalProperties: false
livekit.publicapi.projects.v1.UpdateProjectRequest:
type: object
properties:
projectId:
type: string
title: project_id
name:
type:
- string
- "null"
title: name
subdomain:
type:
- string
- "null"
title: subdomain
customDomain:
type:
- string
- "null"
title: custom_domain
enableAnalytics:
type:
- boolean
- "null"
title: enable_analytics
enableAutoCreate:
type:
- boolean
- "null"
title: enable_auto_create
enableRemoteUnmute:
type:
- boolean
- "null"
title: enable_remote_unmute
enabledCodecs:
type: array
items:
type: string
title: enabled_codecs
egressClusterId:
type:
- string
- "null"
title: egress_cluster_id
description: LK-admin only
enableHostedAgents:
type:
- boolean
- "null"
title: enable_hosted_agents
description: LK-admin only
enableUserDataRecording:
type:
- boolean
- "null"
title: enable_user_data_recording
requireExplicitDispatch:
type:
- boolean
- "null"
title: require_explicit_dispatch
isPrivate:
type:
- boolean
- "null"
title: is_private
members:
type: array
items:
$ref: '#/components/schemas/livekit.publicapi.projects.v1.CreateProjectMember'
title: members
description: 'Used when becoming private: explicit member set (actor kept as ADMIN).'
enablePiiRedaction:
type:
- boolean
- "null"
title: enable_pii_redaction
piiRedactionCategories:
type: array
items:
$ref: '#/components/schemas/cloud_protocol.PIIRedactionCategory'
title: pii_redaction_categories
description: |-
Non-empty list replaces the stored set (validated via Canonical).
Empty is ignored (cannot clear). When enabling with nothing stored,
defaults are applied server-side — same as cloud-api UpdateProject.
enableInferenceRegionRestriction:
type:
- boolean
- "null"
title: enable_inference_region_restriction
hideOnboarding:
type:
- boolean
- "null"
title: hide_onboarding
description: Preferences (flat, matching cloud-api UpdateProjectRequest).
discoverableByDomain:
type:
- boolean
- "null"
title: discoverable_by_domain
joinableByDomain:
type:
- boolean
- "null"
title: joinable_by_domain
hideSampleAppGallery:
type:
- boolean
- "null"
title: hide_sample_app_gallery
disableTokenEndpoint:
type:
- boolean
- "null"
title: disable_token_endpoint
tokenEndpointKey:
type:
- string
- "null"
title: token_endpoint_key
sfuAllowPause:
type:
- boolean
- "null"
title: sfu_allow_pause
enableEgressBackupStorage:
type:
- boolean
- "null"
title: enable_egress_backup_storage
enableEgressAutoRetry:
type:
- boolean
- "null"
title: enable_egress_auto_retry
featureFlags:
type: object
title: feature_flags
additionalProperties:
type: string
title: value
roomConfigsToUpsert:
type: array
items:
$ref: '#/components/schemas/livekit.RoomConfiguration'
title: room_configs_to_upsert
description: RoomConfiguration management (stored on project preferences).
roomConfigsToDelete:
type: array
items:
type: string
title: room_configs_to_delete
pinnedRegions:
title: pinned_regions
description: |-
SFU/datacenter region pins. Unset leaves them unchanged; a set message
replaces the stored set, so an empty regions list clears the pins (same
shape as cloud AdminPinnedRegions). Distinct from user_data_region.
$ref: '#/components/schemas/livekit.publicapi.projects.v1.PinnedRegions'
title: UpdateProjectRequest
additionalProperties: false
description: |-
UpdateProjectRequest patches a project. Unset optional fields are left
unchanged (proto3 optional). Mirrors cloud-api UpdateProject for local mode;
webhooks are separate RPCs (not included here).
livekit.publicapi.projects.v1.UpdateProjectRequest.FeatureFlagsEntry:
type: object
properties:
key:
type: string
title: key
value:
type: string
title: value
title: FeatureFlagsEntry
additionalProperties: false
livekit.publicapi.projects.v1.UpdateProjectResponse:
type: object
properties:
project:
title: project
$ref: '#/components/schemas/livekit.publicapi.projects.v1.Project'
title: UpdateProjectResponse
additionalProperties: false
livekit.publicapi.projects.v1.Webhook:
type: object
properties:
id:
type: string
title: id
name:
type: string
title: name
url:
type: string
title: url
signingKey:
type: string
title: signing_key
filterParams:
title: filter_params
$ref: '#/components/schemas/livekit.FilterParams'
title: Webhook
additionalProperties: false
description: Webhook is a project webhook destination (mirrors backend-common Webhook).
livekit.publicapi.simulations.v1.Scenarios.GenerateFromSession.Request:
type: object
properties:
projectId:
type: string
title: project_id
roomId:
type: string
title: room_id
description: Room session (RM_...) to derive the scenario from.
region:
type: string
title: region
description: 'Unused today: the session''s recording is found by project and room.'
title: Request
additionalProperties: false
livekit.publicapi.simulations.v1.Scenarios.GenerateFromSession.Response:
type: object
properties:
scenario:
title: scenario
$ref: '#/components/schemas/livekit.Scenario'
title: Response
additionalProperties: false
livekit.publicapi.simulations.v1.SimulationRuns.Cancel.Request:
type: object
properties:
projectId:
type: string
title: project_id
simulationRunId:
type: string
title: simulation_run_id
title: Request
additionalProperties: false
livekit.publicapi.simulations.v1.SimulationRuns.Cancel.Response:
type: object
title: Response
additionalProperties: false
livekit.publicapi.simulations.v1.SimulationRuns.ConfirmSourceUpload.Request:
type: object
properties:
projectId:
type: string
title: project_id
simulationRunId:
type: string
title: simulation_run_id
codeEntrypoint:
type: string
title: code_entrypoint
description: Entrypoint of the uploaded source, for example "agent.py".
title: Request
additionalProperties: false
livekit.publicapi.simulations.v1.SimulationRuns.ConfirmSourceUpload.Response:
type: object
title: Response
additionalProperties: false
livekit.publicapi.simulations.v1.SimulationRuns.Counts.Request:
type: object
properties:
projectId:
type: string
title: project_id
startTime:
title: start_time
description: |-
Half-open window [start_time, end_time) on the run's creation time.
Both are required and end_time must be after start_time.
$ref: '#/components/schemas/google.protobuf.Timestamp'
endTime:
title: end_time
$ref: '#/components/schemas/google.protobuf.Timestamp'
status:
oneOf:
- $ref: '#/components/schemas/livekit.SimulationRun.Status'
- type: "null"
title: status
description: Only runs in this status.
agentName:
type:
- string
- "null"
title: agent_name
description: Only runs of this agent (exact name).
mode:
oneOf:
- $ref: '#/components/schemas/livekit.SimulationMode'
- type: "null"
title: mode
description: Only runs in this conversation mode.
title: Request
additionalProperties: false
livekit.publicapi.simulations.v1.SimulationRuns.Counts.Response:
type: object
properties:
buckets:
type: array
items:
$ref: '#/components/schemas/livekit.SimulationRun.Counts.Bucket'
title: buckets
description: |-
Buckets holding at least one run, ascending by bucket_start. Empty
buckets are omitted; each run lands in exactly one bucket, so the
counts sum to the number of runs in the window.
interval:
title: interval
description: |-
The bucket width the service chose for the window (at most 60 buckets,
never narrower than one minute), so a client zero-fills the omitted
buckets on the grid the counts were built on.
$ref: '#/components/schemas/google.protobuf.Duration'
title: Response
additionalProperties: false
livekit.publicapi.simulations.v1.SimulationRuns.Create.Request:
type: object
properties:
projectId:
type: string
title: project_id
agentName:
type: string
title: agent_name
description: |-
Name the agent under test is registered under; every job dispatches it
into the simulation room, so it must already be deployed or running as
a worker. Empty uses the project's default agent. Recorded on the run
and usable as a ListSimulationRuns filter.
numSimulations:
type: integer
title: num_simulations
format: int32
description: |-
Number of scenarios to generate from the agent source when
scenario_group is unset.
region:
type: string
title: region
description: 'Reserved: must be empty, and the service chooses where the run happens.'
scenarioGroup:
oneOf:
- $ref: '#/components/schemas/livekit.ScenarioGroup'
- type: "null"
title: scenario_group
description: |-
Run exactly these scenarios (the contents of a scenarios.yaml) instead
of generating num_simulations of them; the run then needs no source
upload and starts immediately.
concurrency:
type:
- integer
- "null"
title: concurrency
format: int32
description: |-
Maximum jobs running in parallel, at most 20; above that the request is
InvalidArgument. The project's concurrency quota can run fewer at once.
Unset uses the server default.
mode:
title: mode
description: Conversation mode for every job; unspecified means TEXT.
$ref: '#/components/schemas/livekit.SimulationMode'
backgroundNoise:
type: boolean
title: background_noise
description: Audio impairments applied to the simulated user; AUDIO mode only.
lowQualityMicrophone:
type: boolean
title: low_quality_microphone
packetLoss:
type: boolean
title: packet_loss
ci:
oneOf:
- $ref: '#/components/schemas/livekit.SimulationRun.CI'
- type: "null"
title: ci
description: |-
The CI pipeline this run came from, so runs can be linked back to
commits.
title: Request
additionalProperties: false
livekit.publicapi.simulations.v1.SimulationRuns.Create.Response:
type: object
properties:
simulationRunId:
type: string
title: simulation_run_id
presignedPostRequest:
title: presigned_post_request
description: |-
Presigned POST for uploading the agent source archive that scenarios
are generated from; upload, then call ConfirmSimulationSourceUpload.
Unset when the run was created with a scenario_group.
$ref: '#/components/schemas/livekit.PresignedPostRequest'
title: Response
additionalProperties: false
livekit.publicapi.simulations.v1.SimulationRuns.Get.Request:
type: object
properties:
projectId:
type: string
title: project_id
simulationRunId:
type: string
title: simulation_run_id
title: Request
additionalProperties: false
livekit.publicapi.simulations.v1.SimulationRuns.Get.Response:
type: object
properties:
run:
title: run
description: |-
The run. summary_zstd is always empty here; see
GetSimulationRunSummary.
$ref: '#/components/schemas/livekit.SimulationRun'
title: Response
additionalProperties: false
livekit.publicapi.simulations.v1.SimulationRuns.GetSummary.Request:
type: object
properties:
projectId:
type: string
title: project_id
simulationRunId:
type: string
title: simulation_run_id
title: Request
additionalProperties: false
livekit.publicapi.simulations.v1.SimulationRuns.GetSummary.Response:
type: object
properties:
summary:
title: summary
description: The decoded summary of a finished run.
$ref: '#/components/schemas/livekit.SimulationRunSummary'
title: Response
additionalProperties: false
livekit.publicapi.simulations.v1.SimulationRuns.List.Request:
type: object
properties:
projectId:
type: string
title: project_id
page:
title: page
description: |-
Cursor paging. page_size is accepted for forward compatibility but not
honored: the page size is fixed by the simulation service.
$ref: '#/components/schemas/livekit.publicapi.common.v1.PageRequest'
status:
oneOf:
- $ref: '#/components/schemas/livekit.SimulationRun.Status'
- type: "null"
title: status
description: Only runs in this status.
agentName:
type:
- string
- "null"
title: agent_name
description: Only runs of this agent (exact name).
startTime:
title: start_time
description: |-
Half-open window [start_time, end_time) on the run's creation time.
Either bound may be left unset.
$ref: '#/components/schemas/google.protobuf.Timestamp'
endTime:
title: end_time
$ref: '#/components/schemas/google.protobuf.Timestamp'
mode:
oneOf:
- $ref: '#/components/schemas/livekit.SimulationMode'
- type: "null"
title: mode
description: Only runs in this conversation mode.
title: Request
additionalProperties: false
livekit.publicapi.simulations.v1.SimulationRuns.List.Response:
type: object
properties:
items:
type: array
items:
$ref: '#/components/schemas/livekit.SimulationRun'
title: items
pageInfo:
title: page_info
$ref: '#/components/schemas/livekit.publicapi.common.v1.PageInfo'
title: Response
additionalProperties: false
livekit.publicapi.threads.v1.Threads.Create.Request:
type: object
properties:
projectId:
type: string
title: project_id
scope:
type: string
title: scope
description: |-
Optional scope grouping the thread (typically the user's identity),
at most 256 bytes.
attributes:
type: object
title: attributes
additionalProperties:
type: string
title: value
idleTtl:
title: idle_ttl
description: Unset takes the server default.
$ref: '#/components/schemas/google.protobuf.Duration'
title: Request
additionalProperties: false
livekit.publicapi.threads.v1.Threads.Create.Request.AttributesEntry:
type: object
properties:
key:
type: string
title: key
value:
type: string
title: value
title: AttributesEntry
additionalProperties: false
livekit.publicapi.threads.v1.Threads.Create.Response:
type: object
properties:
thread:
title: thread
$ref: '#/components/schemas/livekit.agent.AgentThread.Thread'
title: Response
additionalProperties: false
livekit.publicapi.threads.v1.Threads.Delete.Request:
type: object
properties:
projectId:
type: string
title: project_id
threadId:
type: string
title: thread_id
title: Request
additionalProperties: false
livekit.publicapi.threads.v1.Threads.Delete.Response:
type: object
title: Response
additionalProperties: false
livekit.publicapi.threads.v1.Threads.Get.Request:
type: object
properties:
projectId:
type: string
title: project_id
threadId:
type: string
title: thread_id
title: Request
additionalProperties: false
livekit.publicapi.threads.v1.Threads.Get.Response:
type: object
properties:
thread:
title: thread
$ref: '#/components/schemas/livekit.agent.AgentThread.Thread'
title: Response
additionalProperties: false
livekit.publicapi.threads.v1.Threads.Items.Request:
type: object
properties:
projectId:
type: string
title: project_id
threadId:
type: string
title: thread_id
agent:
type: string
title: agent
description: One agent's items; empty for every agent's.
page:
title: page
$ref: '#/components/schemas/livekit.publicapi.common.v1.PageRequest'
sortOrder:
title: sort_order
description: |-
Direction of the item order. Defaults to ascending (oldest first) when
unset; descending starts from the latest item and pages back.
$ref: '#/components/schemas/livekit.publicapi.common.v1.SortOrder'
title: Request
additionalProperties: false
livekit.publicapi.threads.v1.Threads.Items.Response:
type: object
properties:
items:
type: array
items:
$ref: '#/components/schemas/livekit.agent.AgentThread.Item'
title: items
pageInfo:
title: page_info
$ref: '#/components/schemas/livekit.publicapi.common.v1.PageInfo'
title: Response
additionalProperties: false
livekit.publicapi.threads.v1.Threads.List.Request:
type: object
properties:
projectId:
type: string
title: project_id
scope:
type: string
title: scope
page:
title: page
$ref: '#/components/schemas/livekit.publicapi.common.v1.PageRequest'
title: Request
additionalProperties: false
livekit.publicapi.threads.v1.Threads.List.Response:
type: object
properties:
items:
type: array
items:
$ref: '#/components/schemas/livekit.agent.AgentThread.Thread'
title: items
pageInfo:
title: page_info
$ref: '#/components/schemas/livekit.publicapi.common.v1.PageInfo'
title: Response
additionalProperties: false
livekit.publicapi.threads.v1.Threads.Tasks.Request:
type: object
properties:
projectId:
type: string
title: project_id
threadId:
type: string
title: thread_id
status:
oneOf:
- $ref: '#/components/schemas/livekit.agent.AgentTask.Status'
- type: "null"
title: status
description: Only tasks in this status; unset for every status.
page:
title: page
$ref: '#/components/schemas/livekit.publicapi.common.v1.PageRequest'
title: Request
additionalProperties: false
livekit.publicapi.threads.v1.Threads.Tasks.Response:
type: object
properties:
items:
type: array
items:
$ref: '#/components/schemas/livekit.agent.AgentTask.Task'
title: items
pageInfo:
title: page_info
$ref: '#/components/schemas/livekit.publicapi.common.v1.PageInfo'
title: Response
additionalProperties: false
livekit.publicapi.threads.v1.Threads.Update.Request:
type: object
properties:
projectId:
type: string
title: project_id
threadId:
type: string
title: thread_id
attributes:
type: object
title: attributes
additionalProperties:
type: string
title: value
idleTtl:
title: idle_ttl
$ref: '#/components/schemas/google.protobuf.Duration'
title: Request
additionalProperties: false
livekit.publicapi.threads.v1.Threads.Update.Request.AttributesEntry:
type: object
properties:
key:
type: string
title: key
value:
type: string
title: value
title: AttributesEntry
additionalProperties: false
livekit.publicapi.threads.v1.Threads.Update.Response:
type: object
properties:
thread:
title: thread
$ref: '#/components/schemas/livekit.agent.AgentThread.Thread'
title: Response
additionalProperties: false
livekit.publicapi.users.v1.GetCurrentUserRequest:
type: object
title: GetCurrentUserRequest
additionalProperties: false
livekit.publicapi.users.v1.GetCurrentUserResponse:
type: object
properties:
user:
title: user
$ref: '#/components/schemas/livekit.publicapi.users.v1.User'
title: GetCurrentUserResponse
additionalProperties: false
livekit.publicapi.users.v1.GetUserRequest:
type: object
properties:
userId:
type: string
title: user_id
title: GetUserRequest
additionalProperties: false
livekit.publicapi.users.v1.GetUserResponse:
type: object
properties:
user:
title: user
$ref: '#/components/schemas/livekit.publicapi.users.v1.User'
title: GetUserResponse
additionalProperties: false
livekit.publicapi.users.v1.ListUsersRequest:
type: object
properties:
page:
title: page
$ref: '#/components/schemas/livekit.publicapi.common.v1.PageRequest'
projectId:
type: string
title: project_id
description: |-
At least one of project_id or workspace_id is required.
If both are set, project_id must belong to workspace_id; members are
the project's members.
workspaceId:
type: string
title: workspace_id
title: ListUsersRequest
additionalProperties: false
livekit.publicapi.users.v1.ListUsersResponse:
type: object
properties:
items:
type: array
items:
$ref: '#/components/schemas/livekit.publicapi.users.v1.User'
title: items
pageInfo:
title: page_info
$ref: '#/components/schemas/livekit.publicapi.common.v1.PageInfo'
title: ListUsersResponse
additionalProperties: false
livekit.publicapi.users.v1.User:
type: object
properties:
id:
type: string
title: id
email:
type: string
title: email
createdAt:
title: created_at
$ref: '#/components/schemas/google.protobuf.Timestamp'
title: User
additionalProperties: false
description: User is a LiveKit Cloud user (owned by cloud-api-server).
livekit.publicapi.workspaces.v1.AnswerInviteRequest:
type: object
properties:
inviteToken:
type: string
title: invite_token
accept:
type: boolean
title: accept
title: AnswerInviteRequest
additionalProperties: false
livekit.publicapi.workspaces.v1.AnswerInviteResponse:
type: object
properties:
member:
title: member
description: set when accept=true
$ref: '#/components/schemas/livekit.publicapi.workspaces.v1.WorkspaceMember'
title: AnswerInviteResponse
additionalProperties: false
livekit.publicapi.workspaces.v1.CreateInviteRequest:
type: object
properties:
workspaceId:
type: string
title: workspace_id
email:
type: string
title: email
role:
type: integer
title: role
format: int32
title: CreateInviteRequest
additionalProperties: false
livekit.publicapi.workspaces.v1.CreateInviteResponse:
type: object
properties:
workspaceId:
type: string
title: workspace_id
inviteToken:
type: string
title: invite_token
title: CreateInviteResponse
additionalProperties: false
livekit.publicapi.workspaces.v1.CreateProjectRequest:
type: object
properties:
workspaceId:
type: string
title: workspace_id
name:
type: string
title: name
subdomain:
type: string
title: subdomain
description: optional; generated from name when empty
isPrivate:
type: boolean
title: is_private
members:
type: array
items:
$ref: '#/components/schemas/livekit.publicapi.projects.v1.CreateProjectMember'
title: members
userDataRegion:
type: string
title: user_data_region
description: create-only; empty keeps the deployment default
title: CreateProjectRequest
additionalProperties: false
livekit.publicapi.workspaces.v1.CreateWorkspaceRequest:
type: object
properties:
name:
type: string
title: name
organizationId:
type: string
title: organization_id
description: |-
Optional organization association. from_project_id and preferences are intentionally omitted: cloud treats
from_project_id as admin-only, and hipaa_compliant preferences cascade to
every project (AdminService.UpdateWorkspace only).
title: CreateWorkspaceRequest
additionalProperties: false
livekit.publicapi.workspaces.v1.CreateWorkspaceResponse:
type: object
properties:
workspace:
title: workspace
$ref: '#/components/schemas/livekit.publicapi.workspaces.v1.Workspace'
title: CreateWorkspaceResponse
additionalProperties: false
livekit.publicapi.workspaces.v1.DeleteInviteRequest:
type: object
properties:
workspaceId:
type: string
title: workspace_id
email:
type: string
title: email
title: DeleteInviteRequest
additionalProperties: false
livekit.publicapi.workspaces.v1.DeleteInviteResponse:
type: object
title: DeleteInviteResponse
additionalProperties: false
livekit.publicapi.workspaces.v1.DeleteMemberRequest:
type: object
properties:
workspaceId:
type: string
title: workspace_id
userId:
type: string
title: user_id
title: DeleteMemberRequest
additionalProperties: false
livekit.publicapi.workspaces.v1.DeleteMemberResponse:
type: object
title: DeleteMemberResponse
additionalProperties: false
livekit.publicapi.workspaces.v1.DeleteProjectRequest:
type: object
properties:
workspaceId:
type: string
title: workspace_id
projectId:
type: string
title: project_id
title: DeleteProjectRequest
additionalProperties: false
livekit.publicapi.workspaces.v1.DeleteWorkspaceRequest:
type: object
properties:
workspaceId:
type: string
title: workspace_id
title: DeleteWorkspaceRequest
additionalProperties: false
livekit.publicapi.workspaces.v1.DeleteWorkspaceResponse:
type: object
title: DeleteWorkspaceResponse
additionalProperties: false
livekit.publicapi.workspaces.v1.GetInviteRequest:
type: object
properties:
inviteToken:
type: string
title: invite_token
title: GetInviteRequest
additionalProperties: false
livekit.publicapi.workspaces.v1.GetInviteResponse:
type: object
properties:
invite:
title: invite
$ref: '#/components/schemas/livekit.publicapi.workspaces.v1.WorkspaceInvite'
title: GetInviteResponse
additionalProperties: false
livekit.publicapi.workspaces.v1.GetMemberRequest:
type: object
properties:
workspaceId:
type: string
title: workspace_id
userId:
type: string
title: user_id
title: GetMemberRequest
additionalProperties: false
livekit.publicapi.workspaces.v1.GetMemberResponse:
type: object
properties:
member:
title: member
$ref: '#/components/schemas/livekit.publicapi.workspaces.v1.WorkspaceMember'
title: GetMemberResponse
additionalProperties: false
livekit.publicapi.workspaces.v1.GetProjectRequest:
type: object
properties:
workspaceId:
type: string
title: workspace_id
projectId:
type: string
title: project_id
title: GetProjectRequest
additionalProperties: false
livekit.publicapi.workspaces.v1.GetWorkspaceRequest:
type: object
properties:
workspaceId:
type: string
title: workspace_id
title: GetWorkspaceRequest
additionalProperties: false
livekit.publicapi.workspaces.v1.GetWorkspaceResponse:
type: object
properties:
workspace:
title: workspace
$ref: '#/components/schemas/livekit.publicapi.workspaces.v1.Workspace'
title: GetWorkspaceResponse
additionalProperties: false
livekit.publicapi.workspaces.v1.ListInvitesRequest:
type: object
properties:
workspaceId:
type: string
title: workspace_id
title: ListInvitesRequest
additionalProperties: false
livekit.publicapi.workspaces.v1.ListInvitesResponse:
type: object
properties:
items:
type: array
items:
$ref: '#/components/schemas/livekit.publicapi.workspaces.v1.WorkspaceInvite'
title: items
title: ListInvitesResponse
additionalProperties: false
livekit.publicapi.workspaces.v1.ListMembersRequest:
type: object
properties:
workspaceId:
type: string
title: workspace_id
title: ListMembersRequest
additionalProperties: false
livekit.publicapi.workspaces.v1.ListMembersResponse:
type: object
properties:
items:
type: array
items:
$ref: '#/components/schemas/livekit.publicapi.workspaces.v1.WorkspaceMember'
title: items
title: ListMembersResponse
additionalProperties: false
livekit.publicapi.workspaces.v1.ListProjectsRequest:
type: object
properties:
workspaceId:
type: string
title: workspace_id
page:
title: page
$ref: '#/components/schemas/livekit.publicapi.common.v1.PageRequest'
title: ListProjectsRequest
additionalProperties: false
description: |-
Workspace-scoped project RPCs: requests are owned here (required
workspace_id); responses reuse projects.v1.
livekit.publicapi.workspaces.v1.ListWorkspacesRequest:
type: object
properties:
page:
title: page
$ref: '#/components/schemas/livekit.publicapi.common.v1.PageRequest'
title: ListWorkspacesRequest
additionalProperties: false
livekit.publicapi.workspaces.v1.ListWorkspacesResponse:
type: object
properties:
items:
type: array
items:
$ref: '#/components/schemas/livekit.publicapi.workspaces.v1.Workspace'
title: items
pageInfo:
title: page_info
$ref: '#/components/schemas/livekit.publicapi.common.v1.PageInfo'
title: ListWorkspacesResponse
additionalProperties: false
livekit.publicapi.workspaces.v1.UpdateMemberRequest:
type: object
properties:
workspaceId:
type: string
title: workspace_id
userId:
type: string
title: user_id
role:
type: integer
title: role
format: int32
title: UpdateMemberRequest
additionalProperties: false
livekit.publicapi.workspaces.v1.UpdateMemberResponse:
type: object
properties:
member:
title: member
$ref: '#/components/schemas/livekit.publicapi.workspaces.v1.WorkspaceMember'
title: UpdateMemberResponse
additionalProperties: false
livekit.publicapi.workspaces.v1.UpdateProjectRequest:
type: object
properties:
workspaceId:
type: string
title: workspace_id
update:
title: update
description: |-
Nested projects.v1 update; the handler applies this request's workspace_id
as the store constraint.
$ref: '#/components/schemas/livekit.publicapi.projects.v1.UpdateProjectRequest'
title: UpdateProjectRequest
additionalProperties: false
livekit.publicapi.workspaces.v1.UpdateWorkspaceRequest:
type: object
properties:
workspaceId:
type: string
title: workspace_id
name:
type:
- string
- "null"
title: name
title: UpdateWorkspaceRequest
additionalProperties: false
description: |-
Mirrors cloud-api WorkspaceService.UpdateWorkspace, which only accepts a
name: workspace preferences (hipaa_compliant) cascade to every project in the
workspace and are LK-admin-only there (AdminService.UpdateWorkspace), so they
are deliberately not settable on this path.
livekit.publicapi.workspaces.v1.UpdateWorkspaceResponse:
type: object
properties:
workspace:
title: workspace
$ref: '#/components/schemas/livekit.publicapi.workspaces.v1.Workspace'
title: UpdateWorkspaceResponse
additionalProperties: false
livekit.publicapi.workspaces.v1.Workspace:
type: object
properties:
id:
type: string
title: id
name:
type: string
title: name
creatorId:
type: string
title: creator_id
organizationId:
type: string
title: organization_id
createdAt:
title: created_at
$ref: '#/components/schemas/google.protobuf.Timestamp'
preferences:
title: preferences
$ref: '#/components/schemas/livekit.publicapi.workspaces.v1.WorkspacePreferences'
title: Workspace
additionalProperties: false
description: |-
Workspace is a LiveKit Cloud workspace (owned by cloud-api-server).
Field set mirrors backend-common model.Workspace.ToProto(); members/invites
are separate list resources and are not embedded here.
livekit.publicapi.workspaces.v1.WorkspaceInvite:
type: object
properties:
workspaceId:
type: string
title: workspace_id
email:
type: string
title: email
role:
type: integer
title: role
format: int32
inviteToken:
type: string
title: invite_token
expiresAt:
title: expires_at
$ref: '#/components/schemas/google.protobuf.Timestamp'
title: WorkspaceInvite
additionalProperties: false
description: WorkspaceInvite is a pending email invite to a workspace.
livekit.publicapi.workspaces.v1.WorkspaceMember:
type: object
properties:
workspaceId:
type: string
title: workspace_id
userId:
type: string
title: user_id
email:
type: string
title: email
role:
type: integer
title: role
format: int32
description: 'Matches cloud_protocol.ProjectMemberRole: INVITED=0, READ=1, WRITE=2, ADMIN=3.'
title: WorkspaceMember
additionalProperties: false
description: WorkspaceMember is a user's membership on a workspace.
livekit.publicapi.workspaces.v1.WorkspacePreferences:
type: object
properties:
hipaaCompliant:
type: boolean
title: hipaa_compliant
title: WorkspacePreferences
additionalProperties: false
description: |-
WorkspacePreferences holds per-workspace settings (mirrors backend-common
WorkspacePreferences).
security: []
tags:
- name: livekit.publicapi.analytics.v1.AnalyticsService
description: |-
AnalyticsService is the project-scoped, typed analytics surface (READ tier).
It exposes the same data the LiveKit Cloud dashboard renders, mapped into
stable typed messages: room sessions and their participants/events, and
pre-derived project/agent statistics sourced from the aggregator.
Each operation's request and response are namespaced under a page-shaped
parent message (Sessions, SessionParticipants, SessionEvents, ProjectOverview,
Agents) so the top-level surface stays legible. The returned data shapes
(Session, SessionDetail, ParticipantInfo, AgentAnalytics, ...) are top-level
and shared.
Raw per-session observability (transcripts, logs, traces, metrics,
recordings) is NOT here — it lives in the ObservabilityService in
livekit.publicapi.observability.v1, gated at the ADMIN tier.
Authorization mirrors cloud-api-server: these reads require project READ.
- name: livekit.publicapi.databases.v1.DatabaseService
description: |-
DatabaseService manages a project's agent databases: SQLite databases an
agent keeps across sessions, stored durably by agent-db in the project's data
region. Queries do not go through this service: they run over the WebSocket
data plane at /v0/agentstore/db.
Authorization: a LiveKit access token for the project with the agent
databaseAdmin grant, or a user with project READ (Get, List, Export) or WRITE
(Create, Delete).
- name: livekit.publicapi.observability.v1.ObservabilityService
description: |-
ObservabilityService serves raw per-session observability data. Sessions are
identified by their room-session id (RM_...), the same id AnalyticsService
returns as `session_id`.
- name: livekit.publicapi.projects.v1.ProjectService
description: ProjectService is the projects domain of the public API.
- name: livekit.publicapi.simulations.v1.SimulationService
description: |-
SimulationService runs agent simulations against a project's agent and
returns their graded outcomes. Each job puts a simulated user in a room with
the agent under test, dispatched by agent_name, so that agent must be
deployed or running as a worker before the run starts.
Runs are asynchronous. CreateSimulationRun returns a run id and runs in one
of two ways:
- With a scenario_group, the run starts immediately (RUNNING) and plays
exactly those scenarios.
- Without one, the service generates num_simulations scenarios from the
agent's source: the run waits in PENDING_UPLOAD for the source to be
uploaded to the returned presigned POST and confirmed with
ConfirmSimulationSourceUpload, then goes GENERATING, then RUNNING. The
source is only read to write scenarios; it is not the agent under test.
Read the outcome back with GetSimulationRun and GetSimulationRunSummary.
Authorization: reads (Get, List, GetSummary) require project READ; writes
(Create, ConfirmSourceUpload, Cancel, GenerateScenarioFromSession) require
project WRITE. A project the caller cannot see is NotFound; a project the
caller can see but lacks the role for is PermissionDenied.
- name: livekit.publicapi.threads.v1.ThreadService
description: |-
ThreadService manages a project's agent threads: the durable conversation an
agent has with a person across channels and over time, named by its "AT_" id.
Each thread has its own database, created with it.
Authorization: a LiveKit access token for the project whose agentThread grant
allows the action (list and create by scope; get, items, tasks and delete by
thread id; any thread with all), or a user with project READ (Get, List,
items, tasks) or WRITE (everything else).
- name: livekit.publicapi.users.v1.UserService
description: UserService is the users domain of the public API.
- name: livekit.publicapi.workspaces.v1.WorkspaceService
description: WorkspaceService is the workspaces domain of the public API.