---
title: "Admin API: logs, audit and alerts"
description: Read the request log, run log queries, export requests and the audit log, set alerts and org webhooks, take backups and compliance packs, and manage shared, live and handed-off sessions over /api/admin/v1.
section: cloud
order: 340
audience: [operator, builder, agent]
sources: [services/nodejs-cloud/app/api/admin/v1/logs, services/nodejs-cloud/app/api/admin/v1/requests, services/nodejs-cloud/app/api/admin/v1/alerts, services/nodejs-cloud/app/api/admin/v1/webhooks, services/nodejs-cloud/app/api/admin/v1/audit, services/nodejs-cloud/lib/observability/index.ts, services/nodejs-cloud/lib/webhooks/index.ts, services/nodejs-cloud/lib/alerts, services/nodejs-cloud/lib/export/index.ts, services/nodejs-cloud/lib/backup, services/nodejs-cloud/lib/compliance, services/nodejs-cloud/lib/session-shares/index.ts, services/nodejs-cloud/lib/live-sessions/index.ts, services/nodejs-cloud/lib/handoffs/index.ts, docs/cloud-log-query.md, docs/cloud-mesh.md]
features: [cloud.api-admin-logs, cloud.api-admin-requests, cloud.api-admin-failures, cloud.api-admin-alerts, cloud.api-admin-webhooks, cloud.api-admin-activity, cloud.api-admin-audit, cloud.api-admin-export, cloud.api-admin-backup, cloud.api-admin-compliance, cloud.api-admin-captured-sessions, cloud.api-admin-session-pauses, cloud.api-admin-session-shares, cloud.api-admin-session-summaries, cloud.api-admin-live-sessions, cloud.api-admin-handoffs]
---

Everything the console shows about what happened in an org (requests, failures, the audit log, alerts, shared
sessions) comes from these `/api/admin/v1` routes. Use them to feed your own SIEM, to page someone from a webhook,
to archive the audit log, or to build a support tool on top of an org's sessions.

Credentials and roles are on [Venom Cloud APIs overview](/docs/cloud/api-overview.md#admin-credentials). Every route below
answers in the scope of the caller: an org member sees their org, a key group admin key (`vak_…`) its key group, and the
operator every org (narrow a listing with `?tenant=<org id>`). Something outside the scope answers `404`, never
`403`, so ids do not leak.

```bash
export VENOM_CLOUD=https://cloud.usevenom.dev
export ADMIN="Authorization: Bearer $VENOM_ADMIN_KEY"   # the admin token or a vak_ key

# the last 20 failed requests
curl -s "$VENOM_CLOUD/api/admin/v1/requests?status=error&limit=20" -H "$ADMIN"

# the same with the log query language, as NDJSON
curl -s "$VENOM_CLOUD/api/admin/v1/export?source=requests&format=ndjson&q=status:5xx%20since:24h" -H "$ADMIN" -o errors.ndjson

# audit rows about API keys, newest first
curl -s "$VENOM_CLOUD/api/admin/v1/audit?action=key&limit=100" -H "$ADMIN"
```

## Request log {#requests}

| Route | Permission | What it does |
|---|---|---|
| `GET /api/admin/v1/requests` | `logs:read` | Request log rows, newest first: key, session, path, requested and served model, mode, served by (`daemon` or `cloud`), daemon, upstream, status, error code, route and fallback reason, attempts, tokens, `cost_usd`, `ttft_ms`, `duration_ms`, `has_content`. |
| `GET /api/admin/v1/requests/{id}` | `logs:read` | One request's trace (`object: "venom.admin.trace"`): the log row, every job with its candidates in cost order, timestamps (queued, dispatched, acked, first byte, finished, with hybrid-logical-clock stamps), the shared session of its root session when the caller may open one, and whether content is stored. `{id}` is `req_<uuid>`, else `400`. |
| `GET /api/admin/v1/requests/{id}/content` | `content:read` | The stored request and response bodies, when the org logs content. Every read writes a `content.viewed` audit row. `503 vault_not_configured` when the deployment has no vault. |

Query parameters of `GET /api/admin/v1/requests`:

| Parameter | Default | Meaning |
|---|---|---|
| `key` | none | a key id (uuid) |
| `model` | none | the requested model, exact |
| `status` | none | a status code (`502`), or `error` for every status ≥ 400 or row with an error code |
| `daemon` | none | a daemon id, or `cloud` for requests the cloud's providers served |
| `provider` | none | the upstream, exact |
| `since`, `until` | none | RFC 3339 times; `until` is exclusive |
| `limit` | 200 | 1 to 500 |
| `tenant` | none | operator only |

When no content is stored, the trace's `content.why` says why: `direct` (a 307 request never passed through the
cloud), `no_vault`, `off` (the org does not log content) or `none`.

