List Knowledge

Retrieve all knowledge items in your workspace with optional filtering.

Endpoint

GET /v1/workspaces/{workspaceId}/knowledge

Authentication

Requires API key authentication with a valid access token.

Request

curl -X GET \
  'https://api.sharely.ai/v1/workspaces/{workspaceId}/knowledge?limit=50' \
  -H 'Authorization: Bearer YOUR_ACCESS_TOKEN' \
  -H 'Content-Type: application/json' \
  -H 'organizationid: your-organization-id'

Path Parameters

ParameterTypeRequiredDescription
workspaceIdstring (UUID)YesThe unique identifier of the workspace

Query Parameters

ParameterTypeRequiredDescription
limitnumberNoMaximum number of results (default: 100, max: 1000)
offsetnumberNoNumber of results to skip for pagination (default: 0)
typestringNoFilter by knowledge type: FILE, LINK, TEXT
categoryIdstring (UUID)NoFilter by category
roleIdstring (UUID)NoFilter by assigned role (RBAC)
languagestringNoFilter by language (e.g., "en", "es", "pt")

Headers

HeaderTypeRequiredDescription
AuthorizationstringYesBearer token with access token
organizationidstring (UUID)YesYour organization ID
Content-TypestringYesMust be application/json

Response

Success Response (200 OK)

{
  "knowledge": [
    {
      "id": "knowledge-uuid-1",
      "workspaceId": "workspace-uuid",
      "title": "Product Specification",
      "type": "FILE",
      "status": "COMPLETED",
      "metadata": {
        "filename": "product-spec-v2.pdf",
        "fileSize": 2048576,
        "language": "en",
        "mimeType": "application/pdf"
      },
      "createdAt": "2024-01-15T10:30:00Z",
      "updatedAt": "2024-11-14T15:45:00Z"
    },
    {
      "id": "knowledge-uuid-2",
      "workspaceId": "workspace-uuid",
      "title": "Company Website",
      "type": "LINK",
      "status": "COMPLETED",
      "metadata": {
        "url": "https://example.com",
        "language": "en"
      },
      "createdAt": "2024-02-20T14:00:00Z",
      "updatedAt": "2024-11-14T16:00:00Z"
    }
  ],
  "total": 2,
  "limit": 50,
  "offset": 0
}

Response Fields

FieldTypeDescription
knowledgearrayArray of knowledge objects
knowledge[].idstring (UUID)Knowledge unique identifier
knowledge[].workspaceIdstring (UUID)Parent workspace ID
knowledge[].titlestringKnowledge title
knowledge[].typestringType: FILE, LINK, or TEXT
knowledge[].statusstringProcessing status: PENDING, PROCESSING, COMPLETED, FAILED
knowledge[].metadataobjectType-specific metadata
knowledge[].createdAtstring (ISO 8601)Creation timestamp
knowledge[].updatedAtstring (ISO 8601)Last update timestamp
totalnumberTotal number of matching knowledge items
limitnumberApplied result limit
offsetnumberApplied offset for pagination

Example Usage

List All Knowledge

const fetch = require('node-fetch');
 
async function listKnowledge(workspaceId, accessToken, organizationId) {
  const response = await fetch(
    `https://api.sharely.ai/v1/workspaces/${workspaceId}/knowledge`,
    {
      method: 'GET',
      headers: {
        'Authorization': `Bearer ${accessToken}`,
        'Content-Type': 'application/json',
        'organizationid': organizationId
      }
    }
  );
 
  if (!response.ok) {
    throw new Error(`Failed to list knowledge: ${response.status}`);
  }
 
  return await response.json();
}

Pagination

async function getAllKnowledge(workspaceId, accessToken, organizationId) {
  let allKnowledge = [];
  let offset = 0;
  const limit = 100;
 
  while (true) {
    const response = await fetch(
      `https://api.sharely.ai/v1/workspaces/${workspaceId}/knowledge?limit=${limit}&offset=${offset}`,
      {
        method: 'GET',
        headers: {
          'Authorization': `Bearer ${accessToken}`,
          'Content-Type': 'application/json',
          'organizationid': organizationId
        }
      }
    );
 
    const data = await response.json();
    allKnowledge = allKnowledge.concat(data.knowledge);
 
    if (data.knowledge.length < limit) {
      break; // No more results
    }
 
    offset += limit;
  }
 
  return allKnowledge;
}

Filter by Type

# Get only PDF files
curl -X GET \
  'https://api.sharely.ai/v1/workspaces/{workspaceId}/knowledge?type=FILE' \
  -H 'Authorization: Bearer YOUR_ACCESS_TOKEN' \
  -H 'Content-Type: application/json' \
  -H 'organizationid: your-organization-id'

Filter by Language

# Get only English knowledge
curl -X GET \
  'https://api.sharely.ai/v1/workspaces/{workspaceId}/knowledge?language=en' \
  -H 'Authorization: Bearer YOUR_ACCESS_TOKEN' \
  -H 'Content-Type: application/json' \
  -H 'organizationid: your-organization-id'

Knowledge Types

FILE

Uploaded documents (PDF, Word, etc.)

{
  "type": "FILE",
  "metadata": {
    "filename": "document.pdf",
    "fileSize": 1048576,
    "mimeType": "application/pdf",
    "language": "en"
  }
}

LINK

Web URLs that have been crawled

{
  "type": "LINK",
  "metadata": {
    "url": "https://example.com/article",
    "title": "Article Title",
    "language": "en"
  }
}

TEXT

Manually entered text content

{
  "type": "TEXT",
  "metadata": {
    "content": "Knowledge content here...",
    "language": "en"
  }
}

Knowledge Status

StatusDescription
PENDINGQueued for processing
PROCESSINGCurrently being processed (text extraction, embedding)
COMPLETEDReady for use in searches
FAILEDProcessing failed (check error details)

Related Endpoints