Baze de cunoștințe

11 endpoint-uri. Fiecare cale de mai jos este relativă la URL-ul de bază al API-ului și include deja prefixul /api/v1 — vezi convențiile pentru autentificare, paginare, erori și idempotență.

	Endpoint
GET	`/knowledge-bases`	Lists the organization's knowledge bases, newest first
POST	`/knowledge-bases`	Creates a knowledge base with its embedding, chunking and retrieval configuration
GET	`/knowledge-bases/{knowledgeBase}`	Returns one knowledge base with its retrieval and embedding settings
PUT	`/knowledge-bases/{knowledgeBase}`	Updates a knowledge base, refusing an embedding model change once content has already been embedded
DELETE	`/knowledge-bases/{knowledgeBase}`	Deletes a knowledge base, every document and chunk in it, and detaches it from all assistants
GET	`/knowledge-bases/{knowledgeBase}/documents`	Lists the documents in a knowledge base with their ingestion status and progress
POST	`/knowledge-bases/{knowledgeBase}/documents`	Accepts a file, URL or pasted text for ingestion and queues extraction and embedding on the queue
GET	`/knowledge-bases/{knowledgeBase}/documents/{document}`	Returns one knowledge document with its ingestion status, progress and failure reason
DELETE	`/knowledge-bases/{knowledgeBase}/documents/{document}`	Deletes one document, its chunks and its stored source file, and refreshes the base's counters
POST	`/knowledge-bases/{knowledgeBase}/documents/{document}/retry`	Clears a document's chunks and failure state and re-queues it for ingestion
POST	`/knowledge-bases/{knowledgeBase}/query`	Runs a real hybrid retrieval query against the knowledge base and returns the matching passages

Endpoint-uri

Lists the organization's knowledge bases, newest first

GET/knowledge-bases

Necesită knowledge.read.
Only limit is honoured (default 25, capped at 100); there are no filters.

Parametri de interogare

Nume	Tip	Obligatoriu	Note
`limit`	integer	—	default `25`

cURLJavaScriptPHPPython

bash

curl -X GET "$CALLAGENT_API_URL/knowledge-bases?limit=25" \
  -H "Authorization: Bearer $CALLAGENT_API_KEY" \
  -H "Accept: application/json"

const response = await fetch(`${process.env.CALLAGENT_API_URL}/knowledge-bases?limit=25`, {
  method: 'GET',
  headers: {
    Authorization: `Bearer ${process.env.CALLAGENT_API_KEY}`,
    Accept: 'application/json',
  },
});

if (!response.ok) {
  const { error } = await response.json();
  throw new Error(`${error.type}: ${error.message}`);
}

const { data } = await response.json();

php

<?php

$handle = curl_init(getenv('CALLAGENT_API_URL') . '/knowledge-bases?limit=25');

curl_setopt_array($handle, [
    CURLOPT_CUSTOMREQUEST => 'GET',
    CURLOPT_RETURNTRANSFER => true,
    CURLOPT_HTTPHEADER => [
        'Authorization: Bearer ' . getenv('CALLAGENT_API_KEY'),
        'Accept: application/json',
    ],
]);

$body = json_decode(curl_exec($handle), true);
$status = curl_getinfo($handle, CURLINFO_HTTP_CODE);
curl_close($handle);

if ($status >= 400) {
    throw new RuntimeException("{$body['error']['type']}: {$body['error']['message']}");
}

$data = $body['data'];

python

import os, requests

response = requests.get(
    f"{os.environ['CALLAGENT_API_URL']}/knowledge-bases?limit=25",
    headers={"Authorization": f"Bearer {os.environ['CALLAGENT_API_KEY']}"},
    timeout=30,
)
response.raise_for_status()
data = response.json()["data"]

Răspunsuri

Status	Corp
`200`	Paginated set of `KnowledgeBaseResource`

Erori

Status	Când apare
`403`	The key lacks knowledge.read

Exemplu de răspuns, generat din schemă:

json

{
  "data": [
    {
      "id": "01JQ0000000000000000000000",
      "object": "string",
      "name": "Support Line",
      "description": "string",
      "provider": "string",
      "namespace": "Support Line",
      "embedding": {},
      "chunk_size": 1,
      "chunk_overlap": 1,
      "retrieval": {},
      "custom_provider": {},
      "knowledge_only": true,
      "knowledge_only_plan": {},
      "status": "string",
      "document_count": 1,
      "chunk_count": 1,
      "total_bytes": 1,
      "metadata": {},
      "documents": [],
      "created_at": "2026-01-01T12:00:00+00:00",
      "updated_at": "2026-01-01T12:00:00+00:00"
    }
  ],
  "links": {
    "first": "string",
    "last": "string",
    "prev": "string",
    "next": "string"
  },
  "meta": {
    "current_page": 1,
    "from": 1,
    "last_page": 1,
    "links": [
      {}
    ],
    "path": "string",
    "per_page": 25,
    "to": 1,
    "total": 1
  }
}

Creates a knowledge base with its embedding, chunking and retrieval configuration

POST/knowledge-bases

Necesită knowledge.write.

Corpul cererii

Câmp	Tip	Obligatoriu	Note
`name`	string	da	max 255 chars
`description`	string \| null	—	max 255 chars
`provider`	`pgvector` · `custom` · `qdrant` · `pinecone` · `weaviate` \| null	—
`namespace`	string \| null	—	max 255 chars
`embedding_provider`	string \| null	—	max 48 chars
`embedding_model`	string \| null	—	max 96 chars
`chunk_size`	integer \| null	—	min 64. max 4000
`chunk_overlap`	integer \| null	—	min 0. max 2000
`retrieval`	object	—
`retrieval.top_k`	integer \| null	—	min 1. max 50
`retrieval.threshold`	number \| null	—	min 0. max 1
`retrieval.vector_weight`	number \| null	—	min 0. max 1
`retrieval.lexical_weight`	number \| null	—	min 0. max 1
`retrieval.max_context_chars`	integer \| null	—	min 200. max 100000
`retrieval.citations`	`inline` · `footnote` · `none` · `null` \| null	—
`retrieval.metadata_filters`	string[] \| null	—
`custom_provider`	object	—
`custom_provider.url`	string \| null	—	uri. max 2048 chars
`custom_provider.headers`	string[] \| null	—
`custom_provider.timeout_seconds`	integer \| null	—	min 1. max 60
`knowledge_only`	boolean \| null	—
`knowledge_only_plan`	string[] \| null	—
`metadata`	string[] \| null	—