## Log queries {#logs}

The console's log explorer runs on these routes. The query language (fields, operators, windows, pipes) is
described in [Log queries over the admin API](/docs/cloud/api-log-query.md) and [Log query language](/docs/cloud/console-log-query.md); this table lists the HTTP side. Every route needs
`logs:read`. A key group admin key reads its key group's rows; an org member their org's; `?tenant=` narrows the operator
only.

| Route | Parameters | What it returns |
|---|---|---|
| `GET /api/admin/v1/logs/query` | `q`, `cursor`, `limit` (1–500, default 50), `tz`, `tenant` | `object: "venom.logs.query"`: the canonical query, diagnostics, the resolved window, and a `result` of `kind` `rows` (with `next_cursor`), `table` or `timeseries`, plus timings |
| `GET /api/admin/v1/logs/suggest` | `q`, `pos` (UTF-16 offset; default the end), `tenant` | completions at the cursor: `replace` span, `items`, `context` |
| `GET /api/admin/v1/logs/fields` | none | the field registry: name, aliases, type, description, examples, which fields can group, aggregate and sort |
| `GET /api/admin/v1/logs/facets` | `q`, `fields` (comma list, at most 30), `tz`, `tenant` | the top 10 values, distinct and missing counts of each field, or min/avg/p50/p95/p99/max for numbers, over the newest 20,000 matched rows (`sample` says when it sampled) |
| `GET /api/admin/v1/logs/patterns` | `q`, `tz`, `tenant` | the matched rows grouped into request shapes (variable tokens masked as `<*>`), at most 50, each with a count, a sparkline and a `filter`/`exclude` query |
| `GET /api/admin/v1/logs/live` | `q`, `cursor`, `tenant` | the live feed: rows that finished since the cursor (at most 100 a poll, the first poll covers the last hour), `more`, `total`, and on the first page a 30-minute `spark`. Poll it; it is not a stream |
| `GET /api/admin/v1/logs/saved` | `tenant` | the caller's saved queries and those shared in its scope, own first; each has `mine` |
| `POST /api/admin/v1/logs/saved` | body `{name, query, shared?, tenant_id?}` | save a query (stored canonical): `201` |
| `PATCH /api/admin/v1/logs/saved/{id}` | body `{name?, query?, shared?}` | the author, or `org:manage` for a shared query |
| `DELETE /api/admin/v1/logs/saved/{id}` | none | the author, or `org:manage` for a shared query |

`next_cursor` is opaque and pins the first page's window, so a relative window does not slide while you page. Send
it back with the same `q`, `tz` and scope.

On the live feed, a developer or viewer sees only requests made with keys they created (the answer says
`own: true`); owners, admins, key group admin keys and the operator see the whole scope. The live filter takes no
pipes (`400 live_pipeline`), no window (`live_window`) and no content terms (`live_content`).

