/ Docs
APIBots

Search Bots

Search bots using a JSON filter DSL (recursive AND/OR/Condition). An empty body (or one with only ``pagination``) is equivalent to ``GET /bots``. See ``core/src/botyard_core/filters/AGENTS.md`` for the wire-format spec and ``BotFilterField`` for the list of filterable fields.

POST
/v1/orgs/{org_id}/bots/search

Authorization

BearerAuth
AuthorizationBearer <token>

Botyard API key — see /docs/authentication.

In: header

Path Parameters

org_id*Org Id

Request Body

application/json

TypeScript Definitions

Use the request body type in TypeScript.

Request body for POST /v1/orgs/{org_id}/bots/search.

Response Body

application/json

curl -X POST "https://example.com/v1/orgs/string/bots/search" \  -H "Content-Type: application/json" \  -d '{}'
{
  "items": [
    {
      "id": "string",
      "slug": "string",
      "org_id": "string",
      "name": "string",
      "avatar_url": "string",
      "description": "string",
      "tier": "starter",
      "hosting_type": "hosted",
      "owner_id": "string",
      "created_by_name": "string",
      "created_by_actor_type": "user",
      "member_role": "owner",
      "access": "open",
      "can_use": true,
      "desired_state": "running",
      "observed_state": "pending",
      "observed_status": {},
      "health_status": "healthy",
      "maintenance_restart_pending": false,
      "reconcile_error": "string",
      "updated_at": "2019-08-24T14:15:22Z"
    }
  ],
  "total": 0,
  "limit": 0,
  "offset": 0,
  "has_more": true
}
{
  "type": "string",
  "title": "string",
  "status": 0,
  "detail": "string",
  "instance": "string",
  "error_code": "string",
  "errors": [
    {
      "pointer": "string",
      "detail": "string",
      "type": "string"
    }
  ],
  "trace_id": "string"
}

Copy Bot

Create a new bot with the same definition as an existing one. Copies what the source bot *is*: its config, managed workspace files, skills, tools, tool domain settings, credential assignments, and (by default) its Runtime Vault policy links. Does not copy what it has *lived* — memory, conversations, disk, schedules, devices, health, its email address, or its access list. The caller becomes the copy's owner. Two gates apply. ``bot:bot.create`` because this creates a bot, and so the copy is metered and capped exactly like any other creation (``MeterKey.BOT_COUNT``); and bot ownership of the *source*, because copying reads its whole definition — including which secrets it can reach.

Get Bot Hosting Options

List the ``(hosting_type, harness)`` combinations a bot may be created with. Served from the allowlist in :mod:`botyard_core.hosting` — the same constant bot creation validates against — so the "Add bot" UI derives its options rather than carrying a third copy of the table that can drift. Org-scoped by route so the set can later vary by plan or feature flag without a breaking URL change; today it is identical for every org.