API reference: Knowledge

Knowledge. What your agent answers from.

Add web pages, whole websites, files and text to a chatbot's knowledge, edit and refresh them, and remove them. Sources are processed in the background.

yourshop.com (32 pages)ready
Returns-policy.pdfready
Delivery timesprocessing
old.yourshop.comfailed

On this page

From added to ready

A new source starts as pending, becomes processing and ends ready (the chatbot now uses it) or failed (see error). A page or text is ready in about a minute; a whole website takes longer. Poll GET …/knowledge/{sourceId} or subscribe to the knowledge.synced webhook.

Only add content you trust: the agent may repeat it to visitors. Text in a source is treated as information to answer from, never as instructions to the agent, so a page that says "ignore your rules" is not obeyed.

List knowledge sources

GET/chatbots/{chatbotId}/knowledge

The chatbot's sources, newest first, without their text.

Permission: knowledge:read

Path parameters

chatbotId
string (uuid)required

The chatbot. Listed by GET /chatbots.

Query parameters

limit
integer

Items per page, 1 to 100. Default 20.

cursor
string

meta.pagination.nextCursor from the previous page.

type
string

Only website, file or text sources.

Request
curl https://get-api.simplyboost.io/api/v1/chatbots/CHATBOT_ID/knowledge?type=website \
  -H "Authorization: Bearer $SIMPLYBOOST_TOKEN"

Response 200 OK

{
  "ok": true,
  "data": {
    "sources": [
      {
        "id": "c2a7e3f1-9b4d-4e1a-a6c0-5d8f2b9e4a31",
        "chatbotId": "f45268b2-1980-470d-865d-5048a89aedce",
        "type": "website",
        "title": "yourshop.com",
        "url": "https://yourshop.com",
        "status": "ready",
        "error": null,
        "isSourceOfTruth": false,
        "refreshInterval": "weekly",
        "lastSyncedAt": "2026-10-07T10:05:00+00:00",
        "createdAt": "2026-10-07T10:02:00+00:00",
        "updatedAt": "2026-10-07T10:02:00+00:00"
      }
    ]
  },
  "meta": { "requestId": "req_…", "pagination": { "limit": 20, "hasMore": false, "nextCursor": null } }
}

Response fields

data.sources[].id
string

The source's ID.

data.sources[].chatbotId
string

The chatbot that uses it.

data.sources[].type
string

website, file or text.

data.sources[].title
string | null

Its title.

data.sources[].url
string | null

The web address, for a website.

data.sources[].status
string

pending, processing, ready or failed. The chatbot uses a source once it is ready.

data.sources[].error
string | null

Why processing failed.

data.sources[].isSourceOfTruth
boolean

When sources disagree, this one wins.

data.sources[].refreshInterval
string

off, daily or weekly: how often a website is read again.

data.sources[].lastSyncedAt
string | null

When a website was last read.

data.sources[].createdAt
string (date-time)

When it was added.

data.sources[].updatedAt
string (date-time)

When it last changed.

meta.pagination
object

limit, hasMore (true when there is another page) and nextCursor (null on the last page).

Errors

StatusCodeWhen
404not_foundNo such chatbot, or this token may not see it.
400validation_errortype, limit or cursor is not valid.

Add a website

POST/chatbots/{chatbotId}/knowledge/website

Reads one page, or follows its links up to 50 pages and 2 levels deep. Only public addresses are accepted.

Permission: knowledge:write

Path parameters

chatbotId
string (uuid)required

The chatbot. Listed by GET /chatbots.

Body (JSON)

url
stringrequired

The page or site, https://…, up to 2,048 characters.

crawl
string

page (only this address, the default) or site (follow its links).

pageUrls
string[]

Read exactly these pages of the same website, up to 50.

includePaths
string[]

With site: only read pages under these paths, for example ["/help"].

excludePaths
string[]

With site: skip pages under these paths, for example ["/blog"].

refreshInterval
string

off (default), daily or weekly: read the website again on a schedule.

title
string

Up to 255 characters. Defaults to the address.

Request
curl -X POST https://get-api.simplyboost.io/api/v1/chatbots/CHATBOT_ID/knowledge/website \
  -H "Authorization: Bearer $SIMPLYBOOST_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"url": "https://yourshop.com", "crawl": "site", "excludePaths": ["/blog"], "refreshInterval": "weekly"}'