| Error | When |
|---|---|
| `400 invalid_query` | the query does not parse; `error.diagnostics` and `error.canonical` say where |
| `400 cursor_mismatch`, `400 invalid_cursor` | a cursor from another query, time zone or scope; a malformed cursor |
| `403 content_forbidden` | a content term (`prompt:`, `response:`, `content:`) without `content:read` |
| `409 content_logging_off`, `400 content_needs_org` | content search where the org does not log content; the operator searching content across orgs |
| `409 name_taken`, `409 too_many_saved_queries` | a saved query name in use; more than 200 saved queries per person |
| `504 query_timeout` | the query ran past 5 seconds |

## Exports {#export}

`GET /api/admin/v1/export` streams a download, a page at a time. It needs `org:manage` plus `logs:read`
(requests) or `audit:read` (audit log), and writes `logs.exported` or `audit.exported` to the audit log before the
first byte.

| Parameter | Values | Notes |
|---|---|---|
| `source` | `requests`, `audit` | required |
| `format` | `ndjson`, `csv` | NDJSON is `application/x-ndjson`, one object per line; CSV is RFC 4180 with a header line |
| `q`, `tz`, `tenant` | requests only | a log query without pipes (`400 export_pipeline`) or content terms (`400 export_content_search`); the query's window, default 24 hours; at most 50,000 rows |
| `content=1` | requests only | adds `request`, `response` and `content_truncated`; needs `content:read` and one org with content logging on |
| `since`, `until`, `action`, `actor` | audit only | `action` is an action or its subject (`content`, `key`); at most 100,000 rows with columns `id, ts, tenant_id, actor, action, target, detail` |

The response carries `x-venom-export-limit` with the row cap that applied.

## Audit log {#audit}

| Route | Permission | What it does |
|---|---|---|
| `GET /api/admin/v1/audit` | `audit:read` | Audit rows, newest first: `id`, `ts`, `tenant_id`, `actor`, `action`, `target`, `detail` (redacted), and `undone_by` when an undo reversed it. Filters `since`, `until` (RFC 3339), `action` (`[a-z0-9_.]`, up to 64), `actor`, `target`, `q` (text), `before` (a row id, for paging), `limit` (1–1000, default 1000). The answer is `{data, next_before}`; pass `next_before` as `before` for the next page. A team admin key sees rows it made or that name its team. |
| `POST /api/admin/v1/audit/{id}/undo` | `audit:read`, then the permission of the original change | Put a settings change back. The change is replayed backwards through the same operation, so its own checks apply (a viewer can undo nothing, a developer cannot undo a members change). Answers `{object: "venom.audit.undo", undone, entry}`; the new row carries `undo_of`. |

Changes that can be undone include gears, prompt filters, budgets, the spend cap, pricing, routing modes, auto
routing, content and session sharing settings, quality settings, member roles, key updates and scopes, and model
access. Undo errors are `409`: `not_undoable` (another kind of entry, no before/after, or a secret in it),
`already_undone`, `changed_since` (the setting changed again after this entry: undo the newer one first).

## Presence {#activity}

`GET /api/admin/v1/activity` (`daemons:read`, `?tenant=` for the operator) answers
`{object: "venom.admin.activity", window_s: 300, daemons, users}`: the scope's daemons with an `effective_state`
derived from heartbeats (`enrolled`, `offline`, `draining`, `suspect`, or their state), and the console users seen
in the last 5 minutes.

## Failure clusters {#failures}

| Route | Permission | What it does |
|---|---|---|
| `GET /api/admin/v1/failures` | `logs:read` | Failed and troubled sessions and requests grouped by cause (`tool_error`, `loop`, `refusal`, `content_filter`, `timeout`, `provider_error`, `budget_block`, `allowlist_block`, `context_overflow`, `other`): per cause the count, sessions, a daily series, kinds, 5 example sessions, the latest spike and the settings changes around it. `days` is `7` (default), `30` or `90`; `gear` narrows. |
| `GET /api/admin/v1/failures/settings` | `logs:read` | The classifier: `{classifier, gear, daily_cap}`. |
| `PUT /api/admin/v1/failures/settings` | `org:manage` | `{classifier: bool, gear, daily_cap}` (`daily_cap` 1–500, default 50). Off by default. Audited `failures.settings`. |
| `POST /api/admin/v1/failures/classify` | `org:manage` | Run the classifier now, within the day's cap. Each label is one small, billed request on the gear's classifier model. `409 classifier_off` while it is off. |

