# Lightspeed JSON-RPC API Reference Generated from the Rust API method manifest. Parameter and result field details live in `api.schema.json` and `openrpc.json`; this reference focuses on operation semantics. ## Universe methods ### `initialize` **Inspect the Lightspeed protocol** Returns protocol version, server identity, and supported capabilities without changing universe state. - Params: `InitializeParams` - Result: `AgentApiOutcome` ### `session/start` **Create or reopen a session** Creates a session with optional config/profile setup. Profile metadata and retention supply creation defaults; explicit start values override them. An existing-or-none environment override can replace the profile intent. Retrying an existing session id returns that session. - Params: `SessionStartParams` - Result: `AgentApiOutcome` ### `session/managed/start` **Create or reopen a managed session** Creates a session with immutable lifecycle and workflow-tool declarations using explicit bound dispatch. Profile metadata, retention, and environment overrides follow session/start semantics. Retrying an id requires the same managed declaration; an ordinary session cannot be upgraded. - Params: `ManagedSessionStartParams` - Result: `AgentApiOutcome` ### `session/read` **Read a session** Returns current state plus a bounded newest-first run-summary page. Follow nextRunCursor with session/runs/list when hasOlderRuns is true; use session/events/read for the transcript. - Params: `SessionReadParams` - Result: `AgentApiOutcome` ### `session/list` **List sessions** Returns a cursor-paginated summary list ordered by most recent update. Pages may shift while sessions are changing. - Params: `SessionListParams` - Result: `AgentApiOutcome` ### `session/config/put` **Replace session configuration** Replaces the complete sparse config while the session is idle. Use the current config revision for safe read-modify-write; omitted features are revoked and an identical document is a no-op. - Params: `SessionConfigPutParams` - Result: `AgentApiOutcome` ### `session/rename` **Rename a session** Sets the display name, or clears it when displayName is omitted. - Params: `SessionRenameParams` - Result: `AgentApiOutcome` ### `session/metadata/put` **Replace session metadata** Replaces the complete descriptive key/value map (bounded like session/start); an omitted or empty map clears it. Record-only: the event log and updatedAtMs are untouched. - Params: `SessionMetadataPutParams` - Result: `AgentApiOutcome` ### `session/retention/put` **Replace session retention** Sets the positive close-relative automatic-deletion duration on a retention root, or clears it with null. Forks and delegated children inherit the root policy and cannot override it. - Params: `SessionRetentionPutParams` - Result: `AgentApiOutcome` ### `session/close` **Close a session** Closes an idle session and detaches its environment bindings. Force mode cancels active work, drops queued runs, and can recover a session whose workflow is unavailable. - Params: `SessionCloseParams` - Result: `AgentApiOutcome` ### `session/delete` **Delete closed sessions** Permanently removes a closed retention-tree leaf, or its closed history-fork and delegated-child subtree when cascade is true. Config-only clones are never included. - Params: `SessionDeleteParams` - Result: `AgentApiOutcome` ### `session/events/read` **Read the session event stream** Returns chronological events. Forward (default) follows after and supports long-polling. Backward reads the latest window below before (or the head); pass nextCursor as before until complete. Follow live events after the initial backward headCursor. Windows may split runs/tool batches; keep historical reconstruction separate from live controls. - Params: `SessionEventsReadParams` - Result: `AgentApiOutcome` ### `session/context/append` **Append keyed session context** Admits a batch of context entries with per-entry results. Stable keys make same-content retries no-ops; media preprocessing can fail one entry without discarding successful entries. - Params: `ContextAppendParams` - Result: `AgentApiOutcome` ### `session/context/remove` **Remove keyed session context** Removes active entries by stable key with per-key results. Missing keys are idempotent no-ops; runtime-reserved run keys cannot be removed. - Params: `ContextRemoveParams` - Result: `AgentApiOutcome` ### `session/context/compact` **Compact session context** Runs the configured compaction policy on an open idle session and waits for the resulting context revision. - Params: `ContextCompactParams` - Result: `AgentApiOutcome` ### `session/runs/start` **Start an agent run** Accepts input or existing context keys and returns once the run is accepted — queued behind an active run, or running — not when it finishes. Supply submissionId for retry safety, then follow session events or reread the session. - Params: `RunStartParams` - Result: `AgentApiOutcome` ### `session/runs/list` **List session runs** Returns a newest-first keyset page of bounded run summaries projected from current reducer state. - Params: `RunListParams` - Result: `AgentApiOutcome` ### `session/runs/read` **Read one session run** Reads and projects one run from its bounded event interval, paged by event sequence. - Params: `RunReadParams` - Result: `AgentApiOutcome` ### `session/runs/cancel` **Cancel a run** Requests cancellation of the named queued or active run and returns its current projected state; observe session events for terminal completion. In-flight model and tool activity is aborted; no grace turn runs. - Params: `RunCancelParams` - Result: `AgentApiOutcome` ### `session/runs/approvals/decide` **Decide pending run approvals** Approves or rejects pending MCP tool calls on the named active run. Valid decisions apply independently; the run resumes only after every pending approval has a decision. - Params: `RunApprovalsDecideParams` - Result: `AgentApiOutcome` ### `session/runs/steer` **Steer the active run** Injects input into the named active run; the model sees it at the next turn boundary without interrupting the in-flight turn. Accepted while the run is running or parked on an await; rejected for queued, cancelling, or finished runs. - Params: `RunSteerParams` - Result: `AgentApiOutcome` ### `session/skills/list` **List available session skills** Refreshes the session's configured VFS skill catalog and reports which discovered skills are enabled and active. An absent catalog yields an empty result. - Params: `SkillListParams` - Result: `AgentApiOutcome` ### `session/skills/active` **List active session skills** Returns skill instructions currently injected into context, including activation scope and source. - Params: `SkillActiveParams` - Result: `AgentApiOutcome` ### `session/skills/activate` **Activate a session skill** Loads an enabled skill from the current catalog and injects its instructions into an open idle session. Run-scoped activation is the default. - Params: `SkillActivateParams` - Result: `AgentApiOutcome` ### `session/skills/deactivate` **Deactivate a session skill** Removes an active skill's injected context from an open idle session; the skill must currently be active. - Params: `SkillDeactivateParams` - Result: `AgentApiOutcome` ### `session/profiles/apply` **Apply a profile to a session** Applies a named or inline profile's config, instructions, and environment setup to an existing session; mutating profile sections require it to be open and idle. Pass current revisions to guard concurrent changes. - Params: `ProfileApplyParams` - Result: `AgentApiOutcome` ### `session/environments/activate` **Activate a session environment** Selects an allowed, live universe environment for environment-targeted tools while the session is idle. - Params: `SessionEnvironmentActivateParams` - Result: `AgentApiOutcome` ### `session/environments/deactivate` **Deactivate the session environment** Clears active environment selection without changing or closing the universe environment. - Params: `SessionEnvironmentDeactivateParams` - Result: `AgentApiOutcome` ### `environments/credentials/bind` **Bind a credential into an environment** Maps an environment variable name to an existing grant/provider/direct-secret handle for a universe environment. The response exposes only the source handle, never secret material. - Params: `EnvironmentCredentialBindParams` - Result: `AgentApiOutcome` ### `environments/credentials/list` **List environment credential bindings** Returns variable names and credential source handles for a universe environment; resolved secret values are never returned. - Params: `EnvironmentCredentialListParams` - Result: `AgentApiOutcome` ### `environments/credentials/unbind` **Unbind an environment credential** Removes one variable-to-credential mapping without deleting the underlying grant, provider credential, or secret. - Params: `EnvironmentCredentialUnbindParams` - Result: `AgentApiOutcome` ### `environments/create` **Create an environment** Records an idempotent provisioning intent against an enabled universe binding. The provider validates its provider-wide template and provisions through its backend asynchronously. - Params: `EnvironmentCreateParams` - Result: `AgentApiOutcome` ### `environments/read` **Read an environment** Returns the durable universe resource, source binding, logical lifecycle state, and minimal current-incarnation identity. - Params: `EnvironmentReadParams` - Result: `AgentApiOutcome` ### `environments/list` **List environments** Lists universe-owned environment resources, optionally filtered by provider, binding, or logical lifecycle state. - Params: `EnvironmentListParams` - Result: `AgentApiOutcome` ### `environments/close` **Close an environment** Records an asynchronous idempotent close intent. Provider cleanup is resumed by lifecycle reconciliation; quota is released only after Closed. - Params: `EnvironmentCloseParams` - Result: `AgentApiOutcome` ### `environments/external/create` **Register an external environment** Creates an environment backed by a Lightspeed-reachable envd WebSocket endpoint. Reachability is checked on demand. - Params: `EnvironmentExternalCreateParams` - Result: `AgentApiOutcome` ### `environments/ingress/put` **Configure environment public ingress** Synchronously enables or disables one provider-authorized HTTPS endpoint for a provisioned environment. The provider owns hostname allocation, the approved guest port, routing, TLS, and health. - Params: `EnvironmentIngressPutParams` - Result: `AgentApiOutcome` ### `environments/power/put` **Set environment power intent** Records the desired power state (running, paused, suspended, or stopped) of a provisioned environment; the lifecycle reconciler converges the provider target asynchronously. Powered-down environments wake transparently on their next use. Rejected when the provider does not support the state. - Params: `EnvironmentPowerPutParams` - Result: `AgentApiOutcome` ### `environments/idle-policy/put` **Set environment idle policy** Replaces or clears the staged idle policy of a provisioned environment. The power reaper measures the daemon's idle duration against the pause/suspend/stop/close thresholds and escalates through the stages the provider supports. - Params: `EnvironmentIdlePolicyPutParams` - Result: `AgentApiOutcome` ### `environments/provider-bindings/list` **List environment provider bindings** Lists this universe's revisioned routing and admission bindings to deployment-scoped physical providers. - Params: `EnvironmentProviderBindingListParams` - Result: `AgentApiOutcome` ### `environments/provider-bindings/read` **Read an environment provider binding** Returns one universe routing and admission binding. Provider-wide templates and physical resource, network, and ingress policy remain provider-owned. - Params: `EnvironmentProviderBindingReadParams` - Result: `AgentApiOutcome` ### `environments/templates/list` **List environment templates** Reads immutable templates directly from the selected bound provider controller. - Params: `EnvironmentTemplateListParams` - Result: `AgentApiOutcome` ### `environments/templates/read` **Read an environment template** Returns one immutable template version from the selected bound provider controller. - Params: `EnvironmentTemplateReadParams` - Result: `AgentApiOutcome` ### `environments/jobs/create` **Create environment jobs** Starts a dependency-aware job group on one environment instance, injecting the environment's configured credentials at provider start. requestId is the retry identity; jobs are owned by the instance rather than a session. A powered-down environment is woken on use: the call fails with environment\_not\_ready while the wake is in progress; retry with backoff. - Params: `EnvironmentJobCreateParams` - Result: `AgentApiOutcome` ### `environments/jobs/read` **Read environment jobs** Reads selected job handles with bounded output, optional sequence continuation, and optional artifacts; use returned status/sequence data for polling. - Params: `EnvironmentJobReadParams` - Result: `AgentApiOutcome` ### `environments/jobs/cancel` **Cancel environment jobs** Requests cancellation for selected jobs, optionally including dependents. Force is provider-specific escalation; inspect each per-job result. - Params: `EnvironmentJobCancelParams` - Result: `AgentApiOutcome` ### `environments/registration-keys/create` **Mint an environment registration key** Creates a reusable universe-scoped key that lets outbound envd daemons register as environments. The plaintext secret is returned exactly once; only its hash is stored. Identity mode, active limit, disconnect grace, and expiry are the key's policy. Treat the secret like a cluster-join credential. - Params: `EnvironmentRegistrationKeyCreateParams` - Result: `AgentApiOutcome` ### `environments/registration-keys/read` **Read an environment registration key** Returns the key's display prefix, policy, status, and derived environment counts; never the secret or its hash. - Params: `EnvironmentRegistrationKeyReadParams` - Result: `AgentApiOutcome` ### `environments/registration-keys/list` **List environment registration keys** Lists this universe's registration keys with policy, status, and derived counts. Each key is the group of the environments it admitted. - Params: `EnvironmentRegistrationKeyListParams` - Result: `AgentApiOutcome` ### `environments/registration-keys/revoke` **Revoke an environment registration key** Stops the key from admitting new daemon identities; already registered daemons keep reconnecting. With closeEnvironments, also closes every non-closed environment the key admitted. Idempotent. - Params: `EnvironmentRegistrationKeyRevokeParams` - Result: `AgentApiOutcome` ### `models/list` **Discover available models** Queries supported providers directly, with a brief process-local burst cache, and returns best-effort selectable routes. One provider failure does not discard successful results from others. - Params: `ModelListParams` - Result: `AgentApiOutcome` ### `profiles/create` **Create an agent profile** Creates a new universe-scoped reusable profile document; use profiles/put for create-or-replace revision semantics. - Params: `ProfileCreateParams` - Result: `AgentApiOutcome` ### `profiles/read` **Read an agent profile** Returns the complete profile document and current revision. - Params: `ProfileReadParams` - Result: `AgentApiOutcome` ### `profiles/list` **List agent profiles** Returns lightweight summaries of universe-scoped reusable profiles. - Params: `ProfileListParams` - Result: `AgentApiOutcome` ### `profiles/put` **Create or replace an agent profile** Stores the complete profile document. Use expectedRevision from profiles/read when replacing to prevent lost updates; absence writes unconditionally. - Params: `ProfilePutParams` - Result: `AgentApiOutcome` ### `profiles/delete` **Delete an agent profile** Deletes the catalog document; sessions previously created or configured from it retain their materialized state. - Params: `ProfileDeleteParams` - Result: `AgentApiOutcome` ### `blobs/put` **Store content-addressed blobs** Decodes and stores a batch of base64 payloads, returning immutable content references in request order. Re-uploading identical bytes is naturally deduplicated. - Params: `BlobPutParams` - Result: `AgentApiOutcome` ### `blobs/read` **Read a content-addressed blob** Returns the complete immutable blob as base64; large values count against gateway and MCP response limits. - Params: `BlobReadParams` - Result: `AgentApiOutcome` ### `blobs/has` **Check blob availability** Checks a batch of content references without returning blob bodies, preserving request order. - Params: `BlobHasParams` - Result: `AgentApiOutcome` ### `vfs/snapshots/commit` **Commit a VFS snapshot** Validates and stores an immutable filesystem manifest. Upload referenced file blobs first; the returned snapshot ref is content-addressed. - Params: `VfsSnapshotCommitParams` - Result: `AgentApiOutcome` ### `vfs/snapshots/read` **Read a VFS snapshot** Returns an immutable snapshot manifest and aggregate file/byte counts; file bodies remain separate blobs. - Params: `VfsSnapshotReadParams` - Result: `AgentApiOutcome` ### `vfs/workspaces/create` **Create a mutable VFS workspace** Creates a universe workspace at an optional seed snapshot; absence starts from a server-created empty snapshot. - Params: `VfsWorkspaceCreateParams` - Result: `AgentApiOutcome` ### `vfs/workspaces/read` **Read a VFS workspace** Returns workspace metadata, current head snapshot, and revision for safe updates. - Params: `VfsWorkspaceReadParams` - Result: `AgentApiOutcome` ### `vfs/workspaces/list` **List VFS workspaces** Lists mutable universe workspaces with head snapshots, sizes, and revisions. - Params: `VfsWorkspaceListParams` - Result: `AgentApiOutcome` ### `vfs/workspaces/update` **Update a VFS workspace** Moves the workspace head to an existing snapshot and updates its display name. Pass expectedRevision from a read to prevent lost updates. - Params: `VfsWorkspaceUpdateParams` - Result: `AgentApiOutcome` ### `vfs/workspaces/delete` **Delete a VFS workspace** Deletes the mutable workspace record; immutable snapshots and blobs remain content-addressed resources. - Params: `VfsWorkspaceDeleteParams` - Result: `AgentApiOutcome` ### `mcp/servers/put` **Create or replace an MCP server record** Stores the complete universe catalog document, including its optional universe auth-grant credential. Use expectedRevision when replacing; token material is never accepted or returned. - Params: `McpServerPutParams` - Result: `AgentApiOutcome` ### `mcp/servers/auth/discover` **Discover MCP server authentication** Looks for standards-based OAuth protected-resource metadata without creating a server, OAuth client, flow, or grant. An absent OAuth result is inconclusive and callers must allow manual auth selection. - Params: `McpServerAuthDiscoverParams` - Result: `AgentApiOutcome` ### `mcp/servers/tools/discover` **Discover MCP server tools** Connects directly to the configured MCP server with its current universe credential and returns one bounded live tools/list result. The inventory is never persisted or cached and no tool is invoked. - Params: `McpServerToolsDiscoverParams` - Result: `AgentApiOutcome` ### `mcp/servers/read` **Read an MCP server record** Returns one catalog document with defaults, auth policy, non-secret grant binding, status, and revision; no credential value is exposed. - Params: `McpServerReadParams` - Result: `AgentApiOutcome` ### `mcp/servers/list` **List MCP server records** Lists universe catalog entries, optionally filtered by lifecycle/configuration status. - Params: `McpServerListParams` - Result: `AgentApiOutcome` ### `mcp/servers/delete` **Delete an MCP server record** Deletes the catalog document. Existing session configs that reference it are not silently rewritten and may need explicit reconfiguration. - Params: `McpServerDeleteParams` - Result: `AgentApiOutcome` ### `auth/grants/import` **Import a static bearer grant** Accepts a plaintext token, encrypts it immediately, and returns only grant metadata/token-presence flags. Brokered is the default; retrievable exposure is immutable and permits service-only leases. - Params: `AuthGrantImportParams` - Result: `AgentApiOutcome` ## Service methods ### `auth/grants/lease` **Lease a retrievable authentication grant** Service callers only. Resolves the current access token through the broker, records the lease, and returns it once. Cache only in memory until expiry minus margin (or at most five minutes without expiry), re-lease after target 401/403, and never persist or place the token in workflow payloads. - Params: `AuthGrantLeaseParams` - Result: `AgentApiOutcome` ## Universe methods ### `auth/grants/read` **Read authentication grant metadata** Returns principal, provider binding, scopes, audience, expiry, status, and token-presence flags; access and refresh token values are never returned. - Params: `AuthGrantReadParams` - Result: `AgentApiOutcome` ### `auth/grants/list` **List authentication grants** Lists non-secret grant metadata for the universe, optionally filtered by status. - Params: `AuthGrantListParams` - Result: `AgentApiOutcome` ### `auth/grants/revoke` **Revoke an authentication grant** Marks the grant unusable by token consumers while retaining non-secret audit metadata. - Params: `AuthGrantRevokeParams` - Result: `AgentApiOutcome` ### `auth/clients/create` **Register an OAuth client** Stores provider endpoints and client identity; an optional plaintext client secret is encrypted and represented thereafter only by hasClientSecret. - Params: `AuthClientCreateParams` - Result: `AgentApiOutcome` ### `auth/clients/read` **Read OAuth client metadata** Returns endpoints, public client identity, defaults, and secret-presence state; the client secret is never returned. - Params: `AuthClientReadParams` - Result: `AgentApiOutcome` ### `auth/clients/list` **List OAuth clients** Lists non-secret OAuth client registrations in the universe. - Params: `AuthClientListParams` - Result: `AgentApiOutcome` ### `auth/clients/delete` **Delete an OAuth client** Deletes the client registration and its stored client secret; grants already created from it remain separate records. - Params: `AuthClientDeleteParams` - Result: `AgentApiOutcome` ### `auth/flows/start` **Start an OAuth authorization flow** Creates a short-lived PKCE flow carrying the immutable grant exposure choice and returns a browser authorization URL containing one-time state. Treat the URL as sensitive and poll auth/flows/read for completion. - Params: `AuthFlowStartParams` - Result: `AgentApiOutcome` ### `auth/flows/read` **Read OAuth flow status** Polls a flow's pending/completed/failed/expired state and returns the resulting grant id when authorization succeeds; no token value is exposed. - Params: `AuthFlowStatusParams` - Result: `AgentApiOutcome` ### `auth/providers/create` **Register an authentication provider** Creates a model or GitHub credential source. Plaintext API keys/private keys are encrypted on receipt and later represented only by configuration plus hasCredential. - Params: `AuthProviderCreateParams` - Result: `AgentApiOutcome` ### `auth/providers/read` **Read authentication provider metadata** Returns provider kind, non-secret configuration, credential-presence state, and status; stored credentials are never returned. - Params: `AuthProviderReadParams` - Result: `AgentApiOutcome` ### `auth/providers/list` **List authentication providers** Lists non-secret model/GitHub provider registrations for the universe. - Params: `AuthProviderListParams` - Result: `AgentApiOutcome` ### `auth/providers/delete` **Delete an authentication provider** Deletes the provider registration and its directly stored credential; separately stored grants remain independent records. - Params: `AuthProviderDeleteParams` - Result: `AgentApiOutcome` ### `auth/github/installations/list` **List GitHub App installations** Uses the registered GitHub App provider credential to query accessible installations and returns account/permission metadata without tokens. - Params: `AuthGitHubInstallationListParams` - Result: `AgentApiOutcome` ### `auth/github/installations/grant` **Grant access to a GitHub App installation** Creates or refreshes a universe auth grant for one accessible installation. The installation token is brokered internally and never returned. - Params: `AuthGitHubInstallationGrantParams` - Result: `AgentApiOutcome` ### `bots/create` **Create a bot** Creates the bot record, optionally with its triggers, and starts its controller. Fails if the bot id exists; a trigger failure rolls the bot back. - Params: `BotCreateParams` - Result: `AgentApiOutcome` ### `bots/put` **Create or replace a bot document** Replaces the mutable configuration whole and signals the controller, which applies it at its next idle boundary. Pass expectedRevision when replacing; a closed bot accepts label-only edits. - Params: `BotPutParams` - Result: `AgentApiOutcome` ### `bots/read` **Read a bot** Returns the bot record, its current revision, and lifecycle columns. - Params: `BotReadParams` - Result: `AgentApiOutcome` ### `bots/list` **List bots** Returns the roster: every bot with its trigger count, pending event count, and latest event. - Params: `BotListParams` - Result: `AgentApiOutcome` ### `bots/close` **Close a bot** Terminal and idempotent: disables every trigger, drops schedules, and tells the controller to archive pending events and force-close its sessions. Returns once signalled; follow bots/state/read for closing to closed. - Params: `BotCloseParams` - Result: `AgentApiOutcome` ### `bots/delete` **Delete a bot** Closes the bot if needed, waits for its controller to complete, deletes the sessions it closed, and removes the record so the bot id is free again. - Params: `BotDeleteParams` - Result: `AgentApiOutcome` ### `bots/state/read` **Read bot controller state** Queries the controller workflow for its live snapshot (sessions, buffers, active and recent deliveries, budget) and lists sub-agent descendants. The controller is absent until the bot's first event. - Params: `BotStateReadParams` - Result: `AgentApiOutcome` ### `bots/sessions/rotate` **Rotate a bot session** Asks the controller to close one of the bot's sessions at its next idle boundary and continue on a fresh generation; queued deliveries follow. - Params: `BotSessionRotateParams` - Result: `AgentApiOutcome` ### `bots/triggers/put` **Create or replace a trigger** Validates the trigger document (CEL parses, grants exist, one inbox per bot, chat routes per conversation), reconciles its Temporal Schedule, and stores it. A poll spec edit resets the cursor; a webhook keeps its URL token. - Params: `BotTriggerPutParams` - Result: `AgentApiOutcome` ### `bots/triggers/read` **Read a trigger** Returns one trigger with its incidents and cursor; the ingest path and pairing code are shown only to managing principals. - Params: `BotTriggerReadParams` - Result: `AgentApiOutcome` ### `bots/triggers/list` **List a bot's triggers** Returns every trigger of the bot ordered by id, secrets redacted for non-managing principals. - Params: `BotTriggerListParams` - Result: `AgentApiOutcome` ### `bots/triggers/delete` **Delete a trigger** Drops the trigger's Temporal Schedule and pairings, then the record; stored events keep their history. - Params: `BotTriggerDeleteParams` - Result: `AgentApiOutcome` ### `bots/events/admit` **Admit an event manually** Stores an operator-authored event for the bot's main session and wakes the controller. eventId is the dedupe identity; a duplicate returns the stored row. - Params: `BotEventAdmitParams` - Result: `AgentApiOutcome` ### `bots/events/replay` **Replay a stored event** Re-admits the stored envelope as a fresh event with the original routing; the replay never coalesces. - Params: `BotEventReplayParams` - Result: `AgentApiOutcome` ### `bots/events/list` **List a bot's events** Cursor-paginated event log, newest first, with outcomes; payload documents stay in the CAS. - Params: `BotEventListParams` - Result: `AgentApiOutcome` ### `bots/events/read` **Read an event by number** Returns the event row and its full stored envelope document. - Params: `BotEventReadParams` - Result: `AgentApiOutcome` ### `bots/filters/test` **Test a CEL filter** Evaluates a filter against one payload or a sample of recent stored events, reporting matches and evaluation errors without changing anything. - Params: `BotFilterTestParams` - Result: `AgentApiOutcome` ### `channels/accounts/create` **Create a channel account** Registers a provider account (Telegram, WhatsApp) for this universe. The credential is a retrievable grant reference; no token is accepted here. - Params: `ChannelAccountCreateParams` - Result: `AgentApiOutcome` ### `channels/accounts/put` **Create or replace a channel account** Replaces the account document whole; pass expectedRevision when replacing. The connector host picks the change up on its next discovery pass. - Params: `ChannelAccountPutParams` - Result: `AgentApiOutcome` ### `channels/accounts/read` **Read a channel account** Returns the account document and revision. - Params: `ChannelAccountReadParams` - Result: `AgentApiOutcome` ### `channels/accounts/list` **List channel accounts** Lists this universe's provider accounts, optionally by provider. - Params: `ChannelAccountListParams` - Result: `AgentApiOutcome` ### `channels/accounts/delete` **Delete a channel account** Removes the account and its pairings; chat triggers that reference it stop serving conversations. - Params: `ChannelAccountDeleteParams` - Result: `AgentApiOutcome` ## Service methods ### `channels/inbound/admit` **Admit a provider message** Service callers only. Resolves the chat trigger for the conversation, applies pairing, and signals the conversation workflow. Returns the decision so the connector can send pairing prompts itself; acknowledge the provider only after this returns. - Params: `ChannelInboundAdmitParams` - Result: `AgentApiOutcome` ## Universe methods ### `channels/pairings/list` **List chat pairings** Lists conversations paired to chat triggers, optionally by account or bot. - Params: `ChannelPairingListParams` - Result: `AgentApiOutcome` ### `channels/pairings/delete` **Unpair a conversation** Removes one pairing; the conversation must present the pairing code again to reconnect. - Params: `ChannelPairingDeleteParams` - Result: `AgentApiOutcome` ### `channels/conversations/read` **Read a conversation snapshot** Queries the conversation workflow's live state for one chat, for debugging; absent when no workflow exists yet. - Params: `ChannelConversationReadParams` - Result: `AgentApiOutcome` ## Operator methods ### `operator/universes/create` **Create a universe** Creates the deployment tenant boundary for an explicit UUID. The operation is idempotent and reports whether a new universe was created. - Params: `OperatorUniverseCreateParams` - Result: `AgentApiOutcome` ### `operator/universes/list` **List universes** Returns deployment-wide universe summaries with approximate live aggregate counts and last session activity. - Params: `OperatorUniverseListParams` - Result: `AgentApiOutcome` ### `operator/universes/read` **Read a universe** Returns one deployment tenant summary with aggregate session, workspace, profile, and blob usage. - Params: `OperatorUniverseReadParams` - Result: `AgentApiOutcome` ### `operator/universes/delete` **Purge a universe** Permanently terminates live session workflows, deletes external blob objects, and cascades universe data. The purge is resumable/idempotent after partial failure. - Params: `OperatorUniverseDeleteParams` - Result: `AgentApiOutcome` ### `operator/api-keys/create` **Create a universe API key** Mints an inbound gateway key for one existing universe. The plaintext secret is returned exactly once and cannot be recovered; persist only the displayed prefix for identification. - Params: `OperatorApiKeyCreateParams` - Result: `AgentApiOutcome` ### `operator/api-keys/list` **List universe API keys** Returns only non-secret key metadata for the requested universe, including revocation and last-use timestamps. Plaintext secrets are never stored or returned. - Params: `OperatorApiKeyListParams` - Result: `AgentApiOutcome` ### `operator/api-keys/revoke` **Revoke a universe API key** Immediately and idempotently revokes the matching key only when it belongs to the requested universe. Unknown and foreign-universe prefixes return not found. - Params: `OperatorApiKeyRevokeParams` - Result: `AgentApiOutcome` ### `operator/environment-providers/put` **Put an environment provider** Registers or replaces one deployment provider and its controller connection. The provider does not call this API or require access to Lightspeed. - Params: `OperatorEnvironmentProviderPutParams` - Result: `AgentApiOutcome` ### `operator/environment-providers/list` **List environment providers** Returns every operator-registered deployment provider and its controller connection. - Params: `OperatorEnvironmentProviderListParams` - Result: `AgentApiOutcome` ### `operator/environment-providers/read` **Read an environment provider** Returns one operator-registered deployment provider and its controller connection. - Params: `OperatorEnvironmentProviderReadParams` - Result: `AgentApiOutcome` ### `operator/environment-providers/delete` **Delete an environment provider** Deletes a deployment provider only when no universe binding references it. - Params: `OperatorEnvironmentProviderDeleteParams` - Result: `AgentApiOutcome` ### `operator/environment-providers/bindings/put` **Put an environment provider binding** Creates or replaces one universe's complete revisioned routing and admission binding. A deployment provider may have at most one binding in a universe. - Params: `OperatorProviderBindingPutParams` - Result: `AgentApiOutcome` ### `operator/environment-providers/bindings/delete` **Delete an environment provider binding** Deletes a universe provider binding only after every referencing environment has reached Closed. - Params: `OperatorProviderBindingDeleteParams` - Result: `AgentApiOutcome` ### `operator/environments/adopt` **Adopt a provider environment** Creates a universe environment by transferring an existing provider target into Lightspeed's managed lifecycle. The caller must explicitly accept ownership transfer. - Params: `OperatorEnvironmentAdoptParams` - Result: `AgentApiOutcome` ### `operator/channels/accounts/list` **List channel accounts across universes** The connector host's discovery call: every enabled provider account of the deployment with its universe id and credential grant reference. Re-poll to pick up accounts created or disabled since. - Params: `OperatorChannelAccountListParams` - Result: `AgentApiOutcome`