Response 201 Created

{
  "ok": true,
  "data": {
    "source": {
      "id": "c2a7e3f1-9b4d-4e1a-a6c0-5d8f2b9e4a31",
      "chatbotId": "f45268b2-1980-470d-865d-5048a89aedce",
      "type": "website",
      "title": "yourshop.com",
      "url": "https://yourshop.com",
      "status": "pending",
      "error": null,
      "isSourceOfTruth": false,
      "refreshInterval": "weekly",
      "lastSyncedAt": null,
      "createdAt": "2026-10-07T10:02:00+00:00",
      "updatedAt": "2026-10-07T10:02:00+00:00"
    }
  },
  "meta": { "requestId": "req_7c1e4b2a9f0d4e6c8b3a5d7f9e1c2b4a" }
}

Response fields

data.source.id
string

The source's ID.

data.source.chatbotId
string

The chatbot that uses it.

data.source.type
string

website, file or text.

data.source.title
string | null

Its title.

data.source.url
string | null

The web address, for a website.

data.source.status
string

pending, processing, ready or failed. The chatbot uses a source once it is ready.

data.source.error
string | null

Why processing failed.

data.source.isSourceOfTruth
boolean

When sources disagree, this one wins.

data.source.refreshInterval
string

off, daily or weekly: how often a website is read again.

data.source.lastSyncedAt
string | null

When a website was last read.

data.source.createdAt
string (date-time)

When it was added.

data.source.updatedAt
string (date-time)

When it last changed.

Errors

StatusCodeWhen
400validation_errorurl is missing or not a public http(s) address, a picked page is on another website, or another field is not valid.
404not_foundNo such chatbot, or this token may not see it.
403subscription_inactiveThe subscription is not active, so knowledge cannot be added.

Add text

POST/chatbots/{chatbotId}/knowledge/text

Adds text you write or export from another system, for example FAQs or opening hours.

Permission: knowledge:write

Path parameters

chatbotId
string (uuid)required

The chatbot. Listed by GET /chatbots.

Body (JSON)

title
stringrequired

1 to 255 characters.

text
stringrequired

1 to 200,000 characters. Split longer content into several sources.

Request
curl -X POST https://get-api.simplyboost.io/api/v1/chatbots/CHATBOT_ID/knowledge/text \
  -H "Authorization: Bearer $SIMPLYBOOST_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"title": "Opening hours", "text": "We are open Monday to Friday, 9:00 to 17:30."}'

Response 201 Created

{
  "ok": true,
  "data": { "source": { "id": "…", "type": "text", "title": "Opening hours", "status": "pending", … } },
  "meta": { "requestId": "req_7c1e4b2a9f0d4e6c8b3a5d7f9e1c2b4a" }
}

Response fields

data.source.id
string

The source's ID.

data.source.chatbotId
string

The chatbot that uses it.

data.source.type
string

website, file or text.

data.source.title
string | null

Its title.

data.source.url
string | null

The web address, for a website.

data.source.status
string

pending, processing, ready or failed. The chatbot uses a source once it is ready.

data.source.error
string | null

Why processing failed.

data.source.isSourceOfTruth
boolean

When sources disagree, this one wins.

data.source.refreshInterval
string

off, daily or weekly: how often a website is read again.

data.source.lastSyncedAt
string | null

When a website was last read.

data.source.createdAt
string (date-time)

When it was added.

data.source.updatedAt
string (date-time)

When it last changed.

Errors

StatusCodeWhen
400validation_errortitle or text is missing, empty or too long.
404not_foundNo such chatbot, or this token may not see it.
403subscription_inactiveThe subscription is not active.

Upload a file

POST/chatbots/{chatbotId}/knowledge/files

Upload a PDF (scanned PDFs are read with text recognition), Word (.docx), CSV, text (.txt), Markdown (.md) or image file (PNG, JPEG, WebP, GIF, BMP) up to 50 MB. The file's content is checked, not only its name.

Permission: knowledge:write

Path parameters

chatbotId
string (uuid)required

The chatbot. Listed by GET /chatbots.

Form fields (multipart/form-data)

file
filerequired

The file, sent as multipart/form-data.

title
string

Up to 255 characters. Defaults to the file name.

