1. Reference
2. Web API
3. Agents

Agents

The Agents API has methods for managing AI agents and chat bots.

Create agent

Create AI agent.

POST /api/agents

Body parameters

uid string required

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

name string required

Agent name. Used in listings, @mentions etc.

provider string required

The AI provider for the agent, must be one of openai, anthropic, gemini, or kapa.

model string required

The model to use for the agent, e.g. "gpt-4.1-mini" or "gemini-2.0-flash" etc.

instructions string

System instructions for the agent.

knowledge_base_id integer

Id of the agent's knowledge base (a Files app).

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 agent (id or name).

comment string

Comment or other application-specific information about the agent.

tags array of strings

A list of tags to associate with the agent.

metadata object

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

Example request

curl {WEAVY-URL}/api/agents
-H "Authorization: Bearer {API-KEY}"
--json "{ 'uid': 'tweety-bird', 'name': 'Tweety Bird', 'provider': 'openai', 'model': 'gpt-4.1-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",
  "knowledge_base_id": "integer",
  "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_agent": "boolean",
  "is_trashed": "boolean"
}

Get agent

Get AI agent with specified identifier.

GET /api/agents/{agent}

Path parameters

agent string required

Agent identifier (id or uid).

Query parameters

trashed boolean

true to return agent even if trashed.

Example request

curl {WEAVY-URL}/api/agents/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",
  "metadata": "object",
  "tags": [
    "string"
  ],
  "created_at": "string",
  "updated_at": "string",
  "is_trashed": "boolean"
}

Update agent

Update AI agent.

PATCH /api/agents/{agent}

Path parameters

agent string required

Agent identifier (id or uid).

Body parameters

uid string

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

name string

Agent name. Used in listings, @mentions etc.

provider string

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

model string

The model to use for the agent, e.g. "gpt-4.1-mini" or "gemini-2.0-flash" etc.

instructions string

System instructions for the agent.

knowledge_base_id integer

Id of the agent's knowledge base (a Files app).

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 agent (id or name).

comment string

Comment or other application-specific information about the agent.

tags array of strings

A list of tags to associate with the agent.

metadata object

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

Example request

curl -X PATCH {WEAVY-URL}/api/agents/tweety-bird
-H "Authorization: Bearer {API-KEY}"
--json "{ 'model': 'gpt-4.1-nano' }"

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",
  "knowledge_base_id": "integer",
  "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_agent": "boolean",
  "is_trashed": "boolean"
}

List agents

List AI agents.

GET /api/agents

Query parameters

autocomplete boolean

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

directory string

Directory identifier (id or name). When unspecified agents 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/agents?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",
      "knowledge_base_id": "integer",
      "avatar_url": "string",
      "comment": "string",
      "tags": [
        "string"
      ],
      "metadata": "object",
      "created_at": "string",
      "updated_at": "string",
      "is_agent": "boolean",
      "is_trashed": "boolean"
    }
  ],
  "start": "integer",
  "end": "integer",
  "count": "integer"
}

Trash agent

Move an AI agent to the trash.

POST /api/agents/{agent}/trash

Path parameters

agent string required

Identifier (id or uid) of agent to trash.

Example request

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

Response codes

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

Restore agent

Restore an AI agent from the trash.

POST /api/agents/{agent}/restore

Path parameters

agent string required

Identifier (id or uid) of agent to restore.

Example request

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

Response codes

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

Delete agent

Permanently delete an AI agent. Content generated by the agent won’t be removed (this includes comments, files, messages and other data).

DELETE /api/agents/{agent}

Path parameters

agent string required

Identifier (id or uid) of agent to delete.

Example request

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

Response codes

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