Create chunks (batch)
curl --request POST \
--url https://api.talkpilot.io/v1/agents/{agentId}/knowledge-base/{documentId}/chunks \
--header 'Content-Type: application/json' \
--header 'X-API-Key: <api-key>' \
--data '
{
"chunks": [
{
"content": "Produkt A kostet 29,99 EUR pro Monat...",
"embedding": [
0.012,
-0.034,
0.056
],
"chunk_index": 0,
"token_count": 150,
"metadata": {
"source": "pricing-system",
"version": "2.1"
}
},
{
"content": "Produkt B kostet 49,99 EUR pro Monat...",
"embedding": [
0.023,
-0.045,
0.067
],
"chunk_index": 1,
"token_count": 120,
"metadata": {
"source": "pricing-system",
"version": "2.1"
}
}
]
}
'import requests
url = "https://api.talkpilot.io/v1/agents/{agentId}/knowledge-base/{documentId}/chunks"
payload = { "chunks": [
{
"content": "Produkt A kostet 29,99 EUR pro Monat...",
"embedding": [0.012, -0.034, 0.056],
"chunk_index": 0,
"token_count": 150,
"metadata": {
"source": "pricing-system",
"version": "2.1"
}
},
{
"content": "Produkt B kostet 49,99 EUR pro Monat...",
"embedding": [0.023, -0.045, 0.067],
"chunk_index": 1,
"token_count": 120,
"metadata": {
"source": "pricing-system",
"version": "2.1"
}
}
] }
headers = {
"X-API-Key": "<api-key>",
"Content-Type": "application/json"
}
response = requests.post(url, json=payload, headers=headers)
print(response.text)const options = {
method: 'POST',
headers: {'X-API-Key': '<api-key>', 'Content-Type': 'application/json'},
body: JSON.stringify({
chunks: [
{
content: 'Produkt A kostet 29,99 EUR pro Monat...',
embedding: [0.012, -0.034, 0.056],
chunk_index: 0,
token_count: 150,
metadata: {source: 'pricing-system', version: '2.1'}
},
{
content: 'Produkt B kostet 49,99 EUR pro Monat...',
embedding: [0.023, -0.045, 0.067],
chunk_index: 1,
token_count: 120,
metadata: {source: 'pricing-system', version: '2.1'}
}
]
})
};
fetch('https://api.talkpilot.io/v1/agents/{agentId}/knowledge-base/{documentId}/chunks', options)
.then(res => res.json())
.then(res => console.log(res))
.catch(err => console.error(err));<?php
$curl = curl_init();
curl_setopt_array($curl, [
CURLOPT_URL => "https://api.talkpilot.io/v1/agents/{agentId}/knowledge-base/{documentId}/chunks",
CURLOPT_RETURNTRANSFER => true,
CURLOPT_ENCODING => "",
CURLOPT_MAXREDIRS => 10,
CURLOPT_TIMEOUT => 30,
CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
CURLOPT_CUSTOMREQUEST => "POST",
CURLOPT_POSTFIELDS => json_encode([
'chunks' => [
[
'content' => 'Produkt A kostet 29,99 EUR pro Monat...',
'embedding' => [
0.012,
-0.034,
0.056
],
'chunk_index' => 0,
'token_count' => 150,
'metadata' => [
'source' => 'pricing-system',
'version' => '2.1'
]
],
[
'content' => 'Produkt B kostet 49,99 EUR pro Monat...',
'embedding' => [
0.023,
-0.045,
0.067
],
'chunk_index' => 1,
'token_count' => 120,
'metadata' => [
'source' => 'pricing-system',
'version' => '2.1'
]
]
]
]),
CURLOPT_HTTPHEADER => [
"Content-Type: application/json",
"X-API-Key: <api-key>"
],
]);
$response = curl_exec($curl);
$err = curl_error($curl);
curl_close($curl);
if ($err) {
echo "cURL Error #:" . $err;
} else {
echo $response;
}package main
import (
"fmt"
"strings"
"net/http"
"io"
)
func main() {
url := "https://api.talkpilot.io/v1/agents/{agentId}/knowledge-base/{documentId}/chunks"
payload := strings.NewReader("{\n \"chunks\": [\n {\n \"content\": \"Produkt A kostet 29,99 EUR pro Monat...\",\n \"embedding\": [\n 0.012,\n -0.034,\n 0.056\n ],\n \"chunk_index\": 0,\n \"token_count\": 150,\n \"metadata\": {\n \"source\": \"pricing-system\",\n \"version\": \"2.1\"\n }\n },\n {\n \"content\": \"Produkt B kostet 49,99 EUR pro Monat...\",\n \"embedding\": [\n 0.023,\n -0.045,\n 0.067\n ],\n \"chunk_index\": 1,\n \"token_count\": 120,\n \"metadata\": {\n \"source\": \"pricing-system\",\n \"version\": \"2.1\"\n }\n }\n ]\n}")
req, _ := http.NewRequest("POST", url, payload)
req.Header.Add("X-API-Key", "<api-key>")
req.Header.Add("Content-Type", "application/json")
res, _ := http.DefaultClient.Do(req)
defer res.Body.Close()
body, _ := io.ReadAll(res.Body)
fmt.Println(string(body))
}HttpResponse<String> response = Unirest.post("https://api.talkpilot.io/v1/agents/{agentId}/knowledge-base/{documentId}/chunks")
.header("X-API-Key", "<api-key>")
.header("Content-Type", "application/json")
.body("{\n \"chunks\": [\n {\n \"content\": \"Produkt A kostet 29,99 EUR pro Monat...\",\n \"embedding\": [\n 0.012,\n -0.034,\n 0.056\n ],\n \"chunk_index\": 0,\n \"token_count\": 150,\n \"metadata\": {\n \"source\": \"pricing-system\",\n \"version\": \"2.1\"\n }\n },\n {\n \"content\": \"Produkt B kostet 49,99 EUR pro Monat...\",\n \"embedding\": [\n 0.023,\n -0.045,\n 0.067\n ],\n \"chunk_index\": 1,\n \"token_count\": 120,\n \"metadata\": {\n \"source\": \"pricing-system\",\n \"version\": \"2.1\"\n }\n }\n ]\n}")
.asString();require 'uri'
require 'net/http'
url = URI("https://api.talkpilot.io/v1/agents/{agentId}/knowledge-base/{documentId}/chunks")
http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true
request = Net::HTTP::Post.new(url)
request["X-API-Key"] = '<api-key>'
request["Content-Type"] = 'application/json'
request.body = "{\n \"chunks\": [\n {\n \"content\": \"Produkt A kostet 29,99 EUR pro Monat...\",\n \"embedding\": [\n 0.012,\n -0.034,\n 0.056\n ],\n \"chunk_index\": 0,\n \"token_count\": 150,\n \"metadata\": {\n \"source\": \"pricing-system\",\n \"version\": \"2.1\"\n }\n },\n {\n \"content\": \"Produkt B kostet 49,99 EUR pro Monat...\",\n \"embedding\": [\n 0.023,\n -0.045,\n 0.067\n ],\n \"chunk_index\": 1,\n \"token_count\": 120,\n \"metadata\": {\n \"source\": \"pricing-system\",\n \"version\": \"2.1\"\n }\n }\n ]\n}"
response = http.request(request)
puts response.read_body{
"data": [
{
"id": "chunk-uuid-1",
"document_id": "doc-uuid-1",
"agent_id": "550e8400-e29b-41d4-a716-446655440000",
"content": "Produkt A kostet 29,99 EUR...",
"chunk_index": 0,
"token_count": 150,
"metadata": {
"source": "pricing-system"
},
"created_at": "2026-04-27T10:00:00Z"
}
],
"inserted_count": 2
}Knowledge Base
Create chunks (batch)
Insert one or more pre-processed chunks for a document. Use this when your external system handles its own text splitting and embedding generation. Embeddings are write-only: they are never returned by the read endpoints.
The embedding field expects a 1536-dimensional vector compatible with
OpenAI’s text-embedding-3-small model. Chunks without embeddings will not
appear in vector search results during calls.
Access is scoped to your organization — you can only write chunks for agents that belong to an organization you are a member of.
POST
/
v1
/
agents
/
{agentId}
/
knowledge-base
/
{documentId}
/
chunks
Create chunks (batch)
curl --request POST \
--url https://api.talkpilot.io/v1/agents/{agentId}/knowledge-base/{documentId}/chunks \
--header 'Content-Type: application/json' \
--header 'X-API-Key: <api-key>' \
--data '
{
"chunks": [
{
"content": "Produkt A kostet 29,99 EUR pro Monat...",
"embedding": [
0.012,
-0.034,
0.056
],
"chunk_index": 0,
"token_count": 150,
"metadata": {
"source": "pricing-system",
"version": "2.1"
}
},
{
"content": "Produkt B kostet 49,99 EUR pro Monat...",
"embedding": [
0.023,
-0.045,
0.067
],
"chunk_index": 1,
"token_count": 120,
"metadata": {
"source": "pricing-system",
"version": "2.1"
}
}
]
}
'import requests
url = "https://api.talkpilot.io/v1/agents/{agentId}/knowledge-base/{documentId}/chunks"
payload = { "chunks": [
{
"content": "Produkt A kostet 29,99 EUR pro Monat...",
"embedding": [0.012, -0.034, 0.056],
"chunk_index": 0,
"token_count": 150,
"metadata": {
"source": "pricing-system",
"version": "2.1"
}
},
{
"content": "Produkt B kostet 49,99 EUR pro Monat...",
"embedding": [0.023, -0.045, 0.067],
"chunk_index": 1,
"token_count": 120,
"metadata": {
"source": "pricing-system",
"version": "2.1"
}
}
] }
headers = {
"X-API-Key": "<api-key>",
"Content-Type": "application/json"
}
response = requests.post(url, json=payload, headers=headers)
print(response.text)const options = {
method: 'POST',
headers: {'X-API-Key': '<api-key>', 'Content-Type': 'application/json'},
body: JSON.stringify({
chunks: [
{
content: 'Produkt A kostet 29,99 EUR pro Monat...',
embedding: [0.012, -0.034, 0.056],
chunk_index: 0,
token_count: 150,
metadata: {source: 'pricing-system', version: '2.1'}
},
{
content: 'Produkt B kostet 49,99 EUR pro Monat...',
embedding: [0.023, -0.045, 0.067],
chunk_index: 1,
token_count: 120,
metadata: {source: 'pricing-system', version: '2.1'}
}
]
})
};
fetch('https://api.talkpilot.io/v1/agents/{agentId}/knowledge-base/{documentId}/chunks', options)
.then(res => res.json())
.then(res => console.log(res))
.catch(err => console.error(err));<?php
$curl = curl_init();
curl_setopt_array($curl, [
CURLOPT_URL => "https://api.talkpilot.io/v1/agents/{agentId}/knowledge-base/{documentId}/chunks",
CURLOPT_RETURNTRANSFER => true,
CURLOPT_ENCODING => "",
CURLOPT_MAXREDIRS => 10,
CURLOPT_TIMEOUT => 30,
CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
CURLOPT_CUSTOMREQUEST => "POST",
CURLOPT_POSTFIELDS => json_encode([
'chunks' => [
[
'content' => 'Produkt A kostet 29,99 EUR pro Monat...',
'embedding' => [
0.012,
-0.034,
0.056
],
'chunk_index' => 0,
'token_count' => 150,
'metadata' => [
'source' => 'pricing-system',
'version' => '2.1'
]
],
[
'content' => 'Produkt B kostet 49,99 EUR pro Monat...',
'embedding' => [
0.023,
-0.045,
0.067
],
'chunk_index' => 1,
'token_count' => 120,
'metadata' => [
'source' => 'pricing-system',
'version' => '2.1'
]
]
]
]),
CURLOPT_HTTPHEADER => [
"Content-Type: application/json",
"X-API-Key: <api-key>"
],
]);
$response = curl_exec($curl);
$err = curl_error($curl);
curl_close($curl);
if ($err) {
echo "cURL Error #:" . $err;
} else {
echo $response;
}package main
import (
"fmt"
"strings"
"net/http"
"io"
)
func main() {
url := "https://api.talkpilot.io/v1/agents/{agentId}/knowledge-base/{documentId}/chunks"
payload := strings.NewReader("{\n \"chunks\": [\n {\n \"content\": \"Produkt A kostet 29,99 EUR pro Monat...\",\n \"embedding\": [\n 0.012,\n -0.034,\n 0.056\n ],\n \"chunk_index\": 0,\n \"token_count\": 150,\n \"metadata\": {\n \"source\": \"pricing-system\",\n \"version\": \"2.1\"\n }\n },\n {\n \"content\": \"Produkt B kostet 49,99 EUR pro Monat...\",\n \"embedding\": [\n 0.023,\n -0.045,\n 0.067\n ],\n \"chunk_index\": 1,\n \"token_count\": 120,\n \"metadata\": {\n \"source\": \"pricing-system\",\n \"version\": \"2.1\"\n }\n }\n ]\n}")
req, _ := http.NewRequest("POST", url, payload)
req.Header.Add("X-API-Key", "<api-key>")
req.Header.Add("Content-Type", "application/json")
res, _ := http.DefaultClient.Do(req)
defer res.Body.Close()
body, _ := io.ReadAll(res.Body)
fmt.Println(string(body))
}HttpResponse<String> response = Unirest.post("https://api.talkpilot.io/v1/agents/{agentId}/knowledge-base/{documentId}/chunks")
.header("X-API-Key", "<api-key>")
.header("Content-Type", "application/json")
.body("{\n \"chunks\": [\n {\n \"content\": \"Produkt A kostet 29,99 EUR pro Monat...\",\n \"embedding\": [\n 0.012,\n -0.034,\n 0.056\n ],\n \"chunk_index\": 0,\n \"token_count\": 150,\n \"metadata\": {\n \"source\": \"pricing-system\",\n \"version\": \"2.1\"\n }\n },\n {\n \"content\": \"Produkt B kostet 49,99 EUR pro Monat...\",\n \"embedding\": [\n 0.023,\n -0.045,\n 0.067\n ],\n \"chunk_index\": 1,\n \"token_count\": 120,\n \"metadata\": {\n \"source\": \"pricing-system\",\n \"version\": \"2.1\"\n }\n }\n ]\n}")
.asString();require 'uri'
require 'net/http'
url = URI("https://api.talkpilot.io/v1/agents/{agentId}/knowledge-base/{documentId}/chunks")
http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true
request = Net::HTTP::Post.new(url)
request["X-API-Key"] = '<api-key>'
request["Content-Type"] = 'application/json'
request.body = "{\n \"chunks\": [\n {\n \"content\": \"Produkt A kostet 29,99 EUR pro Monat...\",\n \"embedding\": [\n 0.012,\n -0.034,\n 0.056\n ],\n \"chunk_index\": 0,\n \"token_count\": 150,\n \"metadata\": {\n \"source\": \"pricing-system\",\n \"version\": \"2.1\"\n }\n },\n {\n \"content\": \"Produkt B kostet 49,99 EUR pro Monat...\",\n \"embedding\": [\n 0.023,\n -0.045,\n 0.067\n ],\n \"chunk_index\": 1,\n \"token_count\": 120,\n \"metadata\": {\n \"source\": \"pricing-system\",\n \"version\": \"2.1\"\n }\n }\n ]\n}"
response = http.request(request)
puts response.read_body{
"data": [
{
"id": "chunk-uuid-1",
"document_id": "doc-uuid-1",
"agent_id": "550e8400-e29b-41d4-a716-446655440000",
"content": "Produkt A kostet 29,99 EUR...",
"chunk_index": 0,
"token_count": 150,
"metadata": {
"source": "pricing-system"
},
"created_at": "2026-04-27T10:00:00Z"
}
],
"inserted_count": 2
}Authorizations
API key for external access. Format: tp_live_<32-hex-chars>.
Create keys in the TalkPilot Dashboard under Settings > API.
Path Parameters
Agent UUID
Knowledge base document UUID
Body
application/json
Array of chunks to insert (max 100 per request)
Required array length:
1 - 100 elementsShow child attributes
Show child attributes