cURLJavaScriptPHPPython

bash

curl -X POST "$CALLAGENT_API_URL/knowledge-bases" \
  -H "Authorization: Bearer $CALLAGENT_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Accept: application/json" \
  -d '{
       "name": "Support Line",
       "provider": "pgvector",
       "namespace": "Support Line",
       "chunk_size": 1,
       "chunk_overlap": 1,
       "retrieval": {
         "top_k": 1,
         "threshold": 1,
         "vector_weight": 1,
         "lexical_weight": 1,
         "max_context_chars": 1,
         "citations": "inline",
         "metadata_filters": [
           "string"
         ]
       },
       "custom_provider": {
         "url": "https://example.com/hook",
         "headers": [
           "string"
         ],
         "timeout_seconds": 30
       }
     }'

const response = await fetch(`${process.env.CALLAGENT_API_URL}/knowledge-bases`, {
  method: 'POST',
  headers: {
    Authorization: `Bearer ${process.env.CALLAGENT_API_KEY}`,
    Accept: 'application/json',
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({
    "name": "Support Line",
    "provider": "pgvector",
    "namespace": "Support Line",
    "chunk_size": 1,
    "chunk_overlap": 1,
    "retrieval": {
      "top_k": 1,
      "threshold": 1,
      "vector_weight": 1,
      "lexical_weight": 1,
      "max_context_chars": 1,
      "citations": "inline",
      "metadata_filters": [
        "string"
      ]
    },
    "custom_provider": {
      "url": "https://example.com/hook",
      "headers": [
        "string"
      ],
      "timeout_seconds": 30
    }
  }),
});

if (!response.ok) {
  const { error } = await response.json();
  throw new Error(`${error.type}: ${error.message}`);
}

const { data } = await response.json();

php

<?php

$handle = curl_init(getenv('CALLAGENT_API_URL') . '/knowledge-bases');

curl_setopt_array($handle, [
    CURLOPT_CUSTOMREQUEST => 'POST',
    CURLOPT_RETURNTRANSFER => true,
    CURLOPT_HTTPHEADER => [
        'Authorization: Bearer ' . getenv('CALLAGENT_API_KEY'),
        'Accept: application/json',
        'Content-Type: application/json',
    ],
    CURLOPT_POSTFIELDS => json_encode([
    'name' => 'Support Line',
    'provider' => 'pgvector',
    'namespace' => 'Support Line',
    'chunk_size' => 1,
    'chunk_overlap' => 1,
    'retrieval' => [
        'top_k' => 1,
        'threshold' => 1,
        'vector_weight' => 1,
        'lexical_weight' => 1,
        'max_context_chars' => 1,
        'citations' => 'inline',
        'metadata_filters' => [
            'string',
        ],
    ],
    'custom_provider' => [
        'url' => 'https://example.com/hook',
        'headers' => [
            'string',
        ],
        'timeout_seconds' => 30,
    ],
]),
]);

$body = json_decode(curl_exec($handle), true);
$status = curl_getinfo($handle, CURLINFO_HTTP_CODE);
curl_close($handle);

if ($status >= 400) {
    throw new RuntimeException("{$body['error']['type']}: {$body['error']['message']}");
}

$data = $body['data'];

python

import os, requests

response = requests.post(
    f"{os.environ['CALLAGENT_API_URL']}/knowledge-bases",
    headers={"Authorization": f"Bearer {os.environ['CALLAGENT_API_KEY']}"},
    json={
      "name": "Support Line",
      "provider": "pgvector",
      "namespace": "Support Line",
      "chunk_size": 1,
      "chunk_overlap": 1,
      "retrieval": {
        "top_k": 1,
        "threshold": 1,
        "vector_weight": 1,
        "lexical_weight": 1,
        "max_context_chars": 1,
        "citations": "inline",
        "metadata_filters": [
          "string"
        ]
      },
      "custom_provider": {
        "url": "https://example.com/hook",
        "headers": [
          "string"
        ],
        "timeout_seconds": 30
      }
    },
    timeout=30,
)
response.raise_for_status()
data = response.json()["data"]

Răspunsuri

Status	Corp
`201`	`KnowledgeBaseResource`

Erori

Status	Când apare
`403`	The key lacks knowledge.write
`422`	Validation failed

Exemplu de răspuns, generat din schemă:

json

{
  "data": {
    "id": "01JQ0000000000000000000000",
    "object": "string",
    "name": "Support Line",
    "description": "string",
    "provider": "string",
    "namespace": "Support Line",
    "embedding": {
      "provider": "string",
      "model": "string",
      "dimensions": 1
    },
    "chunk_size": 1,
    "chunk_overlap": 1,
    "retrieval": {},
    "custom_provider": {},
    "knowledge_only": true,
    "knowledge_only_plan": {},
    "status": "string",
    "document_count": 1,
    "chunk_count": 1,
    "total_bytes": 1,
    "metadata": {},
    "documents": [
      {}
    ],
    "created_at": "2026-01-01T12:00:00+00:00",
    "updated_at": "2026-01-01T12:00:00+00:00"
  }
}

Returns one knowledge base with its retrieval and embedding settings

GET/knowledge-bases/{knowledgeBase}

Necesită knowledge.read.

Parametri de cale

Nume	Tip	Obligatoriu	Note
`knowledgeBase`	string	da	The knowledge base ID

cURLJavaScriptPHPPython

bash

curl -X GET "$CALLAGENT_API_URL/knowledge-bases/01JQ0000000000000000000000" \
  -H "Authorization: Bearer $CALLAGENT_API_KEY" \
  -H "Accept: application/json"

const response = await fetch(`${process.env.CALLAGENT_API_URL}/knowledge-bases/01JQ0000000000000000000000`, {
  method: 'GET',
  headers: {
    Authorization: `Bearer ${process.env.CALLAGENT_API_KEY}`,
    Accept: 'application/json',
  },
});

if (!response.ok) {
  const { error } = await response.json();
  throw new Error(`${error.type}: ${error.message}`);
}

const { data } = await response.json();

php

<?php

$handle = curl_init(getenv('CALLAGENT_API_URL') . '/knowledge-bases/01JQ0000000000000000000000');

curl_setopt_array($handle, [
    CURLOPT_CUSTOMREQUEST => 'GET',
    CURLOPT_RETURNTRANSFER => true,
    CURLOPT_HTTPHEADER => [
        'Authorization: Bearer ' . getenv('CALLAGENT_API_KEY'),
        'Accept: application/json',
    ],
]);

$body = json_decode(curl_exec($handle), true);
$status = curl_getinfo($handle, CURLINFO_HTTP_CODE);
curl_close($handle);

if ($status >= 400) {
    throw new RuntimeException("{$body['error']['type']}: {$body['error']['message']}");
}

$data = $body['data'];

python

import os, requests

response = requests.get(
    f"{os.environ['CALLAGENT_API_URL']}/knowledge-bases/01JQ0000000000000000000000",
    headers={"Authorization": f"Bearer {os.environ['CALLAGENT_API_KEY']}"},
    timeout=30,
)
response.raise_for_status()
data = response.json()["data"]

Răspunsuri

Status	Corp
`200`	`KnowledgeBaseResource`

Erori

Status	Când apare
`403`	The key lacks knowledge.read
`404`	No such knowledge base in this organization

Exemplu de răspuns, generat din schemă:

json

{
  "data": {
    "id": "01JQ0000000000000000000000",
    "object": "string",
    "name": "Support Line",
    "description": "string",
    "provider": "string",
    "namespace": "Support Line",
    "embedding": {
      "provider": "string",
      "model": "string",
      "dimensions": 1
    },
    "chunk_size": 1,
    "chunk_overlap": 1,
    "retrieval": {},
    "custom_provider": {},
    "knowledge_only": true,
    "knowledge_only_plan": {},
    "status": "string",
    "document_count": 1,
    "chunk_count": 1,
    "total_bytes": 1,
    "metadata": {},
    "documents": [
      {}
    ],
    "created_at": "2026-01-01T12:00:00+00:00",
    "updated_at": "2026-01-01T12:00:00+00:00"
  }
}

Updates a knowledge base, refusing an embedding model change once content has already been embedded

PUT/knowledge-bases/{knowledgeBase}

Necesită knowledge.write.
PATCH este acceptat pe aceeași cale, cu același corp.
Changing embedding_model on a base with stored chunks is a 422: create a new knowledge base instead.

Parametri de cale

Nume	Tip	Obligatoriu	Note
`knowledgeBase`	string	da	The knowledge base ID

Corpul cererii

Câmp	Tip	Obligatoriu	Note
`name`	string	—	max 255 chars
`description`	string \| null	—	max 255 chars
`provider`	`pgvector` · `custom` · `qdrant` · `pinecone` · `weaviate` \| null	—
`namespace`	string \| null	—	max 255 chars
`embedding_provider`	string \| null	—	max 48 chars
`embedding_model`	string \| null	—	max 96 chars
`chunk_size`	integer \| null	—	min 64. max 4000
`chunk_overlap`	integer \| null	—	min 0. max 2000
`retrieval`	object	—
`retrieval.top_k`	integer \| null	—	min 1. max 50
`retrieval.threshold`	number \| null	—	min 0. max 1
`retrieval.vector_weight`	number \| null	—	min 0. max 1
`retrieval.lexical_weight`	number \| null	—	min 0. max 1
`retrieval.max_context_chars`	integer \| null	—	min 200. max 100000
`retrieval.citations`	`inline` · `footnote` · `none` · `null` \| null	—
`retrieval.metadata_filters`	string[] \| null	—
`custom_provider`	object	—
`custom_provider.url`	string \| null	—	uri. max 2048 chars
`custom_provider.headers`	string[] \| null	—
`custom_provider.timeout_seconds`	integer \| null	—	min 1. max 60
`knowledge_only`	boolean \| null	—
`knowledge_only_plan`	string[] \| null	—
`metadata`	string[] \| null	—

cURLJavaScriptPHPPython

bash

curl -X PUT "$CALLAGENT_API_URL/knowledge-bases/01JQ0000000000000000000000" \
  -H "Authorization: Bearer $CALLAGENT_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Accept: application/json" \
  -d '{
       "name": "Support Line",
       "provider": "pgvector",
       "namespace": "Support Line",
       "chunk_size": 1,
       "chunk_overlap": 1,
       "retrieval": {
         "top_k": 1,
         "threshold": 1,
         "vector_weight": 1,
         "lexical_weight": 1,
         "max_context_chars": 1,
         "citations": "inline",
         "metadata_filters": [
           "string"
         ]
       },
       "custom_provider": {
         "url": "https://example.com/hook",
         "headers": [
           "string"
         ],
         "timeout_seconds": 30
       }
     }'

