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.

7 min read Updated

List knowledge sources

GET/v1/agents/{agent_id}/knowledge

Permission knowledge:read

URLs, files, FAQs and cloud sources with status and revision.

Parameters

ParameterTypeDescription
agent_idrequiredstringpathThe agent's id, from GET /v1/agents.
limitintegerqueryItems per page. Default 25. 1 to 100.
afterstringqueryThe next_cursor of the previous page. Up to 20 characters.
source_typestringqueryOnly sources of this type: website, faq, document, google_drive, onedrive or notion. Up to 40 characters.
qstringqueryOnly sources whose file name, description, address or text contains this, ignoring case. Up to 200 characters.
statusstringqueryOnly sources in this state. One of completed, failed, scraping, deleting.

Response 200 OK

FieldTypeDescription
dataarray of objectsThe items on this page.
data[].can_refreshboolean or nulltrue for websites and cloud files, which Read sources again imports anew.
data[].content_lengthinteger or nullLength of the stored text in characters.
data[].created_atstring or nullWhen it was created, in UTC (ISO 8601).
data[].descriptionstring or nullShort description; for an FAQ its question.
data[].document_namestring or nullFile name of an uploaded document.
data[].download_urlstring or nullLink to the original file when it is downloadable.
data[].downloadableboolean or nulltrue when the original file can be downloaded.
data[].failure_codestring or nullWhy the import failed, as a code.
data[].failure_reasonstring or nullWhy the import failed, in words.
data[].idintegerId of the knowledge source.
data[].revisionstringPass it as expected_revision when you change, refresh or delete the source.
data[].source_typestring or nullwebsite, faq, document or a cloud source.
data[].statusstringcompleted, failed, scraping or deleting.
data[].titlestring or nullTitle of the source.
data[].typestringStored type, e.g. faq, url_link, document.
data[].urlstring or nullAddress of a website source.
next_cursorstring or nullPass it as after to get the next page. null on the last page.
objectstringAlways list.

Example request

curl "https://api.ultimo-bots.com/v1/agents/c3e02486-f107-40c4-ac4d-e6155111bc8e/knowledge" \
  -H "Authorization: Bearer $ULTIMO_API_KEY"

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}

Permission knowledge:read

The content in pages of up to 16000 characters (next_offset).

Parameters

ParameterTypeDescription
agent_idrequiredstringpathThe agent's id, from GET /v1/agents.
knowledge_idrequiredintegerpathId of the knowledge source.
offsetintegerqueryCharacter to start from. Use next_offset of the previous page. Default 0.
max_charsintegerqueryCharacters per page. Default 8000. 1 to 16000.

Response 200 OK

FieldTypeDescription
can_refreshboolean or nulltrue for websites and cloud files, which Read sources again imports anew.
contentstring or nullThe text of the source, from content_offset on.
content_lengthinteger or nullLength of the whole stored text in characters.
content_offsetintegerCharacter where content starts. Default 0.
created_atstring or nullWhen it was created, in UTC (ISO 8601).
descriptionstring or nullShort description; for an FAQ its question.
document_namestring or nullFile name of an uploaded document.
download_urlstring or nullLink to the original file when it is downloadable.
downloadableboolean or nulltrue when the original file can be downloaded.
failure_codestring or nullWhy the import failed, as a code.
failure_reasonstring or nullWhy the import failed, in words.
idintegerId of the knowledge source.
next_offsetinteger or nullOffset of the next page, null at the end.
revisionstringPass it as expected_revision when you change, refresh or delete the source.
source_typestring or nullwebsite, faq, document or a cloud source.
statusstringcompleted, failed, scraping or deleting.
titlestring or nullTitle of the source.
typestringStored type, e.g. faq, url_link, document.
urlstring or nullAddress 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"

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

Permission knowledge:writeNeeds an integration with read and change access

Adds a website (crawled), an FAQ or an uploaded document. Returns an operation: poll GET /v1/operations/{id} or receive knowledge.operation.completed.

Parameters

ParameterTypeDescription
agent_idrequiredstringpathThe agent's id, from GET /v1/agents.
Idempotency-KeystringheaderAny 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

FieldTypeDescription
titlerequiredstringName of the source. For an FAQ, the question. Up to 500 characters.
typerequiredstringOne of website, faq, document.
textstring or nulltype faq: the answer text. Up to 60000 characters.
upload_idstring or nulltype document: upload_id from POST .../knowledge/uploads
urlstring or nulltype website: the page or sitemap address. Up to 2048 characters.

Response 202 Accepted

