Knowledge API

The Knowledge API allows you to manage your workspace's knowledge base programmatically. You can create, search, and delete knowledge items of various types including files, URLs, links, and text content.

What is Knowledge?

In Sharely.ai, "knowledge" represents any piece of content you want your AI to understand and reference. This includes:

• Files: Documents (PDF, Word, Excel), images, videos, and other file types
• URLs: Web pages that are automatically scraped and processed
• Links: URL references without content scraping
• Strings: Direct text content

Knowledge Types

Processing Modes

Knowledge creation supports two processing modes:

Synchronous Processing (Default)

The API processes the knowledge immediately and returns the result once processing is complete. Best for:

• Small content
• Immediate feedback requirements
• Testing and development

Asynchronous Processing

The knowledge is queued for background processing and an immediate response is returned. Best for:

• Large files
• Batch operations
• High-volume integrations

To use async mode, include "status": "BACKGROUND_START" in your create request.

Available Endpoints

Create Knowledge

POST /v1/workspaces/{workspaceId}/knowledge

Create a new knowledge item with automatic content processing. Supports all knowledge types.

Create Link

POST /v1/workspaces/{workspaceId}/knowledge/link

Create a link-type knowledge item without content scraping. Ideal for external references.

Upload File

POST /v1/workspaces/{workspaceId}/knowledge/file

Upload files directly using multipart/form-data. Supports all file types with automatic content processing.

Delete Knowledge

DELETE /v1/workspaces/{workspaceId}/knowledge/{knowledgeId}

Delete a knowledge item. Optionally cascade delete to remove related items.

Search Knowledge

GET /v1/workspaces/{workspaceId}/knowledge

Search knowledge items using semantic search or title matching. Filter by audience if needed.

Knowledge Roles (RBAC)

GET/POST/DELETE /v1/workspaces/{workspaceId}/knowledge/{knowledgeId}/role

Manage role-based access control for knowledge items. Assign or unassign roles to control which users can access specific content.

Knowledge Permissions

GET/POST /v1/workspaces/{workspaceId}/knowledges/{knowledgeId}/permissions

Manage content visibility permissions for knowledge items. Control whether users can view source URLs and download files.

Search by Metadata

POST /v1/workspaces/{workspaceId}/knowledge/search

Filter knowledge items by metadata fields (status, type, language, title).

Knowledge Stats

GET /v1/workspaces/{workspaceId}/knowledge/stats

Get aggregated statistics about knowledge items including counts by status and RBAC coverage.

Common Workflows

Upload and Process a File

Upload a file directly using multipart/form-data:

POST /v1/workspaces/{workspaceId}/knowledge/file
Content-Type: multipart/form-data
 
file: [binary file data]
title: "My Document"
description: "Description of the document"
language: "en"
status: "BACKGROUND_START"

Create from URL

Simply create a knowledge item with type: "URL":

POST /v1/workspaces/{workspaceId}/knowledge
{
  "type": "URL",
  "url": "https://example.com/article",
  "title": "Example Article"
}

Create Quick Link

For references without content processing:

POST /v1/workspaces/{workspaceId}/knowledge/link
{
  "type": "LINK",
  "url": "https://example.com",
  "title": "Example Link"
}

Search Your Knowledge

Use semantic search to find relevant content:

GET /v1/workspaces/{workspaceId}/knowledge?q=your search query

Or search by title:

GET /v1/workspaces/{workspaceId}/knowledge?title=specific title

Best Practices

File Uploads

• Use the file upload endpoint with multipart/form-data for all file uploads
• Always specify the correct MIME type
• Use async processing (status: "BACKGROUND_START") for large files

Content Processing

• Provide descriptive titles for better searchability
• Use metadata to add context and categorization
• Consider async mode for bulk operations

Search

• Use semantic search (q parameter) for natural language queries
• Use title search for exact match lookups
• Limit results to improve performance
• Filter by audience when relevant

Deletion

• Use cascade deletion carefully - it removes related items
• Verify the knowledge ID before deletion
• Consider soft deletion in your application logic

Metadata and Organization

All knowledge items support custom metadata for flexible organization:

{
  "metadata": {
    "category": "Product Documentation",
    "author": "John Doe",
    "tags": ["api", "reference"],
    "customField": "value"
  }
}

Role-Based Access Control

When RBAC is enabled for your workspace, you can control which users have access to specific knowledge items based on their assigned roles. This enables:

• Departmental knowledge isolation - Sales, support, and engineering teams see only relevant content
• Hierarchical access - Managers can access team-specific and company-wide content
• Client-specific content - Different clients see only their designated materials
• Compliance and security - Sensitive information is restricted to authorized roles

See the Knowledge Roles API for managing role-based access to knowledge items.

Next Steps

Explore the detailed endpoint documentation:

• Create Knowledge - Create knowledge items
• Create Links - Create link references
• Upload Files - Direct file upload with multipart/form-data
• Delete Knowledge - Remove knowledge items
• Search Knowledge - Find knowledge items
• Knowledge Roles - Manage RBAC for knowledge items