Add a text source
Add a plain-text knowledge-base source to the agent. The content is chunked (~512 tokens), embedded at 1024 dimensions, and stored for retrieval via the `search_knowledge_base` tool at call time. Use when the caller's content lives in your prompt / docs / FAQ, paste it here rather than stuffing it into the system prompt. **The first source on an agent auto-attaches the `search_knowledge_base` tool**; the agent will start citing the new content on its next call.
Authorization
bearerAuth A personal access token from Settings > API tokens.
In: header
Path Parameters
Workspace slug (GET /me lists yours).
Agent slug within the workspace.
Header Parameters
A key you choose, such as a UUID, that makes this POST safe to retry. Within 24 hours the same key and request answers with the first successful answer and runs nothing, the same key with a different request answers 422 idempotency_key_reused, and a key whose request is still running answers 409 idempotency_key_in_use. A failed request keeps nothing, so the same key runs it again.
1 <= length <= 255Request Body
application/json
TypeScript Definitions
Use the request body type in TypeScript.
Response Body
application/json
application/problem+json
application/problem+json
application/problem+json
application/problem+json
application/problem+json
application/problem+json
application/problem+json
curl -X POST "https://example.com/workspaces/string/agents/string/knowledge-base/texts" \ -H "Content-Type: application/json" \ -d '{ "name": "string", "content": "stringstringstringst" }'{
"source": {
"id": "string",
"status": "string",
"property1": null,
"property2": null
},
"property1": null,
"property2": null
}{
"type": "http://example.com",
"title": "string",
"status": 0,
"detail": "string",
"code": "string",
"errors": [
{
"path": "string",
"message": "string"
}
],
"estimate": {},
"retryAfterSeconds": 0
}{
"type": "http://example.com",
"title": "string",
"status": 0,
"detail": "string",
"code": "string",
"errors": [
{
"path": "string",
"message": "string"
}
],
"estimate": {},
"retryAfterSeconds": 0
}{
"type": "http://example.com",
"title": "string",
"status": 0,
"detail": "string",
"code": "string",
"errors": [
{
"path": "string",
"message": "string"
}
],
"estimate": {},
"retryAfterSeconds": 0
}{
"type": "http://example.com",
"title": "string",
"status": 0,
"detail": "string",
"code": "string",
"errors": [
{
"path": "string",
"message": "string"
}
],
"estimate": {},
"retryAfterSeconds": 0
}{
"type": "http://example.com",
"title": "string",
"status": 0,
"detail": "string",
"code": "string",
"errors": [
{
"path": "string",
"message": "string"
}
],
"estimate": {},
"retryAfterSeconds": 0
}{
"type": "http://example.com",
"title": "string",
"status": 0,
"detail": "string",
"code": "string",
"errors": [
{
"path": "string",
"message": "string"
}
],
"estimate": {},
"retryAfterSeconds": 0
}{
"type": "http://example.com",
"title": "string",
"status": 0,
"detail": "string",
"code": "string",
"errors": [
{
"path": "string",
"message": "string"
}
],
"estimate": {},
"retryAfterSeconds": 0
}Set a plain variable PUT
Create or update a plain (non-secret) per-agent variable. These get interpolated into HTTP tool URLs and bodies, e.g. setting `tenant_id = acme-prod` lets a tool URL be `https://api/example.com/{{tenant_id}}/users`, and into the system prompt, where `{{opening_hours}}` reaches the model as its value. Only plain variables fill into the system prompt. Plain variables are stored in the row as-is and ARE inlined in the agent snapshot. **For API keys, OAuth tokens, anything sensitive, use the secret path instead**: `request_secret_variable` in the app (the operator types the value into a dialog you never see), or `set_secret_variable` over the MCP. Either way the value goes to the encrypted secret store and is never echoed; this tool rejects secret-shaped values. To rename an existing variable, use `rename_variable`, never delete-and-recreate, which orphans every reference.
Add a web page or site POST
Add a URL knowledge-base source. The page is read, cleaned to its main text, chunked, and embedded, the same shape as `add_text_kb_source` but the content is pulled at ingest time. Pass `wholeSite: true` to read up to 100 pages of the same site as one source instead. Re-fetch is manual unless a schedule is set with `edit_kb_source_schedule`. Paywalled pages, or a site with no readable pages, fail with an error the operator can act on. Use for public content the operator wants to keep current (pricing page, FAQ page, policy page, or a whole small-business site).