FieldTypeDescription
agent_idstringThe agent's id.
knowledge_idsarray of integersThe knowledge sources it covers.
operation_idstringOperation id. Follow it with GET /v1/operations/{operation_id}.
replayedbooleantrue: this Idempotency-Key was used before, and the stored result is returned. Default false.
statusstringState 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"
}'

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

Permission knowledge:writeNeeds an integration with read and change access

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

ParameterTypeDescription
agent_idrequiredstringpathThe agent's id, from GET /v1/agents.
Idempotency-KeystringheaderAny 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

FieldTypeDescription
filenamerequiredstringpdf, docx, doc, rtf, txt, csv or md. Up to 180 characters.
size_bytesrequiredintegerSize of the file in bytes. 1 to 10485760.
knowledge_idinteger or nullSet to replace this uploaded document. At least 1.

Response 201 Created

FieldTypeDescription
expires_atstringUntil when the address accepts the upload, in UTC.
headersobjectSend these headers with the upload.
max_bytesintegerLargest upload the address accepts, in bytes.
methodstringAlways PUT. Always PUT.
next_stepstringWhat to do next, in words.
replayedbooleantrue: this Idempotency-Key was used before, and the stored result is returned. Default false.
upload_idstringSend it as upload_id to Add a source or Change a source.
upload_urlstringOne-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
}'

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}

Permission knowledge:writeNeeds an integration with read and change access

FAQ: send title and text. Document: send upload_id.

Parameters

ParameterTypeDescription
agent_idrequiredstringpathThe agent's id, from GET /v1/agents.
knowledge_idrequiredintegerpathId of the knowledge source.
Idempotency-KeystringheaderAny 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

FieldTypeDescription
expected_revisionrequiredstringrevision from GET .../knowledge/{id}. Up to 64 characters.
textstring or nullFAQ: new answer. Up to 60000 characters.
titlestring or nullFAQ: new question/title. Up to 500 characters.
upload_idstring or nullDocument: replace with this upload

Response 202 Accepted

FieldTypeDescription
agent_idstringThe agent's id.
knowledge_idsarray of integersThe knowledge sources it covers.
operation_idstringOperation id. Follow it with GET /v1/operations/{operation_id}.
replayedbooleantrue: this Idempotency-Key was used before, and the stored result is returned. Default false.
statusstringState 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?"
}'

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}

Permission knowledge:writeNeeds an integration with read and change access

Removes the source from the agent's knowledge (an operation).

Parameters

ParameterTypeDescription
agent_idrequiredstringpathThe agent's id, from GET /v1/agents.
knowledge_idrequiredintegerpathId of the knowledge source.
expected_revisionrequiredstringqueryThe source's revision from your last read. A changed source answers 409 version_conflict. Up to 64 characters.
Idempotency-KeystringheaderAny 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

FieldTypeDescription
agent_idstringThe agent's id.
knowledge_idsarray of integersThe knowledge sources it covers.
operation_idstringOperation id. Follow it with GET /v1/operations/{operation_id}.
replayedbooleantrue: this Idempotency-Key was used before, and the stored result is returned. Default false.
statusstringState 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)"

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

Permission knowledge:writeNeeds an integration with read and change access

Re-imports websites and cloud files now.

Parameters

ParameterTypeDescription
agent_idrequiredstringpathThe agent's id, from GET /v1/agents.
Idempotency-KeystringheaderAny 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

FieldTypeDescription
sourcesrequiredarray of objects[{"knowledge_id": 1, "expected_revision": "..."}]

Response 202 Accepted

FieldTypeDescription
agent_idstringThe agent's id.
knowledge_idsarray of integersThe knowledge sources it covers.
operation_idstringOperation id. Follow it with GET /v1/operations/{operation_id}.
replayedbooleantrue: this Idempotency-Key was used before, and the stored result is returned. Default false.
statusstringState 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
    }
  ]
}'

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}

Permission knowledge:read

queued, running, succeeded or failed, with per-item results.

Parameters

ParameterTypeDescription
operation_idrequiredstringpathThe operation_id from the 202 answer of a knowledge change.

Response 200 OK

FieldTypeDescription
actionstringWhat runs: ingest, import, refresh, delete or discover.
agent_idstringThe agent's id.
attemptsinteger or nullHow often the worker started it.
created_atstring or nullWhen it was queued, in UTC.
error_codestring or nullError code when it failed, otherwise null.
finished_atstring or nullWhen it finished, in UTC.
knowledge_idsarray of integersThe knowledge sources it covers.
operation_idstringOperation id.
resultobject or nullThe result once it finished, e.g. indexed_knowledge_ids.
statusstringOne 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"

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.

Next steps