Skip to content
Docs menu

The bot register for admins

See every bot in your organisation, who owns it and what it may do, on one read-only page for owners and admins. Its instructions, memory and messages stay private to its owner.

View .md

Members make bots for themselves, and a bot can run on a schedule, act without asking and send messages on its own. The bot register lets the organisation's owners and admins see which bots exist, who owns each one and what it is allowed to do. It is a list to check, not a control panel: nothing on it changes a bot.

Open it

In the console, open Admin, then Bots (/bots). Only owners and admins see the link; anyone else who opens the page gets the same "no access" page as other admin pages. A platform operator first picks an organisation.

Each row is one bot:

Column What it shows
Bot Its name, description and tile (emoji or initials on its colour). Badges: Working now, Autonomous (it acts without asking), Asks first, Can send, Off, Own computer
Owner The member who made it, by email. Owner left when that person is no longer in the organisation; the bot stays listed until someone deletes it
May do Its daily spending cap (the default, $2 a day, when the owner set none), servers, skills, gear, and whether it keeps a memory note
Reaches out Drafts only, sends through Comms, or sends from its own computer; its channels, the daily cap per channel, and who it may contact
Routines How many, how many are on, and each one's name, trigger (schedule, email, webhook or events), whether it is off or paused, and whether it acts on what an email or webhook sends it
Activity Whether it is working now (the routine's name, or "a chat", and when it started), its last run and how it ended, runs and spend today and over the last 30 days, and messages sent in the last 30 days
Audit log Opens the audit log filtered to the bot (target agent_bot:<id>)

A bot can send when it delivers through Comms on a channel Comms carries, or from its own computer on WhatsApp or LinkedIn, either by its own setting or through a routine that is on. A bot in drafts-only mode leaves messages for its owner and never counts as one that sends.

Working now follows the same rule as the owner's own view (Bots → Working now): one of the bot's runs is going, or a chat with it has a turn running; a run waiting for its owner, or one that crashed and went quiet, does not count. It is as of when the page loaded: reload to check again. The register shows only that the bot is working, on which routine (or "a chat") and since when, never the chat itself.

Filter by owner, autonomy, on or off, can send or drafts only, and by text in the name. The counts above the table cover every bot the filters match, not only the page you see. The list shows 50 bots a page.

What admins can and cannot see

The register shows metadata and permissions only. It never shows:

  • a bot's instructions,
  • its memory note,
  • the chats and run transcripts of the bot or its routines, or a run's results,
  • the messages it drafted or sent (only how many it sent),
  • a routine's instruction, or the secret of an email or webhook routine,
  • the bot's uploaded picture (the tile shows its emoji or initials instead).

Bots stay private to their owners for everything else: an admin cannot open, chat with, edit, run, pause or delete someone else's bot. To stop a bot, ask its owner to turn it off. When an owner leaves the organisation, their bots stay in the register but every new run fails with "The bot's owner is no longer in the organisation", because a run acts as its owner.

API and MCP tools

Route MCP tool What
GET /api/admin/v1/bots admin_bot_list Every bot in the organisation, a page at a time
GET /api/admin/v1/bots/{id} admin_bot_get One bot in the same shape

Both need the owner or admin role (org:manage); any other role gets 403 forbidden. A bot in another organisation, or none, is 404 not_found. The REST twins for scripts are GET /api/v1/admin/bots and GET /api/v1/admin/bots/{bot} (REST API).

Query parameters of GET /api/admin/v1/bots (the tool takes the same names as arguments):

Parameter Default What
owner none Only this member's bots (their user id)
autonomy none ask or auto
enabled none true or false
can_send none true: only bots that can send; false: only drafts-only bots
q none Text in the bot's name, up to 80 characters
limit 50 Bots per page, 1 to 200
cursor none The next_cursor of the previous page
tenant the caller's organisation The platform operator names the organisation
curl -s https://cloud.example.com/api/v1/admin/bots?can_send=true \
  -H "authorization: Bearer vck_…"

The answer:

{
  "object": "venom.bots.register",
  "tenant_id": "…",
  "counts": { "bots": 3, "enabled": 2, "auto": 1, "can_send": 1, "owner_left": 1 },
  "truncated": false,
  "owners": [{ "uid": "user_…", "name": "ana", "email": "ana@example.com", "member": true, "bots": 2 }],
  "data": [
    {
      "id": "…",
      "name": "Contacts keeper",
      "owner": { "uid": "user_…", "name": "ana", "email": "ana@example.com", "member": true, "role": "developer" },
      "may": { "autonomy": "auto", "daily_cap_usd": 5, "daily_cap_default": false, "servers": ["globe", "people"], "skills": [], "gear": null, "computer": false, "memory": true },
      "outreach": { "mode": "comms", "channels": ["email"], "caps": { "email": 20 }, "can_send": true, "modes": ["comms"], "scope": { "kind": "mine" } },
      "routines": { "count": 1, "enabled": 1, "items": [{ "name": "Nightly", "trigger": "schedule", "events": [], "enabled": true, "trust_context": false }] },
      "activity": { "last_run_at": "2026-11-16T05:30:00.000Z", "last_run_status": "done", "runs_today": 1, "runs_30d": 28, "spend_today_usd": 0.12, "spend_30d_usd": 3.4, "messages_30d": 41 },
      "working": { "count": 1, "kind": "routine", "routine_id": "…", "routine_name": "Nightly", "since": "2026-11-17T05:30:04.000Z" }
    }
  ],
  "next_cursor": null
}

working is null when the bot is idle or only waiting for its owner. For a chat, kind is chat and the routine fields are null.

One request looks at up to 5,000 bots. When an organisation has more, truncated is true: narrow the list by owner or name.

  • Bots: making a bot, its settings, routines and runs.
  • Bots that reach out: delivery modes, channels and caps.
  • Audit log: every change to a bot, as agents.bot_*.