const response = await fetch(`${process.env.CALLAGENT_API_URL}/knowledge-bases/01JQ0000000000000000000000`, {
  method: 'PUT',
  headers: {
    Authorization: `Bearer ${process.env.CALLAGENT_API_KEY}`,
    Accept: 'application/json',
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({
    "name": "Support Line",
    "provider": "pgvector",
    "namespace": "Support Line",
    "chunk_size": 1,
    "chunk_overlap": 1,
    "retrieval": {
      "top_k": 1,
      "threshold": 1,
      "vector_weight": 1,
      "lexical_weight": 1,
      "max_context_chars": 1,
      "citations": "inline",
      "metadata_filters": [
        "string"
      ]
    },
    "custom_provider": {
      "url": "https://example.com/hook",
      "headers": [
        "string"
      ],
      "timeout_seconds": 30
    }
  }),
});

if (!response.ok) {
  const { error } = await response.json();
  throw new Error(`${error.type}: ${error.message}`);
}

const { data } = await response.json();

php

<?php

$handle = curl_init(getenv('CALLAGENT_API_URL') . '/knowledge-bases/01JQ0000000000000000000000');

curl_setopt_array($handle, [
    CURLOPT_CUSTOMREQUEST => 'PUT',
    CURLOPT_RETURNTRANSFER => true,
    CURLOPT_HTTPHEADER => [
        'Authorization: Bearer ' . getenv('CALLAGENT_API_KEY'),
        'Accept: application/json',
        'Content-Type: application/json',
    ],
    CURLOPT_POSTFIELDS => json_encode([
    'name' => 'Support Line',
    'provider' => 'pgvector',
    'namespace' => 'Support Line',
    'chunk_size' => 1,
    'chunk_overlap' => 1,
    'retrieval' => [
        'top_k' => 1,
        'threshold' => 1,
        'vector_weight' => 1,
        'lexical_weight' => 1,
        'max_context_chars' => 1,
        'citations' => 'inline',
        'metadata_filters' => [
            'string',
        ],
    ],
    'custom_provider' => [
        'url' => 'https://example.com/hook',
        'headers' => [
            'string',
        ],
        'timeout_seconds' => 30,
    ],
]),
]);

$body = json_decode(curl_exec($handle), true);
$status = curl_getinfo($handle, CURLINFO_HTTP_CODE);
curl_close($handle);

if ($status >= 400) {
    throw new RuntimeException("{$body['error']['type']}: {$body['error']['message']}");
}

$data = $body['data'];

python

import os, requests

response = requests.put(
    f"{os.environ['CALLAGENT_API_URL']}/knowledge-bases/01JQ0000000000000000000000",
    headers={"Authorization": f"Bearer {os.environ['CALLAGENT_API_KEY']}"},
    json={
      "name": "Support Line",
      "provider": "pgvector",
      "namespace": "Support Line",
      "chunk_size": 1,
      "chunk_overlap": 1,
      "retrieval": {
        "top_k": 1,
        "threshold": 1,
        "vector_weight": 1,
        "lexical_weight": 1,
        "max_context_chars": 1,
        "citations": "inline",
        "metadata_filters": [
          "string"
        ]
      },
      "custom_provider": {
        "url": "https://example.com/hook",
        "headers": [
          "string"
        ],
        "timeout_seconds": 30
      }
    },
    timeout=30,
)
response.raise_for_status()
data = response.json()["data"]

Răspunsuri

Status	Corp
`200`	`KnowledgeBaseResource`

Erori

Status	Când apare
`403`	The key lacks knowledge.write
`404`	No such knowledge base in this organization
`422`	Validation failed, or the embedding model was changed on a base that already has chunks

Exemplu de răspuns, generat din schemă:

json

{
  "data": {
    "id": "01JQ0000000000000000000000",
    "object": "string",
    "name": "Support Line",
    "description": "string",
    "provider": "string",
    "namespace": "Support Line",
    "embedding": {
      "provider": "string",
      "model": "string",
      "dimensions": 1
    },
    "chunk_size": 1,
    "chunk_overlap": 1,
    "retrieval": {},
    "custom_provider": {},
    "knowledge_only": true,
    "knowledge_only_plan": {},
    "status": "string",
    "document_count": 1,
    "chunk_count": 1,
    "total_bytes": 1,
    "metadata": {},
    "documents": [
      {}
    ],
    "created_at": "2026-01-01T12:00:00+00:00",
    "updated_at": "2026-01-01T12:00:00+00:00"
  }
}

Deletes a knowledge base, every document and chunk in it, and detaches it from all assistants

DELETE/knowledge-bases/{knowledgeBase}

Necesită knowledge.write.
Acest răspuns nu este împachetat în data.
Body is a bare {"deleted": true, "id": "..."}. Side effects: stored source files are removed from disk and assistants are detached.

Parametri de cale

Nume	Tip	Obligatoriu	Note
`knowledgeBase`	string	da	The knowledge base ID

cURLJavaScriptPHPPython

bash

curl -X DELETE "$CALLAGENT_API_URL/knowledge-bases/01JQ0000000000000000000000" \
  -H "Authorization: Bearer $CALLAGENT_API_KEY" \
  -H "Accept: application/json"

const response = await fetch(`${process.env.CALLAGENT_API_URL}/knowledge-bases/01JQ0000000000000000000000`, {
  method: 'DELETE',
  headers: {
    Authorization: `Bearer ${process.env.CALLAGENT_API_KEY}`,
    Accept: 'application/json',
  },
});

if (!response.ok) {
  const { error } = await response.json();
  throw new Error(`${error.type}: ${error.message}`);
}

const { data } = await response.json();

php

<?php

$handle = curl_init(getenv('CALLAGENT_API_URL') . '/knowledge-bases/01JQ0000000000000000000000');

curl_setopt_array($handle, [
    CURLOPT_CUSTOMREQUEST => 'DELETE',
    CURLOPT_RETURNTRANSFER => true,
    CURLOPT_HTTPHEADER => [
        'Authorization: Bearer ' . getenv('CALLAGENT_API_KEY'),
        'Accept: application/json',
    ],
]);

$body = json_decode(curl_exec($handle), true);
$status = curl_getinfo($handle, CURLINFO_HTTP_CODE);
curl_close($handle);

if ($status >= 400) {
    throw new RuntimeException("{$body['error']['type']}: {$body['error']['message']}");
}

$data = $body['data'];

python

import os, requests

response = requests.delete(
    f"{os.environ['CALLAGENT_API_URL']}/knowledge-bases/01JQ0000000000000000000000",
    headers={"Authorization": f"Bearer {os.environ['CALLAGENT_API_KEY']}"},
    timeout=30,
)
response.raise_for_status()
data = response.json()["data"]

Răspunsuri

Status	Corp
`200`	Bare JSON object, not `data`-wrapped

Erori

Status	Când apare
`403`	The key lacks knowledge.write
`404`	No such knowledge base in this organization

Exemplu de răspuns, generat din schemă:

json

{
  "deleted": true,
  "id": null
}

Lists the documents in a knowledge base with their ingestion status and progress

GET/knowledge-bases/{knowledgeBase}/documents

Necesită knowledge.read.
Query params: status, limit (default 25, capped at 100).

Parametri de cale

Nume	Tip	Obligatoriu	Note
`knowledgeBase`	string	da	The knowledge base ID

Parametri de interogare

Nume	Tip	Obligatoriu	Note
`limit`	integer	—	default `25`

cURLJavaScriptPHPPython

bash

curl -X GET "$CALLAGENT_API_URL/knowledge-bases/01JQ0000000000000000000000/documents?limit=25" \
  -H "Authorization: Bearer $CALLAGENT_API_KEY" \
  -H "Accept: application/json"

const response = await fetch(`${process.env.CALLAGENT_API_URL}/knowledge-bases/01JQ0000000000000000000000/documents?limit=25`, {
  method: 'GET',
  headers: {
    Authorization: `Bearer ${process.env.CALLAGENT_API_KEY}`,
    Accept: 'application/json',
  },
});

if (!response.ok) {
  const { error } = await response.json();
  throw new Error(`${error.type}: ${error.message}`);
}

const { data } = await response.json();

php

<?php

$handle = curl_init(getenv('CALLAGENT_API_URL') . '/knowledge-bases/01JQ0000000000000000000000/documents?limit=25');

curl_setopt_array($handle, [
    CURLOPT_CUSTOMREQUEST => 'GET',
    CURLOPT_RETURNTRANSFER => true,
    CURLOPT_HTTPHEADER => [
        'Authorization: Bearer ' . getenv('CALLAGENT_API_KEY'),
        'Accept: application/json',
    ],
]);

$body = json_decode(curl_exec($handle), true);
$status = curl_getinfo($handle, CURLINFO_HTTP_CODE);
curl_close($handle);

if ($status >= 400) {
    throw new RuntimeException("{$body['error']['type']}: {$body['error']['message']}");
}

$data = $body['data'];

python

import os, requests

response = requests.get(
    f"{os.environ['CALLAGENT_API_URL']}/knowledge-bases/01JQ0000000000000000000000/documents?limit=25",
    headers={"Authorization": f"Bearer {os.environ['CALLAGENT_API_KEY']}"},
    timeout=30,
)
response.raise_for_status()
data = response.json()["data"]

Răspunsuri

Status	Corp
`200`	Paginated set of `KnowledgeDocumentResource`

Erori

Status	Când apare
`403`	The key lacks knowledge.read
`404`	No such knowledge base in this organization

Exemplu de răspuns, generat din schemă:

json

{
  "data": [
    {
      "id": "01JQ0000000000000000000000",
      "object": "string",
      "knowledge_base_id": "01JQ0000000000000000000000",
      "title": "string",
      "source_type": "string",
      "source_url": "https://example.com/hook",
      "mime_type": "string",
      "extension": "string",
      "size_bytes": 1,
      "status": "string",
      "progress": 1,
      "failure_code": "string",
      "failure_reason": "string",
      "extracted_chars": 1,
      "chunk_count": 1,
      "token_count": 1,
      "language": "string",
      "metadata": {},
      "ingested_at": "2026-01-01T12:00:00+00:00",
      "created_at": "2026-01-01T12:00:00+00:00"
    }
  ],
  "links": {
    "first": "string",
    "last": "string",
    "prev": "string",
    "next": "string"
  },
  "meta": {
    "current_page": 1,
    "from": 1,
    "last_page": 1,
    "links": [
      {}
    ],
    "path": "string",
    "per_page": 25,
    "to": 1,
    "total": 1
  }
}

Accepts a file, URL or pasted text for ingestion and queues extraction and embedding on the queue

POST/knowledge-bases/{knowledgeBase}/documents

Necesită knowledge.write.
202, not 201: the document is accepted, not ingested. source_type (file|url|text) is required; a file upload is multipart and is size- and extension-checked.

Parametri de cale

Nume	Tip	Obligatoriu	Note
`knowledgeBase`	string	da	The knowledge base ID

Corpul cererii

Câmp	Tip	Obligatoriu	Note
`source_type`	`file` · `url` · `text`	da
`title`	string \| null	—	max 255 chars
`file`	string	—	The extension list is the one the extractor genuinely handles — accepting a PDF we cannot parse would be a silent ingestion of nothing (§188).. binary
`url`	string \| null	—	uri. max 2048 chars
`text`	string \| null	—	max 2000000 chars
`metadata`	string[] \| null	—

cURLJavaScriptPHPPython

bash

curl -X POST "$CALLAGENT_API_URL/knowledge-bases/01JQ0000000000000000000000/documents" \
  -H "Authorization: Bearer $CALLAGENT_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Accept: application/json" \
  -d '{
       "source_type": "file",
       "url": "https://example.com/hook"
     }'

