Knowledge
The sources an agent answers from: websites, FAQs, documents and cloud files. Changes run in the background as an operation; follow it with GET /v1/operations/{operation_id} or the knowledge.operation.completed webhook.
- GET
/v1/agents/{agent_id}/knowledgeList knowledge sources - GET
/v1/agents/{agent_id}/knowledge/{knowledge_id}A knowledge source with content - POST
/v1/agents/{agent_id}/knowledgeAdd a source - POST
/v1/agents/{agent_id}/knowledge/uploadsPrepare a file upload - PUT
/v1/agents/{agent_id}/knowledge/{knowledge_id}Change an FAQ or replace a document - DELETE
/v1/agents/{agent_id}/knowledge/{knowledge_id}Delete a source - POST
/v1/agents/{agent_id}/knowledge/refreshRead sources again - GET
/v1/operations/{operation_id}State of a long operation
List knowledge sources
GET/v1/agents/{agent_id}/knowledge
URLs, files, FAQs and cloud sources with status and revision.
Parameters
| Parameter | Type | Description |
|---|---|---|
agent_idrequired | stringpath | The agent's id, from GET /v1/agents. |
limit | integerquery | Items per page. Default 25. 1 to 100. |
after | stringquery | The next_cursor of the previous page. Up to 20 characters. |
source_type | stringquery | Only sources of this type: website, faq, document, google_drive, onedrive or notion. Up to 40 characters. |
q | stringquery | Only sources whose file name, description, address or text contains this, ignoring case. Up to 200 characters. |
status | stringquery | Only sources in this state. One of completed, failed, scraping, deleting. |
Response 200 OK
| Field | Type | Description |
|---|---|---|
data | array of objects | The items on this page. |
data[].can_refresh | boolean or null | true for websites and cloud files, which Read sources again imports anew. |
data[].content_length | integer or null | Length of the stored text in characters. |
data[].created_at | string or null | When it was created, in UTC (ISO 8601). |
data[].description | string or null | Short description; for an FAQ its question. |
data[].document_name | string or null | File name of an uploaded document. |
data[].download_url | string or null | Link to the original file when it is downloadable. |
data[].downloadable | boolean or null | true when the original file can be downloaded. |
data[].failure_code | string or null | Why the import failed, as a code. |
data[].failure_reason | string or null | Why the import failed, in words. |
data[].id | integer | Id of the knowledge source. |
data[].revision | string | Pass it as expected_revision when you change, refresh or delete the source. |
data[].source_type | string or null | website, faq, document or a cloud source. |
data[].status | string | completed, failed, scraping or deleting. |
data[].title | string or null | Title of the source. |
data[].type | string | Stored type, e.g. faq, url_link, document. |
data[].url | string or null | Address of a website source. |
next_cursor | string or null | Pass it as after to get the next page. null on the last page. |
object | string | Always list. |
Example request
curl "https://api.ultimo-bots.com/v1/agents/c3e02486-f107-40c4-ac4d-e6155111bc8e/knowledge" \
-H "Authorization: Bearer $ULTIMO_API_KEY"import os, requests
r = requests.get(
"https://api.ultimo-bots.com/v1/agents/c3e02486-f107-40c4-ac4d-e6155111bc8e/knowledge",
headers={"Authorization": f"Bearer {os.environ['ULTIMO_API_KEY']}"},
timeout=30,
)
print(r.status_code, r.json())const res = await fetch("https://api.ultimo-bots.com/v1/agents/c3e02486-f107-40c4-ac4d-e6155111bc8e/knowledge", {
headers: {
Authorization: `Bearer ${process.env.ULTIMO_API_KEY}`
}
});
console.log(res.status, await res.json());Response 200 OK
{
"data": [
{
"can_refresh": false,
"content_length": 21,
"created_at": "2026-11-10T17:00:49.169767",
"description": "Is parking free?",
"document_name": null,
"download_url": null,
"downloadable": false,
"failure_code": null,
"failure_reason": null,
"id": 226064,
"revision": "2",
"source_type": "faq",
"status": "completed",
"title": "Is parking free?",
"type": "faq",
"url": null
}
],
"next_cursor": null,
"object": "list"
}Errors: 400, 401, 403, 404, 422, 429, 500, 503. What each code means: Error codes.
A knowledge source with content
GET/v1/agents/{agent_id}/knowledge/{knowledge_id}
The content in pages of up to 16000 characters (next_offset).
Parameters
| Parameter | Type | Description |
|---|---|---|
agent_idrequired | stringpath | The agent's id, from GET /v1/agents. |
knowledge_idrequired | integerpath | Id of the knowledge source. |
offset | integerquery | Character to start from. Use next_offset of the previous page. Default 0. |
max_chars | integerquery | Characters per page. Default 8000. 1 to 16000. |
Response 200 OK
| Field | Type | Description |
|---|---|---|
can_refresh | boolean or null | true for websites and cloud files, which Read sources again imports anew. |
content | string or null | The text of the source, from content_offset on. |
content_length | integer or null | Length of the whole stored text in characters. |
content_offset | integer | Character where content starts. Default 0. |
created_at | string or null | When it was created, in UTC (ISO 8601). |
description | string or null | Short description; for an FAQ its question. |
document_name | string or null | File name of an uploaded document. |
download_url | string or null | Link to the original file when it is downloadable. |
downloadable | boolean or null | true when the original file can be downloaded. |
failure_code | string or null | Why the import failed, as a code. |
failure_reason | string or null | Why the import failed, in words. |
id | integer | Id of the knowledge source. |
next_offset | integer or null | Offset of the next page, null at the end. |
revision | string | Pass it as expected_revision when you change, refresh or delete the source. |
source_type | string or null | website, faq, document or a cloud source. |
status | string | completed, failed, scraping or deleting. |
title | string or null | Title of the source. |
type | string | Stored type, e.g. faq, url_link, document. |
url | string or null | Address of a website source. |
Example request
curl "https://api.ultimo-bots.com/v1/agents/c3e02486-f107-40c4-ac4d-e6155111bc8e/knowledge/226064" \
-H "Authorization: Bearer $ULTIMO_API_KEY"import os, requests
r = requests.get(
"https://api.ultimo-bots.com/v1/agents/c3e02486-f107-40c4-ac4d-e6155111bc8e/knowledge/226064",
headers={"Authorization": f"Bearer {os.environ['ULTIMO_API_KEY']}"},
timeout=30,
)
print(r.status_code, r.json())const res = await fetch("https://api.ultimo-bots.com/v1/agents/c3e02486-f107-40c4-ac4d-e6155111bc8e/knowledge/226064", {
headers: {
Authorization: `Bearer ${process.env.ULTIMO_API_KEY}`
}
});
console.log(res.status, await res.json());Response 200 OK
{
"can_refresh": false,
"content": "Yes, parking is free.",
"content_length": 21,
"content_offset": 0,
"created_at": "2026-11-10T17:00:49.169767",
"description": "Is parking free?",
"document_name": null,
"download_url": null,
"downloadable": false,
"failure_code": null,
"failure_reason": null,
"id": 226064,
"next_offset": null,
"revision": "2",
"source_type": "faq",
"status": "completed",
"title": "Is parking free?",
"type": "faq",
"url": null
}Errors: 400, 401, 403, 404, 422, 429, 500, 503. What each code means: Error codes.
Add a source
POST/v1/agents/{agent_id}/knowledge
Adds a website (crawled), an FAQ or an uploaded document. Returns an operation: poll GET /v1/operations/{id} or receive knowledge.operation.completed.
Parameters
| Parameter | Type | Description |
|---|---|---|
agent_idrequired | stringpath | The agent's id, from GET /v1/agents. |
Idempotency-Key | stringheader | Any unique string up to 255 characters. The same key with the same body returns the stored result for 24 hours instead of running again. See Retries. |
Request body
| Field | Type | Description |
|---|---|---|
titlerequired | string | Name of the source. For an FAQ, the question. Up to 500 characters. |
typerequired | string | One of website, faq, document. |
text | string or null | type faq: the answer text. Up to 60000 characters. |
upload_id | string or null | type document: upload_id from POST .../knowledge/uploads |
url | string or null | type website: the page or sitemap address. Up to 2048 characters. |
Response 202 Accepted
| Field | Type | Description |
|---|---|---|
agent_id | string | The agent's id. |
knowledge_ids | array of integers | The knowledge sources it covers. |
operation_id | string | Operation id. Follow it with GET /v1/operations/{operation_id}. |
replayed | boolean | true: this Idempotency-Key was used before, and the stored result is returned. Default false. |
status | string | State right after queuing, usually queued. One of queued, running, succeeded, failed. |
Example request
curl -X POST "https://api.ultimo-bots.com/v1/agents/c3e02486-f107-40c4-ac4d-e6155111bc8e/knowledge" \
-H "Authorization: Bearer $ULTIMO_API_KEY" \
-H "Idempotency-Key: $(uuidgen)" \
-H "Content-Type: application/json" \
-d '{
"text": "Yes, parking in the yard is free.",
"title": "Is parking free?",
"type": "faq"
}'import os, uuid, requests
r = requests.post(
"https://api.ultimo-bots.com/v1/agents/c3e02486-f107-40c4-ac4d-e6155111bc8e/knowledge",
headers={
"Authorization": f"Bearer {os.environ['ULTIMO_API_KEY']}",
"Idempotency-Key": str(uuid.uuid4()),
},
json={
"text": "Yes, parking in the yard is free.",
"title": "Is parking free?",
"type": "faq",
},
timeout=30,
)
print(r.status_code, r.json())const res = await fetch("https://api.ultimo-bots.com/v1/agents/c3e02486-f107-40c4-ac4d-e6155111bc8e/knowledge", {
method: "POST",
headers: {
Authorization: `Bearer ${process.env.ULTIMO_API_KEY}`,
"Idempotency-Key": crypto.randomUUID(),
"Content-Type": "application/json"
},
body: JSON.stringify({
"text": "Yes, parking in the yard is free.",
"title": "Is parking free?",
"type": "faq"
})
});
console.log(res.status, await res.json());Response 202 Accepted
{
"agent_id": "c3e02486-f107-40c4-ac4d-e6155111bc8e",
"knowledge_ids": [
226069
],
"operation_id": "8735fcb4-5d35-4c9b-ac8b-300546fa1a3d",
"replayed": false,
"status": "queued"
}Errors: 400, 401, 403, 404, 409, 422, 429, 500, 503. What each code means: Error codes.
Prepare a file upload
POST/v1/agents/{agent_id}/knowledge/uploads
Returns a one-time upload address. Send the bytes there with HTTP PUT, then add the document with POST .../knowledge (type: document, upload_id) or replace one with PUT .../knowledge/{id}.
Parameters
| Parameter | Type | Description |
|---|---|---|
agent_idrequired | stringpath | The agent's id, from GET /v1/agents. |
Idempotency-Key | stringheader | Any unique string up to 255 characters. The same key with the same body returns the stored result for 24 hours instead of running again. See Retries. |
Request body
| Field | Type | Description |
|---|---|---|
filenamerequired | string | pdf, docx, doc, rtf, txt, csv or md. Up to 180 characters. |
size_bytesrequired | integer | Size of the file in bytes. 1 to 10485760. |
knowledge_id | integer or null | Set to replace this uploaded document. At least 1. |
Response 201 Created
| Field | Type | Description |
|---|---|---|
expires_at | string | Until when the address accepts the upload, in UTC. |
headers | object | Send these headers with the upload. |
max_bytes | integer | Largest upload the address accepts, in bytes. |
method | string | Always PUT. Always PUT. |
next_step | string | What to do next, in words. |
replayed | boolean | true: this Idempotency-Key was used before, and the stored result is returned. Default false. |
upload_id | string | Send it as upload_id to Add a source or Change a source. |
upload_url | string | One-time address: send the file bytes here with HTTP PUT and the headers. |
Example request
curl -X POST "https://api.ultimo-bots.com/v1/agents/c3e02486-f107-40c4-ac4d-e6155111bc8e/knowledge/uploads" \
-H "Authorization: Bearer $ULTIMO_API_KEY" \
-H "Idempotency-Key: $(uuidgen)" \
-H "Content-Type: application/json" \
-d '{
"filename": "price-list.pdf",
"size_bytes": 48211
}'import os, uuid, requests
r = requests.post(
"https://api.ultimo-bots.com/v1/agents/c3e02486-f107-40c4-ac4d-e6155111bc8e/knowledge/uploads",
headers={
"Authorization": f"Bearer {os.environ['ULTIMO_API_KEY']}",
"Idempotency-Key": str(uuid.uuid4()),
},
json={
"filename": "price-list.pdf",
"size_bytes": 48211,
},
timeout=30,
)
print(r.status_code, r.json())const res = await fetch("https://api.ultimo-bots.com/v1/agents/c3e02486-f107-40c4-ac4d-e6155111bc8e/knowledge/uploads", {
method: "POST",
headers: {
Authorization: `Bearer ${process.env.ULTIMO_API_KEY}`,
"Idempotency-Key": crypto.randomUUID(),
"Content-Type": "application/json"
},
body: JSON.stringify({
"filename": "price-list.pdf",
"size_bytes": 48211
})
});
console.log(res.status, await res.json());Response 201 Created
{
"expires_at": "2026-11-10T18:12:04.045492+00:00",
"headers": {
"Authorization": "Bearer <one-time upload token>",
"Content-Type": "application/octet-stream"
},
"max_bytes": 48211,
"method": "PUT",
"next_step": "PUT the exact file bytes to upload_url with these headers, then call POST /v1/agents/{id}/knowledge with type=document and upload_id (or PUT /v1/agents/{id}/knowledge/{knowledge_id} to replace).",
"replayed": false,
"upload_id": "38dfa648-592f-489a-9a43-6dd25ccdea45",
"upload_url": "https://portal.ultimo-bots.com/api/mcp-platform/uploads/38dfa648-592f-489a-9a43-6dd25ccdea45"
}Errors: 400, 401, 403, 404, 409, 422, 429, 500, 503. What each code means: Error codes.
Change an FAQ or replace a document
PUT/v1/agents/{agent_id}/knowledge/{knowledge_id}
FAQ: send title and text. Document: send upload_id.
Parameters
| Parameter | Type | Description |
|---|---|---|
agent_idrequired | stringpath | The agent's id, from GET /v1/agents. |
knowledge_idrequired | integerpath | Id of the knowledge source. |
Idempotency-Key | stringheader | Any unique string up to 255 characters. The same key with the same body returns the stored result for 24 hours instead of running again. See Retries. |
Request body
| Field | Type | Description |
|---|---|---|
expected_revisionrequired | string | revision from GET .../knowledge/{id}. Up to 64 characters. |
text | string or null | FAQ: new answer. Up to 60000 characters. |
title | string or null | FAQ: new question/title. Up to 500 characters. |
upload_id | string or null | Document: replace with this upload |
Response 202 Accepted
| Field | Type | Description |
|---|---|---|
agent_id | string | The agent's id. |
knowledge_ids | array of integers | The knowledge sources it covers. |
operation_id | string | Operation id. Follow it with GET /v1/operations/{operation_id}. |
replayed | boolean | true: this Idempotency-Key was used before, and the stored result is returned. Default false. |
status | string | State right after queuing, usually queued. One of queued, running, succeeded, failed. |
Example request
curl -X PUT "https://api.ultimo-bots.com/v1/agents/c3e02486-f107-40c4-ac4d-e6155111bc8e/knowledge/226064" \
-H "Authorization: Bearer $ULTIMO_API_KEY" \
-H "Idempotency-Key: $(uuidgen)" \
-H "Content-Type: application/json" \
-d '{
"expected_revision": "2",
"text": "Yes, parking in the yard and on the street is free.",
"title": "Is parking free?"
}'import os, uuid, requests
r = requests.put(
"https://api.ultimo-bots.com/v1/agents/c3e02486-f107-40c4-ac4d-e6155111bc8e/knowledge/226064",
headers={
"Authorization": f"Bearer {os.environ['ULTIMO_API_KEY']}",
"Idempotency-Key": str(uuid.uuid4()),
},
json={
"expected_revision": "2",
"text": "Yes, parking in the yard and on the street is free.",
"title": "Is parking free?",
},
timeout=30,
)
print(r.status_code, r.json())const res = await fetch("https://api.ultimo-bots.com/v1/agents/c3e02486-f107-40c4-ac4d-e6155111bc8e/knowledge/226064", {
method: "PUT",
headers: {
Authorization: `Bearer ${process.env.ULTIMO_API_KEY}`,
"Idempotency-Key": crypto.randomUUID(),
"Content-Type": "application/json"
},
body: JSON.stringify({
"expected_revision": "2",
"text": "Yes, parking in the yard and on the street is free.",
"title": "Is parking free?"
})
});
console.log(res.status, await res.json());Response 202 Accepted
{
"agent_id": "c3e02486-f107-40c4-ac4d-e6155111bc8e",
"knowledge_ids": [
226064
],
"operation_id": "8735fcb4-5d35-4c9b-ac8b-300546fa1a3d",
"replayed": false,
"status": "queued"
}Errors: 400, 401, 403, 404, 409, 422, 429, 500, 503. What each code means: Error codes.
Delete a source
DELETE/v1/agents/{agent_id}/knowledge/{knowledge_id}
Removes the source from the agent's knowledge (an operation).
Parameters
| Parameter | Type | Description |
|---|---|---|
agent_idrequired | stringpath | The agent's id, from GET /v1/agents. |
knowledge_idrequired | integerpath | Id of the knowledge source. |
expected_revisionrequired | stringquery | The source's revision from your last read. A changed source answers 409 version_conflict. Up to 64 characters. |
Idempotency-Key | stringheader | Any unique string up to 255 characters. The same key with the same body returns the stored result for 24 hours instead of running again. See Retries. |
Response 202 Accepted
| Field | Type | Description |
|---|---|---|
agent_id | string | The agent's id. |
knowledge_ids | array of integers | The knowledge sources it covers. |
operation_id | string | Operation id. Follow it with GET /v1/operations/{operation_id}. |
replayed | boolean | true: this Idempotency-Key was used before, and the stored result is returned. Default false. |
status | string | State right after queuing, usually queued. One of queued, running, succeeded, failed. |
Example request
curl -X DELETE "https://api.ultimo-bots.com/v1/agents/c3e02486-f107-40c4-ac4d-e6155111bc8e/knowledge/226064?expected_revision=2" \
-H "Authorization: Bearer $ULTIMO_API_KEY" \
-H "Idempotency-Key: $(uuidgen)"import os, uuid, requests
r = requests.delete(
"https://api.ultimo-bots.com/v1/agents/c3e02486-f107-40c4-ac4d-e6155111bc8e/knowledge/226064?expected_revision=2",
headers={
"Authorization": f"Bearer {os.environ['ULTIMO_API_KEY']}",
"Idempotency-Key": str(uuid.uuid4()),
},
timeout=30,
)
print(r.status_code, r.json())const res = await fetch("https://api.ultimo-bots.com/v1/agents/c3e02486-f107-40c4-ac4d-e6155111bc8e/knowledge/226064?expected_revision=2", {
method: "DELETE",
headers: {
Authorization: `Bearer ${process.env.ULTIMO_API_KEY}`,
"Idempotency-Key": crypto.randomUUID()
}
});
console.log(res.status, await res.json());Response 202 Accepted
{
"agent_id": "c3e02486-f107-40c4-ac4d-e6155111bc8e",
"knowledge_ids": [
226064
],
"operation_id": "8735fcb4-5d35-4c9b-ac8b-300546fa1a3d",
"replayed": false,
"status": "queued"
}Errors: 400, 401, 403, 404, 409, 422, 429, 500, 503. What each code means: Error codes.
Read sources again
POST/v1/agents/{agent_id}/knowledge/refresh
Re-imports websites and cloud files now.
Parameters
| Parameter | Type | Description |
|---|---|---|
agent_idrequired | stringpath | The agent's id, from GET /v1/agents. |
Idempotency-Key | stringheader | Any unique string up to 255 characters. The same key with the same body returns the stored result for 24 hours instead of running again. See Retries. |
Request body
| Field | Type | Description |
|---|---|---|
sourcesrequired | array of objects | [{"knowledge_id": 1, "expected_revision": "..."}] |
Response 202 Accepted
| Field | Type | Description |
|---|---|---|
agent_id | string | The agent's id. |
knowledge_ids | array of integers | The knowledge sources it covers. |
operation_id | string | Operation id. Follow it with GET /v1/operations/{operation_id}. |
replayed | boolean | true: this Idempotency-Key was used before, and the stored result is returned. Default false. |
status | string | State right after queuing, usually queued. One of queued, running, succeeded, failed. |
Example request
curl -X POST "https://api.ultimo-bots.com/v1/agents/c3e02486-f107-40c4-ac4d-e6155111bc8e/knowledge/refresh" \
-H "Authorization: Bearer $ULTIMO_API_KEY" \
-H "Idempotency-Key: $(uuidgen)" \
-H "Content-Type: application/json" \
-d '{
"sources": [
{
"expected_revision": "2",
"knowledge_id": 226065
}
]
}'import os, uuid, requests
r = requests.post(
"https://api.ultimo-bots.com/v1/agents/c3e02486-f107-40c4-ac4d-e6155111bc8e/knowledge/refresh",
headers={
"Authorization": f"Bearer {os.environ['ULTIMO_API_KEY']}",
"Idempotency-Key": str(uuid.uuid4()),
},
json={
"sources": [
{
"expected_revision": "2",
"knowledge_id": 226065,
},
],
},
timeout=30,
)
print(r.status_code, r.json())const res = await fetch("https://api.ultimo-bots.com/v1/agents/c3e02486-f107-40c4-ac4d-e6155111bc8e/knowledge/refresh", {
method: "POST",
headers: {
Authorization: `Bearer ${process.env.ULTIMO_API_KEY}`,
"Idempotency-Key": crypto.randomUUID(),
"Content-Type": "application/json"
},
body: JSON.stringify({
"sources": [
{
"expected_revision": "2",
"knowledge_id": 226065
}
]
})
});
console.log(res.status, await res.json());Response 202 Accepted
{
"agent_id": "c3e02486-f107-40c4-ac4d-e6155111bc8e",
"knowledge_ids": [
226065
],
"operation_id": "8735fcb4-5d35-4c9b-ac8b-300546fa1a3d",
"replayed": false,
"status": "queued"
}Errors: 400, 401, 403, 404, 409, 422, 429, 500, 503. What each code means: Error codes.
State of a long operation
GET/v1/operations/{operation_id}
queued, running, succeeded or failed, with per-item results.
Parameters
| Parameter | Type | Description |
|---|---|---|
operation_idrequired | stringpath | The operation_id from the 202 answer of a knowledge change. |
Response 200 OK
| Field | Type | Description |
|---|---|---|
action | string | What runs: ingest, import, refresh, delete or discover. |
agent_id | string | The agent's id. |
attempts | integer or null | How often the worker started it. |
created_at | string or null | When it was queued, in UTC. |
error_code | string or null | Error code when it failed, otherwise null. |
finished_at | string or null | When it finished, in UTC. |
knowledge_ids | array of integers | The knowledge sources it covers. |
operation_id | string | Operation id. |
result | object or null | The result once it finished, e.g. indexed_knowledge_ids. |
status | string | One of queued, running, succeeded, failed. |
Example request
curl "https://api.ultimo-bots.com/v1/operations/8735fcb4-5d35-4c9b-ac8b-300546fa1a3d" \
-H "Authorization: Bearer $ULTIMO_API_KEY"import os, requests
r = requests.get(
"https://api.ultimo-bots.com/v1/operations/8735fcb4-5d35-4c9b-ac8b-300546fa1a3d",
headers={"Authorization": f"Bearer {os.environ['ULTIMO_API_KEY']}"},
timeout=30,
)
print(r.status_code, r.json())const res = await fetch("https://api.ultimo-bots.com/v1/operations/8735fcb4-5d35-4c9b-ac8b-300546fa1a3d", {
headers: {
Authorization: `Bearer ${process.env.ULTIMO_API_KEY}`
}
});
console.log(res.status, await res.json());Response 200 OK
{
"action": "ingest",
"agent_id": "c3e02486-f107-40c4-ac4d-e6155111bc8e",
"attempts": 1,
"created_at": "2026-11-10T17:57:04.057886+00:00",
"error_code": null,
"finished_at": "2026-11-10T17:57:06.005898+00:00",
"knowledge_ids": [
226069
],
"operation_id": "8735fcb4-5d35-4c9b-ac8b-300546fa1a3d",
"result": {
"indexed_knowledge_ids": [
226069
]
},
"status": "succeeded"
}Errors: 400, 401, 403, 404, 422, 429, 500, 503. What each code means: Error codes.