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

Requires Bearer token authentication. See Authentication for details.

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
statusstringNoSet to BACKGROUND_START for async processing

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 Modes

Synchronous (Default): Content is processed immediately. The response is returned after processing completes.

Asynchronous: Include "status": "BACKGROUND_START" to queue the processing job and receive an immediate response.

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:

curl -X POST \
  'https://api.sharely.ai/v1/workspaces/your-workspace-id/knowledge' \
  -H 'Authorization: Bearer YOUR_API_KEY' \
  -H 'Content-Type: application/json' \
  -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:

curl -X POST \
  'https://api.sharely.ai/v1/workspaces/your-workspace-id/knowledge' \
  -H 'Authorization: Bearer YOUR_API_KEY' \
  -H 'Content-Type: application/json' \
  -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

Async Processing Behavior

When using status: "BACKGROUND_START":

  • The response is returned immediately with the knowledge ID
  • Processing happens in the background
  • The knowledge item may not be immediately searchable
  • Check processing status via your workspace dashboard

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