Create Knowledge

Create a new knowledge item in your workspace. This endpoint supports creating knowledge from files, URLs, links, and text strings with automatic content processing.

Endpoint

POST /v1/workspaces/{workspaceId}/knowledge

Authentication

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

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

See Authentication for the complete authentication flow.

Required Headers:

  • Authorization: Bearer {access_token} - The JWT access token (NOT your raw API key)
  • organizationid: {your-organization-id} - Your organization ID

Path Parameters

ParameterTypeRequiredDescription
workspaceIdstring (UUID)YesThe ID of your workspace

Request Body

FieldTypeRequiredDescription
typestringYesType of knowledge: FILE, URL, LINK, or STRING
contentstringConditionalRequired for STRING type. The text content
urlstringConditionalRequired for URL type. For LINK type, use the Create Link endpoint
titlestringNoOptional title for the knowledge item
metadataobjectNoCustom metadata as key-value pairs

Knowledge Types

  • FILE: For uploaded files. Use the Upload File endpoint for direct multipart file uploads.
  • URL: For web content. The URL will be fetched and processed automatically.
  • LINK: For URL references without content processing. Use the dedicated Create Link endpoint which provides proper title and metadata support.
  • STRING: For direct text content. Provide content in the content field.

Note: This endpoint supports multiple knowledge types. For creating links, use the dedicated Create Link endpoint which is optimized for link references with better title handling and metadata support. For file uploads, use the Upload File endpoint.

Processing

This endpoint processes content synchronously — the response is returned after processing completes. For large files, use the Upload File endpoint instead: it processes asynchronously and you can poll Upload File Metadata for completion.

Response

Success Response

Status Code: 201 Created

Headers:

X-API-Version: v1

Body:

{
  "id": "550e8400-e29b-41d4-a716-446655440000",
  "knowledgeId": "550e8400-e29b-41d4-a716-446655440000"
}
FieldTypeDescription
idstring (UUID)Unique identifier for the knowledge item
knowledgeIdstring (UUID)Same as id, provided for compatibility

Examples

Create from URL

Create knowledge by processing a web page:

# 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: Create knowledge using the access token
curl -X POST \
  'https://api.sharely.ai/v1/workspaces/your-workspace-id/knowledge' \
  -H "Authorization: Bearer $ACCESS_TOKEN" \
  -H 'Content-Type: application/json' \
  -H 'organizationid: your-organization-id' \
  -d '{
    "type": "URL",
    "url": "https://example.com/article",
    "title": "Example Article",
    "metadata": {
      "category": "Resources",
      "source": "blog"
    }
  }'

Response:

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

Create from String

Create knowledge from direct text content:

# Using the access token from Step 1 above
curl -X POST \
  'https://api.sharely.ai/v1/workspaces/your-workspace-id/knowledge' \
  -H "Authorization: Bearer $ACCESS_TOKEN" \
  -H 'Content-Type: application/json' \
  -H 'organizationid: your-organization-id' \
  -d '{
    "type": "STRING",
    "content": "This is important information about our product features and capabilities.",
    "title": "Product Features",
    "metadata": {
      "department": "Product",
      "version": "2.0"
    }
  }'

Response:

{
  "id": "987fcdeb-51a2-43f7-b8c9-123456789abc",
  "knowledgeId": "987fcdeb-51a2-43f7-b8c9-123456789abc"
}

Error Responses

400 Bad Request

Missing or invalid request parameters:

{
  "error": "Bad Request",
  "message": "Missing required field: 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 for this workspace"
}

422 Unprocessable Entity

Content cannot be processed:

{
  "error": "Unprocessable Entity",
  "message": "Unable to fetch or process the provided URL"
}

500 Internal Server Error

Server error during processing:

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

Notes

URL Processing

When using type: "URL":

  • The URL must be publicly accessible
  • JavaScript-rendered content is supported
  • The page will be scraped and processed automatically
  • Processing time depends on page size and complexity

Large Content

For large documents, prefer the Upload File endpoint:

  • The upload returns immediately and processing happens in the background
  • Poll Upload File Metadata for completion
  • The knowledge item may not be searchable until processing finishes

Metadata Best Practices

  • Use consistent keys across similar knowledge items
  • Store categorization information for easier filtering
  • Include source information for tracking
  • Avoid storing sensitive information in metadata

Related Endpoints