Request
curl https://get-api.simplyboost.io/api/v1/chatbots/CHATBOT_ID/knowledge/files \
  -H "Authorization: Bearer $SIMPLYBOOST_TOKEN" \
  -F "file=@returns-policy.pdf" \
  -F "title=Returns policy"

Response 201 Created

{
  "ok": true,
  "data": { "source": { "id": "…", "type": "file", "title": "Returns policy", "status": "pending", … } },
  "meta": { "requestId": "req_7c1e4b2a9f0d4e6c8b3a5d7f9e1c2b4a" }
}

Response fields

data.source.id
string

The source's ID.

data.source.chatbotId
string

The chatbot that uses it.

data.source.type
string

website, file or text.

data.source.title
string | null

Its title.

data.source.url
string | null

The web address, for a website.

data.source.status
string

pending, processing, ready or failed. The chatbot uses a source once it is ready.

data.source.error
string | null

Why processing failed.

data.source.isSourceOfTruth
boolean

When sources disagree, this one wins.

data.source.refreshInterval
string

off, daily or weekly: how often a website is read again.

data.source.lastSyncedAt
string | null

When a website was last read.

data.source.createdAt
string (date-time)

When it was added.

data.source.updatedAt
string (date-time)

When it last changed.

Errors

StatusCodeWhen
400validation_errorNo file, a file type that is not accepted, content that does not match the extension, or over 50 MB.
413payload_too_largeThe whole request is over 50 MB.
404not_foundNo such chatbot, or this token may not see it.
403subscription_inactiveThe subscription is not active.

Get a knowledge source

GET/chatbots/{chatbotId}/knowledge/{sourceId}

One source. Add ?include=text to get the text the chatbot reads.

Permission: knowledge:read

Path parameters

chatbotId
string (uuid)required

The chatbot. Listed by GET /chatbots.

sourceId
string (uuid)required

The knowledge source, from source.id.

Query parameters

include
string

text: add the source's text as source.text.

Request
curl https://get-api.simplyboost.io/api/v1/chatbots/CHATBOT_ID/knowledge/SOURCE_ID?include=text \
  -H "Authorization: Bearer $SIMPLYBOOST_TOKEN"

Response 200 OK

{
  "ok": true,
  "data": { "source": { "id": "…", "type": "text", "title": "Opening hours", "status": "ready", …, "text": "We are open Monday to Friday, 9:00 to 17:30." } },
  "meta": { "requestId": "req_7c1e4b2a9f0d4e6c8b3a5d7f9e1c2b4a" }
}

Response fields

data.source.id
string

The source's ID.

data.source.chatbotId
string

The chatbot that uses it.

data.source.type
string

website, file or text.

data.source.title
string | null

Its title.

data.source.url
string | null

The web address, for a website.

data.source.status
string

pending, processing, ready or failed. The chatbot uses a source once it is ready.

data.source.error
string | null

Why processing failed.

data.source.isSourceOfTruth
boolean

When sources disagree, this one wins.

data.source.refreshInterval
string

off, daily or weekly: how often a website is read again.

data.source.lastSyncedAt
string | null

When a website was last read.

data.source.createdAt
string (date-time)

When it was added.

data.source.updatedAt
string (date-time)

When it last changed.

data.source.text
string

Only with ?include=text.

Errors

StatusCodeWhen
404not_foundNo such chatbot or source, or this token may not see it.

Update a knowledge source

PATCH/chatbots/{chatbotId}/knowledge/{sourceId}

Change only the fields you send. New text for a text source replaces the old text and is processed again; the chatbot uses it once the source is ready.

Permission: knowledge:write

Path parameters

chatbotId
string (uuid)required

The chatbot. Listed by GET /chatbots.

sourceId
string (uuid)required

The knowledge source, from source.id.

Body (JSON)

title
string

1 to 255 characters.

text
string

Text sources only. 1 to 200,000 characters.

isSourceOfTruth
boolean

When sources disagree, the chatbot trusts this one.

refreshInterval
string

Websites only. off, daily or weekly.

Request
curl -X PATCH https://get-api.simplyboost.io/api/v1/chatbots/CHATBOT_ID/knowledge/SOURCE_ID \
  -H "Authorization: Bearer $SIMPLYBOOST_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"text": "We are open Monday to Saturday, 9:00 to 17:30.", "isSourceOfTruth": true}'

Response 200 OK

