1. Reference
2. Web API
3. Bots

Bots

The Bots API has methods for managing AI chat bots.

Create bot

Create bot user.

POST /api/bots

Body parameters

uid string required

Unique identifier (cannot contain whitespace and must contain at least one non-digit).

name string required

Bot name. Used in listings, @mentions etc.

provider string required

The bot provider to use, must be one of openai, anthropic, gemini, or kapa.

model string required

The model to use for the bot, e.g. "gpt-4o-mini" or "gemini-2.0-flash" etc.

instructions string

System instructions for the bot.

picture string

Profile picture. Can be a public URL, a base64 encoded data URI or a blob id.

directory string

Optional user directory for the bot (id or name).

comment string

Comment or other application-specific information about the bot.

tags array of strings

A list of tags to associate with the bot.

metadata object

Additional metadata properties, e.g. { "color": "blue", "size": "XL" }.

Example request

curl {WEAVY-URL}/api/bots
-H "Authorization: Bearer {API-KEY}"
--json "{ 'uid': 'tweety-bird', 'name': 'Tweety Bird', 'provider': 'openai', 'model': 'gpt-4o-mini', 'prompt': 'You’re a cute cartoon character with an aggressive nature.' }"

Response codes

201 Created
400 Bad Request
401 Unauthorized
403 Forbidden
422 Validation Failed

Response schema

{
  "id": "integer",
  "uid": "string",
  "name": "string",
  "provider": "string",
  "model": "string",
  "instructions": "string",
  "avatar_url": "string",
  "picture": {
    "id": "integer",
    "name": "string",
    "media_type": "string",
    "width": "integer",
    "height": "integer",
    "size": "integer",
    "thumbnail_url": "string",
    "raw": "string"
  },
  "directory": {
    "id": "integer",
    "name": "string"
  },
  "comment": "string",
  "tags": [
    "string"
  ],
  "metadata": "object",
  "created_at": "string",
  "updated_at": "string",
  "is_bot": "boolean",
  "is_trashed": "boolean"
}

Get bot

Get bot user with specified identifier.

GET /api/bots/{bot}

Path parameters

bot string required

Bot identifier (id or uid).

Query parameters

trashed boolean

true to return bot even if trashed.

Example request

curl {WEAVY-URL}/api/bots/tweety-bird
-H "Authorization: Bearer {API-KEY}"

Response codes

200 OK
401 Unauthorized
404 Not Found

Response schema

{
  "id": "integer",
  "uid": "string",
  "name": "string",
  "given_name": "string",
  "middle_name": "string",
  "family_name": "string",
  "nickname": "string",
  "email": "string",
  "phone_number": "string",
  "avatar_url": "string",
  "picture": {
    "id": "integer",
    "name": "string",
    "media_type": "string",
    "width": "integer",
    "height": "integer",
    "size": "integer",
    "thumbnail_url": "string",
    "raw": "string"
  },
  "directory": {
    "id": "integer",
    "name": "string"
  },
  "presence": "string",
  "comment": "string",
  "tags": [
    "string"
  ],
  "metadata": "object",
  "created_at": "string",
  "updated_at": "string",
  "is_trashed": "boolean"
}

Update bot

Update bot user.

PATCH /api/bots/{bot}

Path parameters

bot string required

Bot identifier (id or uid).

Body parameters

uid string

Unique identifier (cannot contain whitespace and must contain at least one non-digit).

name string

Bot name. Used in listings, @mentions etc.

provider string

The bot provider to use, must be one of openai, anthropic, gemini, or kapa.

model string

The model to use for the bot, e.g. "gpt-4o-mini" or "gemini-2.0-flash" etc.

instructions string

System instructions for the bot.

picture string

Profile picture. Can be a public URL, a base64 encoded data URI or a blob id.

directory string

Optional user directory for the bot (id or name).

comment string

Comment or other application-specific information about the bot.

tags array of strings

A list of tags to associate with the bot.

metadata object

Additional metadata properties, e.g. { "color": "blue", "size": "XL" }.

Example request

curl -X PATCH {WEAVY-URL}/api/bots/tweety-bird
-H "Authorization: Bearer {API-KEY}"
--json "{ 'model': 'gpt-4o' }"

Response codes

200 OK
400 Bad Request
401 Unauthorized
403 Forbidden
404 Not Found
422 Validation Failed

Response schema

{
  "id": "integer",
  "uid": "string",
  "name": "string",
  "provider": "string",
  "model": "string",
  "instructions": "string",
  "avatar_url": "string",
  "picture": {
    "id": "integer",
    "name": "string",
    "media_type": "string",
    "width": "integer",
    "height": "integer",
    "size": "integer",
    "thumbnail_url": "string",
    "raw": "string"
  },
  "directory": {
    "id": "integer",
    "name": "string"
  },
  "comment": "string",
  "tags": [
    "string"
  ],
  "metadata": "object",
  "created_at": "string",
  "updated_at": "string",
  "is_bot": "boolean",
  "is_trashed": "boolean"
}

List bots

List bot users.

GET /api/bots

Query parameters

autocomplete boolean

true (default) to use "autocomplete" search, otherwise false.

directory string

Directory identifier (id or name). When unspecified bots from all directories are listed.

q string

A string used to find matching items by name, e.g. q=test.

tag string

List items with the specified tag.

trashed boolean

Indicates whether trashed items should be listed (default is false). Specify null to list both trashed and non-trashed items.

order_by string

Specifies the sort order and direction for the listing, e.g. order_by=id or order_by=id+desc.

skip integer

The number of items to skip. Used together with take to return a specific range of items (for pagination).

take integer

Maximum number of items to return in the listing. Should be a value between 1 and 100. Default is 25.

count_only boolean

true to count the number of matching items instead of listing them; when specified the response will only contain the count property.

Example request

curl {WEAVY-URL}/api/bots?take=25
-H "Authorization: Bearer {ACCESS-TOKEN | API-KEY}"

Response codes

200 OK
401 Unauthorized

Response schema

{
  "data": [
    {
      "id": "integer",
      "uid": "string",
      "name": "string",
      "provider": "string",
      "model": "string",
      "instructions": "string",
      "avatar_url": "string",
      "comment": "string",
      "tags": [
        "string"
      ],
      "metadata": "object",
      "created_at": "string",
      "updated_at": "string",
      "is_bot": "boolean",
      "is_trashed": "boolean"
    }
  ],
  "start": "integer",
  "end": "integer",
  "count": "integer"
}

Trash bot

Move a bot user to the trash.

POST /api/bots/{bot}/trash

Path parameters

bot string required

Identifier (id or uid) of the bot to trash.

Example request

curl -X POST {WEAVY-URL}/api/bots/tweety-bird/trash
-H "Authorization: Bearer {API-KEY}"

Response codes

204 No Content
400 Bad Request
401 Unauthorized
403 Forbidden
404 Not Found

Restore bot

Restore a bot user from the trash.

POST /api/bots/{bot}/restore

Path parameters

bot string required

Identifier (id or uid) of the bot to restore.

Example request

curl -X POST {WEAVY-URL}/api/bots/tweety-bird/restore
-H "Authorization: Bearer {API-KEY}"

Response codes

204 No Content
400 Bad Request
401 Unauthorized
403 Forbidden
404 Not Found