## Alerts {#alerts}

An alert is a saved log search the cloud runs every 5 minutes over the requests logged since its last run. A run
that matches at least `threshold` requests records a hit and, when the org set one, posts it to the alert webhook.
Reading needs `audit:read`; creating, changing, deleting and the webhook need `org:manage` (plus `content:read`
for an alert that reads bodies). At most 50 alerts per org; hits are kept 90 days.

| Route | Body or parameters | What it does |
|---|---|---|
| `GET /api/admin/v1/alerts` | `tenant` | `data` (the alerts), `unread`, `webhook` (its URL and the secret's last four characters), `can_manage` |
| `POST /api/admin/v1/alerts` | `{name, query, threshold?}` or `{builtin}` | create one. `query` is a plain search (no time terms, no pipes). Built-ins: `secrets` (a secret in a prompt), `shell` (shell tool use), `large-prompt` (prompts over 200k characters), `errors` (50 or more 5xx) |
| `PATCH /api/admin/v1/alerts/{id}` | `{name?, query?, threshold?, enabled?}` | change or pause it; resuming starts from now |
| `DELETE /api/admin/v1/alerts/{id}` | none | delete it |
| `GET /api/admin/v1/alerts/hits` | `alert`, `before`, `limit` | hits, newest first, each with `unread` for the caller; page with `next_before` |
| `POST /api/admin/v1/alerts/seen` | none | mark every hit so far as seen by the caller |
| `PUT /api/admin/v1/alerts/webhook` | `{url, rotate?}` | set the org's alert webhook. The signing secret (`vwh_…`) is made on the first save or with `rotate: true` and shown once |
| `DELETE /api/admin/v1/alerts/webhook` | none | remove it |
| `POST /api/admin/v1/alerts/webhook/test` | none | send one signed `alert.test` event |

The alert webhook gets one POST per hit (5 seconds, no redirects, no retries) with `venom-event: alert.hit`,
`venom-delivery: <hit id>` and the signature header described under [Org webhooks](#signature). The body holds the
alert, the count, the window, up to 50 request ids and console links, never a prompt or response:

```json
{"type": "alert.hit", "id": "42", "created_at": "2026-11-03T09:00:00Z", "org": {"id": "…"},
 "alert": {"id": "…", "name": "Shell tool use", "query": "tool:(bash OR shell)", "threshold": 1, "detector": null},
 "count": 3, "truncated": false, "window": {"since": "…", "until": "…"},
 "request_ids": ["req_…"], "links": {"alert": "https://…", "explorer": "https://…", "requests": ["https://…"]}}
```

## Org webhooks {#webhooks}

An org's own HTTPS endpoints, told when something needs a person: spend, keys, daemons, filters, autoscaling,
quality, SLAs, handoffs. Reading needs `audit:read`, changing needs `org:manage`. At most 10 endpoints per org; a
legacy key group session (signed in with a `vak_` key) has none (`403`). Events and deliveries are kept 30 days.

| Route | Body or parameters | What it does |
|---|---|---|
| `GET /api/admin/v1/webhooks` | `tenant` | the org's endpoints: URL, events, description, enabled, the secret's last four characters |
| `POST /api/admin/v1/webhooks` | `{url, events, description?, tenant_id?}` | create one; `201` with `secret` (`vwh_…`), shown once |
| `PATCH /api/admin/v1/webhooks/{id}` | `{url?, events?, description?, enabled?, rotate?}` | change it; `rotate: true` returns a new `secret` once |
| `DELETE /api/admin/v1/webhooks/{id}` | none | delete it and its delivery log |
| `POST /api/admin/v1/webhooks/{id}/test` | none | send one signed `webhook.test` event now (one attempt, not retried) |
| `GET /api/admin/v1/webhooks/deliveries` | `endpoint`, `state` (`pending`, `delivered`, `failed`), `before` (RFC 3339), `limit` (1–200, default 50) | the delivery log, newest first, with status, error, attempts and latency; page with `next_before` |
| `POST /api/admin/v1/webhooks/deliveries/{id}/retry` | none | queue a failed or waiting delivery again with a fresh attempt count. `409 test_delivery`, `409 already_delivered` |

`url` must be `https`, without credentials, at most 2,000 characters, and resolve to a public address
(`400 blocked_url` otherwise; checked again at every delivery). `description` is at most 200 characters.
`409 vault_not_configured` when the deployment cannot seal the secret; `409 too_many_endpoints` past 10.

Event types for `events`:

| Group | Types |
|---|---|
| spend | `spend_cap.warning`, `spend_cap.reached`, `budget.warning`, `budget.reached`, `spend.threshold`, `spend.forecast`, `spend.anomaly`, `chargeback.statement` |
| keys | `key.expiring`, `key.expired`, `key_rotation.due`, `key_rotation.overdue`, `key_rotation.completed` |
| models and providers | `model.retiring`, `price.changed`, `credits.expiring`, `quality.degraded`, `quality.recovered` |
| daemons | `daemon.offline`, `daemon.online`, `autoscale.machine_added`, `autoscale.machine_joined`, `autoscale.machine_draining`, `autoscale.machine_removed`, `autoscale.machine_interrupted`, `autoscale.join_timeout`, `autoscale.cap_reached` |
| filters | `prompt_filter.blocked`, `prompt_filter.response_blocked` |
| SLAs | `sla.breach`, `sla.credit_drafted` |
| sessions | `handoff.created`, `handoff.accepted`, `handoff.declined` |
| Venom Tasks | `tasks.issue.created`, `tasks.issue.updated`, `tasks.issue.deleted`, `tasks.comment.created`, `tasks.issue.delegated` |
| Venom Notes (never a personal vault) | `globe.note.created`, `globe.note.updated`, `globe.note.deleted` (the org vault), `globe.team_note.created`, `globe.team_note.updated`, `globe.team_note.deleted` (team vaults) |
| Venom Experiments | `experiments.guardrail_breached`, `experiments.decided`, `experiments.started`, `experiments.ramped`, `experiments.stopped` |
| Venom Flags | `flags.flag.created`, `flags.flag.updated`, `flags.flag.deleted` |
| Venom People (org-wide people only) | `people.person.created`, `people.person.updated`, `people.person.removed` |
| Venom Funnel (org-wide deals only) | `funnel.deal.created`, `funnel.deal.updated`, `funnel.deal.stage_changed`, `funnel.deal.archived` |
| Venom Chat (public channels only) | `chat.channel.created`, `chat.channel.archived`, `chat.message.created` |
| Teams | `org.team.created`, `org.team.updated`, `org.team.archived`, `org.team.member_added`, `org.team.member_removed` |
| Status page | `status.incident.created`, `status.incident.updated`, `status.incident.resolved`, `status.maintenance.scheduled`, `status.maintenance.started`, `status.maintenance.completed`, `status.component.changed` |
| Venom Incidents | `errors.issue.created`, `errors.issue.regressed`, `errors.alert.fired`, `incidents.created`, `incidents.updated`, `incidents.resolved`, `incidents.page` |
| Venom Forms | `forms.response.created` |
| test | `webhook.test` (sent only by the test route) |

### Delivery and signature {#signature}

Each event is a POST with `content-type: application/json` and these headers:

| Header | Value |
|---|---|
| `venom-event` | the event type |
| `venom-event-id` | the event id: use it as your idempotency key, since a delivery can arrive twice |
| `venom-delivery` | the delivery id |
| `venom-signature` | `t=<unix seconds>,v1=<hex HMAC-SHA256 of "<t>.<body>" keyed by the secret>` |

The body is `{id, type, created_at, org: {id}, data, links}`: ids, names, numbers and console links, never a key,
a secret or request content. A `2xx` answer is delivered; anything else is retried after 1, 2, 4 … 128 minutes
with ±20 % jitter (9 attempts, about 4 hours 15 minutes), then marked `failed`.

Check the signature before you trust a body: recompute the HMAC over the raw body, compare in constant time and
refuse a `t` older than 5 minutes.

```ts
import { createHmac, timingSafeEqual } from "node:crypto";

export function verifyVenomWebhook(rawBody: string, header: string, secret: string, now = Date.now()): boolean {
  const parts = Object.fromEntries(header.split(",").map((p) => p.split("=") as [string, string]));
  const t = Number(parts.t);
  if (!Number.isFinite(t) || Math.abs(now / 1000 - t) > 300 || !parts.v1) return false;
  const want = createHmac("sha256", secret).update(`${t}.${rawBody}`).digest("hex");
  return want.length === parts.v1.length && timingSafeEqual(Buffer.from(want), Buffer.from(parts.v1));
}
```

```python
import hashlib, hmac, time

def verify_venom_webhook(raw_body: bytes, header: str, secret: str) -> bool:
    parts = dict(p.split("=", 1) for p in header.split(","))
    t = int(parts.get("t", "0"))
    if abs(time.time() - t) > 300 or "v1" not in parts:
        return False
    want = hmac.new(secret.encode(), f"{t}.".encode() + raw_body, hashlib.sha256).hexdigest()
    return hmac.compare_digest(want, parts["v1"])
```

The alert webhook uses the same scheme.

## Backup and restore {#backup}

| Route | Permission | What it does |
|---|---|---|
| `GET /api/admin/v1/backup` | `org:manage` (`members:read` too with `members=1`) | The org's configuration as one versioned JSON bundle (`format: "venom.org-backup"`, `version: 1`), as an attachment. Sections include teams, settings, gears, routing, model allowlists, filters, customers, budgets, library, memory, experiments, marketplace, alerts, webhooks, integrations, autoscaling, single sign-on and permission profiles. `members=1` adds members and roles. Audited `org.backup_exported`. |
| `POST /api/admin/v1/backup/restore` | `org:manage` (`members:manage` for members) | `{backup, dry_run?, on_conflict?, sections?, members?}`. `dry_run` defaults to `true`: the answer is a plan per item (`create`, `update` with the differing fields, or `skip` with why). `on_conflict: "keep"` skips items that differ. A restore never deletes. Applied, it runs in one transaction and is audited `org.backup_restored`. |

A bundle never holds a secret: no provider, GPU cloud or API keys, integration tokens, webhook secrets, the OIDC
client secret or SCIM tokens, and no logs or usage. Its `reenter` list names what to enter again after a restore
elsewhere. Webhooks come back turned off with new secrets, integrations as `pending`, and single sign-on turned
off until a test sign-in. Sections whose page needs more than `org:manage` are skipped for callers without it:
`customers` needs `billing:manage`, `sso` needs `sso:manage`. A bundle is at most 2 MiB. The CLI does the same with
`venom cloud backup` and `venom cloud restore`.

## Compliance pack {#compliance}

`GET /api/admin/v1/compliance/export?since=YYYY-MM-DD&until=YYYY-MM-DD[&tenant_id=…]` (`org:manage`) streams one
signed ZIP of evidence for a period: members, teams, keys (never a key), spend by model, key, member and day, the
models used and model access rules, provider keys (last four characters only), the controls in place and every
change to them with before and after, the redacted audit log (up to 50,000 rows), incidents, signed session seals,
a readable `summary.html`, `manifest.json` and an Ed25519 `signature.json`.

- The period is two UTC days, inclusive, at most 366 days; ISO times work too. No period: the last 30 days.
- The response is `application/zip` with `x-venom-pack-sha256`. Each download is audited `compliance.exported`
  with the hash.
- It is signed with the org's policy-signing key, else the deployment's; with neither,
  `503 policy_signing_not_configured`.
- Verify it offline with `venom compliance verify <pack.zip>`.

## Sessions {#sessions}

### Captured sessions {#captured-sessions}

Every request that carried `x-venom-session` is in the request log, so a session can be replayed without anyone
sharing it. Metadata only: a request's body opens from its row (`/requests/{id}/content`).

| Route | Permission | What it does |
|---|---|---|
| `GET /api/admin/v1/captured-sessions` | `logs:read` | Sessions in the request log, newest first. `days` (default 7, at most 30), `q` (text), `limit` (default 50, at most 200), `tenant`. |
| `GET /api/admin/v1/captured-sessions/{session}` | `logs:read` | One session's request log rows with the prompt and response filter rules that hit them, for the replay debugger. |

### Shared sessions {#session-shares}

Traces members uploaded with `venom session share` (`/v1/session-shares`). `visibility: "org"` shows a share to
everyone with `logs:read`; `"admins"` only to `org:manage` (and a key group admin key of the sharing key group).

| Route | Permission | What it does |
|---|---|---|
| `GET /api/admin/v1/session-shares` | `logs:read` (`admins` shares need `org:manage`) | Shares, newest first, without traces. `q`, `limit` (default 100, at most 200), `tenant`. |
| `GET /api/admin/v1/session-shares/{id}` | `logs:read` | One share with its trace and comments. Audited `session_share.viewed`. |
| `GET /api/admin/v1/session-shares/{id}/replay` | `logs:read` | The share plus its session's request log rows (`requests`), for the replay debugger. Audited like a view. |
| `PATCH /api/admin/v1/session-shares/{id}` | `org:manage` | `{title?, visibility?}` (`org` or `admins`). |
| `DELETE /api/admin/v1/session-shares/{id}` | `org:manage` | Delete it and its comments. |
| `GET /api/admin/v1/session-shares/{id}/comments` | `logs:read` | Its comments. |
| `POST /api/admin/v1/session-shares/{id}/comments` | `logs:read` | `{body, step?}`: a comment, optionally on a step. |
| `DELETE /api/admin/v1/session-shares/{id}/comments/{cid}` | the comment's author, or `org:manage` | Delete a comment. |
| `POST /api/admin/v1/session-shares/{id}/public` | `org:manage` | `{expires_in_days?}`: a read-only public link (`vss_…`, shown once), 1 to the org's `public_max_days` (default 7, at most 30). Needs the org's `public_links` setting on. A new link replaces the old one. |
| `DELETE /api/admin/v1/session-shares/{id}/public` | `org:manage` | Revoke the public link. |

### Session summaries {#session-summaries}

The org's session history, when it collects summaries (off by default; the setting is
`PUT /api/admin/v1/settings/session-summaries`).

| Route | Permission | What it does |
|---|---|---|
| `GET /api/admin/v1/session-summaries` | `logs:read` | Summaries newest first, 50 a page with a `next` cursor. `q` is full text (words, "phrases", `-not`, `or`), `member` and `repo` are substrings, plus `outcome` (`done`, `partial`, `failed`, `abandoned`), `min_cost`, `max_cost`, `days`, `before`, `limit`. Also carries the org's setting and the last 30 days' count and cost. |
| `GET /api/admin/v1/session-summaries/{id}` | `logs:read` | One summary. |
| `DELETE /api/admin/v1/session-summaries/{id}` | `org:manage` | Delete it; audited. |

### Session guard pauses {#session-pauses}

Sessions the org's session guard paused (`429 session_paused` on their requests) because they ran too long or spent
too much with no human message. The limits are `GET`/`PUT /api/admin/v1/settings/session-guard`.

| Route | Permission | What it does |
|---|---|---|
| `GET /api/admin/v1/session-pauses` | `org:read` | Paused sessions, newest first; `open=1` for the ones still paused. |
| `POST /api/admin/v1/session-pauses/{id}/resume` | `org:manage` | Resume one; its limits count from now. Audited `session_guard.resume`. |

### Live sessions {#live-sessions}

Sessions a member shares live with `/share live`, watched and co-driven from the console. Watching needs
`logs:read` in the org, being in the share's audience and not being blocked; anything else is `404`.

| Route | Who | What it does |
|---|---|---|
| `GET /api/admin/v1/live-sessions` | a watcher | The live shares the caller may watch. |
| `GET /api/admin/v1/live-sessions/{id}` | a watcher | A long poll: `after=<seq>` and `wait=<0..20>` seconds. Answers what changed after `seq` (items by index, events, open permission prompts, viewers) and marks the caller present. |
| `PATCH /api/admin/v1/live-sessions/{id}` | the owner, or `org:manage` | Change grants and audience, as `PATCH /v1/live-sessions/{id}` does: `{title?, audience?, invite?, drivers?, approvers?, block?, unblock?, revoke?, extend_minutes?}`. |
| `DELETE /api/admin/v1/live-sessions/{id}` | the owner, or `org:manage` | Stop it; the transcript, events and inputs are deleted at once. |
| `POST /api/admin/v1/live-sessions/{id}/inputs` | a driver or approver | `{kind: "message", text}` (at most 8,000 characters), `{kind: "approval", prompt_id, decision: "allow" \| "deny", feedback?}`, or while pairing `{kind: "comment", text}`. `202 {id, state: "queued"}`. |
| `POST /api/admin/v1/live-sessions/{id}/pass` | the driver, or the owner | `{to?: "owner" \| "partner"}`: hand the pairing driver token over (default the other side). `200 {driver, moved}`. |

Input errors: `403 not_a_driver`, `403 approvals_not_granted`, `409 prompt_closed`, `403 prompt_blocked` (an org
prompt filter), and while pairing `403 not_the_driver`, `409 driver_cannot_comment`, `403 not_paired`. An
approval is always "allow once".

### Handoffs {#handoffs}

Sessions a member packaged for a teammate with `/handoff`. Recipients and the sender see a handoff; `org:manage`
sees every one in the org.

| Route | Who | What it does |
|---|---|---|
| `GET /api/admin/v1/handoffs` | a member | `box=inbox` (default; with `open_count`), `sent`, or `all` (`org:manage`). |
| `GET /api/admin/v1/handoffs/{id}` | recipients, the sender, `org:manage` | One handoff with its note, git summary and state. |
| `POST /api/admin/v1/handoffs/{id}/decline` | a recipient | `{reason?}`. |
| `DELETE /api/admin/v1/handoffs/{id}` | the sender, or `org:manage` | Cancel it. |

Accepting happens on the recipient's machine (`venom handoff accept <id>`). Open handoffs expire after 14 days.

## Errors {#errors}

These routes use the admin error shape (`type: "mesh_error"`) from
[Venom Cloud APIs overview](/docs/cloud/api-overview.md#errors). Common ones here: `403 forbidden` (the role lacks the
permission named in the message), `404 not_found` (outside the caller's scope), `400 invalid_request` (a bad
field, named in the message), `409` conflicts listed in each section, `503 vault_not_configured`.

## Related {#related}

- [Venom Cloud APIs overview](/docs/cloud/api-overview.md): credentials, roles, error codes, limits.
- [Admin API: knowledge, tools and integrations](/docs/cloud/api-admin-content.md).
- [Signed action log](/docs/security.md) and the CLI's `venom compliance verify` in the [CLI section](/docs/cli.md).
