Knowledge Base API

Programmatically manage your chatbot’s knowledge base — create, process, and search knowledge sources via the v1 API.

Overview

The Knowledge Base API lets you:

List chatbots in your workspace
Create knowledge sources (text, URL, or file upload)
Process sources into searchable chunks with embeddings
Search the knowledge base semantically
Refresh URL sources to pick up content changes

Required Scopes

Scope	Description
`chatbot:read`	List chatbots
`knowledge:read`	List and read knowledge sources and stats
`knowledge:write`	Create, update, delete, and process sources
`knowledge:search`	Perform semantic search

Create an API key with these scopes in Settings → API Keys.

List Chatbots


GET /api/v1/chatbots

Query parameters:

Parameter	Type	Default	Description
`page`	integer	1	Page number
`limit`	integer	20	Results per page (max 100)

cURL


curl -X GET "https://trigglio.com/api/v1/chatbots?page=1&limit=10" \
  -H "Authorization: Bearer tr_live_your_api_key"

JavaScript


const res = await fetch('https://trigglio.com/api/v1/chatbots?page=1&limit=10', {
  headers: { 'Authorization': 'Bearer tr_live_your_api_key' }
});
const { chatbots, pagination } = await res.json();

Python


import requests
 
res = requests.get(
    'https://trigglio.com/api/v1/chatbots',
    headers={'Authorization': 'Bearer tr_live_your_api_key'},
    params={'page': 1, 'limit': 10}
)
data = res.json()

Response:


{
  "status": "success",
  "chatbots": [
    {
      "id": "cm_abc123",
      "name": "Customer Support Bot",
      "slug": "customer-support-bot",
      "descriptor": "Answers common customer questions",
      "createdAt": "2024-06-15T10:30:00Z",
      "sourceCount": 5,
      "conversationCount": 142
    }
  ],
  "pagination": {
    "page": 1,
    "limit": 10,
    "total": 1,
    "totalPages": 1
  }
}

List Knowledge Sources


GET /api/v1/chatbots/:chatbotId/sources

Query parameters:

Parameter	Type	Default	Description
`page`	integer	1	Page number
`limit`	integer	20	Results per page (max 100)
`status`	string	—	Filter by status: `pending`, `processing`, `ready`, `error`
`type`	string	—	Filter by type: `text`, `url`, `file`

cURL


curl -X GET "https://trigglio.com/api/v1/chatbots/CHATBOT_ID/sources?status=ready" \
  -H "Authorization: Bearer tr_live_your_api_key"

JavaScript


const res = await fetch(
  `https://trigglio.com/api/v1/chatbots/${chatbotId}/sources?status=ready`,
  { headers: { 'Authorization': 'Bearer tr_live_your_api_key' } }
);
const { sources, pagination } = await res.json();

Python


res = requests.get(
    f'https://trigglio.com/api/v1/chatbots/{chatbot_id}/sources',
    headers={'Authorization': 'Bearer tr_live_your_api_key'},
    params={'status': 'ready'}
)

Create Knowledge Source


POST /api/v1/chatbots/:chatbotId/sources

Three source types are supported: text, URL, and file upload.

Text Source

cURL


curl -X POST "https://trigglio.com/api/v1/chatbots/CHATBOT_ID/sources" \
  -H "Authorization: Bearer tr_live_your_api_key" \
  -H "Content-Type: application/json" \
  -d '{
    "type": "text",
    "name": "Product FAQ",
    "content": "Our product supports integration with Slack, Teams, and Discord..."
  }'

JavaScript


const res = await fetch(`https://trigglio.com/api/v1/chatbots/${chatbotId}/sources`, {
  method: 'POST',
  headers: {
    'Authorization': 'Bearer tr_live_your_api_key',
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({
    type: 'text',
    name: 'Product FAQ',
    content: 'Our product supports integration with Slack, Teams, and Discord...',
  }),
});
const { source } = await res.json();

Python


res = requests.post(
    f'https://trigglio.com/api/v1/chatbots/{chatbot_id}/sources',
    headers={
        'Authorization': 'Bearer tr_live_your_api_key',
        'Content-Type': 'application/json',
    },
    json={
        'type': 'text',
        'name': 'Product FAQ',
        'content': 'Our product supports integration with Slack, Teams, and Discord...',
    }
)

URL Source


curl -X POST "https://trigglio.com/api/v1/chatbots/CHATBOT_ID/sources" \
  -H "Authorization: Bearer tr_live_your_api_key" \
  -H "Content-Type: application/json" \
  -d '{
    "type": "url",
    "name": "Help Center",
    "url": "https://help.example.com",
    "crawlDepth": 2
  }'

