Create Link

Create a link-type knowledge item without content scraping or processing. This endpoint is ideal for creating references to external resources that you don't want to process or store locally.

Endpoint

POST /v1/workspaces/{workspaceId}/knowledge/link

Authentication

Requires Bearer token authentication. See Authentication for details.

Path Parameters

ParameterTypeRequiredDescription
workspaceIdstring (UUID)YesThe ID of your workspace

Request Body

FieldTypeRequiredDescription
typestringYesMust be LINK
urlstringYesThe URL to reference
titlestringNoOptional title for the link
metadataobjectNoCustom metadata as key-value pairs

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 link
knowledgeIdstring (UUID)Same as id, provided for compatibility

Examples

Create a Simple Link

curl -X POST \
  'https://api.sharely.ai/v1/workspaces/your-workspace-id/knowledge/link' \
  -H 'Authorization: Bearer YOUR_API_KEY' \
  -H 'Content-Type: application/json' \
  -d '{
    "type": "LINK",
    "url": "https://docs.example.com",
    "title": "External Documentation"
  }'

Response:

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

Create Link with Metadata

curl -X POST \
  'https://api.sharely.ai/v1/workspaces/your-workspace-id/knowledge/link' \
  -H 'Authorization: Bearer YOUR_API_KEY' \
  -H 'Content-Type: application/json' \
  -d '{
    "type": "LINK",
    "url": "https://github.com/example/repo",
    "title": "Project Repository",
    "metadata": {
      "category": "Development",
      "resourceType": "repository",
      "lastChecked": "2025-01-15"
    }
  }'

Response:

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

Batch Create Multiple Links

# Create multiple links sequentially
for url in "https://docs.example.com" "https://api.example.com" "https://guides.example.com"
do
  curl -X POST \
    'https://api.sharely.ai/v1/workspaces/your-workspace-id/knowledge/link' \
    -H 'Authorization: Bearer YOUR_API_KEY' \
    -H 'Content-Type: application/json' \
    -d "{
      \"type\": \"LINK\",
      \"url\": \"$url\",
      \"title\": \"Documentation Link\"
    }"
done

Error Responses

400 Bad Request

Missing or invalid request parameters:

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

Or invalid type:

{
  "error": "Bad Request",
  "message": "Type must be 'LINK' for this endpoint"
}

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

Invalid URL format:

{
  "error": "Unprocessable Entity",
  "message": "Invalid URL format"
}

Use Cases

External Resource References

Create quick links to external resources without processing overhead:

{
  "type": "LINK",
  "url": "https://external-docs.com",
  "title": "Partner Documentation",
  "metadata": {
    "partner": "Acme Corp",
    "accessLevel": "public"
  }
}

Tool and Service Links

Reference tools and services your team uses:

{
  "type": "LINK",
  "url": "https://analytics.example.com/dashboard",
  "title": "Analytics Dashboard",
  "metadata": {
    "category": "Tools",
    "requiresAuth": true
  }
}

Quick Bookmarks

Create a curated list of bookmarks:

{
  "type": "LINK",
  "url": "https://stackoverflow.com/questions/tagged/javascript",
  "title": "JavaScript Q&A",
  "metadata": {
    "category": "Community Resources"
  }
}

Comparison: Links vs. URLs

FeatureLINK (this endpoint)URL (create endpoint)
Content ProcessingNoYes
Storage UsageMinimalStores full content
Processing TimeInstantDepends on content
SearchabilityBy title/metadata onlyFull content search
Use CaseQuick referencesKnowledge base content

Best Practices

When to Use Links

  • External resources you don't control
  • Frequently changing content (news sites, dashboards)
  • Resources requiring authentication
  • Quick bookmarking without processing overhead

When to Use URL Type Instead

  • Content you want to search semantically
  • Important documentation to preserve
  • Content that might become unavailable
  • Resources you want AI to understand deeply

Organizing Links

Use metadata consistently to organize links:

{
  "type": "LINK",
  "url": "https://example.com",
  "title": "Resource Name",
  "metadata": {
    "category": "Documentation",      // Group by category
    "team": "Engineering",             // Assign to team
    "priority": "high",                // Set priority
    "tags": ["api", "reference"],      // Add tags
    "addedBy": "user@example.com"      // Track contributor
  }
}

Notes

No Content Scraping

Unlike the URL type in the create knowledge endpoint, links are not scraped or processed. Only the URL and metadata are stored.

Instant Creation

Links are created instantly - there's no processing delay or background job queue.

URL Validation

The API validates that the URL is properly formatted but does not verify that the URL is accessible or active.

Metadata Flexibility

Use metadata to store any additional context about the link, such as:

  • Access requirements
  • Update frequency
  • Related resources
  • Internal notes

Related Endpoints