Knowledge bases

11 endpoints. Every path below is relative to the API base URL and already includes the /api/v1 prefix — see conventions for authentication, pagination, errors and idempotency.

	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

Endpoints

Lists the organization's knowledge bases, newest first

GET/knowledge-bases

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

Query parameters

Name	Type	Required	Notes
`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"]

Responses

Status	Body
`200`	Paginated set of `KnowledgeBaseResource`

Errors

Status	When it happens
`403`	The key lacks knowledge.read

Example response, generated from the schema:

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

Requires knowledge.write.

Request body

Field	Type	Required	Notes
`name`	string	yes	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"]

Responses

Status	Body
`201`	`KnowledgeBaseResource`

Errors

Status	When it happens
`403`	The key lacks knowledge.write
`422`	Validation failed

Example response, generated from the schema:

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}

Requires knowledge.read.

Path parameters

Name	Type	Required	Notes
`knowledgeBase`	string	yes	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"]

Responses

Status	Body
`200`	`KnowledgeBaseResource`

Errors

Status	When it happens
`403`	The key lacks knowledge.read
`404`	No such knowledge base in this organization

Example response, generated from the schema:

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}

Requires knowledge.write.
PATCH is accepted on the same path, with the same body.
Changing embedding_model on a base with stored chunks is a 422: create a new knowledge base instead.

Path parameters

Name	Type	Required	Notes
`knowledgeBase`	string	yes	The knowledge base ID

Request body

Field	Type	Required	Notes
`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"]

Responses

Status	Body
`200`	`KnowledgeBaseResource`

Errors

Status	When it happens
`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

Example response, generated from the schema:

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}

Requires knowledge.write.
This response is not data-wrapped.
Body is a bare {"deleted": true, "id": "..."}. Side effects: stored source files are removed from disk and assistants are detached.

Path parameters

Name	Type	Required	Notes
`knowledgeBase`	string	yes	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"]

Responses

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

Errors

Status	When it happens
`403`	The key lacks knowledge.write
`404`	No such knowledge base in this organization

Example response, generated from the schema:

json

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

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

GET/knowledge-bases/{knowledgeBase}/documents

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

Path parameters

Name	Type	Required	Notes
`knowledgeBase`	string	yes	The knowledge base ID

Query parameters

Name	Type	Required	Notes
`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"]

Responses

Status	Body
`200`	Paginated set of `KnowledgeDocumentResource`

Errors

Status	When it happens
`403`	The key lacks knowledge.read
`404`	No such knowledge base in this organization

Example response, generated from the schema:

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

Requires 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.

Path parameters

Name	Type	Required	Notes
`knowledgeBase`	string	yes	The knowledge base ID

Request body

Field	Type	Required	Notes
`source_type`	`file` · `url` · `text`	yes
`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"]

Responses

Status	Body
`202`	`KnowledgeDocumentResource`

Errors

Status	When it happens
`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

Example response, generated from the schema:

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}

Requires knowledge.read.

Path parameters

Name	Type	Required	Notes
`knowledgeBase`	string	yes	The knowledge base ID
`document`	string	yes	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"]

Responses

Status	Body
`200`	`KnowledgeDocumentResource`

Errors

Status	When it happens
`403`	The key lacks knowledge.read
`404`	No such knowledge base, or the document belongs to another base

Example response, generated from the schema:

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}

Requires knowledge.write.
This response is not data-wrapped.
Body is a bare {"deleted": true, "id": "..."}. Deleting a document requires the base's update permission, not a delete permission.

Path parameters

Name	Type	Required	Notes
`knowledgeBase`	string	yes	The knowledge base ID
`document`	string	yes	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"]

Responses

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

Errors

Status	When it happens
`403`	The key lacks knowledge.write
`404`	No such knowledge base, or the document belongs to another base

Example response, generated from the schema:

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

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

Path parameters

Name	Type	Required	Notes
`knowledgeBase`	string	yes	The knowledge base ID
`document`	string	yes	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"]

Responses

Status	Body
`202`	`KnowledgeDocumentResource`

Errors

Status	When it happens
`403`	The key lacks knowledge.write
`404`	No such knowledge base, or the document belongs to another base

Example response, generated from the schema:

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

Requires 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.

Path parameters

Name	Type	Required	Notes
`knowledgeBase`	string	yes	The knowledge base ID

Request body

Field	Type	Required	Notes
`query`	string	yes	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"]

Responses

Status	Body
`200`	`data`-wrapped object

Errors

Status	When it happens
`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

Example response, generated from the schema:

json

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

Knowledge bases ​

Endpoints ​

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 ​

Knowledge bases

Endpoints

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