const response = await fetch(`${process.env.CALLAGENT_API_URL}/knowledge-bases/01JQ0000000000000000000000/documents`, {
  method: 'POST',
  headers: {
    Authorization: `Bearer ${process.env.CALLAGENT_API_KEY}`,
    Accept: 'application/json',
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({
    "source_type": "file",
    "url": "https://example.com/hook"
  }),
});

if (!response.ok) {
  const { error } = await response.json();
  throw new Error(`${error.type}: ${error.message}`);
}

const { data } = await response.json();

php

<?php

$handle = curl_init(getenv('CALLAGENT_API_URL') . '/knowledge-bases/01JQ0000000000000000000000/documents');

curl_setopt_array($handle, [
    CURLOPT_CUSTOMREQUEST => 'POST',
    CURLOPT_RETURNTRANSFER => true,
    CURLOPT_HTTPHEADER => [
        'Authorization: Bearer ' . getenv('CALLAGENT_API_KEY'),
        'Accept: application/json',
        'Content-Type: application/json',
    ],
    CURLOPT_POSTFIELDS => json_encode([
    'source_type' => 'file',
    'url' => 'https://example.com/hook',
]),
]);

$body = json_decode(curl_exec($handle), true);
$status = curl_getinfo($handle, CURLINFO_HTTP_CODE);
curl_close($handle);

if ($status >= 400) {
    throw new RuntimeException("{$body['error']['type']}: {$body['error']['message']}");
}

$data = $body['data'];

python

import os, requests

response = requests.post(
    f"{os.environ['CALLAGENT_API_URL']}/knowledge-bases/01JQ0000000000000000000000/documents",
    headers={"Authorization": f"Bearer {os.environ['CALLAGENT_API_KEY']}"},
    json={
      "source_type": "file",
      "url": "https://example.com/hook"
    },
    timeout=30,
)
response.raise_for_status()
data = response.json()["data"]

Răspunsuri

Status	Corp
`202`	`KnowledgeDocumentResource`

Erori

Status	Când apare
`403`	The key lacks knowledge.write
`404`	No such knowledge base in this organization
`422`	Validation failed, an unsupported file type, or a URL refused by the SSRF guard

Exemplu de răspuns, generat din schemă:

json

{
  "data": {
    "id": "01JQ0000000000000000000000",
    "object": "string",
    "knowledge_base_id": "01JQ0000000000000000000000",
    "title": "string",
    "source_type": "string",
    "source_url": "https://example.com/hook",
    "mime_type": "string",
    "extension": "string",
    "size_bytes": 1,
    "status": "string",
    "progress": 1,
    "failure_code": "string",
    "failure_reason": "string",
    "extracted_chars": 1,
    "chunk_count": 1,
    "token_count": 1,
    "language": "string",
    "metadata": {},
    "ingested_at": "2026-01-01T12:00:00+00:00",
    "created_at": "2026-01-01T12:00:00+00:00"
  }
}

Returns one knowledge document with its ingestion status, progress and failure reason

GET/knowledge-bases/{knowledgeBase}/documents/{document}

Necesită knowledge.read.

Parametri de cale

Nume	Tip	Obligatoriu	Note
`knowledgeBase`	string	da	The knowledge base ID
`document`	string	da	The document ID

cURLJavaScriptPHPPython

bash

curl -X GET "$CALLAGENT_API_URL/knowledge-bases/01JQ0000000000000000000000/documents/01JQ0000000000000000000000" \
  -H "Authorization: Bearer $CALLAGENT_API_KEY" \
  -H "Accept: application/json"

const response = await fetch(`${process.env.CALLAGENT_API_URL}/knowledge-bases/01JQ0000000000000000000000/documents/01JQ0000000000000000000000`, {
  method: 'GET',
  headers: {
    Authorization: `Bearer ${process.env.CALLAGENT_API_KEY}`,
    Accept: 'application/json',
  },
});

if (!response.ok) {
  const { error } = await response.json();
  throw new Error(`${error.type}: ${error.message}`);
}

const { data } = await response.json();

php

<?php

$handle = curl_init(getenv('CALLAGENT_API_URL') . '/knowledge-bases/01JQ0000000000000000000000/documents/01JQ0000000000000000000000');

curl_setopt_array($handle, [
    CURLOPT_CUSTOMREQUEST => 'GET',
    CURLOPT_RETURNTRANSFER => true,
    CURLOPT_HTTPHEADER => [
        'Authorization: Bearer ' . getenv('CALLAGENT_API_KEY'),
        'Accept: application/json',
    ],
]);

$body = json_decode(curl_exec($handle), true);
$status = curl_getinfo($handle, CURLINFO_HTTP_CODE);
curl_close($handle);

if ($status >= 400) {
    throw new RuntimeException("{$body['error']['type']}: {$body['error']['message']}");
}

$data = $body['data'];

python

import os, requests

response = requests.get(
    f"{os.environ['CALLAGENT_API_URL']}/knowledge-bases/01JQ0000000000000000000000/documents/01JQ0000000000000000000000",
    headers={"Authorization": f"Bearer {os.environ['CALLAGENT_API_KEY']}"},
    timeout=30,
)
response.raise_for_status()
data = response.json()["data"]

Răspunsuri

Status	Corp
`200`	`KnowledgeDocumentResource`

Erori

Status	Când apare
`403`	The key lacks knowledge.read
`404`	No such knowledge base, or the document belongs to another base

Exemplu de răspuns, generat din schemă:

json

{
  "data": {
    "id": "01JQ0000000000000000000000",
    "object": "string",
    "knowledge_base_id": "01JQ0000000000000000000000",
    "title": "string",
    "source_type": "string",
    "source_url": "https://example.com/hook",
    "mime_type": "string",
    "extension": "string",
    "size_bytes": 1,
    "status": "string",
    "progress": 1,
    "failure_code": "string",
    "failure_reason": "string",
    "extracted_chars": 1,
    "chunk_count": 1,
    "token_count": 1,
    "language": "string",
    "metadata": {},
    "ingested_at": "2026-01-01T12:00:00+00:00",
    "created_at": "2026-01-01T12:00:00+00:00"
  }
}

Deletes one document, its chunks and its stored source file, and refreshes the base's counters

DELETE/knowledge-bases/{knowledgeBase}/documents/{document}

Necesită knowledge.write.
Acest răspuns nu este împachetat în data.
Body is a bare {"deleted": true, "id": "..."}. Deleting a document requires the base's update permission, not a delete permission.

Parametri de cale

Nume	Tip	Obligatoriu	Note
`knowledgeBase`	string	da	The knowledge base ID
`document`	string	da	The document ID

cURLJavaScriptPHPPython

bash

curl -X DELETE "$CALLAGENT_API_URL/knowledge-bases/01JQ0000000000000000000000/documents/01JQ0000000000000000000000" \
  -H "Authorization: Bearer $CALLAGENT_API_KEY" \
  -H "Accept: application/json"

const response = await fetch(`${process.env.CALLAGENT_API_URL}/knowledge-bases/01JQ0000000000000000000000/documents/01JQ0000000000000000000000`, {
  method: 'DELETE',
  headers: {
    Authorization: `Bearer ${process.env.CALLAGENT_API_KEY}`,
    Accept: 'application/json',
  },
});

if (!response.ok) {
  const { error } = await response.json();
  throw new Error(`${error.type}: ${error.message}`);
}

const { data } = await response.json();

php

<?php

$handle = curl_init(getenv('CALLAGENT_API_URL') . '/knowledge-bases/01JQ0000000000000000000000/documents/01JQ0000000000000000000000');

curl_setopt_array($handle, [
    CURLOPT_CUSTOMREQUEST => 'DELETE',
    CURLOPT_RETURNTRANSFER => true,
    CURLOPT_HTTPHEADER => [
        'Authorization: Bearer ' . getenv('CALLAGENT_API_KEY'),
        'Accept: application/json',
    ],
]);

$body = json_decode(curl_exec($handle), true);
$status = curl_getinfo($handle, CURLINFO_HTTP_CODE);
curl_close($handle);

if ($status >= 400) {
    throw new RuntimeException("{$body['error']['type']}: {$body['error']['message']}");
}

$data = $body['data'];

python

import os, requests

response = requests.delete(
    f"{os.environ['CALLAGENT_API_URL']}/knowledge-bases/01JQ0000000000000000000000/documents/01JQ0000000000000000000000",
    headers={"Authorization": f"Bearer {os.environ['CALLAGENT_API_KEY']}"},
    timeout=30,
)
response.raise_for_status()
data = response.json()["data"]

Răspunsuri

Status	Corp
`200`	Bare JSON object, not `data`-wrapped

Erori

Status	Când apare
`403`	The key lacks knowledge.write
`404`	No such knowledge base, or the document belongs to another base

Exemplu de răspuns, generat din schemă:

json

{
  "deleted": true,
  "id": null
}

Clears a document's chunks and failure state and re-queues it for ingestion

POST/knowledge-bases/{knowledgeBase}/documents/{document}/retry

Necesită knowledge.write.
Accepts any document in any state, not just failed ones, and destroys its existing chunks before re-queueing.

Parametri de cale

Nume	Tip	Obligatoriu	Note
`knowledgeBase`	string	da	The knowledge base ID
`document`	string	da	The document ID

cURLJavaScriptPHPPython

bash

curl -X POST "$CALLAGENT_API_URL/knowledge-bases/01JQ0000000000000000000000/documents/01JQ0000000000000000000000/retry" \
  -H "Authorization: Bearer $CALLAGENT_API_KEY" \
  -H "Accept: application/json"

const response = await fetch(`${process.env.CALLAGENT_API_URL}/knowledge-bases/01JQ0000000000000000000000/documents/01JQ0000000000000000000000/retry`, {
  method: 'POST',
  headers: {
    Authorization: `Bearer ${process.env.CALLAGENT_API_KEY}`,
    Accept: 'application/json',
  },
});

if (!response.ok) {
  const { error } = await response.json();
  throw new Error(`${error.type}: ${error.message}`);
}

const { data } = await response.json();

php

<?php

$handle = curl_init(getenv('CALLAGENT_API_URL') . '/knowledge-bases/01JQ0000000000000000000000/documents/01JQ0000000000000000000000/retry');

curl_setopt_array($handle, [
    CURLOPT_CUSTOMREQUEST => 'POST',
    CURLOPT_RETURNTRANSFER => true,
    CURLOPT_HTTPHEADER => [
        'Authorization: Bearer ' . getenv('CALLAGENT_API_KEY'),
        'Accept: application/json',
    ],
]);

$body = json_decode(curl_exec($handle), true);
$status = curl_getinfo($handle, CURLINFO_HTTP_CODE);
curl_close($handle);

if ($status >= 400) {
    throw new RuntimeException("{$body['error']['type']}: {$body['error']['message']}");
}

$data = $body['data'];

python

import os, requests

response = requests.post(
    f"{os.environ['CALLAGENT_API_URL']}/knowledge-bases/01JQ0000000000000000000000/documents/01JQ0000000000000000000000/retry",
    headers={"Authorization": f"Bearer {os.environ['CALLAGENT_API_KEY']}"},
    timeout=30,
)
response.raise_for_status()
data = response.json()["data"]

Răspunsuri

Status	Corp
`202`	`KnowledgeDocumentResource`

Erori

Status	Când apare
`403`	The key lacks knowledge.write
`404`	No such knowledge base, or the document belongs to another base

Exemplu de răspuns, generat din schemă:

json

{
  "data": {
    "id": "01JQ0000000000000000000000",
    "object": "string",
    "knowledge_base_id": "01JQ0000000000000000000000",
    "title": "string",
    "source_type": "string",
    "source_url": "https://example.com/hook",
    "mime_type": "string",
    "extension": "string",
    "size_bytes": 1,
    "status": "string",
    "progress": 1,
    "failure_code": "string",
    "failure_reason": "string",
    "extracted_chars": 1,
    "chunk_count": 1,
    "token_count": 1,
    "language": "string",
    "metadata": {},
    "ingested_at": "2026-01-01T12:00:00+00:00",
    "created_at": "2026-01-01T12:00:00+00:00"
  }
}

Runs a real hybrid retrieval query against the knowledge base and returns the matching passages

POST/knowledge-bases/{knowledgeBase}/query

Necesită knowledge.read.
Read-only despite being a POST. query is required; top_k, threshold, namespace and metadata_filters override the base's defaults for this call only.

Parametri de cale

Nume	Tip	Obligatoriu	Note
`knowledgeBase`	string	da	The knowledge base ID

Corpul cererii

Câmp	Tip	Obligatoriu	Note
`query`	string	da	max 4000 chars. min 1 chars
`top_k`	integer \| null	—	min 1. max 50
`threshold`	number \| null	—	min 0. max 1
`namespace`	string \| null	—	max 255 chars
`metadata_filters`	string[] \| null	—

cURLJavaScriptPHPPython

bash

curl -X POST "$CALLAGENT_API_URL/knowledge-bases/01JQ0000000000000000000000/query" \
  -H "Authorization: Bearer $CALLAGENT_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Accept: application/json" \
  -d '{
       "query": "string",
       "top_k": 1,
       "threshold": 1,
       "namespace": "Support Line"
     }'