{
  "ok": true,
  "data": { "source": { "id": "…", "status": "pending", "isSourceOfTruth": true, … } },
  "meta": { "requestId": "req_7c1e4b2a9f0d4e6c8b3a5d7f9e1c2b4a" }
}

Response fields

data.source.id
string

The source's ID.

data.source.chatbotId
string

The chatbot that uses it.

data.source.type
string

website, file or text.

data.source.title
string | null

Its title.

data.source.url
string | null

The web address, for a website.

data.source.status
string

pending, processing, ready or failed. The chatbot uses a source once it is ready.

data.source.error
string | null

Why processing failed.

data.source.isSourceOfTruth
boolean

When sources disagree, this one wins.

data.source.refreshInterval
string

off, daily or weekly: how often a website is read again.

data.source.lastSyncedAt
string | null

When a website was last read.

data.source.createdAt
string (date-time)

When it was added.

data.source.updatedAt
string (date-time)

When it last changed.

Errors

StatusCodeWhen
400validation_errorAn unknown field, a wrong type, text on a non-text source or refreshInterval on a non-website source.
404not_foundNo such chatbot or source, or this token may not see it.
409not_readyChanging the text while the source is still being processed.

Delete a knowledge source

DELETE/chatbots/{chatbotId}/knowledge/{sourceId}

The chatbot stops using the source straight away.

Permission: knowledge:delete

Path parameters

chatbotId
string (uuid)required

The chatbot. Listed by GET /chatbots.

sourceId
string (uuid)required

The knowledge source, from source.id.

Request
curl -X DELETE https://get-api.simplyboost.io/api/v1/chatbots/CHATBOT_ID/knowledge/SOURCE_ID \
  -H "Authorization: Bearer $SIMPLYBOOST_TOKEN"

Response 200 OK

{
  "ok": true,
  "data": { "id": "c2a7e3f1-9b4d-4e1a-a6c0-5d8f2b9e4a31", "deleted": true },
  "meta": { "requestId": "req_7c1e4b2a9f0d4e6c8b3a5d7f9e1c2b4a" }
}

Response fields

data.id
string

The deleted source's ID.

data.deleted
boolean

Always true.

Errors

StatusCodeWhen
404not_foundNo such chatbot or source, or this token may not see it.

Refresh a website now

POST/chatbots/{chatbotId}/knowledge/{sourceId}/refresh

Reads the website again now, instead of waiting for its refresh interval.

Permission: knowledge:write

Path parameters

chatbotId
string (uuid)required

The chatbot. Listed by GET /chatbots.

sourceId
string (uuid)required

The knowledge source, from source.id.

Request
curl -X POST https://get-api.simplyboost.io/api/v1/chatbots/CHATBOT_ID/knowledge/SOURCE_ID/refresh \
  -H "Authorization: Bearer $SIMPLYBOOST_TOKEN"

Response 202 Accepted

{
  "ok": true,
  "data": { "source": { "id": "…", "type": "website", "status": "processing", … } },
  "meta": { "requestId": "req_7c1e4b2a9f0d4e6c8b3a5d7f9e1c2b4a" }
}

Response fields

data.source.id
string

The source's ID.

data.source.chatbotId
string

The chatbot that uses it.

data.source.type
string

website, file or text.

data.source.title
string | null

Its title.

data.source.url
string | null

The web address, for a website.

data.source.status
string

pending, processing, ready or failed. The chatbot uses a source once it is ready.

data.source.error
string | null

Why processing failed.

data.source.isSourceOfTruth
boolean

When sources disagree, this one wins.

data.source.refreshInterval
string

off, daily or weekly: how often a website is read again.

data.source.lastSyncedAt
string | null

When a website was last read.

data.source.createdAt
string (date-time)

When it was added.

data.source.updatedAt
string (date-time)

When it last changed.

Errors

StatusCodeWhen
400not_a_websiteOnly websites can be refreshed.
404not_foundNo such chatbot or source, or this token may not see it.
409not_readyThe website is still being read for the first time.
409refresh_runningA refresh is already running.
PreviousLeadsNextWebhooks

Try SimplyBoost with your own content

Start a 7-day free trial with 100 AI replies. Add your website, install the widget and see how the agent answers your customers.

Start free trial
See pricing
  • No credit card required
  • 7 days, 100 AI replies
  • From €39 a month
  • Hosted in Europe