Add knowledge base content via the API

Most knowledge lands in a chatbot through a file upload or a crawl. When the content you want to add is already text — a Markdown article, a curated question/answer pair, a snippet pasted from somewhere else — you can send it directly with a single call instead of turning it into a file first:

POST /api/v1/chatbots/{chatbotId}/text

Each entry you send becomes its own searchable, listable, deletable knowledge source, exactly like an uploaded document. Processing is synchronous — the response reports the per-entry result — and long entries are split into searchable segments automatically.

Required scope: documents:write. See Authentication & scopes.

Add a single entry

Send a text string. fileName is an optional display name / citation title (up to 300 characters):

curl -X POST https://www.wizchat.com/api/v1/chatbots/$CHATBOT_ID/text \
  -H "Authorization: Bearer $WIZCHAT_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "text": "# Refund policy\n\nRefunds are issued within 14 days of purchase.",
    "fileName": "Refund policy",
    "kind": "markdown"
  }'

The optional kind field (markdown, text, or snippet) controls how the content is split. When omitted, it is inferred from the file name.

A success is a 200 describing what was added:

{
  "success": true,
  "ingested": 1,
  "failed": 0,
  "documents": [
    {
      "fileName": "Refund policy",
      "success": true,
      "document_id": "doc_abc123",
      "chunks": 1
    }
  ]
}

document_id is the id of the new source — use it with the document list/delete operations in the API reference. chunks is the number of searchable segments the entry was split into.

Add a batch of entries

To add several entries at once, send an items array instead of text (use one or the other, not both). Each item needs its own text, and may carry its own fileName (or title, an alias) and kind. A single request accepts up to 50 items — useful for seeding curated question/answer pairs:

curl -X POST https://www.wizchat.com/api/v1/chatbots/$CHATBOT_ID/text \
  -H "Authorization: Bearer $WIZCHAT_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "items": [
      { "text": "Q: Do you ship to the EU?\nA: Yes, to all EU countries.", "fileName": "Shipping — EU" },
      { "text": "Q: How long does delivery take?\nA: 3–5 business days.", "fileName": "Shipping — delivery time" }
    ]
  }'

Each entry can hold up to roughly 1 MB of text.

Partial success

A batch is not all-or-nothing. If some entries are added and others fail, the response is a 207 Multi-Status and each element of documents[] reports its own success (with a document_id and chunks on success, or an error on failure):

{
  "success": false,
  "ingested": 1,
  "failed": 1,
  "documents": [
    { "fileName": "Shipping — EU", "success": true, "document_id": "doc_1", "chunks": 1 },
    { "fileName": "Shipping — delivery time", "success": false, "error": "..." }
  ]
}

Always check documents[].success per entry rather than relying on the HTTP status alone. A 500 means every entry failed. That response carries a top-level error object (code is always "ingest_failed", with a human-readable message) alongside the same documents[] array, so you can read each entry's own error for the per-entry reason:

{
  "error": {
    "code": "ingest_failed",
    "message": "Failed to add the submitted entries."
  },
  "documents": [
    { "fileName": "Shipping — EU", "success": false, "error": "..." },
    { "fileName": "Shipping — delivery time", "success": false, "error": "..." }
  ]
}

Visibility and scope

By default, added content is owner-only. To make it more widely available, set viewAccessLevel to one of owner-only, authenticated-users, anyone-with-link, or permanent-public. When access is restricted, you can grant specific viewers with authorizedEmails (up to 200) or authorizedGroups (email-group ids, up to 200):

curl -X POST https://www.wizchat.com/api/v1/chatbots/$CHATBOT_ID/text \
  -H "Authorization: Bearer $WIZCHAT_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "text": "Internal onboarding notes …",
    "fileName": "Onboarding",
    "viewAccessLevel": "authenticated-users",
    "authorizedEmails": ["alex@example.com"]
  }'

To place the content in a specific knowledge scope, pass its id as scopeId; omit it to use the default scope.

Errors

Status	Meaning
`400`	Invalid input
`401`	Missing or invalid API key
`403`	Key lacks the `documents:write` scope
`404`	Chatbot not found
`413`	An entry or the batch exceeds the size limit, or the account storage limit
`429`	Rate limit exceeded — see Errors & rate limits
`500`	Every entry failed — the response carries `error.code: "ingest_failed"` plus the per-entry reasons in `documents[]`

Next steps

Add text or a .txt/.md file to the knowledge base — the full request/response schema with a "try it" console
Managing documents — organize and maintain knowledge base sources
Knowledge scopes — partition a chatbot's knowledge

Add a single entry​

Add a batch of entries​

Partial success​

Visibility and scope​

Errors​

Next steps​