Knowledge Permissions

Manage content visibility permissions for knowledge items. These permissions control whether users can view the source content and download files associated with knowledge items.

What are Knowledge Permissions?

Knowledge permissions provide fine-grained control over how users interact with your content:

Source Permission: Controls whether users can see the original source/URL of the knowledge item
Download Permission: Controls whether users can download the associated file (requires source permission)

These permissions work alongside RBAC (Role-Based Access Control) to provide comprehensive content access management.

Endpoints

Get Knowledge Permissions

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

Retrieve the current permission settings for a knowledge item.

Set Knowledge Permissions

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

Create or update permission settings for a knowledge item.

Authentication

Both endpoints require API key authentication via x-api-key header. See Authentication for details.

Get Knowledge Permissions

Retrieve the current permission settings for a specific knowledge item.

Endpoint

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

Path Parameters

Parameter	Type	Required	Description
`workspaceId`	string (UUID)	Yes	The ID of your workspace
`knowledgeId`	string (UUID)	Yes	The ID of the knowledge item

Headers

Header	Type	Required	Description
`x-api-key`	string	Yes	Your workspace API key

Response

Success Response

Status Code: 200 OK

Body (when permissions are set):

{
  "id": "perm-uuid-123",
  "source": true,
  "download": false
}

Body (when no permissions are set - defaults):

{
  "source": false,
  "download": false
}

Response Fields

Field	Type	Description
`id`	string (UUID)	Permission record ID (only present if permissions have been set)
`source`	boolean	Whether users can view the source URL/content
`download`	boolean	Whether users can download the file

Example

curl -X GET \
  'https://api.sharely.ai/v1/workspaces/{workspaceId}/knowledges/{knowledgeId}/permissions' \
  -H 'x-api-key: sk-sharely-your-api-key'

Set Knowledge Permissions

Create or update permission settings for a knowledge item. This endpoint uses upsert logic - it will create permissions if they don't exist, or update them if they do.

Endpoint

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

Path Parameters

Parameter	Type	Required	Description
`workspaceId`	string (UUID)	Yes	The ID of your workspace
`knowledgeId`	string (UUID)	Yes	The ID of the knowledge item

Headers

Header	Type	Required	Description
`x-api-key`	string	Yes	Your workspace API key
`Content-Type`	string	Yes	Must be `application/json`

Request Body

Field	Type	Required	Description
`source`	boolean	Yes	Allow users to view the source URL/content
`download`	boolean	Yes	Allow users to download the file

Important Notes:

download can only be true if source is also true
Setting download: true with source: false will return an error

Response

Success Response

Status Code: 200 OK

Body:

{
  "id": "knowledge-uuid-123"
}

Examples

Allow Source Viewing Only

curl -X POST \
  'https://api.sharely.ai/v1/workspaces/{workspaceId}/knowledges/{knowledgeId}/permissions' \
  -H 'x-api-key: sk-sharely-your-api-key' \
  -H 'Content-Type: application/json' \
  -d '{
    "source": true,
    "download": false
  }'

Allow Both Source and Download

curl -X POST \
  'https://api.sharely.ai/v1/workspaces/{workspaceId}/knowledges/{knowledgeId}/permissions' \
  -H 'x-api-key: sk-sharely-your-api-key' \
  -H 'Content-Type: application/json' \
  -d '{
    "source": true,
    "download": true
  }'

Disable All Permissions

curl -X POST \
  'https://api.sharely.ai/v1/workspaces/{workspaceId}/knowledges/{knowledgeId}/permissions' \
  -H 'x-api-key: sk-sharely-your-api-key' \
  -H 'Content-Type: application/json' \
  -d '{
    "source": false,
    "download": false
  }'

Error Responses

400 Bad Request

Invalid permission combination:

{
  "error": "Error",
  "message": "Invalid condition"
}

This error occurs when trying to set download: true with source: false.

404 Not Found

Knowledge item not found:

{
  "error": "Error",
  "message": "Invalid knowledge"
}

Knowledge item has been deleted:

{
  "error": "Error",
  "message": "Knowledge not found"
}

JavaScript Example

const API_KEY = 'sk-sharely-your-api-key';
const WORKSPACE_ID = 'your-workspace-id';
const BASE_URL = 'https://api.sharely.ai';
 
