Knowledge Base API — Sources and Content Management

The Knowledge Base API lets you programmatically manage the content sources that power your AI agents. A source is any piece of content — a URL, a plain-text block, or an uploaded document — that Beenos Solutions indexes and makes available for retrieval. You can use these endpoints to automate content ingestion pipelines, synchronize your documentation with the knowledge base, or build custom admin tools on top of the platform.

POST /v1/knowledge-base/sources

Add a new content source to your knowledge base. After you submit a source, Beenos Solutions begins processing and indexing it asynchronously. Retrieve the source from the GET /v1/knowledge-base/sources list endpoint and check its status field, or listen for a webhook event, to confirm when indexing is complete.

Request Body

string

required

The type of content source. Must be one of document, url, or text.

string

required

A human-readable label for this source. Use a descriptive name that helps you identify the content at a glance.

string

The raw text content to index. Required when type is text.

string

The URL to fetch and index. Beenos Solutions crawls the page and indexes its text content. Required when type is url.

file

The document file to upload. Accepted formats include PDF, DOCX, and TXT. Required when type is document. Use multipart/form-data encoding for this request type.

array

An optional list of string tags for organizing and filtering sources. For example, ["docs", "product", "v2"].

Example Request

curl -X POST https://api.beenossolutions.com/v1/knowledge-base/sources \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "type": "url",
    "name": "Product Documentation",
    "url": "https://docs.example.com",
    "tags": ["docs", "product"]
  }'

Response

string

The unique identifier for this source (for example, src_abc123). Use this ID to retrieve, update, or delete the source.

string

The source type you specified in the request: document, url, or text.

string

The human-readable name you assigned to this source.

string

The current processing status of the source. Possible values:

processing — the source has been received and is being indexed
indexed — indexing is complete and the source is available for search and retrieval
failed — indexing encountered an error; check the error field for details

string

ISO 8601 timestamp indicating when the source was created.

{
  "data": {
    "id": "src_abc123",
    "type": "url",
    "name": "Product Documentation",
    "status": "processing",
    "created_at": "2024-01-15T10:30:00Z"
  },
  "meta": {
    "request_id": "req_abc123",
    "timestamp": "2024-01-15T10:30:00Z"
  }
}

GET /v1/knowledge-base/sources

Retrieve a paginated list of all content sources in your knowledge base. Use the query parameters below to filter results or page through large collections.

Query Parameters

integer

default:"20"

The number of sources to return per page. Minimum 1, maximum 100.

string

A pagination cursor returned as next_cursor in a previous response. Omit this parameter to start from the first page.

string

Filter results by processing status. One of processing, indexed, or failed. Omit to return sources of all statuses.

Example Request

curl "https://api.beenossolutions.com/v1/knowledge-base/sources?limit=20&status=indexed" \
  -H "Authorization: Bearer YOUR_API_KEY"

Example Response

{
  "data": [
    {
      "id": "src_abc123",
      "type": "url",
      "name": "Product Documentation",
      "status": "indexed",
      "created_at": "2024-01-15T10:30:00Z"
    },
    {
      "id": "src_def456",
      "type": "text",
      "name": "Return Policy",
      "status": "indexed",
      "created_at": "2024-01-14T08:00:00Z"
    }
  ],
  "meta": {
    "request_id": "req_xyz789",
    "timestamp": "2024-01-15T10:31:00Z",
    "next_cursor": "cur_ghi012"
  }
}

DELETE /v1/knowledge-base/sources/:id

Permanently delete a content source and remove all of its indexed content from the knowledge base.

Path Parameter

string

required

The unique ID of the source to delete (for example, src_abc123).

Example Request

curl -X DELETE https://api.beenossolutions.com/v1/knowledge-base/sources/src_abc123 \
  -H "Authorization: Bearer YOUR_API_KEY"

Response

Returns 204 No Content on success with an empty response body. If the source does not exist, the API returns 404 Not Found.

Deleting a source removes its content from the knowledge base immediately and cannot be undone. Agents that relied on this content may return incomplete or less accurate answers until you add replacement content. Review which agents use a source before deleting it.

Overview

Endpoints

Knowledge Base API — Sources and Content Management

POST /v1/knowledge-base/sources

Request Body

Example Request

Response

GET /v1/knowledge-base/sources

Query Parameters

Example Request

Example Response

DELETE /v1/knowledge-base/sources/:id

Path Parameter

Example Request

Response

​POST /v1/knowledge-base/sources

​Request Body

​Example Request

​Response

​GET /v1/knowledge-base/sources

​Query Parameters

​Example Request

​Example Response

​DELETE /v1/knowledge-base/sources/:id

​Path Parameter

​Example Request

​Response

POST /v1/knowledge-base/sources

Request Body

Example Request

Response

GET /v1/knowledge-base/sources

Query Parameters

Example Request

Example Response

DELETE /v1/knowledge-base/sources/:id

Path Parameter

Example Request

Response