API Reference
Knowledge API
Add the documents, text and web pages an agent answers from.
An agent's knowledge is the set of sources it searches before it answers: pasted text (prices, policies, FAQs), public web pages (one page, or a crawl of the same site) and files (PDF, Word, HTML, CSV, TXT, Markdown). A new source is stored at once, then read, chunked and embedded in the background: the agent answers from it once its status is ready. Keys need knowledge:read or knowledge:write.
Changes run as the key's creator
Adding, re-reading and removing sources apply the dashboard's rules as the member who created the API key: their role must allow editing agents (owners, admins and builders), and a key whose creator has left the workspace is refused. Files go in one request (about 4 MB through the API); larger documents are uploaded in the dashboard.
Endpoints
/v1/agents/:id/knowledgeList an agent's knowledgePOST/v1/agents/:id/knowledgeAdd a knowledge sourceGET/v1/agents/:id/knowledge/:source_idGet a knowledge sourceDELETE/v1/agents/:id/knowledge/:source_idRemove a knowledge sourcePOST/v1/agents/:id/knowledge/:source_id/reingestRead a knowledge source againList an agent's knowledge
/v1/agents/:id/knowledgeLists the documents, pasted texts and web pages the agent answers from, newest first, with each one's status and size in chunks.
knowledge:readstatus: pending until the source is read, processing while it is chunked and embedded, ready when the agent answers from it, error when it could not be read (error says why). A source read again keeps answering from its previous version until the new one is ready.
Path parameters
| Name | Type | Description |
|---|---|---|
idRequired | uuid | The agent id. |
Query parameters
| Name | Type | Description |
|---|---|---|
limit | integer | Results per page. 1–100. Default: |
offset | integer | Results to skip. At least 0. Default: |
kind | string | Only sources of this kind. One of: file, text, url. |
status | string | Only sources in this status. One of: pending, processing, ready, error. |
Example request
curl -X GET "https://www.nutalk.ai/v1/agents/550e8400-e29b-41d4-a716-446655440000/knowledge?status=ready" \ -H "Authorization: Bearer YOUR_API_KEY"A page of knowledge sources.
{
"success": true,
"data": [
{
"id": "7d8e9f0a-1b2c-4d3e-8f4a-5b6c7d8e9f0a",
"agent_id": "550e8400-e29b-41d4-a716-446655440000",
"kind": "url",
"title": "Prices and services",
"status": "ready",
"chunk_count": 42,
"error": null,
"url": "https://clinic.example.com/prices",
"crawl": true,
"max_pages": 25,
"warnings": [],
"ingested_at": "2026-10-12T18:10:42.318Z",
"created_at": "2026-10-12T18:10:31.904211+00:00",
"updated_at": "2026-10-12T18:10:42.318+00:00"
}
],
"pagination": {
"total": 1,
"limit": 20,
"offset": 0,
"has_more": false
}
}Errors
| Status | Code | When |
|---|---|---|
| 400 | validation_error | A query parameter is invalid (details.errors lists each one). |
| 404 | not_found | No agent with this id in your workspace (ids of other workspaces answer the same). |
Plus the errors every request can return (401, 403, 429, 500): Errors.
Add a knowledge source
/v1/agents/:id/knowledgeAdds a source the agent answers from: pasted text (kind: text) or a public web page (kind: url, optionally crawling the same site's linked pages) as JSON, or a file as multipart/form-data with the file in the file field (PDF, Word .docx, HTML, CSV, TXT or Markdown; the whole request at most 4 MB, larger files are added in the dashboard). The source is stored at once, then read, chunked and embedded in the background: follow its status with GET.
knowledge:writeWorkspace keys only · acts as the key's creatorFile uploads go in one request, so the request's size limit applies (about 4 MB through the API); larger documents are uploaded in the dashboard.
The change runs the dashboard's knowledge rules as the member who created the key: the key needs the scope and that member a role that edits agents (owner, admin or builder). A key whose creator has left the workspace, and a reseller key, are refused.
Path parameters
| Name | Type | Description |
|---|---|---|
idRequired | uuid | The agent id. |
Request body (JSON)
| Name | Type | Description |
|---|---|---|
kindRequired | string |
|
title | string | The source's title. Required for |
text | string |
|
url | string |
|
crawl | boolean |
Default: |
max_pages | integer |
Default: |
Example request
curl -X POST "https://www.nutalk.ai/v1/agents/550e8400-e29b-41d4-a716-446655440000/knowledge" \ -H "Authorization: Bearer YOUR_API_KEY" \ -H "Content-Type: application/json" \ -d '{ "kind": "url", "url": "https://clinic.example.com/prices", "title": "Prices and services", "crawl": true, "max_pages": 25}'The source, pending. ingest_started is false when reading it could not be started now: it is retried within 30 minutes.
{
"success": true,
"data": {
"id": "7d8e9f0a-1b2c-4d3e-8f4a-5b6c7d8e9f0a",
"agent_id": "550e8400-e29b-41d4-a716-446655440000",
"kind": "url",
"title": "Prices and services",
"status": "pending",
"chunk_count": 0,
"error": null,
"url": "https://clinic.example.com/prices",
"crawl": true,
"max_pages": 25,
"warnings": [],
"ingested_at": null,
"created_at": "2026-10-12T18:10:31.904211+00:00",
"updated_at": "2026-10-12T18:10:31.904211+00:00",
"ingest_started": true
}
}Errors
| Status | Code | When |
|---|---|---|
| 400 | validation_error | The body is not JSON, or a field is missing or invalid (details.errors lists each field). |
| 400 | validation_error | The URL is not http(s) or points to a private network, or the file is missing, empty, too large or of another type (details.reason). |
| 403 | forbidden | The member who created the key has a role that can't edit agents or has left the workspace, or the key is a reseller key. |
| 404 | not_found | No agent with this id in your workspace (ids of other workspaces answer the same). |
Plus the errors every request can return (401, 403, 429, 500): Errors.
Get a knowledge source
/v1/agents/:id/knowledge/:source_idReturns one knowledge source of the agent, with its status, its error and its warnings.
knowledge:readstatus: pending until the source is read, processing while it is chunked and embedded, ready when the agent answers from it, error when it could not be read (error says why). A source read again keeps answering from its previous version until the new one is ready.
Path parameters
| Name | Type | Description |
|---|---|---|
idRequired | uuid | The agent id. |
source_idRequired | uuid | The knowledge source id. |
Example request
curl -X GET "https://www.nutalk.ai/v1/agents/550e8400-e29b-41d4-a716-446655440000/knowledge/1f2e3d4c-5b6a-4978-8a9b-0c1d2e3f4a5b" \ -H "Authorization: Bearer YOUR_API_KEY"The knowledge source.
{
"success": true,
"data": {
"id": "7d8e9f0a-1b2c-4d3e-8f4a-5b6c7d8e9f0a",
"agent_id": "550e8400-e29b-41d4-a716-446655440000",
"kind": "url",
"title": "Prices and services",
"status": "ready",
"chunk_count": 42,
"error": null,
"url": "https://clinic.example.com/prices",
"crawl": true,
"max_pages": 25,
"warnings": [],
"ingested_at": "2026-10-12T18:10:42.318Z",
"created_at": "2026-10-12T18:10:31.904211+00:00",
"updated_at": "2026-10-12T18:10:42.318+00:00"
}
}Errors
| Status | Code | When |
|---|---|---|
| 404 | not_found | No agent with this id in your workspace (ids of other workspaces answer the same). |
| 404 | not_found | No knowledge source with this id in your workspace (ids of other workspaces answer the same). |
Plus the errors every request can return (401, 403, 429, 500): Errors.
Remove a knowledge source
/v1/agents/:id/knowledge/:source_idRemoves the source, its stored file or text and its chunks: the agent stops answering from it at once.
knowledge:writeCan wait for approvalWorkspace keys only · acts as the key's creatorThe change runs the dashboard's knowledge rules as the member who created the key: the key needs the scope and that member a role that edits agents (owner, admin or builder). A key whose creator has left the workspace, and a reseller key, are refused.
Path parameters
| Name | Type | Description |
|---|---|---|
idRequired | uuid | The agent id. |
source_idRequired | uuid | The knowledge source id. |
Example request
curl -X DELETE "https://www.nutalk.ai/v1/agents/550e8400-e29b-41d4-a716-446655440000/knowledge/1f2e3d4c-5b6a-4978-8a9b-0c1d2e3f4a5b" \ -H "Authorization: Bearer YOUR_API_KEY"The source was removed.
{
"success": true,
"data": {
"id": "7d8e9f0a-1b2c-4d3e-8f4a-5b6c7d8e9f0a",
"deleted": true
}
}Errors
| Status | Code | When |
|---|---|---|
| 403 | forbidden | The member who created the key has a role that can't edit agents or has left the workspace, or the key is a reseller key. |
| 404 | not_found | No agent with this id in your workspace (ids of other workspaces answer the same). |
| 404 | not_found | No knowledge source with this id in your workspace (ids of other workspaces answer the same). |
Plus the errors every request can return (401, 403, 429, 500): Errors.
Read a knowledge source again
/v1/agents/:id/knowledge/:source_id/reingestReads the source again in the background: a web page is fetched anew, a file or text re-read with the agent's current document search settings. The agent keeps answering from the version it has until the new one is ready.
knowledge:writeCan wait for approvalWorkspace keys only · acts as the key's creatorThe change runs the dashboard's knowledge rules as the member who created the key: the key needs the scope and that member a role that edits agents (owner, admin or builder). A key whose creator has left the workspace, and a reseller key, are refused.
Path parameters
| Name | Type | Description |
|---|---|---|
idRequired | uuid | The agent id. |
source_idRequired | uuid | The knowledge source id. |
Example request
curl -X POST "https://www.nutalk.ai/v1/agents/550e8400-e29b-41d4-a716-446655440000/knowledge/1f2e3d4c-5b6a-4978-8a9b-0c1d2e3f4a5b/reingest" \ -H "Authorization: Bearer YOUR_API_KEY"The source, back to pending.
{
"success": true,
"data": {
"id": "7d8e9f0a-1b2c-4d3e-8f4a-5b6c7d8e9f0a",
"agent_id": "550e8400-e29b-41d4-a716-446655440000",
"kind": "url",
"title": "Prices and services",
"status": "pending",
"chunk_count": 42,
"error": null,
"url": "https://clinic.example.com/prices",
"crawl": true,
"max_pages": 25,
"warnings": [],
"ingested_at": "2026-10-12T18:10:42.318Z",
"created_at": "2026-10-12T18:10:31.904211+00:00",
"updated_at": "2026-10-12T18:10:42.318+00:00",
"ingest_started": true
}
}Errors
| Status | Code | When |
|---|---|---|
| 403 | forbidden | The member who created the key has a role that can't edit agents or has left the workspace, or the key is a reseller key. |
| 404 | not_found | No agent with this id in your workspace (ids of other workspaces answer the same). |
| 404 | not_found | No knowledge source with this id in your workspace (ids of other workspaces answer the same). |
Plus the errors every request can return (401, 403, 429, 500): Errors.