// Get current permissions
async function getKnowledgePermissions(knowledgeId) {
  const response = await fetch(
    `${BASE_URL}/v1/workspaces/${WORKSPACE_ID}/knowledges/${knowledgeId}/permissions`,
    {
      method: 'GET',
      headers: {
        'x-api-key': API_KEY
      }
    }
  );
 
  return await response.json();
}
 
// Set permissions
async function setKnowledgePermissions(knowledgeId, source, download) {
  // Validate: download requires source
  if (download && !source) {
    throw new Error('Download permission requires source permission');
  }
 
  const response = await fetch(
    `${BASE_URL}/v1/workspaces/${WORKSPACE_ID}/knowledges/${knowledgeId}/permissions`,
    {
      method: 'POST',
      headers: {
        'x-api-key': API_KEY,
        'Content-Type': 'application/json'
      },
      body: JSON.stringify({ source, download })
    }
  );
 
  if (!response.ok) {
    throw new Error(`Failed to set permissions: ${response.statusText}`);
  }
 
  return await response.json();
}
 
// Usage examples
const knowledgeId = 'your-knowledge-id';
 
// Check current permissions
const current = await getKnowledgePermissions(knowledgeId);
console.log('Current permissions:', current);
 
// Allow source viewing but not downloads
await setKnowledgePermissions(knowledgeId, true, false);
 
// Allow both source and downloads
await setKnowledgePermissions(knowledgeId, true, true);
 
// Disable all permissions
await setKnowledgePermissions(knowledgeId, false, false);

Python Example

import requests
 
API_KEY = 'sk-sharely-your-api-key'
WORKSPACE_ID = 'your-workspace-id'
BASE_URL = 'https://api.sharely.ai'
 
def get_knowledge_permissions(knowledge_id):
    response = requests.get(
        f'{BASE_URL}/v1/workspaces/{WORKSPACE_ID}/knowledges/{knowledge_id}/permissions',
        headers={'x-api-key': API_KEY}
    )
    response.raise_for_status()
    return response.json()
 
def set_knowledge_permissions(knowledge_id, source, download):
    if download and not source:
        raise ValueError('Download permission requires source permission')
 
    response = requests.post(
        f'{BASE_URL}/v1/workspaces/{WORKSPACE_ID}/knowledges/{knowledge_id}/permissions',
        headers={
            'x-api-key': API_KEY,
            'Content-Type': 'application/json'
        },
        json={'source': source, 'download': download}
    )
    response.raise_for_status()
    return response.json()
 
# Usage
knowledge_id = 'your-knowledge-id'
 
# Check current permissions
current = get_knowledge_permissions(knowledge_id)
print(f'Current permissions: {current}')
 
# Allow source viewing only
set_knowledge_permissions(knowledge_id, source=True, download=False)
 
# Allow both
set_knowledge_permissions(knowledge_id, source=True, download=True)

Use Cases

Sensitive Documents

For documents that users should reference but not download:

// Allow users to see content was sourced from a document
// but prevent them from downloading the original file
await setKnowledgePermissions(sensitiveDocId, true, false);

Downloadable Resources

For resources like guides, templates, or reference materials:

// Allow users to both view the source and download files
await setKnowledgePermissions(resourceId, true, true);

Internal-Only Content

For content that should only be used by the AI, not exposed to users:

// Hide source and prevent downloads
await setKnowledgePermissions(internalDocId, false, false);

Batch Permission Updates

// Update permissions for multiple knowledge items
const knowledgeIds = ['id1', 'id2', 'id3'];
 
for (const id of knowledgeIds) {
  await setKnowledgePermissions(id, true, false);
  console.log(`Updated permissions for ${id}`);
}

Permission Logic

source	download	User Experience
`false`	`false`	Users cannot see the source or download files. Content is used by AI only.
`true`	`false`	Users can see where content came from but cannot download the original file.
`true`	`true`	Users can see the source and download the original file.
`false`	`true`	Invalid - This combination is not allowed. Download requires source visibility.

Notes

Permissions are independent of RBAC - both systems work together
Default permissions (when not set) are source: false, download: false
Permissions persist until explicitly changed
Deleting a knowledge item also removes its permissions

Related Endpoints

Knowledge Roles (RBAC) - Manage role-based access
Get Knowledge - Get knowledge details
Knowledge Stats - View permission statistics