Field	Type	Required	Description
`url`	string	Yes	The URL to crawl
`crawlDepth`	integer	No	How many link levels to follow (1-5, default 1)

File Upload


curl -X POST "https://trigglio.com/api/v1/chatbots/CHATBOT_ID/sources" \
  -H "Authorization: Bearer tr_live_your_api_key" \
  -F "file=@manual.pdf" \
  -F "name=Product Manual"

Supported file types: PDF, DOCX, TXT, Markdown. Max size: 10 MB.

Get Source Detail


GET /api/v1/chatbots/:chatbotId/sources/:sourceId

Returns full source details including chunk count and processing status.

Update Text Source


PATCH /api/v1/chatbots/:chatbotId/sources/:sourceId

Only text sources can be updated. Updating content resets the source to pending status — you’ll need to re-process it.


{
  "name": "Updated FAQ",
  "content": "New content to replace the existing text..."
}

Delete Source


DELETE /api/v1/chatbots/:chatbotId/sources/:sourceId

Deletes the source and all its embedded chunks. Cannot delete sources that are currently being processed (returns 409 Conflict).

Process Source


POST /api/v1/chatbots/:chatbotId/sources/:sourceId/process

Triggers async processing: content extraction → chunking → embedding. Returns 202 Accepted immediately.

Poll the source detail endpoint to check when status changes from "processing" to "ready" or "error".

cURL


# Trigger processing
curl -X POST "https://trigglio.com/api/v1/chatbots/CHATBOT_ID/sources/SOURCE_ID/process" \
  -H "Authorization: Bearer tr_live_your_api_key"
 
# Poll for completion
while true; do
  STATUS=$(curl -s "https://trigglio.com/api/v1/chatbots/CHATBOT_ID/sources/SOURCE_ID" \
    -H "Authorization: Bearer tr_live_your_api_key" | jq -r '.source.status')
  echo "Status: $STATUS"
  [ "$STATUS" = "ready" ] || [ "$STATUS" = "error" ] && break
  sleep 3
done

Refresh URL Source


POST /api/v1/chatbots/:chatbotId/sources/:sourceId/refresh

Re-crawls a URL source and updates embeddings if the content has changed. Only works for url type sources.

Knowledge Stats


GET /api/v1/chatbots/:chatbotId/knowledge/stats

Response:


{
  "status": "success",
  "stats": {
    "totalSources": 5,
    "totalChunks": 127,
    "totalSizeBytes": 245760,
    "sourcesByStatus": {
      "ready": 4,
      "pending": 1
    },
    "sourcesByType": {
      "text": 2,
      "url": 2,
      "file": 1
    }
  }
}

Source Lifecycle


pending → processing → ready
                    ↘ error

Create a source (status: pending)
Process it (status: processing → ready or error)
Once ready, the source is searchable
Refresh URL sources to update content
Update text sources to change content (resets to pending)

Error Codes

Code	HTTP	Description
`not_found`	404	Chatbot or source not found
`missing_content`	400	Text content is required
`content_too_large`	400	Text exceeds 100K character limit
`missing_url`	400	URL is required for URL sources
`invalid_url`	400	URL format is invalid
`url_blocked`	400	URL blocked by SSRF protection
`missing_file`	400	File is required for file uploads
`unsupported_file_type`	400	Only PDF, DOCX, TXT, MD supported
`file_too_large`	400	File exceeds 10MB limit
`storage_limit`	403	Workspace storage quota exceeded
`already_processing`	400	Source is already being processed
`processing_in_progress`	409	Cannot delete/refresh while processing
`invalid_operation`	400	Operation not supported for this source type