Update Reserved Fields

Update the core reserved fields of a knowledge item. Reserved fields include type, title, and language - fundamental properties that define the knowledge item's identity.

Endpoint

PUT /v1/workspaces/{workspaceId}/knowledge/{knowledgeId}/reservedField

Authentication

This endpoint requires a Bearer token obtained through the two-step authentication flow:

First, generate an access token using your API key
Use that access token in the Authorization header

See Authentication for the complete authentication flow.

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 to update

Request Body

Field	Type	Required	Description
`type`	string	Yes	Knowledge type: `URL`, `FILE`, `LINK`, `STRING`, `WEBSITE`, or `ELASTICSEARCH_INDEX`
`title`	string	Yes	New title for the knowledge item
`language`	string	No	Language code (e.g., 'en', 'es', 'fr')

Supported Knowledge Types

The following types can be updated:

URL - Web content fetched from URLs
FILE - Uploaded files
LINK - Link references without content
STRING - Plain text content

Response

Success Response

Status Code: 200 OK

Headers:

X-API-Version: v1

Body:

{
  "knowledgeId": "550e8400-e29b-41d4-a716-446655440000"
}

Examples

Update Knowledge Title

Update the title of a knowledge item:

# Step 1: Generate access token (do this once, reuse for multiple requests)
ACCESS_TOKEN=$(curl -s -X POST \
  'https://api.sharely.ai/workspaces/your-workspace-id/generate-access-key-token' \
  -H 'Content-Type: application/json' \
  -H 'x-api-key: sk-sharely-your-api-key' \
  -d '{}' | jq -r '.token')
 
# Step 2: Update reserved fields using the access token
curl -X PUT \
  'https://api.sharely.ai/v1/workspaces/your-workspace-id/knowledge/123e4567-e89b-12d3-a456-426614174000/reservedField' \
  -H "Authorization: Bearer $ACCESS_TOKEN" \
  -H 'Content-Type: application/json' \
  -H 'organizationid: your-organization-id' \
  -d '{
    "type": "FILE",
    "title": "Updated Product Documentation",
    "language": "en"
  }'

Response:

{
  "knowledgeId": "123e4567-e89b-12d3-a456-426614174000"
}

Update Language Only

Update just the language of a knowledge item:

# Using the access token from Step 1 above
curl -X PUT \
  'https://api.sharely.ai/v1/workspaces/your-workspace-id/knowledge/987fcdeb-51a2-43f7-b8c9-123456789abc/reservedField' \
  -H "Authorization: Bearer $ACCESS_TOKEN" \
  -H 'Content-Type: application/json' \
  -H 'organizationid: your-organization-id' \
  -d '{
    "type": "URL",
    "title": "API Documentation",
    "language": "es"
  }'

JavaScript Example

const API_KEY = 'sk-sharely-your-api-key';
const WORKSPACE_ID = 'your-workspace-id';
const ORGANIZATION_ID = 'your-organization-id';
const API_BASE_URL = 'https://api.sharely.ai';
 
// Step 1: Generate access token
async function getAccessToken() {
  const response = await fetch(
    `${API_BASE_URL}/workspaces/${WORKSPACE_ID}/generate-access-key-token`,
    {
      method: 'POST',
      headers: {
        'Content-Type': 'application/json',
        'x-api-key': API_KEY
      },
      body: JSON.stringify({})
    }
  );
  const data = await response.json();
  return data.token;
}
 
// Step 2: Update reserved fields
async function updateReservedFields(accessToken, knowledgeId, type, title, language = null) {
  const body = {
    type: type,
    title: title
  };
 
  if (language) {
    body.language = language;
  }
 
  const response = await fetch(
    `${API_BASE_URL}/v1/workspaces/${WORKSPACE_ID}/knowledge/${knowledgeId}/reservedField`,
    {
      method: 'PUT',
      headers: {
        'Authorization': `Bearer ${accessToken}`,
        'Content-Type': 'application/json',
        'organizationid': ORGANIZATION_ID
      },
      body: JSON.stringify(body)
    }
  );
 
  if (!response.ok) {
    throw new Error(`Update failed: ${response.statusText}`);
  }
 
  return await response.json();
}
 
// Usage - Update title and language
const accessToken = await getAccessToken();
try {
  const result = await updateReservedFields(
    accessToken,
    '123e4567-e89b-12d3-a456-426614174000',
    'FILE',
    'Updated Documentation',
    'en'
  );
  console.log('Knowledge updated:', result.knowledgeId);
} catch (error) {
  console.error('Update failed:', error.message);
}

Python Example

import requests
 
API_KEY = 'sk-sharely-your-api-key'
WORKSPACE_ID = 'your-workspace-id'
ORGANIZATION_ID = 'your-organization-id'
API_BASE_URL = 'https://api.sharely.ai'
 
