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 anthropic, gemini, kapa, openai or weavy.

model string required

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

instructions string

High-level system instructions describing the desired agent behavior, e.g. main objectives, tone, response style etc.

functions array of objects

A list of function definitions that lets the agent interface with external API endpoints.

knowledge array of integers

Ids of files apps for agent's knowledge.

web_search boolean

Allow the agent to search the web and answer questions with up-to-date information beyond its knowledge cutoff.

max_tokens integer

Maximum number of tokens to generate before stopping.

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', 'instructions': '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",
  "functions": [
    "string"
  ],
  "knowledge": [
    "integer"
  ],
  "web_search": "boolean",
  "max_tokens": "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",
  "provider": "string",
  "model": "string",
  "instructions": "string",
  "functions": [
    "string"
  ],
  "knowledge": [
    "integer"
  ],
  "web_search": "boolean",
  "max_tokens": "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"
}

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

High-level system instructions describing the desired agent behavior, e.g. main objectives, tone, response style etc.

functions array of objects

A list of function definitions that lets the agent interface with external API endpoints.

knowledge array of integers

Ids of files apps for agent's knowledge.

web_search boolean

Allow the agent to search the web and answer questions with up-to-date information beyond its knowledge cutoff.

max_tokens integer

Maximum number of tokens to generate before stopping.

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",
  "functions": [
    "string"
  ],
  "knowledge": [
    "integer"
  ],
  "web_search": "boolean",
  "max_tokens": "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"
}

Upsert agent

Update or insert AI agent. If an agent with the specified uid is found it is updated, otherwise it is created.

PUT /api/agents/{uid}

Path parameters

uid string required

Unique identifier.

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

High-level system instructions describing the desired agent behavior, e.g. main objectives, tone, response style etc.

functions array of objects

A list of function definitions that lets the agent interface with external API endpoints.

knowledge array of integers

Ids of files apps for agent's knowledge.

web_search boolean

Allow the agent to search the web and answer questions with up-to-date information beyond its knowledge cutoff.

max_tokens integer

Maximum number of tokens to generate before stopping.

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 PUT {WEAVY-URL}/api/agents/tweety-bird
-H "Authorization: Bearer {API-KEY}"
--json "{ 'name': 'Tweety Bird', 'provider': 'openai', 'model': 'gpt-4.1-mini', 'instructions': 'You’re a cute cartoon character with an aggressive nature.' }"

Response codes

200 OK
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",
  "functions": [
    "string"
  ],
  "knowledge": [
    "integer"
  ],
  "web_search": "boolean",
  "max_tokens": "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",
      "functions": [
        "string"
      ],
      "knowledge": [
        "integer"
      ],
      "web_search": "boolean",
      "max_tokens": "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

Add function

Adds a function definition to the agent's tools, allowing it to interface with an external API endpoint.

POST /api/agents/{agent}/functions

Path parameters

agent string required

Agent identifier (id or uid).

Body parameters

name string required

The name of the function.

description string required

Describes the purpose of the function to the agent.

url string required

Url to the external API endpoint.

method string

HTTP method to use when calling the endpoint (defaults to GET).

headers object

Headers to include in the request, e.g. Authorization, Content-Type, User-Agent etc.

parameters object

A JSON schema object describing the parameters of the function (if any).

Example request

curl -X POST {WEAVY-URL}/api/agents/tweety-bird/functions
-H "Authorization: Bearer {API-KEY}"
--json "{ 'name': 'get_joke', 'description': 'Returns a joke', 'url': 'https://api.example.com/joke' }"

Response codes

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

Response schema

{
  "name": "string",
  "description": "string",
  "method": "string",
  "url": "string",
  "headers": "object",
  "parameters": "object"
}

Get function

Returns the definition for the specified function.

GET /api/agents/{agent}/functions/{name}

Path parameters

agent string required

Agent identifier (id or uid).

name string required

Name of function.

Example request

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

Response codes

200 OK
401 Unauthorized
404 Not Found

Response schema

{
  "name": "string",
  "description": "string",
  "method": "string",
  "url": "string",
  "headers": "object",
  "parameters": "object"
}

Update function

Updates an existing function definition.

PATCH /api/agents/{agent}/functions/{name}

Path parameters

agent string required

Agent identifier (id or uid).

name string required

Name of function to update.

Body parameters

name string

The name of the function.

description string

Describes the purpose of the function to the agent.

method string

HTTP method to use when calling the endpoint.

url string

Url to the external API endpoint.

headers object

Headers to include in the request, e.g. Authorization, Content-Type, User-Agent etc.

parameters object

A JSON schema object describing the parameters of the function (if any).

Example request

curl -X PATCH {WEAVY-URL}/api/agents/tweety-bird/functions/get_joke
-H "Authorization: Bearer {API-KEY}"
--json "{ 'name': 'get_joke', 'description': 'Returns a joke', 'url': 'https://api.example.com/joke' }"

Response codes

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

Response schema

{
  "name": "string",
  "description": "string",
  "method": "string",
  "url": "string",
  "headers": "object",
  "parameters": "object"
}

Upsert function

Add or update a function definition. If the agent already has a function with the specified name it is updated, otherwise it is added.

PUT /api/agents/{agent}/functions/{name}

Path parameters

agent string required

Agent identifier (id or uid).

name string required

Function name.

Body parameters

name string required

The name of the function.

description string required

Describes the purpose of the function to the agent.

url string required

Url to the external API endpoint.

method string

HTTP method to use when calling the endpoint (defaults to GET).

headers object

Headers to include in the request, e.g. Authorization, Content-Type, User-Agent etc.

parameters object

A JSON schema object describing the parameters of the function (if any).

Example request

curl -X PUT {WEAVY-URL}/api/agents/tweety-bird/functions/get_joke
-H "Authorization: Bearer {API-KEY}"
--json "{ 'name': 'get_joke', 'description': 'Returns a joke', 'url': 'https://api.example.com/joke' }"

Response codes

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

Response schema

{
  "name": "string",
  "description": "string",
  "method": "string",
  "url": "string",
  "headers": "object",
  "parameters": "object"
}

List functions

List all function definitions for an agent.

GET /api/agents/{agent}/functions

Path parameters

agent string required

Agent identifier (id or uid).

Example request

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

Response codes

200 OK
401 Unauthorized

Response schema

[
  {
    "name": "string",
    "description": "string",
    "method": "string",
    "url": "string",
    "headers": "object",
    "parameters": "object"
  }
]

Remove function

Remove a function definition from the agent.

DELETE /api/agents/{agent}/functions/{name}

Path parameters

agent string required

Agent identifier (id or uid).

name string required

Name of function to remove.

Example request

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

Response codes

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