LiveKit Cloud API

Overview

The LiveKit Cloud API lets you manage LiveKit Cloud resources over HTTP from your own tooling or coding agents. Use it to create and configure projects, manage members and API keys, register webhooks, mint access tokens, read session analytics and observability data, and run agent simulations.

To control rooms and the agents in them, use the Room service API and the other server APIs, which cover agent dispatch, telephony, recording, and ingress. To deploy agents from code, use the LiveKit CLI.

The base URL is https://beta-api.livekit.cloud and every path starts with /v0. The API serves its own OpenAPI 3.1 spec.

OpenAPI spec

Download the spec:

curl https://beta-api.livekit.cloud/v0/openapi -o openapi.yaml

Authentication

Every endpoint in this reference authenticates as a LiveKit user with a session token, sent as a bearer token:

Authorization: Bearer <token>

A session token identifies a user, not a project. It isn't the API key and secret you use to sign room access tokens.

Sign in

Get a session token with the LiveKit CLI:

lk cloud auth --user-auth

The command asks for a device name, opens a browser page for you to confirm, then stores the token in ~/.livekit/cli-config.yaml. It needs an interactive terminal.

A session lasts about 30 days and doesn't refresh, so run the command again when one expires.

Because a session belongs to a person and renews in a browser, the API fits one-off tasks, your own scripts, and coding agents that act for you. Automation that runs without a person present can't renew a session.

Pass --user-auth to each lk command that calls the API. The CLI hides some commands, such as lk analytics, until you sign in.

Use a token in a script

Read the stored token and send it as the bearer token:

export LIVEKIT_SESSION_TOKEN=$(grep -m1 session_token ~/.livekit/cli-config.yaml | awk '{print $2}')

curl "https://beta-api.livekit.cloud/v0/users/me" \
  -H "Authorization: Bearer $LIVEKIT_SESSION_TOKEN"

If the file holds tokens for more than one account, the command reads the first one.

The response:

{
  "user": {
    "id": "LIYM4YkVTydCfM4Jm1kXpq",
    "email": "sam@example.com",
    "createdAt": "2025-11-03T09:12:44Z"
  }
}

A request with no token, or with an expired token, returns 401 and a WWW-Authenticate: Bearer realm="public-api" header.

Roles

The API checks each request against your role in the project named in the request path. When your role doesn't permit the operation, the API returns 403. When you aren't a member of the project at all, it returns 404.

Roles are integers:

A pending invitee has role 0 and no access until they accept the invite.

To assign the Read or Write role, the project must be on the Scale or Enterprise plan, which include role-based access control. On other plans, a request that assigns either role returns 403. Admin invites work on every plan. To compare plans, see Pricing .

Making requests

Endpoints are resource-oriented. The path identifies the resource, and the HTTP method identifies the operation. Operations that aren't create, read, update, or delete use a custom verb after a colon, such as POST /v0/project-invites/{inviteToken}:answer.

Request and response bodies are JSON, with camelCase field names. The API sends a 64-bit integer as a string, and a timestamp as an RFC 3339 string such as 2026-01-15T01:30:15Z. Responses include fields at their default value, such as false, 0, an empty string, or an empty list. A field that has no value set, such as an unset object, isn't in the response.

A PATCH request updates only the fields you send and leaves the rest unchanged:

curl -X PATCH "https://beta-api.livekit.cloud/v0/projects/$PROJECT_ID" \
  -H "Authorization: Bearer $LIVEKIT_SESSION_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"enableUserDataRecording":false}'

Some fields replace the whole value instead:

• The filterParams of a webhook. To learn more, see Webhooks.
• The pinnedRegions of a project. An empty list of regions clears the pins.
• The piiRedactionCategories of a project. The API ignores an empty list, so you can't clear the categories this way.

Pagination

List endpoints use a cursor to return results in pages. The list endpoints in this reference put their results in items, include a pageInfo object, and accept these query parameters:

The default and the cap depend on what you read:

These lists don't use the default page sizes:

• Webhooks and webhook events return every result in one page.
• Simulation runs use a page size that the simulation service sets, and ignore page.pageSize.

Pass nextCursor back as page.cursor to get the next page. The hasMore field tells you whether another page follows. On the last page, hasMore is false and nextCursor is empty.

A cursor is opaque. Send a cursor only to the list that returned it, with the same filter parameters that you sent on the first request. A cursor isn't valid against a different list or a different set of filters.

Request

curl "https://beta-api.livekit.cloud/v0/projects?page.pageSize=50&page.cursor=$CURSOR" \
  -H "Authorization: Bearer $LIVEKIT_SESSION_TOKEN"

Response

{
  "items": [],
  "pageInfo": { "nextCursor": "InBfMWEyYjNjNGQ1ZTZmIg", "hasMore": true }
}

Rate limits

The API limits the requests to each project per minute. All requests to a project count toward the same limit, from every user, token, and CLI command. Each request counts as one, whatever the endpoint. Requests that don't name a project, such as a request for the current user, don't count. The limit depends on the plan of the project.

When a project reaches its limit, the API returns status 429. The response has no Retry-After header, so wait, and then send the request again.

Errors

The API uses these status codes. The error body gives the gRPC code in its code field.

Every error returns a JSON body with a numeric code, a message, and details. The code is a gRPC status code , which is finer grained than the HTTP status. For example, a 400 is 3 (InvalidArgument) when the request is malformed, and 9 (FailedPrecondition) when the resource isn't in a state that permits the operation. To tell those apart, read code.

404 Not Found

{
  "code": 5,
  "message": "project not found",
  "details": []
}

400 Bad Request

{
  "code": 9,
  "message": "project has no API key",
  "details": []
}

401 Unauthorized

{
  "code": 16,
  "message": "authentication required",
  "details": []
}

Most errors leave details empty. Some errors include typed context. For example, a session observability read returns 400 with an ObservabilityDisabled detail when user data recording is off for the project and no data exists. The detail links to the observability settings of the project. The message describes the failure for developers, so don't show it to an end user.

With a valid token, a request to a path that the API doesn't serve returns 404 with code 5 and the message not found. Without a valid token, it returns 401.

Request IDs

Every response includes an X-Request-Id header. Include it when you report a problem. If you set the header on a request, the API returns your value.

X-Request-Id: 57b5fab65eb4f5f3cd5a847085869b0a

Resources

These resources have a reference page, an lk command, or both. For the commands and their flags, see the LiveKit CLI reference.