Skip to main content

Documents API

Manage knowledge base documents. All endpoints require authentication.

Document object​

{
  "id": "a1b2c3d4-...",          // UUID, auto-generated on create
  "identifier": "shipping-policy", // string, unique per instance (used for upsert)
  "name": "Shipping Policy",      // string, document title
  "body": "We ship worldwide...", // string, document content (Markdown supported)
  "categoryID": "e5f6a7b8-...",  // UUID or null, parent category ID
  "visibility": "ALL"             // string, visibility setting
}

List documents​

GET /api/kb/documents

Returns all documents for your instance.

Response:

{
  "success": true,
  "data": [
    {
      "id": "a1b2c3d4-...",
      "identifier": "shipping-policy",
      "name": "Shipping Policy",
      "body": "We ship worldwide...",
      "categoryID": "e5f6a7b8-...",
      "visibility": "ALL"
    }
  ]
}

Get document​

GET /api/kb/documents/:id

Response:

{
  "success": true,
  "data": {
    "id": "a1b2c3d4-...",
    "identifier": "shipping-policy",
    "name": "Shipping Policy",
    "body": "We ship worldwide...",
    "categoryID": "e5f6a7b8-...",
    "visibility": "ALL"
  }
}

Errors: 400 invalid id, 404 document not found.

Create document​

POST /api/kb/documents

Request body:

{
  "identifier": "shipping-policy", // required, unique identifier within the instance
  "name": "Shipping Policy",       // required, document title
  "body": "We ship worldwide...",  // required, document content
  "categoryID": "e5f6a7b8-...",   // optional, parent category ID
  "visibility": "ALL",             // optional, visibility setting
  "attributes": {                   // optional, key-value pairs added as YAML frontmatter to the body
    "source": "help-desk",
    "priority": "high"
  }
}

Response (status 201):

{
  "success": true,
  "data": {
    "id": "generated-uuid",
    "identifier": "shipping-policy",
    "name": "Shipping Policy",
    "body": "---\nsource: help-desk\npriority: high\n---\nWe ship worldwide...",
    "visibility": "ALL"
  }
}
info

When attributes are provided, they are prepended to the body as YAML frontmatter. The chatbot uses these attributes as additional context when answering questions.

Update document​

PUT /api/kb/documents/:id

Request body: same as Create document.

Response (status 200): same structure as Create.

Errors: 400 invalid id, 404 document not found.

Delete document​

DELETE /api/kb/documents/:id

Response:

{
  "success": true,
  "message": "deleted"
}

Errors: 400 invalid id.