const response = await fetch(`${process.env.CALLAGENT_API_URL}/knowledge-bases/01JQ0000000000000000000000/query`, {
  method: 'POST',
  headers: {
    Authorization: `Bearer ${process.env.CALLAGENT_API_KEY}`,
    Accept: 'application/json',
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({
    "query": "string",
    "top_k": 1,
    "threshold": 1,
    "namespace": "Support Line"
  }),
});

if (!response.ok) {
  const { error } = await response.json();
  throw new Error(`${error.type}: ${error.message}`);
}

const { data } = await response.json();

php

<?php

$handle = curl_init(getenv('CALLAGENT_API_URL') . '/knowledge-bases/01JQ0000000000000000000000/query');

curl_setopt_array($handle, [
    CURLOPT_CUSTOMREQUEST => 'POST',
    CURLOPT_RETURNTRANSFER => true,
    CURLOPT_HTTPHEADER => [
        'Authorization: Bearer ' . getenv('CALLAGENT_API_KEY'),
        'Accept: application/json',
        'Content-Type: application/json',
    ],
    CURLOPT_POSTFIELDS => json_encode([
    'query' => 'string',
    'top_k' => 1,
    'threshold' => 1,
    'namespace' => 'Support Line',
]),
]);

$body = json_decode(curl_exec($handle), true);
$status = curl_getinfo($handle, CURLINFO_HTTP_CODE);
curl_close($handle);

if ($status >= 400) {
    throw new RuntimeException("{$body['error']['type']}: {$body['error']['message']}");
}

$data = $body['data'];

python

import os, requests

response = requests.post(
    f"{os.environ['CALLAGENT_API_URL']}/knowledge-bases/01JQ0000000000000000000000/query",
    headers={"Authorization": f"Bearer {os.environ['CALLAGENT_API_KEY']}"},
    json={
      "query": "string",
      "top_k": 1,
      "threshold": 1,
      "namespace": "Support Line"
    },
    timeout=30,
)
response.raise_for_status()
data = response.json()["data"]

Răspunsuri

Status	Corp
`200`	`data`-wrapped object

Erori

Status	Când apare
`403`	The key lacks knowledge.read
`404`	No such knowledge base in this organization
`422`	Validation failed, the vector store is unimplemented, or retrieval/embedding failed

Exemplu de răspuns, generat din schemă:

json

{
  "data": {
    "query": "string",
    "untrusted": true,
    "top_score": 1,
    "truncated": true,
    "passages": {}
  }
}

Baze de cunoștințe ​

Endpoint-uri ​

Lists the organization's knowledge bases, newest first ​

Creates a knowledge base with its embedding, chunking and retrieval configuration ​

Returns one knowledge base with its retrieval and embedding settings ​

Updates a knowledge base, refusing an embedding model change once content has already been embedded ​

Deletes a knowledge base, every document and chunk in it, and detaches it from all assistants ​

Lists the documents in a knowledge base with their ingestion status and progress ​

Accepts a file, URL or pasted text for ingestion and queues extraction and embedding on the queue ​

Returns one knowledge document with its ingestion status, progress and failure reason ​

Deletes one document, its chunks and its stored source file, and refreshes the base's counters ​

Clears a document's chunks and failure state and re-queues it for ingestion ​

Runs a real hybrid retrieval query against the knowledge base and returns the matching passages ​

Baze de cunoștințe

Endpoint-uri

Lists the organization's knowledge bases, newest first

Creates a knowledge base with its embedding, chunking and retrieval configuration

Returns one knowledge base with its retrieval and embedding settings

Updates a knowledge base, refusing an embedding model change once content has already been embedded

Deletes a knowledge base, every document and chunk in it, and detaches it from all assistants

Lists the documents in a knowledge base with their ingestion status and progress

Accepts a file, URL or pasted text for ingestion and queues extraction and embedding on the queue

Returns one knowledge document with its ingestion status, progress and failure reason

Deletes one document, its chunks and its stored source file, and refreshes the base's counters

Clears a document's chunks and failure state and re-queues it for ingestion

Runs a real hybrid retrieval query against the knowledge base and returns the matching passages