# Step 1: Generate access token
def get_access_token():
    response = requests.post(
        f'{API_BASE_URL}/workspaces/{WORKSPACE_ID}/generate-access-key-token',
        headers={
            'Content-Type': 'application/json',
            'x-api-key': API_KEY
        },
        json={}
    )
    response.raise_for_status()
    return response.json()['token']
 
# Step 2: Update reserved fields
def update_reserved_fields(access_token, knowledge_id, knowledge_type, title, language=None):
    payload = {
        'type': knowledge_type,
        'title': title
    }
 
    if language:
        payload['language'] = language
 
    response = requests.put(
        f'{API_BASE_URL}/v1/workspaces/{WORKSPACE_ID}/knowledge/{knowledge_id}/reservedField',
        headers={
            'Authorization': f'Bearer {access_token}',
            'Content-Type': 'application/json',
            'organizationid': ORGANIZATION_ID
        },
        json=payload
    )
 
    response.raise_for_status()
    return response.json()
 
# Usage - Update title and language
access_token = get_access_token()
try:
    result = update_reserved_fields(
        access_token,
        '123e4567-e89b-12d3-a456-426614174000',
        'FILE',
        'Updated Documentation',
        'en'
    )
    print(f"Knowledge updated: {result['knowledgeId']}")
except requests.exceptions.HTTPError as error:
    print(f"Update failed: {error}")

Error Responses

400 Bad Request

Missing required fields:

{
  "error": "Bad Request",
  "message": "Missing required field: title"
}

Invalid type:

{
  "error": "Bad Request",
  "message": "Invalid knowledge type"
}

401 Unauthorized

Invalid or missing API key:

{
  "error": "Unauthorized",
  "message": "Invalid or missing API key"
}

403 Forbidden

Insufficient permissions:

{
  "error": "Forbidden",
  "message": "Insufficient permissions to update this knowledge item"
}

404 Not Found

Knowledge item doesn't exist:

{
  "error": "Not Found",
  "message": "Knowledge item not found"
}

422 Unprocessable Entity

Type mismatch:

{
  "error": "Unprocessable Entity",
  "message": "Knowledge type mismatch"
}

500 Internal Server Error

Server error during update:

{
  "error": "Internal Server Error",
  "message": "Failed to update knowledge item"
}

Use Cases

Rename Knowledge Items

Update titles for better organization:

await updateReservedFields(
  knowledgeId,
  'FILE',
  'Q4 2025 Product Roadmap',
  'en'
);

Standardize Titles

Batch update titles to follow naming conventions:

const knowledgeItems = await listKnowledge();
 
for (const item of knowledgeItems) {
  const standardizedTitle = standardizeTitle(item.title);
  await updateReservedFields(
    item.id,
    item.type,
    standardizedTitle,
    item.language
  );
}

Update Language Tags

Set language for multilingual content:

// Update language for Spanish content
await updateReservedFields(
  knowledgeId,
  'URL',
  'Documentación del Producto',
  'es'
);

Validate Before Updating

Check that the knowledge exists and you have permissions:

try {
  const knowledge = await getKnowledge(knowledgeId);
  await updateReservedFields(
    knowledgeId,
    knowledge.type,
    newTitle,
    newLanguage
  );
} catch (error) {
  if (error.status === 404) {
    console.error('Knowledge not found');
  } else if (error.status === 403) {
    console.error('Insufficient permissions');
  }
}

Use Consistent Language Codes

Use standard ISO 639-1 language codes:

// Good
await updateReservedFields(knowledgeId, 'FILE', 'Title', 'en');
await updateReservedFields(knowledgeId, 'FILE', 'Title', 'es');
await updateReservedFields(knowledgeId, 'FILE', 'Title', 'fr');
 
// Avoid non-standard codes
await updateReservedFields(knowledgeId, 'FILE', 'Title', 'english');

Don't Change Type Unnecessarily

The type should match the actual content. Changing it might cause inconsistencies:

// Only update title and language, keep type the same
const knowledge = await getKnowledge(knowledgeId);
await updateReservedFields(
  knowledgeId,
  knowledge.type,  // Keep existing type
  'Updated Title',
  'en'
);

Notes

Type Validation

The API validates that the type matches the knowledge item's stored type. Attempting to change the type will result in a 422 error.

Required Type Field

Even though the type typically shouldn't change, it's required in the request body to ensure you're aware of what you're updating.

Language Field

The language field is optional. If omitted, the existing language value will be preserved.

Immutability of Content

This endpoint only updates the reserved fields. The actual content of the knowledge item remains unchanged.

Search Index Updates

Updated titles and language codes are immediately reflected in search indexes for semantic and title searches.

Related Endpoints

Get Knowledge - Retrieve current field values
Search Knowledge - Find knowledge using updated titles
Create Knowledge - Create new knowledge items