chore: import upstream snapshot with attribution

apps/sim/app/api/knowledge/[id]/connectors/[connectorId]/documents/route.test.ts

@@ -0,0 +1,216 @@
+/**
+ * @vitest-environment node
+ */
+import {
+  auditMock,
+  createMockRequest,
+  hybridAuthMockFns,
+  knowledgeApiUtilsMock,
+  knowledgeApiUtilsMockFns,
+  requestUtilsMockFns,
+} from '@sim/testing'
+import { beforeEach, describe, expect, it, vi } from 'vitest'
+
+const { mockDbChain } = vi.hoisted(() => {
+  const chain = {
+    select: vi.fn().mockReturnThis(),
+    from: vi.fn().mockReturnThis(),
+    where: vi.fn().mockReturnThis(),
+    orderBy: vi.fn().mockResolvedValue([]),
+    limit: vi.fn().mockResolvedValue([]),
+    update: vi.fn().mockReturnThis(),
+    set: vi.fn().mockReturnThis(),
+    returning: vi.fn().mockResolvedValue([]),
+  }
+  return { mockDbChain: chain }
+})
+
+const mockCheckAccess = knowledgeApiUtilsMockFns.mockCheckKnowledgeBaseAccess
+const mockCheckWriteAccess = knowledgeApiUtilsMockFns.mockCheckKnowledgeBaseWriteAccess
+
+vi.mock('@sim/db', () => ({ db: mockDbChain }))
+vi.mock('@/app/api/knowledge/utils', () => knowledgeApiUtilsMock)
+vi.mock('@sim/audit', () => auditMock)
+
+import { GET, PATCH } from '@/app/api/knowledge/[id]/connectors/[connectorId]/documents/route'
+
+describe('Connector Documents API Route', () => {
+  const mockParams = Promise.resolve({ id: 'kb-123', connectorId: 'conn-456' })
+
+  beforeEach(() => {
+    vi.clearAllMocks()
+    requestUtilsMockFns.mockGenerateRequestId.mockReturnValue('test-req-id')
+    mockDbChain.select.mockReturnThis()
+    mockDbChain.from.mockReturnThis()
+    mockDbChain.where.mockReturnThis()
+    mockDbChain.orderBy.mockResolvedValue([])
+    mockDbChain.limit.mockResolvedValue([])
+    mockDbChain.update.mockReturnThis()
+    mockDbChain.set.mockReturnThis()
+    mockDbChain.returning.mockResolvedValue([])
+  })
+
+  describe('GET', () => {
+    it('returns 401 when unauthenticated', async () => {
+      hybridAuthMockFns.mockCheckSessionOrInternalAuth.mockResolvedValue({
+        success: false,
+        userId: null,
+      })
+
+      const req = createMockRequest('GET')
+      const response = await GET(req as never, { params: mockParams })
+
+      expect(response.status).toBe(401)
+    })
+
+    it('returns 404 when connector not found', async () => {
+      hybridAuthMockFns.mockCheckSessionOrInternalAuth.mockResolvedValue({
+        success: true,
+        userId: 'user-1',
+      })
+      mockCheckAccess.mockResolvedValue({ hasAccess: true })
+      mockDbChain.limit.mockResolvedValueOnce([])
+
+      const req = createMockRequest('GET')
+      const response = await GET(req as never, { params: mockParams })
+
+      expect(response.status).toBe(404)
+    })
+
+    it('returns documents list on success', async () => {
+      hybridAuthMockFns.mockCheckSessionOrInternalAuth.mockResolvedValue({
+        success: true,
+        userId: 'user-1',
+      })
+      mockCheckAccess.mockResolvedValue({ hasAccess: true })
+
+      const doc = { id: 'doc-1', filename: 'test.txt', userExcluded: false }
+      mockDbChain.limit.mockResolvedValueOnce([{ id: 'conn-456' }])
+      mockDbChain.orderBy.mockResolvedValueOnce([doc])
+
+      const url = 'http://localhost/api/knowledge/kb-123/connectors/conn-456/documents'
+      const req = createMockRequest('GET', undefined, undefined, url)
+      const response = await GET(req as never, { params: mockParams })
+      const data = await response.json()
+
+      expect(response.status).toBe(200)
+      expect(data.data.documents).toHaveLength(1)
+      expect(data.data.counts.active).toBe(1)
+      expect(data.data.counts.excluded).toBe(0)
+    })
+
+    it('includes excluded documents when includeExcluded=true', async () => {
+      hybridAuthMockFns.mockCheckSessionOrInternalAuth.mockResolvedValue({
+        success: true,
+        userId: 'user-1',
+      })
+      mockCheckAccess.mockResolvedValue({ hasAccess: true })
+
+      mockDbChain.limit.mockResolvedValueOnce([{ id: 'conn-456' }])
+      mockDbChain.orderBy
+        .mockResolvedValueOnce([{ id: 'doc-1', userExcluded: false }])
+        .mockResolvedValueOnce([{ id: 'doc-2', userExcluded: true }])
+
+      const url =
+        'http://localhost/api/knowledge/kb-123/connectors/conn-456/documents?includeExcluded=true'
+      const req = createMockRequest('GET', undefined, undefined, url)
+      const response = await GET(req as never, { params: mockParams })
+      const data = await response.json()
+
+      expect(response.status).toBe(200)
+      expect(data.data.documents).toHaveLength(2)
+      expect(data.data.counts.active).toBe(1)
+      expect(data.data.counts.excluded).toBe(1)
+    })
+  })
+
+  describe('PATCH', () => {
+    it('returns 401 when unauthenticated', async () => {
+      hybridAuthMockFns.mockCheckSessionOrInternalAuth.mockResolvedValue({
+        success: false,
+        userId: null,
+      })
+
+      const req = createMockRequest('PATCH', { operation: 'restore', documentIds: ['doc-1'] })
+      const response = await PATCH(req as never, { params: mockParams })
+
+      expect(response.status).toBe(401)
+    })
+
+    it('returns 400 for invalid body', async () => {
+      hybridAuthMockFns.mockCheckSessionOrInternalAuth.mockResolvedValue({
+        success: true,
+        userId: 'user-1',
+      })
+      mockCheckWriteAccess.mockResolvedValue({ hasAccess: true })
+      mockDbChain.limit.mockResolvedValueOnce([{ id: 'conn-456' }])
+
+      const req = createMockRequest('PATCH', { documentIds: [] })
+      const response = await PATCH(req as never, { params: mockParams })
+
+      expect(response.status).toBe(400)
+    })
+
+    it('returns 404 when connector not found', async () => {
+      hybridAuthMockFns.mockCheckSessionOrInternalAuth.mockResolvedValue({
+        success: true,
+        userId: 'user-1',
+      })
+      mockCheckWriteAccess.mockResolvedValue({ hasAccess: true })
+      mockDbChain.limit.mockResolvedValueOnce([])
+
+      const req = createMockRequest('PATCH', { operation: 'restore', documentIds: ['doc-1'] })
+      const response = await PATCH(req as never, { params: mockParams })
+
+      expect(response.status).toBe(404)
+    })
+
+    it('returns success for restore operation', async () => {
+      hybridAuthMockFns.mockCheckSessionOrInternalAuth.mockResolvedValue({
+        success: true,
+        userId: 'user-1',
+        userName: 'Test',
+        userEmail: 'test@test.com',
+      })
+      mockCheckWriteAccess.mockResolvedValue({
+        hasAccess: true,
+        knowledgeBase: { workspaceId: 'ws-1', name: 'Test KB' },
+      })
+      mockDbChain.limit.mockResolvedValueOnce([{ id: 'conn-456' }])
+      mockDbChain.returning.mockResolvedValueOnce([{ id: 'doc-1' }])
+
+      const req = createMockRequest('PATCH', { operation: 'restore', documentIds: ['doc-1'] })
+      const response = await PATCH(req as never, { params: mockParams })
+      const data = await response.json()
+
+      expect(response.status).toBe(200)
+      expect(data.data.restoredCount).toBe(1)
+    })
+
+    it('returns success for exclude operation', async () => {
+      hybridAuthMockFns.mockCheckSessionOrInternalAuth.mockResolvedValue({
+        success: true,
+        userId: 'user-1',
+        userName: 'Test',
+        userEmail: 'test@test.com',
+      })
+      mockCheckWriteAccess.mockResolvedValue({
+        hasAccess: true,
+        knowledgeBase: { workspaceId: 'ws-1', name: 'Test KB' },
+      })
+      mockDbChain.limit.mockResolvedValueOnce([{ id: 'conn-456' }])
+      mockDbChain.returning.mockResolvedValueOnce([{ id: 'doc-2' }, { id: 'doc-3' }])
+
+      const req = createMockRequest('PATCH', {
+        operation: 'exclude',
+        documentIds: ['doc-2', 'doc-3'],
+      })
+      const response = await PATCH(req as never, { params: mockParams })
+      const data = await response.json()
+
+      expect(response.status).toBe(200)
+      expect(data.data.excludedCount).toBe(2)
+      expect(data.data.documentIds).toEqual(['doc-2', 'doc-3'])
+    })
+  })
+})

apps/sim/app/api/knowledge/[id]/connectors/[connectorId]/documents/route.ts

@@ -0,0 +1,247 @@
+import { AuditAction, AuditResourceType, recordAudit } from '@sim/audit'
+import { db } from '@sim/db'
+import { document, knowledgeConnector } from '@sim/db/schema'
+import { createLogger } from '@sim/logger'
+import { and, eq, inArray, isNull } from 'drizzle-orm'
+import { type NextRequest, NextResponse } from 'next/server'
+import { patchKnowledgeConnectorDocumentsContract } from '@/lib/api/contracts/knowledge'
+import { parseRequest } from '@/lib/api/server'
+import { checkSessionOrInternalAuth } from '@/lib/auth/hybrid'
+import { generateRequestId } from '@/lib/core/utils/request'
+import { withRouteHandler } from '@/lib/core/utils/with-route-handler'
+import { checkKnowledgeBaseAccess, checkKnowledgeBaseWriteAccess } from '@/app/api/knowledge/utils'
+
+const logger = createLogger('ConnectorDocumentsAPI')
+
+type RouteParams = { params: Promise<{ id: string; connectorId: string }> }
+
+/**
+ * GET /api/knowledge/[id]/connectors/[connectorId]/documents
+ * Returns documents for a connector, optionally including user-excluded ones.
+ */
+export const GET = withRouteHandler(async (request: NextRequest, { params }: RouteParams) => {
+  const requestId = generateRequestId()
+  const { id: knowledgeBaseId, connectorId } = await params
+
+  try {
+    const auth = await checkSessionOrInternalAuth(request, { requireWorkflowId: false })
+    if (!auth.success || !auth.userId) {
+      return NextResponse.json({ error: 'Unauthorized' }, { status: 401 })
+    }
+
+    const accessCheck = await checkKnowledgeBaseAccess(knowledgeBaseId, auth.userId)
+    if (!accessCheck.hasAccess) {
+      const status = 'notFound' in accessCheck && accessCheck.notFound ? 404 : 401
+      return NextResponse.json({ error: status === 404 ? 'Not found' : 'Unauthorized' }, { status })
+    }
+
+    const connectorRows = await db
+      .select({ id: knowledgeConnector.id })
+      .from(knowledgeConnector)
+      .where(
+        and(
+          eq(knowledgeConnector.id, connectorId),
+          eq(knowledgeConnector.knowledgeBaseId, knowledgeBaseId),
+          isNull(knowledgeConnector.archivedAt),
+          isNull(knowledgeConnector.deletedAt)
+        )
+      )
+      .limit(1)
+
+    if (connectorRows.length === 0) {
+      return NextResponse.json({ error: 'Connector not found' }, { status: 404 })
+    }
+
+    const includeExcluded = request.nextUrl.searchParams.get('includeExcluded') === 'true'
+
+    const activeDocs = await db
+      .select({
+        id: document.id,
+        filename: document.filename,
+        externalId: document.externalId,
+        sourceUrl: document.sourceUrl,
+        enabled: document.enabled,
+        userExcluded: document.userExcluded,
+        uploadedAt: document.uploadedAt,
+        processingStatus: document.processingStatus,
+      })
+      .from(document)
+      .where(
+        and(
+          eq(document.connectorId, connectorId),
+          isNull(document.archivedAt),
+          isNull(document.deletedAt),
+          eq(document.userExcluded, false)
+        )
+      )
+      .orderBy(document.filename)
+
+    const excludedDocs = includeExcluded
+      ? await db
+          .select({
+            id: document.id,
+            filename: document.filename,
+            externalId: document.externalId,
+            sourceUrl: document.sourceUrl,
+            enabled: document.enabled,
+            userExcluded: document.userExcluded,
+            uploadedAt: document.uploadedAt,
+            processingStatus: document.processingStatus,
+          })
+          .from(document)
+          .where(
+            and(
+              eq(document.connectorId, connectorId),
+              eq(document.userExcluded, true),
+              isNull(document.archivedAt),
+              isNull(document.deletedAt)
+            )
+          )
+          .orderBy(document.filename)
+      : []
+
+    const docs = [...activeDocs, ...excludedDocs]
+    const activeCount = activeDocs.length
+    const excludedCount = excludedDocs.length
+
+    return NextResponse.json({
+      success: true,
+      data: {
+        documents: docs,
+        counts: { active: activeCount, excluded: excludedCount },
+      },
+    })
+  } catch (error) {
+    logger.error(`[${requestId}] Error fetching connector documents`, error)
+    return NextResponse.json({ error: 'Internal server error' }, { status: 500 })
+  }
+})
+
+/**
+ * PATCH /api/knowledge/[id]/connectors/[connectorId]/documents
+ * Restore or exclude connector documents.
+ */
+export const PATCH = withRouteHandler(async (request: NextRequest, context: RouteParams) => {
+  const requestId = generateRequestId()
+  const { id: knowledgeBaseId, connectorId } = await context.params
+
+  try {
+    const auth = await checkSessionOrInternalAuth(request, { requireWorkflowId: false })
+    if (!auth.success || !auth.userId) {
+      return NextResponse.json({ error: 'Unauthorized' }, { status: 401 })
+    }
+
+    const writeCheck = await checkKnowledgeBaseWriteAccess(knowledgeBaseId, auth.userId)
+    if (!writeCheck.hasAccess) {
+      const status = 'notFound' in writeCheck && writeCheck.notFound ? 404 : 401
+      return NextResponse.json({ error: status === 404 ? 'Not found' : 'Unauthorized' }, { status })
+    }
+
+    const connectorRows = await db
+      .select({ id: knowledgeConnector.id })
+      .from(knowledgeConnector)
+      .where(
+        and(
+          eq(knowledgeConnector.id, connectorId),
+          eq(knowledgeConnector.knowledgeBaseId, knowledgeBaseId),
+          isNull(knowledgeConnector.archivedAt),
+          isNull(knowledgeConnector.deletedAt)
+        )
+      )
+      .limit(1)
+
+    if (connectorRows.length === 0) {
+      return NextResponse.json({ error: 'Connector not found' }, { status: 404 })
+    }
+
+    const parsed = await parseRequest(patchKnowledgeConnectorDocumentsContract, request, context)
+    if (!parsed.success) return parsed.response
+
+    const { operation, documentIds } = parsed.data.body
+
+    if (operation === 'restore') {
+      const updated = await db
+        .update(document)
+        .set({ userExcluded: false, enabled: true })
+        .where(
+          and(
+            eq(document.connectorId, connectorId),
+            inArray(document.id, documentIds),
+            eq(document.userExcluded, true),
+            isNull(document.archivedAt),
+            isNull(document.deletedAt)
+          )
+        )
+        .returning({ id: document.id })
+
+      logger.info(`[${requestId}] Restored ${updated.length} excluded documents`, { connectorId })
+
+      recordAudit({
+        workspaceId: writeCheck.knowledgeBase.workspaceId,
+        actorId: auth.userId,
+        actorName: auth.userName,
+        actorEmail: auth.userEmail,
+        action: AuditAction.CONNECTOR_DOCUMENT_RESTORED,
+        resourceType: AuditResourceType.CONNECTOR,
+        resourceId: connectorId,
+        description: `Restored ${updated.length} excluded document(s) for knowledge base "${writeCheck.knowledgeBase.name}"`,
+        metadata: {
+          knowledgeBaseId,
+          knowledgeBaseName: writeCheck.knowledgeBase.name,
+          operation: 'restore',
+          documentCount: updated.length,
+          documentIds: updated.map((d) => d.id),
+        },
+        request,
+      })
+
+      return NextResponse.json({
+        success: true,
+        data: { restoredCount: updated.length, documentIds: updated.map((d) => d.id) },
+      })
+    }
+
+    const updated = await db
+      .update(document)
+      .set({ userExcluded: true, enabled: false })
+      .where(
+        and(
+          eq(document.connectorId, connectorId),
+          inArray(document.id, documentIds),
+          eq(document.userExcluded, false),
+          isNull(document.archivedAt),
+          isNull(document.deletedAt)
+        )
+      )
+      .returning({ id: document.id })
+
+    logger.info(`[${requestId}] Excluded ${updated.length} documents`, { connectorId })
+
+    recordAudit({
+      workspaceId: writeCheck.knowledgeBase.workspaceId,
+      actorId: auth.userId,
+      actorName: auth.userName,
+      actorEmail: auth.userEmail,
+      action: AuditAction.CONNECTOR_DOCUMENT_EXCLUDED,
+      resourceType: AuditResourceType.CONNECTOR,
+      resourceId: connectorId,
+      description: `Excluded ${updated.length} document(s) from knowledge base "${writeCheck.knowledgeBase.name}"`,
+      metadata: {
+        knowledgeBaseId,
+        knowledgeBaseName: writeCheck.knowledgeBase.name,
+        operation: 'exclude',
+        documentCount: updated.length,
+        documentIds: updated.map((d) => d.id),
+      },
+      request,
+    })
+
+    return NextResponse.json({
+      success: true,
+      data: { excludedCount: updated.length, documentIds: updated.map((d) => d.id) },
+    })
+  } catch (error) {
+    logger.error(`[${requestId}] Error updating connector documents`, error)
+    return NextResponse.json({ error: 'Internal server error' }, { status: 500 })
+  }
+})

apps/sim/app/api/knowledge/[id]/connectors/[connectorId]/route.test.ts

@@ -0,0 +1,246 @@
+/**
+ * @vitest-environment node
+ */
+import {
+  auditMock,
+  authOAuthUtilsMock,
+  createMockRequest,
+  hybridAuthMockFns,
+  knowledgeApiUtilsMock,
+  knowledgeApiUtilsMockFns,
+} from '@sim/testing'
+import { beforeEach, describe, expect, it, vi } from 'vitest'
+
+const { mockDbChain, mockValidateConfig } = vi.hoisted(() => {
+  const chain = {
+    select: vi.fn().mockReturnThis(),
+    from: vi.fn().mockReturnThis(),
+    where: vi.fn().mockReturnThis(),
+    orderBy: vi.fn().mockReturnThis(),
+    limit: vi.fn().mockResolvedValue([]),
+    execute: vi.fn().mockResolvedValue(undefined),
+    transaction: vi.fn(),
+    insert: vi.fn().mockReturnThis(),
+    values: vi.fn().mockResolvedValue(undefined),
+    update: vi.fn().mockReturnThis(),
+    delete: vi.fn().mockReturnThis(),
+    set: vi.fn().mockReturnThis(),
+    returning: vi.fn().mockResolvedValue([]),
+  }
+  return {
+    mockDbChain: chain,
+    mockValidateConfig: vi.fn(),
+  }
+})
+
+const mockCheckAccess = knowledgeApiUtilsMockFns.mockCheckKnowledgeBaseAccess
+const mockCheckWriteAccess = knowledgeApiUtilsMockFns.mockCheckKnowledgeBaseWriteAccess
+
+vi.mock('@sim/db', () => ({ db: mockDbChain }))
+vi.mock('@/app/api/knowledge/utils', () => knowledgeApiUtilsMock)
+vi.mock('@/app/api/auth/oauth/utils', () => authOAuthUtilsMock)
+vi.mock('@/connectors/registry.server', () => ({
+  CONNECTOR_REGISTRY: {
+    jira: { validateConfig: mockValidateConfig },
+  },
+}))
+vi.mock('@/lib/knowledge/tags/service', () => ({
+  cleanupUnusedTagDefinitions: vi.fn().mockResolvedValue(undefined),
+}))
+vi.mock('@/lib/knowledge/documents/service', () => ({
+  deleteDocumentStorageFiles: vi.fn().mockResolvedValue(undefined),
+}))
+vi.mock('@sim/audit', () => auditMock)
+
+import { DELETE, GET, PATCH } from '@/app/api/knowledge/[id]/connectors/[connectorId]/route'
+
+describe('Knowledge Connector By ID API Route', () => {
+  const mockParams = Promise.resolve({ id: 'kb-123', connectorId: 'conn-456' })
+
+  beforeEach(() => {
+    vi.clearAllMocks()
+    mockDbChain.select.mockReturnThis()
+    mockDbChain.from.mockReturnThis()
+    mockDbChain.where.mockReturnThis()
+    mockDbChain.orderBy.mockReturnThis()
+    mockDbChain.limit.mockResolvedValue([])
+    mockDbChain.execute.mockResolvedValue(undefined)
+    mockDbChain.transaction.mockImplementation(
+      async (callback: (tx: typeof mockDbChain) => unknown) => callback(mockDbChain)
+    )
+    mockDbChain.update.mockReturnThis()
+    mockDbChain.delete.mockReturnThis()
+    mockDbChain.set.mockReturnThis()
+    mockDbChain.returning.mockResolvedValue([])
+  })
+
+  describe('GET', () => {
+    it('returns 401 when unauthenticated', async () => {
+      hybridAuthMockFns.mockCheckSessionOrInternalAuth.mockResolvedValue({
+        success: false,
+        userId: null,
+      })
+
+      const req = createMockRequest('GET')
+      const response = await GET(req, { params: mockParams })
+
+      expect(response.status).toBe(401)
+    })
+
+    it('returns 404 when KB not found', async () => {
+      hybridAuthMockFns.mockCheckSessionOrInternalAuth.mockResolvedValue({
+        success: true,
+        userId: 'user-1',
+      })
+      mockCheckAccess.mockResolvedValue({ hasAccess: false, notFound: true })
+
+      const req = createMockRequest('GET')
+      const response = await GET(req, { params: mockParams })
+
+      expect(response.status).toBe(404)
+    })
+
+    it('returns 404 when connector not found', async () => {
+      hybridAuthMockFns.mockCheckSessionOrInternalAuth.mockResolvedValue({
+        success: true,
+        userId: 'user-1',
+      })
+      mockCheckAccess.mockResolvedValue({ hasAccess: true })
+      mockDbChain.limit.mockResolvedValueOnce([])
+
+      const req = createMockRequest('GET')
+      const response = await GET(req, { params: mockParams })
+
+      expect(response.status).toBe(404)
+    })
+
+    it('returns connector with sync logs on success', async () => {
+      hybridAuthMockFns.mockCheckSessionOrInternalAuth.mockResolvedValue({
+        success: true,
+        userId: 'user-1',
+      })
+      mockCheckAccess.mockResolvedValue({ hasAccess: true })
+
+      const mockConnector = { id: 'conn-456', connectorType: 'jira', status: 'active' }
+      const mockLogs = [{ id: 'log-1', status: 'completed' }]
+
+      mockDbChain.limit.mockResolvedValueOnce([mockConnector]).mockResolvedValueOnce(mockLogs)
+
+      const req = createMockRequest('GET')
+      const response = await GET(req, { params: mockParams })
+      const data = await response.json()
+
+      expect(response.status).toBe(200)
+      expect(data.success).toBe(true)
+      expect(data.data.id).toBe('conn-456')
+      expect(data.data.syncLogs).toHaveLength(1)
+    })
+  })
+
+  describe('PATCH', () => {
+    it('returns 401 when unauthenticated', async () => {
+      hybridAuthMockFns.mockCheckSessionOrInternalAuth.mockResolvedValue({
+        success: false,
+        userId: null,
+      })
+
+      const req = createMockRequest('PATCH', { status: 'paused' })
+      const response = await PATCH(req, { params: mockParams })
+
+      expect(response.status).toBe(401)
+    })
+
+    it('returns 400 for invalid body', async () => {
+      hybridAuthMockFns.mockCheckSessionOrInternalAuth.mockResolvedValue({
+        success: true,
+        userId: 'user-1',
+      })
+      mockCheckWriteAccess.mockResolvedValue({ hasAccess: true })
+
+      const req = createMockRequest('PATCH', { syncIntervalMinutes: 'not a number' })
+      const response = await PATCH(req, { params: mockParams })
+      const data = await response.json()
+
+      expect(response.status).toBe(400)
+      expect(data.error).toBe('Validation error')
+    })
+
+    it('returns 404 when connector not found during sourceConfig validation', async () => {
+      hybridAuthMockFns.mockCheckSessionOrInternalAuth.mockResolvedValue({
+        success: true,
+        userId: 'user-1',
+      })
+      mockCheckWriteAccess.mockResolvedValue({ hasAccess: true })
+      mockDbChain.limit.mockResolvedValueOnce([])
+
+      const req = createMockRequest('PATCH', { sourceConfig: { project: 'NEW' } })
+      const response = await PATCH(req, { params: mockParams })
+
+      expect(response.status).toBe(404)
+    })
+
+    it('returns 200 and updates status', async () => {
+      hybridAuthMockFns.mockCheckSessionOrInternalAuth.mockResolvedValue({
+        success: true,
+        userId: 'user-1',
+        userName: 'Test',
+        userEmail: 'test@test.com',
+      })
+      mockCheckWriteAccess.mockResolvedValue({
+        hasAccess: true,
+        knowledgeBase: { workspaceId: 'ws-1', name: 'Test KB' },
+      })
+
+      const updatedConnector = { id: 'conn-456', status: 'paused', syncIntervalMinutes: 120 }
+      mockDbChain.limit.mockResolvedValueOnce([updatedConnector])
+
+      const req = createMockRequest('PATCH', { status: 'paused', syncIntervalMinutes: 120 })
+      const response = await PATCH(req, { params: mockParams })
+      const data = await response.json()
+
+      expect(response.status).toBe(200)
+      expect(data.success).toBe(true)
+      expect(data.data.status).toBe('paused')
+    })
+  })
+
+  describe('DELETE', () => {
+    it('returns 401 when unauthenticated', async () => {
+      hybridAuthMockFns.mockCheckSessionOrInternalAuth.mockResolvedValue({
+        success: false,
+        userId: null,
+      })
+
+      const req = createMockRequest('DELETE')
+      const response = await DELETE(req, { params: mockParams })
+
+      expect(response.status).toBe(401)
+    })
+
+    it('returns 200 on successful hard-delete', async () => {
+      hybridAuthMockFns.mockCheckSessionOrInternalAuth.mockResolvedValue({
+        success: true,
+        userId: 'user-1',
+        userName: 'Test',
+        userEmail: 'test@test.com',
+      })
+      mockCheckWriteAccess.mockResolvedValue({
+        hasAccess: true,
+        knowledgeBase: { workspaceId: 'ws-1', name: 'Test KB' },
+      })
+      mockDbChain.where
+        .mockReturnValueOnce(mockDbChain)
+        .mockResolvedValueOnce([{ id: 'doc-1', fileUrl: '/api/uploads/test.txt' }])
+        .mockReturnValueOnce(mockDbChain)
+      mockDbChain.limit.mockResolvedValueOnce([{ id: 'conn-456', connectorType: 'jira' }])
+      mockDbChain.returning.mockResolvedValueOnce([{ id: 'conn-456' }])
+
+      const req = createMockRequest('DELETE')
+      const response = await DELETE(req, { params: mockParams })
+      const data = await response.json()
+
+      expect(response.status).toBe(200)
+      expect(data.success).toBe(true)
+    })
+  })
+})

apps/sim/app/api/knowledge/[id]/connectors/[connectorId]/route.ts

@@ -0,0 +1,420 @@
+import { AuditAction, AuditResourceType, recordAudit } from '@sim/audit'
+import { db } from '@sim/db'
+import {
+  document,
+  embedding,
+  knowledgeBase,
+  knowledgeConnector,
+  knowledgeConnectorSyncLog,
+} from '@sim/db/schema'
+import { createLogger } from '@sim/logger'
+import { and, desc, eq, inArray, isNull, sql } from 'drizzle-orm'
+import { type NextRequest, NextResponse } from 'next/server'
+import { updateKnowledgeConnectorContract } from '@/lib/api/contracts/knowledge'
+import { parseRequest } from '@/lib/api/server'
+import { decryptApiKey } from '@/lib/api-key/crypto'
+import { checkSessionOrInternalAuth } from '@/lib/auth/hybrid'
+import { hasLiveSyncAccess } from '@/lib/billing/core/subscription'
+import { generateRequestId } from '@/lib/core/utils/request'
+import { withRouteHandler } from '@/lib/core/utils/with-route-handler'
+import { deleteDocumentStorageFiles } from '@/lib/knowledge/documents/service'
+import { cleanupUnusedTagDefinitions } from '@/lib/knowledge/tags/service'
+import { captureServerEvent } from '@/lib/posthog/server'
+import { refreshAccessTokenIfNeeded } from '@/app/api/auth/oauth/utils'
+import { checkKnowledgeBaseAccess, checkKnowledgeBaseWriteAccess } from '@/app/api/knowledge/utils'
+import { CONNECTOR_REGISTRY } from '@/connectors/registry.server'
+
+const logger = createLogger('KnowledgeConnectorByIdAPI')
+
+type RouteParams = { params: Promise<{ id: string; connectorId: string }> }
+
+/**
+ * GET /api/knowledge/[id]/connectors/[connectorId] - Get connector details with recent sync logs
+ */
+export const GET = withRouteHandler(async (request: NextRequest, { params }: RouteParams) => {
+  const requestId = generateRequestId()
+  const { id: knowledgeBaseId, connectorId } = await params
+
+  try {
+    const auth = await checkSessionOrInternalAuth(request, { requireWorkflowId: false })
+    if (!auth.success || !auth.userId) {
+      return NextResponse.json({ error: 'Unauthorized' }, { status: 401 })
+    }
+
+    const accessCheck = await checkKnowledgeBaseAccess(knowledgeBaseId, auth.userId)
+    if (!accessCheck.hasAccess) {
+      const status = 'notFound' in accessCheck && accessCheck.notFound ? 404 : 401
+      return NextResponse.json({ error: status === 404 ? 'Not found' : 'Unauthorized' }, { status })
+    }
+
+    const connectorRows = await db
+      .select()
+      .from(knowledgeConnector)
+      .where(
+        and(
+          eq(knowledgeConnector.id, connectorId),
+          eq(knowledgeConnector.knowledgeBaseId, knowledgeBaseId),
+          isNull(knowledgeConnector.archivedAt),
+          isNull(knowledgeConnector.deletedAt)
+        )
+      )
+      .limit(1)
+
+    if (connectorRows.length === 0) {
+      return NextResponse.json({ error: 'Connector not found' }, { status: 404 })
+    }
+
+    const syncLogs = await db
+      .select()
+      .from(knowledgeConnectorSyncLog)
+      .where(eq(knowledgeConnectorSyncLog.connectorId, connectorId))
+      .orderBy(desc(knowledgeConnectorSyncLog.startedAt))
+      .limit(10)
+
+    const { encryptedApiKey: _, ...connectorData } = connectorRows[0]
+    return NextResponse.json({
+      success: true,
+      data: {
+        ...connectorData,
+        syncLogs,
+      },
+    })
+  } catch (error) {
+    logger.error(`[${requestId}] Error fetching connector`, error)
+    return NextResponse.json({ error: 'Internal server error' }, { status: 500 })
+  }
+})
+
+/**
+ * PATCH /api/knowledge/[id]/connectors/[connectorId] - Update a connector
+ */
+export const PATCH = withRouteHandler(async (request: NextRequest, context: RouteParams) => {
+  const requestId = generateRequestId()
+  const { id: knowledgeBaseId, connectorId } = await context.params
+
+  try {
+    const auth = await checkSessionOrInternalAuth(request, { requireWorkflowId: false })
+    if (!auth.success || !auth.userId) {
+      return NextResponse.json({ error: 'Unauthorized' }, { status: 401 })
+    }
+
+    const writeCheck = await checkKnowledgeBaseWriteAccess(knowledgeBaseId, auth.userId)
+    if (!writeCheck.hasAccess) {
+      const status = 'notFound' in writeCheck && writeCheck.notFound ? 404 : 401
+      return NextResponse.json({ error: status === 404 ? 'Not found' : 'Unauthorized' }, { status })
+    }
+
+    const parsed = await parseRequest(updateKnowledgeConnectorContract, request, context)
+    if (!parsed.success) return parsed.response
+    const body = parsed.data.body
+
+    if (
+      body.syncIntervalMinutes !== undefined &&
+      body.syncIntervalMinutes > 0 &&
+      body.syncIntervalMinutes < 60
+    ) {
+      const canUseLiveSync = await hasLiveSyncAccess(auth.userId)
+      if (!canUseLiveSync) {
+        return NextResponse.json(
+          { error: 'Live sync requires a Max or Enterprise plan' },
+          { status: 403 }
+        )
+      }
+    }
+
+    if (body.sourceConfig !== undefined) {
+      const existingRows = await db
+        .select()
+        .from(knowledgeConnector)
+        .where(
+          and(
+            eq(knowledgeConnector.id, connectorId),
+            eq(knowledgeConnector.knowledgeBaseId, knowledgeBaseId),
+            isNull(knowledgeConnector.archivedAt),
+            isNull(knowledgeConnector.deletedAt)
+          )
+        )
+        .limit(1)
+
+      if (existingRows.length === 0) {
+        return NextResponse.json({ error: 'Connector not found' }, { status: 404 })
+      }
+
+      const existing = existingRows[0]
+      const connectorConfig = CONNECTOR_REGISTRY[existing.connectorType]
+
+      if (!connectorConfig) {
+        return NextResponse.json(
+          { error: `Unknown connector type: ${existing.connectorType}` },
+          { status: 400 }
+        )
+      }
+
+      const kbRows = await db
+        .select({ userId: knowledgeBase.userId })
+        .from(knowledgeBase)
+        .where(eq(knowledgeBase.id, knowledgeBaseId))
+        .limit(1)
+
+      if (kbRows.length === 0) {
+        return NextResponse.json({ error: 'Knowledge base not found' }, { status: 404 })
+      }
+
+      let accessToken: string | null = null
+      if (connectorConfig.auth.mode === 'apiKey') {
+        if (!existing.encryptedApiKey) {
+          return NextResponse.json(
+            { error: 'API key not found. Please reconfigure the connector.' },
+            { status: 400 }
+          )
+        }
+        accessToken = (await decryptApiKey(existing.encryptedApiKey)).decrypted
+      } else {
+        if (!existing.credentialId) {
+          return NextResponse.json(
+            { error: 'OAuth credential not found. Please reconfigure the connector.' },
+            { status: 400 }
+          )
+        }
+        accessToken = await refreshAccessTokenIfNeeded(
+          existing.credentialId,
+          kbRows[0].userId,
+          `patch-${connectorId}`
+        )
+      }
+
+      if (!accessToken) {
+        return NextResponse.json(
+          { error: 'Failed to refresh access token. Please reconnect your account.' },
+          { status: 401 }
+        )
+      }
+
+      const validation = await connectorConfig.validateConfig(accessToken, body.sourceConfig)
+      if (!validation.valid) {
+        return NextResponse.json(
+          { error: validation.error || 'Invalid source configuration' },
+          { status: 400 }
+        )
+      }
+    }
+
+    const updates: Record<string, unknown> = { updatedAt: new Date() }
+    if (body.sourceConfig !== undefined) {
+      updates.sourceConfig = body.sourceConfig
+    }
+    if (body.syncIntervalMinutes !== undefined) {
+      updates.syncIntervalMinutes = body.syncIntervalMinutes
+      if (body.syncIntervalMinutes > 0) {
+        updates.nextSyncAt = new Date(Date.now() + body.syncIntervalMinutes * 60 * 1000)
+      } else {
+        updates.nextSyncAt = null
+      }
+    }
+    if (body.status !== undefined) {
+      updates.status = body.status
+      if (body.status === 'active') {
+        updates.consecutiveFailures = 0
+        updates.lastSyncError = null
+        if (updates.nextSyncAt === undefined) {
+          updates.nextSyncAt = new Date()
+        }
+      }
+    }
+
+    await db
+      .update(knowledgeConnector)
+      .set(updates)
+      .where(
+        and(
+          eq(knowledgeConnector.id, connectorId),
+          eq(knowledgeConnector.knowledgeBaseId, knowledgeBaseId),
+          isNull(knowledgeConnector.archivedAt),
+          isNull(knowledgeConnector.deletedAt)
+        )
+      )
+
+    const updated = await db
+      .select()
+      .from(knowledgeConnector)
+      .where(
+        and(
+          eq(knowledgeConnector.id, connectorId),
+          eq(knowledgeConnector.knowledgeBaseId, knowledgeBaseId),
+          isNull(knowledgeConnector.archivedAt),
+          isNull(knowledgeConnector.deletedAt)
+        )
+      )
+      .limit(1)
+
+    const { encryptedApiKey: __, ...updatedData } = updated[0]
+
+    recordAudit({
+      workspaceId: writeCheck.knowledgeBase.workspaceId,
+      actorId: auth.userId,
+      actorName: auth.userName,
+      actorEmail: auth.userEmail,
+      action: AuditAction.CONNECTOR_UPDATED,
+      resourceType: AuditResourceType.CONNECTOR,
+      resourceId: connectorId,
+      resourceName: updatedData.connectorType,
+      description: `Updated connector for knowledge base "${writeCheck.knowledgeBase.name}"`,
+      metadata: {
+        knowledgeBaseId,
+        knowledgeBaseName: writeCheck.knowledgeBase.name,
+        connectorType: updatedData.connectorType,
+        updatedFields: Object.keys(parsed.data),
+        ...(body.syncIntervalMinutes !== undefined && {
+          syncIntervalMinutes: body.syncIntervalMinutes,
+        }),
+        ...(body.status !== undefined && { newStatus: body.status }),
+      },
+      request,
+    })
+
+    return NextResponse.json({ success: true, data: updatedData })
+  } catch (error) {
+    logger.error(`[${requestId}] Error updating connector`, error)
+    return NextResponse.json({ error: 'Internal server error' }, { status: 500 })
+  }
+})
+
+/**
+ * DELETE /api/knowledge/[id]/connectors/[connectorId] - Hard-delete a connector
+ */
+export const DELETE = withRouteHandler(async (request: NextRequest, { params }: RouteParams) => {
+  const requestId = generateRequestId()
+  const { id: knowledgeBaseId, connectorId } = await params
+
+  try {
+    const auth = await checkSessionOrInternalAuth(request, { requireWorkflowId: false })
+    if (!auth.success || !auth.userId) {
+      return NextResponse.json({ error: 'Unauthorized' }, { status: 401 })
+    }
+
+    const writeCheck = await checkKnowledgeBaseWriteAccess(knowledgeBaseId, auth.userId)
+    if (!writeCheck.hasAccess) {
+      const status = 'notFound' in writeCheck && writeCheck.notFound ? 404 : 401
+      return NextResponse.json({ error: status === 404 ? 'Not found' : 'Unauthorized' }, { status })
+    }
+
+    const existingConnector = await db
+      .select({ id: knowledgeConnector.id, connectorType: knowledgeConnector.connectorType })
+      .from(knowledgeConnector)
+      .where(
+        and(
+          eq(knowledgeConnector.id, connectorId),
+          eq(knowledgeConnector.knowledgeBaseId, knowledgeBaseId),
+          isNull(knowledgeConnector.archivedAt),
+          isNull(knowledgeConnector.deletedAt)
+        )
+      )
+      .limit(1)
+
+    if (existingConnector.length === 0) {
+      return NextResponse.json({ error: 'Connector not found' }, { status: 404 })
+    }
+
+    const { searchParams } = new URL(request.url)
+    const deleteDocuments = searchParams.get('deleteDocuments') === 'true'
+
+    const { deletedDocs, docCount } = await db.transaction(async (tx) => {
+      await tx.execute(sql`SELECT 1 FROM knowledge_connector WHERE id = ${connectorId} FOR UPDATE`)
+
+      const docs = await tx
+        .select({ id: document.id, fileUrl: document.fileUrl })
+        .from(document)
+        .where(
+          and(
+            eq(document.connectorId, connectorId),
+            isNull(document.archivedAt),
+            isNull(document.deletedAt)
+          )
+        )
+
+      if (deleteDocuments) {
+        const documentIds = docs.map((doc) => doc.id)
+        if (documentIds.length > 0) {
+          await tx.delete(embedding).where(inArray(embedding.documentId, documentIds))
+          await tx.delete(document).where(inArray(document.id, documentIds))
+        }
+      }
+
+      const deletedConnectors = await tx
+        .delete(knowledgeConnector)
+        .where(
+          and(
+            eq(knowledgeConnector.id, connectorId),
+            eq(knowledgeConnector.knowledgeBaseId, knowledgeBaseId),
+            isNull(knowledgeConnector.archivedAt),
+            isNull(knowledgeConnector.deletedAt)
+          )
+        )
+        .returning({ id: knowledgeConnector.id })
+
+      if (deletedConnectors.length === 0) {
+        throw new Error('Connector not found')
+      }
+
+      return { deletedDocs: deleteDocuments ? docs : [], docCount: docs.length }
+    })
+
+    const kbWorkspaceId = writeCheck.knowledgeBase?.workspaceId ?? null
+
+    if (deleteDocuments) {
+      await Promise.all([
+        deletedDocs.length > 0
+          ? deleteDocumentStorageFiles(
+              deletedDocs.map((doc) => ({ ...doc, workspaceId: kbWorkspaceId })),
+              requestId
+            )
+          : Promise.resolve(),
+        cleanupUnusedTagDefinitions(knowledgeBaseId, requestId).catch((error) => {
+          logger.warn(`[${requestId}] Failed to cleanup tag definitions`, error)
+        }),
+      ])
+    }
+
+    logger.info(
+      `[${requestId}] Deleted connector ${connectorId}${deleteDocuments ? ` and ${docCount} documents` : `, kept ${docCount} documents`}`
+    )
+
+    captureServerEvent(
+      auth.userId,
+      'knowledge_base_connector_removed',
+      {
+        knowledge_base_id: knowledgeBaseId,
+        workspace_id: kbWorkspaceId ?? '',
+        connector_type: existingConnector[0].connectorType,
+        documents_deleted: deleteDocuments ? docCount : 0,
+      },
+      kbWorkspaceId ? { groups: { workspace: kbWorkspaceId } } : undefined
+    )
+
+    recordAudit({
+      workspaceId: writeCheck.knowledgeBase.workspaceId,
+      actorId: auth.userId,
+      actorName: auth.userName,
+      actorEmail: auth.userEmail,
+      action: AuditAction.CONNECTOR_DELETED,
+      resourceType: AuditResourceType.CONNECTOR,
+      resourceId: connectorId,
+      resourceName: existingConnector[0].connectorType,
+      description: `Deleted connector from knowledge base "${writeCheck.knowledgeBase.name}"`,
+      metadata: {
+        knowledgeBaseId,
+        knowledgeBaseName: writeCheck.knowledgeBase.name,
+        connectorType: existingConnector[0].connectorType,
+        deleteDocuments,
+        documentsDeleted: deleteDocuments ? docCount : 0,
+        documentsKept: deleteDocuments ? 0 : docCount,
+      },
+      request,
+    })
+
+    return NextResponse.json({ success: true })
+  } catch (error) {
+    logger.error(`[${requestId}] Error deleting connector`, error)
+    return NextResponse.json({ error: 'Internal server error' }, { status: 500 })
+  }
+})

apps/sim/app/api/knowledge/[id]/connectors/[connectorId]/sync/route.test.ts

@@ -0,0 +1,117 @@
+/**
+ * @vitest-environment node
+ */
+import {
+  auditMock,
+  createMockRequest,
+  hybridAuthMockFns,
+  knowledgeApiUtilsMock,
+  knowledgeApiUtilsMockFns,
+  requestUtilsMockFns,
+} from '@sim/testing'
+import { beforeEach, describe, expect, it, vi } from 'vitest'
+
+const { mockDispatchSync, mockDbChain } = vi.hoisted(() => {
+  const chain = {
+    select: vi.fn().mockReturnThis(),
+    from: vi.fn().mockReturnThis(),
+    where: vi.fn().mockReturnThis(),
+    orderBy: vi.fn().mockResolvedValue([]),
+    limit: vi.fn().mockResolvedValue([]),
+    update: vi.fn().mockReturnThis(),
+    set: vi.fn().mockReturnThis(),
+  }
+  return {
+    mockDispatchSync: vi.fn().mockResolvedValue(undefined),
+    mockDbChain: chain,
+  }
+})
+
+const mockCheckWriteAccess = knowledgeApiUtilsMockFns.mockCheckKnowledgeBaseWriteAccess
+
+vi.mock('@sim/db', () => ({ db: mockDbChain }))
+vi.mock('@/app/api/knowledge/utils', () => knowledgeApiUtilsMock)
+vi.mock('@/lib/knowledge/connectors/sync-engine', () => ({
+  dispatchSync: mockDispatchSync,
+}))
+vi.mock('@sim/audit', () => auditMock)
+
+import { POST } from '@/app/api/knowledge/[id]/connectors/[connectorId]/sync/route'
+
+describe('Connector Manual Sync API Route', () => {
+  const mockParams = Promise.resolve({ id: 'kb-123', connectorId: 'conn-456' })
+
+  beforeEach(() => {
+    vi.clearAllMocks()
+    requestUtilsMockFns.mockGenerateRequestId.mockReturnValue('test-req-id')
+    mockDbChain.select.mockReturnThis()
+    mockDbChain.from.mockReturnThis()
+    mockDbChain.where.mockReturnThis()
+    mockDbChain.orderBy.mockResolvedValue([])
+    mockDbChain.limit.mockResolvedValue([])
+    mockDbChain.update.mockReturnThis()
+    mockDbChain.set.mockReturnThis()
+  })
+
+  it('returns 401 when unauthenticated', async () => {
+    hybridAuthMockFns.mockCheckSessionOrInternalAuth.mockResolvedValue({
+      success: false,
+      userId: null,
+    })
+
+    const req = createMockRequest('POST')
+    const response = await POST(req as never, { params: mockParams })
+
+    expect(response.status).toBe(401)
+  })
+
+  it('returns 404 when connector not found', async () => {
+    hybridAuthMockFns.mockCheckSessionOrInternalAuth.mockResolvedValue({
+      success: true,
+      userId: 'user-1',
+    })
+    mockCheckWriteAccess.mockResolvedValue({ hasAccess: true })
+    mockDbChain.limit.mockResolvedValueOnce([])
+
+    const req = createMockRequest('POST')
+    const response = await POST(req as never, { params: mockParams })
+
+    expect(response.status).toBe(404)
+  })
+
+  it('returns 409 when connector is syncing', async () => {
+    hybridAuthMockFns.mockCheckSessionOrInternalAuth.mockResolvedValue({
+      success: true,
+      userId: 'user-1',
+    })
+    mockCheckWriteAccess.mockResolvedValue({ hasAccess: true })
+    mockDbChain.limit.mockResolvedValueOnce([{ id: 'conn-456', status: 'syncing' }])
+
+    const req = createMockRequest('POST')
+    const response = await POST(req as never, { params: mockParams })
+
+    expect(response.status).toBe(409)
+  })
+
+  it('dispatches sync on valid request', async () => {
+    hybridAuthMockFns.mockCheckSessionOrInternalAuth.mockResolvedValue({
+      success: true,
+      userId: 'user-1',
+      userName: 'Test',
+      userEmail: 'test@test.com',
+    })
+    mockCheckWriteAccess.mockResolvedValue({
+      hasAccess: true,
+      knowledgeBase: { workspaceId: 'ws-1', name: 'Test KB' },
+    })
+    mockDbChain.limit.mockResolvedValueOnce([{ id: 'conn-456', status: 'active' }])
+
+    const req = createMockRequest('POST')
+    const response = await POST(req as never, { params: mockParams })
+    const data = await response.json()
+
+    expect(response.status).toBe(200)
+    expect(data.success).toBe(true)
+    expect(mockDispatchSync).toHaveBeenCalledWith('conn-456', { requestId: 'test-req-id' })
+  })
+})

apps/sim/app/api/knowledge/[id]/connectors/[connectorId]/sync/route.ts

@@ -0,0 +1,111 @@
+import { AuditAction, AuditResourceType, recordAudit } from '@sim/audit'
+import { db } from '@sim/db'
+import { knowledgeConnector } from '@sim/db/schema'
+import { createLogger } from '@sim/logger'
+import { and, eq, isNull } from 'drizzle-orm'
+import { type NextRequest, NextResponse } from 'next/server'
+import { triggerKnowledgeConnectorSyncContract } from '@/lib/api/contracts/knowledge'
+import { parseRequest } from '@/lib/api/server'
+import { checkSessionOrInternalAuth } from '@/lib/auth/hybrid'
+import { generateRequestId } from '@/lib/core/utils/request'
+import { withRouteHandler } from '@/lib/core/utils/with-route-handler'
+import { dispatchSync } from '@/lib/knowledge/connectors/sync-engine'
+import { captureServerEvent } from '@/lib/posthog/server'
+import { checkKnowledgeBaseWriteAccess } from '@/app/api/knowledge/utils'
+
+const logger = createLogger('ConnectorManualSyncAPI')
+
+type RouteParams = { params: Promise<{ id: string; connectorId: string }> }
+
+/**
+ * POST /api/knowledge/[id]/connectors/[connectorId]/sync - Trigger a manual sync
+ */
+export const POST = withRouteHandler(async (request: NextRequest, context: RouteParams) => {
+  const requestId = generateRequestId()
+  const parsed = await parseRequest(triggerKnowledgeConnectorSyncContract, request, context)
+  if (!parsed.success) return parsed.response
+  const { id: knowledgeBaseId, connectorId } = parsed.data.params
+
+  try {
+    const auth = await checkSessionOrInternalAuth(request, { requireWorkflowId: false })
+    if (!auth.success || !auth.userId) {
+      return NextResponse.json({ error: 'Unauthorized' }, { status: 401 })
+    }
+
+    const writeCheck = await checkKnowledgeBaseWriteAccess(knowledgeBaseId, auth.userId)
+    if (!writeCheck.hasAccess) {
+      const status = 'notFound' in writeCheck && writeCheck.notFound ? 404 : 401
+      return NextResponse.json({ error: status === 404 ? 'Not found' : 'Unauthorized' }, { status })
+    }
+
+    const connectorRows = await db
+      .select()
+      .from(knowledgeConnector)
+      .where(
+        and(
+          eq(knowledgeConnector.id, connectorId),
+          eq(knowledgeConnector.knowledgeBaseId, knowledgeBaseId),
+          isNull(knowledgeConnector.archivedAt),
+          isNull(knowledgeConnector.deletedAt)
+        )
+      )
+      .limit(1)
+
+    if (connectorRows.length === 0) {
+      return NextResponse.json({ error: 'Connector not found' }, { status: 404 })
+    }
+
+    if (connectorRows[0].status === 'syncing') {
+      return NextResponse.json({ error: 'Sync already in progress' }, { status: 409 })
+    }
+
+    logger.info(`[${requestId}] Manual sync triggered for connector ${connectorId}`)
+
+    const kbWorkspaceId = writeCheck.knowledgeBase.workspaceId ?? ''
+    captureServerEvent(
+      auth.userId,
+      'knowledge_base_connector_synced',
+      {
+        knowledge_base_id: knowledgeBaseId,
+        workspace_id: kbWorkspaceId,
+        connector_type: connectorRows[0].connectorType,
+      },
+      kbWorkspaceId ? { groups: { workspace: kbWorkspaceId } } : undefined
+    )
+
+    recordAudit({
+      workspaceId: writeCheck.knowledgeBase.workspaceId,
+      actorId: auth.userId,
+      actorName: auth.userName,
+      actorEmail: auth.userEmail,
+      action: AuditAction.CONNECTOR_SYNCED,
+      resourceType: AuditResourceType.CONNECTOR,
+      resourceId: connectorId,
+      resourceName: connectorRows[0].connectorType,
+      description: `Triggered manual sync for connector on knowledge base "${writeCheck.knowledgeBase.name}"`,
+      metadata: {
+        knowledgeBaseId,
+        knowledgeBaseName: writeCheck.knowledgeBase.name,
+        connectorType: connectorRows[0].connectorType,
+        connectorStatus: connectorRows[0].status,
+        syncType: 'manual',
+      },
+      request,
+    })
+
+    dispatchSync(connectorId, { requestId }).catch((error) => {
+      logger.error(
+        `[${requestId}] Failed to dispatch manual sync for connector ${connectorId}`,
+        error
+      )
+    })
+
+    return NextResponse.json({
+      success: true,
+      message: 'Sync triggered',
+    })
+  } catch (error) {
+    logger.error(`[${requestId}] Error triggering manual sync`, error)
+    return NextResponse.json({ error: 'Internal server error' }, { status: 500 })
+  }
+})

apps/sim/app/api/knowledge/[id]/connectors/route.ts

@@ -0,0 +1,320 @@
+import { AuditAction, AuditResourceType, recordAudit } from '@sim/audit'
+import { db } from '@sim/db'
+import { knowledgeBase, knowledgeBaseTagDefinitions, knowledgeConnector } from '@sim/db/schema'
+import { createLogger } from '@sim/logger'
+import { generateId } from '@sim/utils/id'
+import { and, desc, eq, isNull, sql } from 'drizzle-orm'
+import { type NextRequest, NextResponse } from 'next/server'
+import { createKnowledgeConnectorContract } from '@/lib/api/contracts/knowledge'
+import { parseRequest } from '@/lib/api/server'
+import { encryptApiKey } from '@/lib/api-key/crypto'
+import { checkSessionOrInternalAuth } from '@/lib/auth/hybrid'
+import { hasLiveSyncAccess } from '@/lib/billing/core/subscription'
+import { generateRequestId } from '@/lib/core/utils/request'
+import { withRouteHandler } from '@/lib/core/utils/with-route-handler'
+import { dispatchSync } from '@/lib/knowledge/connectors/sync-engine'
+import { allocateTagSlots } from '@/lib/knowledge/constants'
+import { createTagDefinition } from '@/lib/knowledge/tags/service'
+import { captureServerEvent } from '@/lib/posthog/server'
+import { getCredential } from '@/app/api/auth/oauth/utils'
+import { checkKnowledgeBaseAccess, checkKnowledgeBaseWriteAccess } from '@/app/api/knowledge/utils'
+import { CONNECTOR_REGISTRY } from '@/connectors/registry.server'
+
+const logger = createLogger('KnowledgeConnectorsAPI')
+
+/**
+ * GET /api/knowledge/[id]/connectors - List connectors for a knowledge base
+ */
+export const GET = withRouteHandler(
+  async (request: NextRequest, { params }: { params: Promise<{ id: string }> }) => {
+    const requestId = generateRequestId()
+    const { id: knowledgeBaseId } = await params
+
+    try {
+      const auth = await checkSessionOrInternalAuth(request, { requireWorkflowId: false })
+      if (!auth.success || !auth.userId) {
+        return NextResponse.json({ error: 'Unauthorized' }, { status: 401 })
+      }
+
+      const accessCheck = await checkKnowledgeBaseAccess(knowledgeBaseId, auth.userId)
+      if (!accessCheck.hasAccess) {
+        const status = 'notFound' in accessCheck && accessCheck.notFound ? 404 : 401
+        return NextResponse.json(
+          { error: status === 404 ? 'Not found' : 'Unauthorized' },
+          { status }
+        )
+      }
+
+      const connectors = await db
+        .select()
+        .from(knowledgeConnector)
+        .where(
+          and(
+            eq(knowledgeConnector.knowledgeBaseId, knowledgeBaseId),
+            isNull(knowledgeConnector.archivedAt),
+            isNull(knowledgeConnector.deletedAt)
+          )
+        )
+        .orderBy(desc(knowledgeConnector.createdAt))
+
+      return NextResponse.json({
+        success: true,
+        data: connectors.map(({ encryptedApiKey: _, ...rest }) => rest),
+      })
+    } catch (error) {
+      logger.error(`[${requestId}] Error listing connectors`, error)
+      return NextResponse.json({ error: 'Internal server error' }, { status: 500 })
+    }
+  }
+)
+
+/**
+ * POST /api/knowledge/[id]/connectors - Create a new connector
+ */
+export const POST = withRouteHandler(
+  async (request: NextRequest, context: { params: Promise<{ id: string }> }) => {
+    const requestId = generateRequestId()
+    const { id: knowledgeBaseId } = await context.params
+
+    try {
+      const auth = await checkSessionOrInternalAuth(request, { requireWorkflowId: false })
+      if (!auth.success || !auth.userId) {
+        return NextResponse.json({ error: 'Unauthorized' }, { status: 401 })
+      }
+
+      const writeCheck = await checkKnowledgeBaseWriteAccess(knowledgeBaseId, auth.userId)
+      if (!writeCheck.hasAccess) {
+        const status = 'notFound' in writeCheck && writeCheck.notFound ? 404 : 401
+        return NextResponse.json(
+          { error: status === 404 ? 'Not found' : 'Unauthorized' },
+          { status }
+        )
+      }
+
+      const parsed = await parseRequest(createKnowledgeConnectorContract, request, context)
+      if (!parsed.success) return parsed.response
+
+      const { connectorType, credentialId, apiKey, sourceConfig, syncIntervalMinutes } =
+        parsed.data.body
+
+      if (syncIntervalMinutes > 0 && syncIntervalMinutes < 60) {
+        const canUseLiveSync = await hasLiveSyncAccess(auth.userId)
+        if (!canUseLiveSync) {
+          return NextResponse.json(
+            { error: 'Live sync requires a Max or Enterprise plan' },
+            { status: 403 }
+          )
+        }
+      }
+
+      const connectorConfig = CONNECTOR_REGISTRY[connectorType]
+      if (!connectorConfig) {
+        return NextResponse.json(
+          { error: `Unknown connector type: ${connectorType}` },
+          { status: 400 }
+        )
+      }
+
+      let resolvedCredentialId: string | null = null
+      let resolvedEncryptedApiKey: string | null = null
+      let accessToken: string
+
+      if (connectorConfig.auth.mode === 'apiKey') {
+        if (!apiKey) {
+          return NextResponse.json({ error: 'API key is required' }, { status: 400 })
+        }
+        accessToken = apiKey
+      } else {
+        if (!credentialId) {
+          return NextResponse.json({ error: 'Credential is required' }, { status: 400 })
+        }
+
+        const credential = await getCredential(requestId, credentialId, auth.userId)
+        if (!credential) {
+          return NextResponse.json({ error: 'Credential not found' }, { status: 400 })
+        }
+
+        if (!credential.accessToken) {
+          return NextResponse.json(
+            { error: 'Credential has no access token. Please reconnect your account.' },
+            { status: 400 }
+          )
+        }
+
+        accessToken = credential.accessToken
+        resolvedCredentialId = credentialId
+      }
+
+      const configValidation = await connectorConfig.validateConfig(accessToken, sourceConfig)
+      if (!configValidation.valid) {
+        return NextResponse.json(
+          { error: configValidation.error || 'Invalid source configuration' },
+          { status: 400 }
+        )
+      }
+
+      let finalSourceConfig: Record<string, unknown> = { ...sourceConfig }
+
+      if (connectorConfig.auth.mode === 'apiKey' && apiKey) {
+        const { encrypted } = await encryptApiKey(apiKey)
+        resolvedEncryptedApiKey = encrypted
+      }
+
+      const tagSlotMapping: Record<string, string> = {}
+      let newTagSlots: Record<string, string> = {}
+
+      if (connectorConfig.tagDefinitions?.length) {
+        const disabledIds = new Set((sourceConfig.disabledTagIds as string[] | undefined) ?? [])
+        const enabledDefs = connectorConfig.tagDefinitions.filter((td) => !disabledIds.has(td.id))
+
+        const existingDefs = await db
+          .select({
+            tagSlot: knowledgeBaseTagDefinitions.tagSlot,
+            displayName: knowledgeBaseTagDefinitions.displayName,
+            fieldType: knowledgeBaseTagDefinitions.fieldType,
+          })
+          .from(knowledgeBaseTagDefinitions)
+          .where(eq(knowledgeBaseTagDefinitions.knowledgeBaseId, knowledgeBaseId))
+
+        const usedSlots = new Set<string>(existingDefs.map((d) => d.tagSlot))
+        const existingByName = new Map(
+          existingDefs.map((d) => [d.displayName, { tagSlot: d.tagSlot, fieldType: d.fieldType }])
+        )
+
+        const defsNeedingSlots: typeof enabledDefs = []
+        for (const td of enabledDefs) {
+          const existing = existingByName.get(td.displayName)
+          if (existing && existing.fieldType === td.fieldType) {
+            tagSlotMapping[td.id] = existing.tagSlot
+          } else {
+            defsNeedingSlots.push(td)
+          }
+        }
+
+        const { mapping, skipped: skippedTags } = allocateTagSlots(defsNeedingSlots, usedSlots)
+        Object.assign(tagSlotMapping, mapping)
+        newTagSlots = mapping
+
+        for (const name of skippedTags) {
+          logger.warn(`[${requestId}] No available slots for "${name}"`)
+        }
+
+        if (skippedTags.length > 0 && Object.keys(tagSlotMapping).length === 0) {
+          return NextResponse.json(
+            { error: `No available tag slots. Could not assign: ${skippedTags.join(', ')}` },
+            { status: 422 }
+          )
+        }
+
+        finalSourceConfig = { ...finalSourceConfig, tagSlotMapping }
+      }
+
+      const now = new Date()
+      const connectorId = generateId()
+      const nextSyncAt =
+        syncIntervalMinutes > 0 ? new Date(now.getTime() + syncIntervalMinutes * 60 * 1000) : null
+
+      await db.transaction(async (tx) => {
+        await tx.execute(sql`SELECT 1 FROM knowledge_base WHERE id = ${knowledgeBaseId} FOR UPDATE`)
+
+        const activeKb = await tx
+          .select({ id: knowledgeBase.id })
+          .from(knowledgeBase)
+          .where(and(eq(knowledgeBase.id, knowledgeBaseId), isNull(knowledgeBase.deletedAt)))
+          .limit(1)
+
+        if (activeKb.length === 0) {
+          throw new Error('Knowledge base not found')
+        }
+
+        for (const [semanticId, slot] of Object.entries(newTagSlots)) {
+          const td = connectorConfig.tagDefinitions!.find((d) => d.id === semanticId)!
+          await createTagDefinition(
+            {
+              knowledgeBaseId,
+              tagSlot: slot,
+              displayName: td.displayName,
+              fieldType: td.fieldType,
+            },
+            requestId,
+            tx
+          )
+        }
+
+        await tx.insert(knowledgeConnector).values({
+          id: connectorId,
+          knowledgeBaseId,
+          connectorType,
+          credentialId: resolvedCredentialId,
+          encryptedApiKey: resolvedEncryptedApiKey,
+          sourceConfig: finalSourceConfig,
+          syncIntervalMinutes,
+          status: 'active',
+          nextSyncAt,
+          createdAt: now,
+          updatedAt: now,
+        })
+      })
+
+      logger.info(`[${requestId}] Created connector ${connectorId} for KB ${knowledgeBaseId}`)
+
+      const kbWorkspaceId = writeCheck.knowledgeBase.workspaceId ?? ''
+      captureServerEvent(
+        auth.userId,
+        'knowledge_base_connector_added',
+        {
+          knowledge_base_id: knowledgeBaseId,
+          workspace_id: kbWorkspaceId,
+          connector_type: connectorType,
+          sync_interval_minutes: syncIntervalMinutes,
+        },
+        {
+          groups: kbWorkspaceId ? { workspace: kbWorkspaceId } : undefined,
+          setOnce: { first_connector_added_at: new Date().toISOString() },
+        }
+      )
+
+      recordAudit({
+        workspaceId: writeCheck.knowledgeBase.workspaceId,
+        actorId: auth.userId,
+        actorName: auth.userName,
+        actorEmail: auth.userEmail,
+        action: AuditAction.CONNECTOR_CREATED,
+        resourceType: AuditResourceType.CONNECTOR,
+        resourceId: connectorId,
+        resourceName: connectorType,
+        description: `Created ${connectorType} connector for knowledge base "${writeCheck.knowledgeBase.name}"`,
+        metadata: {
+          knowledgeBaseId,
+          knowledgeBaseName: writeCheck.knowledgeBase.name,
+          connectorType,
+          syncIntervalMinutes,
+          authMode: connectorConfig.auth.mode,
+        },
+        request,
+      })
+
+      dispatchSync(connectorId, { requestId }).catch((error) => {
+        logger.error(
+          `[${requestId}] Failed to dispatch initial sync for connector ${connectorId}`,
+          error
+        )
+      })
+
+      const created = await db
+        .select()
+        .from(knowledgeConnector)
+        .where(eq(knowledgeConnector.id, connectorId))
+        .limit(1)
+
+      const { encryptedApiKey: _, ...createdData } = created[0]
+      return NextResponse.json({ success: true, data: createdData }, { status: 201 })
+    } catch (error) {
+      if (error instanceof Error && error.message === 'Knowledge base not found') {
+        return NextResponse.json({ error: 'Not found' }, { status: 404 })
+      }
+      logger.error(`[${requestId}] Error creating connector`, error)
+      return NextResponse.json({ error: 'Internal server error' }, { status: 500 })
+    }
+  }
+)

apps/sim/app/api/knowledge/[id]/documents/[documentId]/chunks/[chunkId]/route.ts

@@ -0,0 +1,195 @@
+import { createLogger } from '@sim/logger'
+import { generateId } from '@sim/utils/id'
+import { type NextRequest, NextResponse } from 'next/server'
+import { updateKnowledgeChunkContract } from '@/lib/api/contracts/knowledge'
+import { parseRequest } from '@/lib/api/server'
+import { getSession } from '@/lib/auth'
+import { withRouteHandler } from '@/lib/core/utils/with-route-handler'
+import { deleteChunk, updateChunk } from '@/lib/knowledge/chunks/service'
+import { checkChunkAccess, checkChunkWriteAccess } from '@/app/api/knowledge/utils'
+
+const logger = createLogger('ChunkByIdAPI')
+
+export const GET = withRouteHandler(
+  async (
+    req: NextRequest,
+    { params }: { params: Promise<{ id: string; documentId: string; chunkId: string }> }
+  ) => {
+    const requestId = generateId().slice(0, 8)
+    const { id: knowledgeBaseId, documentId, chunkId } = await params
+
+    try {
+      const session = await getSession()
+      if (!session?.user?.id) {
+        logger.warn(`[${requestId}] Unauthorized chunk access attempt`)
+        return NextResponse.json({ error: 'Unauthorized' }, { status: 401 })
+      }
+
+      const accessCheck = await checkChunkAccess(
+        knowledgeBaseId,
+        documentId,
+        chunkId,
+        session.user.id
+      )
+
+      if (!accessCheck.hasAccess) {
+        if (accessCheck.notFound) {
+          logger.warn(
+            `[${requestId}] ${accessCheck.reason}: KB=${knowledgeBaseId}, Doc=${documentId}, Chunk=${chunkId}`
+          )
+          return NextResponse.json({ error: accessCheck.reason }, { status: 404 })
+        }
+        logger.warn(
+          `[${requestId}] User ${session.user.id} attempted unauthorized chunk access: ${accessCheck.reason}`
+        )
+        return NextResponse.json({ error: 'Unauthorized' }, { status: 401 })
+      }
+
+      logger.info(
+        `[${requestId}] Retrieved chunk: ${chunkId} from document ${documentId} in knowledge base ${knowledgeBaseId}`
+      )
+
+      return NextResponse.json({
+        success: true,
+        data: accessCheck.chunk,
+      })
+    } catch (error) {
+      logger.error(`[${requestId}] Error fetching chunk`, error)
+      return NextResponse.json({ error: 'Failed to fetch chunk' }, { status: 500 })
+    }
+  }
+)
+
+export const PUT = withRouteHandler(
+  async (
+    req: NextRequest,
+    context: { params: Promise<{ id: string; documentId: string; chunkId: string }> }
+  ) => {
+    const requestId = generateId().slice(0, 8)
+    const { id: knowledgeBaseId, documentId, chunkId } = await context.params
+
+    try {
+      const session = await getSession()
+      if (!session?.user?.id) {
+        logger.warn(`[${requestId}] Unauthorized chunk update attempt`)
+        return NextResponse.json({ error: 'Unauthorized' }, { status: 401 })
+      }
+
+      const accessCheck = await checkChunkWriteAccess(
+        knowledgeBaseId,
+        documentId,
+        chunkId,
+        session.user.id
+      )
+
+      if (!accessCheck.hasAccess) {
+        if (accessCheck.notFound) {
+          logger.warn(
+            `[${requestId}] ${accessCheck.reason}: KB=${knowledgeBaseId}, Doc=${documentId}, Chunk=${chunkId}`
+          )
+          return NextResponse.json({ error: accessCheck.reason }, { status: 404 })
+        }
+        logger.warn(
+          `[${requestId}] User ${session.user.id} attempted unauthorized chunk update: ${accessCheck.reason}`
+        )
+        return NextResponse.json({ error: 'Unauthorized' }, { status: 401 })
+      }
+
+      if (accessCheck.document?.connectorId) {
+        logger.warn(
+          `[${requestId}] User ${session.user.id} attempted to update chunk on connector-synced document: Doc=${documentId}`
+        )
+        return NextResponse.json(
+          { error: 'Chunks from connector-synced documents are read-only' },
+          { status: 403 }
+        )
+      }
+
+      const parsed = await parseRequest(updateKnowledgeChunkContract, req, context)
+      if (!parsed.success) return parsed.response
+
+      const validatedData = parsed.data.body
+
+      const updatedChunk = await updateChunk(
+        chunkId,
+        validatedData,
+        requestId,
+        accessCheck.knowledgeBase?.workspaceId
+      )
+
+      logger.info(
+        `[${requestId}] Chunk updated: ${chunkId} in document ${documentId} in knowledge base ${knowledgeBaseId}`
+      )
+
+      return NextResponse.json({
+        success: true,
+        data: updatedChunk,
+      })
+    } catch (error) {
+      logger.error(`[${requestId}] Error updating chunk`, error)
+      return NextResponse.json({ error: 'Failed to update chunk' }, { status: 500 })
+    }
+  }
+)
+
+export const DELETE = withRouteHandler(
+  async (
+    req: NextRequest,
+    { params }: { params: Promise<{ id: string; documentId: string; chunkId: string }> }
+  ) => {
+    const requestId = generateId().slice(0, 8)
+    const { id: knowledgeBaseId, documentId, chunkId } = await params
+
+    try {
+      const session = await getSession()
+      if (!session?.user?.id) {
+        logger.warn(`[${requestId}] Unauthorized chunk delete attempt`)
+        return NextResponse.json({ error: 'Unauthorized' }, { status: 401 })
+      }
+
+      const accessCheck = await checkChunkWriteAccess(
+        knowledgeBaseId,
+        documentId,
+        chunkId,
+        session.user.id
+      )
+
+      if (!accessCheck.hasAccess) {
+        if (accessCheck.notFound) {
+          logger.warn(
+            `[${requestId}] ${accessCheck.reason}: KB=${knowledgeBaseId}, Doc=${documentId}, Chunk=${chunkId}`
+          )
+          return NextResponse.json({ error: accessCheck.reason }, { status: 404 })
+        }
+        logger.warn(
+          `[${requestId}] User ${session.user.id} attempted unauthorized chunk deletion: ${accessCheck.reason}`
+        )
+        return NextResponse.json({ error: 'Unauthorized' }, { status: 401 })
+      }
+
+      if (accessCheck.document?.connectorId) {
+        logger.warn(
+          `[${requestId}] User ${session.user.id} attempted to delete chunk on connector-synced document: Doc=${documentId}`
+        )
+        return NextResponse.json(
+          { error: 'Chunks from connector-synced documents are read-only' },
+          { status: 403 }
+        )
+      }
+
+      await deleteChunk(chunkId, documentId, requestId)
+
+      logger.info(
+        `[${requestId}] Chunk deleted: ${chunkId} from document ${documentId} in knowledge base ${knowledgeBaseId}`
+      )
+
+      return NextResponse.json({
+        success: true,
+        data: { message: 'Chunk deleted successfully' },
+      })
+    } catch (error) {
+      logger.error(`[${requestId}] Error deleting chunk`, error)
+      return NextResponse.json({ error: 'Failed to delete chunk' }, { status: 500 })
+    }
+  }
+)

apps/sim/app/api/knowledge/[id]/documents/[documentId]/chunks/route.ts

@@ -0,0 +1,334 @@
+import { createLogger } from '@sim/logger'
+import { authorizeWorkflowByWorkspacePermission } from '@sim/platform-authz/workflow'
+import { getErrorMessage } from '@sim/utils/errors'
+import { type NextRequest, NextResponse } from 'next/server'
+import {
+  bulkKnowledgeChunksContract,
+  createChunkBodySchema,
+  listKnowledgeChunksQuerySchema,
+} from '@/lib/api/contracts/knowledge'
+import { isZodError, parseJsonBody, parseRequest } from '@/lib/api/server'
+import { checkSessionOrInternalAuth } from '@/lib/auth/hybrid'
+import { generateRequestId } from '@/lib/core/utils/request'
+import { withRouteHandler } from '@/lib/core/utils/with-route-handler'
+import { batchChunkOperation, createChunk, queryChunks } from '@/lib/knowledge/chunks/service'
+import { checkDocumentAccess, checkDocumentWriteAccess } from '@/app/api/knowledge/utils'
+import { calculateCost } from '@/providers/utils'
+
+const logger = createLogger('DocumentChunksAPI')
+
+export const GET = withRouteHandler(
+  async (req: NextRequest, { params }: { params: Promise<{ id: string; documentId: string }> }) => {
+    const requestId = generateRequestId()
+    const { id: knowledgeBaseId, documentId } = await params
+
+    try {
+      const auth = await checkSessionOrInternalAuth(req, { requireWorkflowId: false })
+      if (!auth.success || !auth.userId) {
+        logger.warn(`[${requestId}] Unauthorized chunks access attempt`)
+        return NextResponse.json({ error: 'Unauthorized' }, { status: 401 })
+      }
+      const userId = auth.userId
+
+      const accessCheck = await checkDocumentAccess(knowledgeBaseId, documentId, userId)
+
+      if (!accessCheck.hasAccess) {
+        if (accessCheck.notFound) {
+          logger.warn(
+            `[${requestId}] ${accessCheck.reason}: KB=${knowledgeBaseId}, Doc=${documentId}`
+          )
+          return NextResponse.json({ error: accessCheck.reason }, { status: 404 })
+        }
+        logger.warn(
+          `[${requestId}] User ${userId} attempted unauthorized chunks access: ${accessCheck.reason}`
+        )
+        return NextResponse.json({ error: 'Unauthorized' }, { status: 401 })
+      }
+
+      const doc = accessCheck.document
+      if (!doc) {
+        logger.warn(
+          `[${requestId}] Document data not available: KB=${knowledgeBaseId}, Doc=${documentId}`
+        )
+        return NextResponse.json({ error: 'Document not found' }, { status: 404 })
+      }
+
+      if (doc.processingStatus !== 'completed') {
+        logger.warn(
+          `[${requestId}] Document ${documentId} is not ready for chunk access (status: ${doc.processingStatus})`
+        )
+        return NextResponse.json(
+          {
+            error: 'Document is not ready for access',
+            details: `Document status: ${doc.processingStatus}`,
+            retryAfter: doc.processingStatus === 'processing' ? 5 : null,
+          },
+          { status: 400 }
+        )
+      }
+
+      const { searchParams } = new URL(req.url)
+      const queryResult = listKnowledgeChunksQuerySchema.safeParse({
+        search: searchParams.get('search') || undefined,
+        enabled: searchParams.get('enabled') || undefined,
+        limit: searchParams.get('limit') || undefined,
+        offset: searchParams.get('offset') || undefined,
+        sortBy: searchParams.get('sortBy') || undefined,
+        sortOrder: searchParams.get('sortOrder') || undefined,
+      })
+      if (!queryResult.success) {
+        return NextResponse.json(
+          { error: 'Invalid query parameters', details: queryResult.error.issues },
+          { status: 400 }
+        )
+      }
+
+      const result = await queryChunks(documentId, queryResult.data, requestId)
+
+      return NextResponse.json({
+        success: true,
+        data: result.chunks,
+        pagination: result.pagination,
+      })
+    } catch (error) {
+      logger.error(`[${requestId}] Error fetching chunks`, error)
+      return NextResponse.json({ error: 'Failed to fetch chunks' }, { status: 500 })
+    }
+  }
+)
+
+export const POST = withRouteHandler(
+  async (req: NextRequest, { params }: { params: Promise<{ id: string; documentId: string }> }) => {
+    const requestId = generateRequestId()
+    const { id: knowledgeBaseId, documentId } = await params
+
+    try {
+      const auth = await checkSessionOrInternalAuth(req, { requireWorkflowId: false })
+      if (!auth.success || !auth.userId) {
+        logger.warn(`[${requestId}] Authentication failed: ${auth.error || 'Unauthorized'}`)
+        return NextResponse.json({ error: 'Unauthorized' }, { status: 401 })
+      }
+      const userId = auth.userId
+
+      const parsedBody = await parseJsonBody(req)
+      if (!parsedBody.success) return parsedBody.response
+      const { workflowId, ...searchParams } = parsedBody.data as Record<string, unknown>
+
+      if (workflowId) {
+        if (typeof workflowId !== 'string') {
+          return NextResponse.json({ error: 'workflowId must be a string' }, { status: 400 })
+        }
+        const authorization = await authorizeWorkflowByWorkspacePermission({
+          workflowId,
+          userId,
+          action: 'write',
+        })
+        if (!authorization.allowed) {
+          return NextResponse.json(
+            { error: authorization.message || 'Access denied' },
+            { status: authorization.status }
+          )
+        }
+      }
+
+      const accessCheck = await checkDocumentWriteAccess(knowledgeBaseId, documentId, userId)
+
+      if (!accessCheck.hasAccess) {
+        if (accessCheck.notFound) {
+          logger.warn(
+            `[${requestId}] ${accessCheck.reason}: KB=${knowledgeBaseId}, Doc=${documentId}`
+          )
+          return NextResponse.json({ error: accessCheck.reason }, { status: 404 })
+        }
+        logger.warn(
+          `[${requestId}] User ${userId} attempted unauthorized chunk creation: ${accessCheck.reason}`
+        )
+        return NextResponse.json({ error: 'Unauthorized' }, { status: 401 })
+      }
+
+      const doc = accessCheck.document
+      if (!doc) {
+        logger.warn(
+          `[${requestId}] Document data not available: KB=${knowledgeBaseId}, Doc=${documentId}`
+        )
+        return NextResponse.json({ error: 'Document not found' }, { status: 404 })
+      }
+
+      if (doc.connectorId) {
+        logger.warn(
+          `[${requestId}] User ${userId} attempted to create chunk on connector-synced document: Doc=${documentId}`
+        )
+        return NextResponse.json(
+          { error: 'Chunks from connector-synced documents are read-only' },
+          { status: 403 }
+        )
+      }
+
+      if (doc.processingStatus === 'failed') {
+        logger.warn(`[${requestId}] Document ${documentId} is in failed state, cannot add chunks`)
+        return NextResponse.json({ error: 'Cannot add chunks to failed document' }, { status: 400 })
+      }
+
+      try {
+        const validatedData = createChunkBodySchema.parse(searchParams)
+
+        const docTags = {
+          tag1: doc.tag1 ?? null,
+          tag2: doc.tag2 ?? null,
+          tag3: doc.tag3 ?? null,
+          tag4: doc.tag4 ?? null,
+          tag5: doc.tag5 ?? null,
+          tag6: doc.tag6 ?? null,
+          tag7: doc.tag7 ?? null,
+          number1: doc.number1 ?? null,
+          number2: doc.number2 ?? null,
+          number3: doc.number3 ?? null,
+          number4: doc.number4 ?? null,
+          number5: doc.number5 ?? null,
+          date1: doc.date1 ?? null,
+          date2: doc.date2 ?? null,
+          boolean1: doc.boolean1 ?? null,
+          boolean2: doc.boolean2 ?? null,
+          boolean3: doc.boolean3 ?? null,
+        }
+
+        const newChunk = await createChunk(
+          knowledgeBaseId,
+          documentId,
+          docTags,
+          validatedData,
+          requestId,
+          accessCheck.knowledgeBase?.workspaceId
+        )
+
+        let cost = null
+        try {
+          cost = calculateCost(
+            accessCheck.knowledgeBase.embeddingModel,
+            newChunk.tokenCount,
+            0,
+            false
+          )
+        } catch (error) {
+          logger.warn(`[${requestId}] Failed to calculate cost for chunk upload`, {
+            error: getErrorMessage(error, 'Unknown error'),
+          })
+        }
+
+        return NextResponse.json({
+          success: true,
+          data: {
+            ...newChunk,
+            documentId,
+            documentName: doc.filename,
+            ...(cost
+              ? {
+                  cost: {
+                    input: cost.input,
+                    output: cost.output,
+                    total: cost.total,
+                    tokens: {
+                      prompt: newChunk.tokenCount,
+                      completion: 0,
+                      total: newChunk.tokenCount,
+                    },
+                    model: accessCheck.knowledgeBase.embeddingModel,
+                    pricing: cost.pricing,
+                  },
+                }
+              : {}),
+          },
+        })
+      } catch (validationError) {
+        if (isZodError(validationError)) {
+          logger.warn(`[${requestId}] Invalid chunk creation data`, {
+            errors: validationError.issues,
+          })
+          return NextResponse.json(
+            { error: 'Invalid request data', details: validationError.issues },
+            { status: 400 }
+          )
+        }
+        throw validationError
+      }
+    } catch (error) {
+      logger.error(`[${requestId}] Error creating chunk`, error)
+      return NextResponse.json({ error: 'Failed to create chunk' }, { status: 500 })
+    }
+  }
+)
+
+export const PATCH = withRouteHandler(
+  async (req: NextRequest, { params }: { params: Promise<{ id: string; documentId: string }> }) => {
+    const requestId = generateRequestId()
+    const { id: knowledgeBaseId, documentId } = await params
+
+    try {
+      const auth = await checkSessionOrInternalAuth(req, { requireWorkflowId: false })
+      if (!auth.success || !auth.userId) {
+        logger.warn(`[${requestId}] Unauthorized batch chunk operation attempt`)
+        return NextResponse.json({ error: 'Unauthorized' }, { status: 401 })
+      }
+      const userId = auth.userId
+
+      const accessCheck = await checkDocumentWriteAccess(knowledgeBaseId, documentId, userId)
+
+      if (!accessCheck.hasAccess) {
+        if (accessCheck.notFound) {
+          logger.warn(
+            `[${requestId}] ${accessCheck.reason}: KB=${knowledgeBaseId}, Doc=${documentId}`
+          )
+          return NextResponse.json({ error: accessCheck.reason }, { status: 404 })
+        }
+        logger.warn(
+          `[${requestId}] User ${userId} attempted unauthorized batch chunk operation: ${accessCheck.reason}`
+        )
+        return NextResponse.json({ error: 'Unauthorized' }, { status: 401 })
+      }
+
+      if (accessCheck.document?.connectorId) {
+        logger.warn(
+          `[${requestId}] User ${userId} attempted batch chunk operation on connector-synced document: Doc=${documentId}`
+        )
+        return NextResponse.json(
+          { error: 'Chunks from connector-synced documents are read-only' },
+          { status: 403 }
+        )
+      }
+
+      const parsed = await parseRequest(
+        bulkKnowledgeChunksContract,
+        req,
+        { params },
+        {
+          validationErrorResponse: (error) => {
+            logger.warn(`[${requestId}] Invalid batch operation data`, { errors: error.issues })
+            return NextResponse.json(
+              { error: 'Invalid request data', details: error.issues },
+              { status: 400 }
+            )
+          },
+        }
+      )
+      if (!parsed.success) return parsed.response
+      const validatedData = parsed.data.body
+      const { operation, chunkIds } = validatedData
+
+      const result = await batchChunkOperation(documentId, operation, chunkIds, requestId)
+
+      return NextResponse.json({
+        success: true,
+        data: {
+          operation,
+          successCount: result.processed,
+          errorCount: result.errors.length,
+          processed: result.processed,
+          errors: result.errors,
+        },
+      })
+    } catch (error) {
+      logger.error(`[${requestId}] Error in batch chunk operation`, error)
+      return NextResponse.json({ error: 'Failed to perform batch operation' }, { status: 500 })
+    }
+  }
+)

apps/sim/app/api/knowledge/[id]/documents/[documentId]/route.test.ts

@@ -0,0 +1,560 @@
+/**
+ * Tests for document by ID API route
+ *
+ * @vitest-environment node
+ */
+import { auditMock, authMockFns, createMockRequest, knowledgeApiUtilsMock } from '@sim/testing'
+import { afterEach, beforeEach, describe, expect, it, vi } from 'vitest'
+
+const { mockDbChain } = vi.hoisted(() => {
+  const mockDbChain = {
+    select: vi.fn().mockReturnThis(),
+    from: vi.fn().mockReturnThis(),
+    where: vi.fn().mockReturnThis(),
+    limit: vi.fn().mockReturnThis(),
+    update: vi.fn().mockReturnThis(),
+    set: vi.fn().mockReturnThis(),
+    delete: vi.fn().mockReturnThis(),
+    transaction: vi.fn(),
+  }
+  return { mockDbChain }
+})
+
+vi.mock('@sim/db', () => ({
+  db: mockDbChain,
+}))
+
+vi.mock('@/app/api/knowledge/utils', () => knowledgeApiUtilsMock)
+
+vi.mock('@/lib/knowledge/documents/service', () => ({
+  updateDocument: vi.fn(),
+  deleteDocument: vi.fn(),
+  markDocumentAsFailedTimeout: vi.fn(),
+  retryDocumentProcessing: vi.fn(),
+  processDocumentAsync: vi.fn(),
+}))
+
+vi.mock('@sim/audit', () => auditMock)
+
+import {
+  deleteDocument,
+  markDocumentAsFailedTimeout,
+  retryDocumentProcessing,
+  updateDocument,
+} from '@/lib/knowledge/documents/service'
+import { DELETE, GET, PUT } from '@/app/api/knowledge/[id]/documents/[documentId]/route'
+import { checkDocumentAccess, checkDocumentWriteAccess } from '@/app/api/knowledge/utils'
+
+describe('Document By ID API Route', () => {
+  const mockDocument = {
+    id: 'doc-123',
+    knowledgeBaseId: 'kb-123',
+    filename: 'test-document.pdf',
+    fileUrl: 'https://example.com/test-document.pdf',
+    fileSize: 1024,
+    mimeType: 'application/pdf',
+    chunkCount: 5,
+    tokenCount: 100,
+    characterCount: 500,
+    processingStatus: 'completed' as const,
+    processingStartedAt: new Date('2023-01-01T10:00:00Z'),
+    processingCompletedAt: new Date('2023-01-01T10:05:00Z'),
+    processingError: null,
+    enabled: true,
+    uploadedAt: new Date('2023-01-01T09:00:00Z'),
+    tag1: null,
+    tag2: null,
+    tag3: null,
+    tag4: null,
+    tag5: null,
+    tag6: null,
+    tag7: null,
+    number1: null,
+    number2: null,
+    number3: null,
+    number4: null,
+    number5: null,
+    date1: null,
+    date2: null,
+    boolean1: null,
+    boolean2: null,
+    boolean3: null,
+    deletedAt: null,
+  }
+
+  const resetMocks = () => {
+    vi.clearAllMocks()
+    Object.values(mockDbChain).forEach((fn) => {
+      if (typeof fn === 'function') {
+        fn.mockClear().mockReset()
+        if (fn !== mockDbChain.transaction) {
+          fn.mockReturnThis()
+        }
+      }
+    })
+  }
+
+  beforeEach(() => {
+    resetMocks()
+
+    vi.stubGlobal('crypto', {
+      randomUUID: vi.fn().mockReturnValue('mock-uuid-1234-5678'),
+    })
+  })
+
+  afterEach(() => {
+    vi.clearAllMocks()
+  })
+
+  describe('GET /api/knowledge/[id]/documents/[documentId]', () => {
+    const mockParams = Promise.resolve({ id: 'kb-123', documentId: 'doc-123' })
+
+    it('should retrieve document successfully for authenticated user', async () => {
+      authMockFns.mockGetSession.mockResolvedValue({
+        user: { id: 'user-123', email: 'test@example.com' },
+      })
+      vi.mocked(checkDocumentAccess).mockResolvedValue({
+        hasAccess: true,
+        document: mockDocument,
+        knowledgeBase: { id: 'kb-123', userId: 'user-123' },
+      })
+
+      const req = createMockRequest('GET')
+      const response = await GET(req, { params: mockParams })
+      const data = await response.json()
+
+      expect(response.status).toBe(200)
+      expect(data.success).toBe(true)
+      expect(data.data.id).toBe('doc-123')
+      expect(data.data.filename).toBe('test-document.pdf')
+      expect(vi.mocked(checkDocumentAccess)).toHaveBeenCalledWith('kb-123', 'doc-123', 'user-123')
+    })
+
+    it('should return unauthorized for unauthenticated user', async () => {
+      authMockFns.mockGetSession.mockResolvedValue(null)
+
+      const req = createMockRequest('GET')
+      const response = await GET(req, { params: mockParams })
+      const data = await response.json()
+
+      expect(response.status).toBe(401)
+      expect(data.error).toBe('Unauthorized')
+    })
+
+    it('should return not found for non-existent document', async () => {
+      authMockFns.mockGetSession.mockResolvedValue({
+        user: { id: 'user-123', email: 'test@example.com' },
+      })
+      vi.mocked(checkDocumentAccess).mockResolvedValue({
+        hasAccess: false,
+        notFound: true,
+        reason: 'Document not found',
+      })
+
+      const req = createMockRequest('GET')
+      const response = await GET(req, { params: mockParams })
+      const data = await response.json()
+
+      expect(response.status).toBe(404)
+      expect(data.error).toBe('Document not found')
+    })
+
+    it('should return unauthorized for document without access', async () => {
+      authMockFns.mockGetSession.mockResolvedValue({
+        user: { id: 'user-123', email: 'test@example.com' },
+      })
+      vi.mocked(checkDocumentAccess).mockResolvedValue({
+        hasAccess: false,
+        reason: 'Access denied',
+      })
+
+      const req = createMockRequest('GET')
+      const response = await GET(req, { params: mockParams })
+      const data = await response.json()
+
+      expect(response.status).toBe(401)
+      expect(data.error).toBe('Unauthorized')
+    })
+
+    it('should handle database errors', async () => {
+      authMockFns.mockGetSession.mockResolvedValue({
+        user: { id: 'user-123', email: 'test@example.com' },
+      })
+      vi.mocked(checkDocumentAccess).mockRejectedValue(new Error('Database error'))
+
+      const req = createMockRequest('GET')
+      const response = await GET(req, { params: mockParams })
+      const data = await response.json()
+
+      expect(response.status).toBe(500)
+      expect(data.error).toBe('Failed to fetch document')
+    })
+  })
+
+  describe('PUT /api/knowledge/[id]/documents/[documentId] - Regular Updates', () => {
+    const mockParams = Promise.resolve({ id: 'kb-123', documentId: 'doc-123' })
+    const validUpdateData = {
+      filename: 'updated-document.pdf',
+      enabled: false,
+      chunkCount: 10,
+      tokenCount: 200,
+    }
+
+    it('should update document successfully', async () => {
+      authMockFns.mockGetSession.mockResolvedValue({
+        user: { id: 'user-123', email: 'test@example.com' },
+      })
+      vi.mocked(checkDocumentWriteAccess).mockResolvedValue({
+        hasAccess: true,
+        document: mockDocument,
+        knowledgeBase: { id: 'kb-123', userId: 'user-123' },
+      })
+
+      const updatedDocument = {
+        ...mockDocument,
+        ...validUpdateData,
+        deletedAt: null,
+      }
+      vi.mocked(updateDocument).mockResolvedValue(updatedDocument)
+
+      const req = createMockRequest('PUT', validUpdateData)
+      const response = await PUT(req, { params: mockParams })
+      const data = await response.json()
+
+      expect(response.status).toBe(200)
+      expect(data.success).toBe(true)
+      expect(data.data.filename).toBe('updated-document.pdf')
+      expect(data.data.enabled).toBe(false)
+      expect(vi.mocked(updateDocument)).toHaveBeenCalledWith(
+        'doc-123',
+        validUpdateData,
+        expect.any(String)
+      )
+    })
+
+    it('should validate update data', async () => {
+      authMockFns.mockGetSession.mockResolvedValue({
+        user: { id: 'user-123', email: 'test@example.com' },
+      })
+      vi.mocked(checkDocumentWriteAccess).mockResolvedValue({
+        hasAccess: true,
+        document: mockDocument,
+        knowledgeBase: { id: 'kb-123', userId: 'user-123' },
+      })
+
+      const invalidData = {
+        filename: '', // Invalid: empty filename
+        chunkCount: -1, // Invalid: negative count
+        processingStatus: 'invalid', // Invalid: not in enum
+      }
+
+      const req = createMockRequest('PUT', invalidData)
+      const response = await PUT(req, { params: mockParams })
+      const data = await response.json()
+
+      expect(response.status).toBe(400)
+      expect(data.error).toBe('Invalid request data')
+      expect(data.details).toBeDefined()
+    })
+  })
+
+  describe('PUT /api/knowledge/[id]/documents/[documentId] - Mark Failed Due to Timeout', () => {
+    const mockParams = Promise.resolve({ id: 'kb-123', documentId: 'doc-123' })
+
+    it('should mark document as failed due to timeout successfully', async () => {
+      const processingDocument = {
+        ...mockDocument,
+        processingStatus: 'processing',
+        processingStartedAt: new Date(Date.now() - 200000), // 200 seconds ago
+      }
+
+      authMockFns.mockGetSession.mockResolvedValue({
+        user: { id: 'user-123', email: 'test@example.com' },
+      })
+      vi.mocked(checkDocumentWriteAccess).mockResolvedValue({
+        hasAccess: true,
+        document: processingDocument,
+        knowledgeBase: { id: 'kb-123', userId: 'user-123' },
+      })
+
+      vi.mocked(markDocumentAsFailedTimeout).mockResolvedValue({
+        success: true,
+        processingDuration: 200000,
+      })
+
+      const req = createMockRequest('PUT', { markFailedDueToTimeout: true })
+      const response = await PUT(req, { params: mockParams })
+      const data = await response.json()
+
+      expect(response.status).toBe(200)
+      expect(data.success).toBe(true)
+      expect(data.data.documentId).toBe('doc-123')
+      expect(data.data.status).toBe('failed')
+      expect(data.data.message).toBe('Document marked as failed due to timeout')
+      expect(vi.mocked(markDocumentAsFailedTimeout)).toHaveBeenCalledWith(
+        'doc-123',
+        processingDocument.processingStartedAt,
+        expect.any(String)
+      )
+    })
+
+    it('should reject marking failed for non-processing document', async () => {
+      authMockFns.mockGetSession.mockResolvedValue({
+        user: { id: 'user-123', email: 'test@example.com' },
+      })
+      vi.mocked(checkDocumentWriteAccess).mockResolvedValue({
+        hasAccess: true,
+        document: { ...mockDocument, processingStatus: 'completed' },
+        knowledgeBase: { id: 'kb-123', userId: 'user-123' },
+      })
+
+      const req = createMockRequest('PUT', { markFailedDueToTimeout: true })
+      const response = await PUT(req, { params: mockParams })
+      const data = await response.json()
+
+      expect(response.status).toBe(400)
+      expect(data.error).toContain('Document is not in processing state')
+    })
+
+    it('should reject marking failed for recently started processing', async () => {
+      const recentProcessingDocument = {
+        ...mockDocument,
+        processingStatus: 'processing',
+        processingStartedAt: new Date(Date.now() - 60000), // 60 seconds ago
+      }
+
+      authMockFns.mockGetSession.mockResolvedValue({
+        user: { id: 'user-123', email: 'test@example.com' },
+      })
+      vi.mocked(checkDocumentWriteAccess).mockResolvedValue({
+        hasAccess: true,
+        document: recentProcessingDocument,
+        knowledgeBase: { id: 'kb-123', userId: 'user-123' },
+      })
+
+      vi.mocked(markDocumentAsFailedTimeout).mockRejectedValue(
+        new Error('Document has not been processing long enough to be considered dead')
+      )
+
+      const req = createMockRequest('PUT', { markFailedDueToTimeout: true })
+      const response = await PUT(req, { params: mockParams })
+      const data = await response.json()
+
+      expect(response.status).toBe(400)
+      expect(data.error).toContain('Document has not been processing long enough')
+    })
+  })
+
+  describe('PUT /api/knowledge/[id]/documents/[documentId] - Retry Processing', () => {
+    const mockParams = Promise.resolve({ id: 'kb-123', documentId: 'doc-123' })
+
+    it('should retry processing successfully', async () => {
+      const failedDocument = {
+        ...mockDocument,
+        processingStatus: 'failed',
+        processingError: 'Previous processing failed',
+      }
+
+      authMockFns.mockGetSession.mockResolvedValue({
+        user: { id: 'user-123', email: 'test@example.com' },
+      })
+      vi.mocked(checkDocumentWriteAccess).mockResolvedValue({
+        hasAccess: true,
+        document: failedDocument,
+        knowledgeBase: { id: 'kb-123', userId: 'user-123' },
+      })
+
+      vi.mocked(retryDocumentProcessing).mockResolvedValue({
+        success: true,
+        status: 'pending',
+        message: 'Document retry processing started',
+      })
+
+      const req = createMockRequest('PUT', { retryProcessing: true })
+      const response = await PUT(req, { params: mockParams })
+      const data = await response.json()
+
+      expect(response.status).toBe(200)
+      expect(data.success).toBe(true)
+      expect(data.data.status).toBe('pending')
+      expect(data.data.message).toBe('Document retry processing started')
+      expect(vi.mocked(retryDocumentProcessing)).toHaveBeenCalledWith(
+        'kb-123',
+        'doc-123',
+        {
+          filename: failedDocument.filename,
+          fileUrl: failedDocument.fileUrl,
+          fileSize: failedDocument.fileSize,
+          mimeType: failedDocument.mimeType,
+        },
+        expect.any(String)
+      )
+    })
+
+    it('should reject retry for non-failed document', async () => {
+      authMockFns.mockGetSession.mockResolvedValue({
+        user: { id: 'user-123', email: 'test@example.com' },
+      })
+      vi.mocked(checkDocumentWriteAccess).mockResolvedValue({
+        hasAccess: true,
+        document: { ...mockDocument, processingStatus: 'completed' },
+        knowledgeBase: { id: 'kb-123', userId: 'user-123' },
+      })
+
+      const req = createMockRequest('PUT', { retryProcessing: true })
+      const response = await PUT(req, { params: mockParams })
+      const data = await response.json()
+
+      expect(response.status).toBe(400)
+      expect(data.error).toBe('Document is not in failed state')
+    })
+  })
+
+  describe('PUT /api/knowledge/[id]/documents/[documentId] - Authentication & Authorization', () => {
+    const mockParams = Promise.resolve({ id: 'kb-123', documentId: 'doc-123' })
+    const validUpdateData = { filename: 'updated-document.pdf' }
+
+    it('should return unauthorized for unauthenticated user', async () => {
+      authMockFns.mockGetSession.mockResolvedValue(null)
+
+      const req = createMockRequest('PUT', validUpdateData)
+      const response = await PUT(req, { params: mockParams })
+      const data = await response.json()
+
+      expect(response.status).toBe(401)
+      expect(data.error).toBe('Unauthorized')
+    })
+
+    it('should return not found for non-existent document', async () => {
+      authMockFns.mockGetSession.mockResolvedValue({
+        user: { id: 'user-123', email: 'test@example.com' },
+      })
+      vi.mocked(checkDocumentWriteAccess).mockResolvedValue({
+        hasAccess: false,
+        notFound: true,
+        reason: 'Document not found',
+      })
+
+      const req = createMockRequest('PUT', validUpdateData)
+      const response = await PUT(req, { params: mockParams })
+      const data = await response.json()
+
+      expect(response.status).toBe(404)
+      expect(data.error).toBe('Document not found')
+    })
+
+    it('should handle database errors during update', async () => {
+      authMockFns.mockGetSession.mockResolvedValue({
+        user: { id: 'user-123', email: 'test@example.com' },
+      })
+      vi.mocked(checkDocumentWriteAccess).mockResolvedValue({
+        hasAccess: true,
+        document: mockDocument,
+        knowledgeBase: { id: 'kb-123', userId: 'user-123' },
+      })
+
+      vi.mocked(updateDocument).mockRejectedValue(new Error('Database error'))
+
+      const req = createMockRequest('PUT', validUpdateData)
+      const response = await PUT(req, { params: mockParams })
+      const data = await response.json()
+
+      expect(response.status).toBe(500)
+      expect(data.error).toBe('Failed to update document')
+    })
+  })
+
+  describe('DELETE /api/knowledge/[id]/documents/[documentId]', () => {
+    const mockParams = Promise.resolve({ id: 'kb-123', documentId: 'doc-123' })
+
+    it('should delete document successfully', async () => {
+      authMockFns.mockGetSession.mockResolvedValue({
+        user: { id: 'user-123', email: 'test@example.com' },
+      })
+      vi.mocked(checkDocumentWriteAccess).mockResolvedValue({
+        hasAccess: true,
+        document: mockDocument,
+        knowledgeBase: { id: 'kb-123', userId: 'user-123' },
+      })
+
+      vi.mocked(deleteDocument).mockResolvedValue({
+        success: true,
+        message: 'Document deleted successfully',
+      })
+
+      const req = createMockRequest('DELETE')
+      const response = await DELETE(req, { params: mockParams })
+      const data = await response.json()
+
+      expect(response.status).toBe(200)
+      expect(data.success).toBe(true)
+      expect(data.data.message).toBe('Document deleted successfully')
+      expect(vi.mocked(deleteDocument)).toHaveBeenCalledWith('doc-123', expect.any(String))
+    })
+
+    it('should return unauthorized for unauthenticated user', async () => {
+      authMockFns.mockGetSession.mockResolvedValue(null)
+
+      const req = createMockRequest('DELETE')
+      const response = await DELETE(req, { params: mockParams })
+      const data = await response.json()
+
+      expect(response.status).toBe(401)
+      expect(data.error).toBe('Unauthorized')
+    })
+
+    it('should return not found for non-existent document', async () => {
+      authMockFns.mockGetSession.mockResolvedValue({
+        user: { id: 'user-123', email: 'test@example.com' },
+      })
+      vi.mocked(checkDocumentWriteAccess).mockResolvedValue({
+        hasAccess: false,
+        notFound: true,
+        reason: 'Document not found',
+      })
+
+      const req = createMockRequest('DELETE')
+      const response = await DELETE(req, { params: mockParams })
+      const data = await response.json()
+
+      expect(response.status).toBe(404)
+      expect(data.error).toBe('Document not found')
+    })
+
+    it('should return unauthorized for document without access', async () => {
+      authMockFns.mockGetSession.mockResolvedValue({
+        user: { id: 'user-123', email: 'test@example.com' },
+      })
+      vi.mocked(checkDocumentWriteAccess).mockResolvedValue({
+        hasAccess: false,
+        reason: 'Access denied',
+      })
+
+      const req = createMockRequest('DELETE')
+      const response = await DELETE(req, { params: mockParams })
+      const data = await response.json()
+
+      expect(response.status).toBe(401)
+      expect(data.error).toBe('Unauthorized')
+    })
+
+    it('should handle database errors during deletion', async () => {
+      authMockFns.mockGetSession.mockResolvedValue({
+        user: { id: 'user-123', email: 'test@example.com' },
+      })
+      vi.mocked(checkDocumentWriteAccess).mockResolvedValue({
+        hasAccess: true,
+        document: mockDocument,
+        knowledgeBase: { id: 'kb-123', userId: 'user-123' },
+      })
+      vi.mocked(deleteDocument).mockRejectedValue(new Error('Database error'))
+
+      const req = createMockRequest('DELETE')
+      const response = await DELETE(req, { params: mockParams })
+      const data = await response.json()
+
+      expect(response.status).toBe(500)
+      expect(data.error).toBe('Failed to delete document')
+    })
+  })
+})

apps/sim/app/api/knowledge/[id]/documents/[documentId]/route.ts

@@ -0,0 +1,286 @@
+import { AuditAction, AuditResourceType, recordAudit } from '@sim/audit'
+import { createLogger } from '@sim/logger'
+import { type NextRequest, NextResponse } from 'next/server'
+import { updateKnowledgeDocumentContract } from '@/lib/api/contracts/knowledge'
+import { parseRequest } from '@/lib/api/server'
+import { checkSessionOrInternalAuth } from '@/lib/auth/hybrid'
+import { generateRequestId } from '@/lib/core/utils/request'
+import { withRouteHandler } from '@/lib/core/utils/with-route-handler'
+import {
+  deleteDocument,
+  markDocumentAsFailedTimeout,
+  retryDocumentProcessing,
+  updateDocument,
+} from '@/lib/knowledge/documents/service'
+import { captureServerEvent } from '@/lib/posthog/server'
+import { checkDocumentAccess, checkDocumentWriteAccess } from '@/app/api/knowledge/utils'
+
+const logger = createLogger('DocumentByIdAPI')
+
+export const GET = withRouteHandler(
+  async (req: NextRequest, { params }: { params: Promise<{ id: string; documentId: string }> }) => {
+    const requestId = generateRequestId()
+    const { id: knowledgeBaseId, documentId } = await params
+
+    try {
+      const auth = await checkSessionOrInternalAuth(req, { requireWorkflowId: false })
+      if (!auth.success || !auth.userId) {
+        logger.warn(`[${requestId}] Unauthorized document access attempt`)
+        return NextResponse.json({ error: 'Unauthorized' }, { status: 401 })
+      }
+      const userId = auth.userId
+
+      const accessCheck = await checkDocumentAccess(knowledgeBaseId, documentId, userId)
+
+      if (!accessCheck.hasAccess) {
+        if (accessCheck.notFound) {
+          logger.warn(
+            `[${requestId}] ${accessCheck.reason}: KB=${knowledgeBaseId}, Doc=${documentId}`
+          )
+          return NextResponse.json({ error: accessCheck.reason }, { status: 404 })
+        }
+        logger.warn(
+          `[${requestId}] User ${userId} attempted unauthorized document access: ${accessCheck.reason}`
+        )
+        return NextResponse.json({ error: 'Unauthorized' }, { status: 401 })
+      }
+
+      logger.info(
+        `[${requestId}] Retrieved document: ${documentId} from knowledge base ${knowledgeBaseId}`
+      )
+
+      return NextResponse.json({
+        success: true,
+        data: accessCheck.document,
+      })
+    } catch (error) {
+      logger.error(`[${requestId}] Error fetching document`, error)
+      return NextResponse.json({ error: 'Failed to fetch document' }, { status: 500 })
+    }
+  }
+)
+
+export const PUT = withRouteHandler(
+  async (req: NextRequest, { params }: { params: Promise<{ id: string; documentId: string }> }) => {
+    const requestId = generateRequestId()
+    const { id: knowledgeBaseId, documentId } = await params
+
+    try {
+      const auth = await checkSessionOrInternalAuth(req, { requireWorkflowId: false })
+      if (!auth.success || !auth.userId) {
+        logger.warn(`[${requestId}] Unauthorized document update attempt`)
+        return NextResponse.json({ error: 'Unauthorized' }, { status: 401 })
+      }
+      const userId = auth.userId
+
+      const accessCheck = await checkDocumentWriteAccess(knowledgeBaseId, documentId, userId)
+
+      if (!accessCheck.hasAccess) {
+        if (accessCheck.notFound) {
+          logger.warn(
+            `[${requestId}] ${accessCheck.reason}: KB=${knowledgeBaseId}, Doc=${documentId}`
+          )
+          return NextResponse.json({ error: accessCheck.reason }, { status: 404 })
+        }
+        logger.warn(
+          `[${requestId}] User ${userId} attempted unauthorized document update: ${accessCheck.reason}`
+        )
+        return NextResponse.json({ error: 'Unauthorized' }, { status: 401 })
+      }
+
+      const parsed = await parseRequest(
+        updateKnowledgeDocumentContract,
+        req,
+        { params },
+        {
+          validationErrorResponse: (error) => {
+            logger.warn(`[${requestId}] Invalid document update data`, { errors: error.issues })
+            return NextResponse.json(
+              { error: 'Invalid request data', details: error.issues },
+              { status: 400 }
+            )
+          },
+        }
+      )
+      if (!parsed.success) return parsed.response
+
+      const validatedData = parsed.data.body
+
+      const updateData: any = {}
+
+      if (validatedData.markFailedDueToTimeout) {
+        const doc = accessCheck.document
+
+        if (doc.processingStatus !== 'processing') {
+          return NextResponse.json(
+            { error: `Document is not in processing state (current: ${doc.processingStatus})` },
+            { status: 400 }
+          )
+        }
+
+        if (!doc.processingStartedAt) {
+          return NextResponse.json(
+            { error: 'Document has no processing start time' },
+            { status: 400 }
+          )
+        }
+
+        try {
+          await markDocumentAsFailedTimeout(documentId, doc.processingStartedAt, requestId)
+
+          return NextResponse.json({
+            success: true,
+            data: {
+              documentId,
+              status: 'failed',
+              message: 'Document marked as failed due to timeout',
+            },
+          })
+        } catch (error) {
+          if (error instanceof Error) {
+            return NextResponse.json({ error: error.message }, { status: 400 })
+          }
+          throw error
+        }
+      } else if (validatedData.retryProcessing) {
+        const doc = accessCheck.document
+
+        if (doc.processingStatus !== 'failed') {
+          return NextResponse.json({ error: 'Document is not in failed state' }, { status: 400 })
+        }
+
+        const docData = {
+          filename: doc.filename,
+          fileUrl: doc.fileUrl,
+          fileSize: doc.fileSize,
+          mimeType: doc.mimeType,
+        }
+
+        const result = await retryDocumentProcessing(
+          knowledgeBaseId,
+          documentId,
+          docData,
+          requestId
+        )
+
+        return NextResponse.json({
+          success: true,
+          data: {
+            documentId,
+            status: result.status,
+            message: result.message,
+          },
+        })
+      } else {
+        const updatedDocument = await updateDocument(documentId, validatedData, requestId)
+
+        logger.info(
+          `[${requestId}] Document updated: ${documentId} in knowledge base ${knowledgeBaseId}`
+        )
+
+        recordAudit({
+          workspaceId: accessCheck.knowledgeBase?.workspaceId ?? null,
+          actorId: userId,
+          actorName: auth.userName,
+          actorEmail: auth.userEmail,
+          action: AuditAction.DOCUMENT_UPDATED,
+          resourceType: AuditResourceType.DOCUMENT,
+          resourceId: documentId,
+          resourceName: validatedData.filename ?? accessCheck.document?.filename,
+          description: `Updated document "${validatedData.filename ?? accessCheck.document?.filename}" in knowledge base "${knowledgeBaseId}"`,
+          metadata: {
+            knowledgeBaseId,
+            knowledgeBaseName: accessCheck.knowledgeBase?.name,
+            fileName: validatedData.filename ?? accessCheck.document?.filename,
+            updatedFields: Object.keys(validatedData).filter(
+              (k) => validatedData[k as keyof typeof validatedData] !== undefined
+            ),
+            ...(validatedData.enabled !== undefined && { enabled: validatedData.enabled }),
+          },
+          request: req,
+        })
+
+        return NextResponse.json({
+          success: true,
+          data: updatedDocument,
+        })
+      }
+    } catch (error) {
+      logger.error(`[${requestId}] Error updating document ${documentId}`, error)
+      return NextResponse.json({ error: 'Failed to update document' }, { status: 500 })
+    }
+  }
+)
+
+export const DELETE = withRouteHandler(
+  async (req: NextRequest, { params }: { params: Promise<{ id: string; documentId: string }> }) => {
+    const requestId = generateRequestId()
+    const { id: knowledgeBaseId, documentId } = await params
+
+    try {
+      const auth = await checkSessionOrInternalAuth(req, { requireWorkflowId: false })
+      if (!auth.success || !auth.userId) {
+        logger.warn(`[${requestId}] Unauthorized document delete attempt`)
+        return NextResponse.json({ error: 'Unauthorized' }, { status: 401 })
+      }
+      const userId = auth.userId
+
+      const accessCheck = await checkDocumentWriteAccess(knowledgeBaseId, documentId, userId)
+
+      if (!accessCheck.hasAccess) {
+        if (accessCheck.notFound) {
+          logger.warn(
+            `[${requestId}] ${accessCheck.reason}: KB=${knowledgeBaseId}, Doc=${documentId}`
+          )
+          return NextResponse.json({ error: accessCheck.reason }, { status: 404 })
+        }
+        logger.warn(
+          `[${requestId}] User ${userId} attempted unauthorized document deletion: ${accessCheck.reason}`
+        )
+        return NextResponse.json({ error: 'Unauthorized' }, { status: 401 })
+      }
+
+      const result = await deleteDocument(documentId, requestId)
+
+      logger.info(
+        `[${requestId}] Document deleted: ${documentId} from knowledge base ${knowledgeBaseId}`
+      )
+
+      recordAudit({
+        workspaceId: accessCheck.knowledgeBase?.workspaceId ?? null,
+        actorId: userId,
+        actorName: auth.userName,
+        actorEmail: auth.userEmail,
+        action: AuditAction.DOCUMENT_DELETED,
+        resourceType: AuditResourceType.DOCUMENT,
+        resourceId: documentId,
+        resourceName: accessCheck.document?.filename,
+        description: `Deleted document "${accessCheck.document?.filename}" from knowledge base "${knowledgeBaseId}"`,
+        metadata: {
+          knowledgeBaseId,
+          knowledgeBaseName: accessCheck.knowledgeBase?.name,
+          fileName: accessCheck.document?.filename,
+          fileSize: accessCheck.document?.fileSize,
+          mimeType: accessCheck.document?.mimeType,
+        },
+        request: req,
+      })
+
+      const kbWorkspaceId = accessCheck.knowledgeBase?.workspaceId ?? ''
+      captureServerEvent(
+        userId,
+        'knowledge_base_document_deleted',
+        { knowledge_base_id: knowledgeBaseId, workspace_id: kbWorkspaceId },
+        kbWorkspaceId ? { groups: { workspace: kbWorkspaceId } } : undefined
+      )
+
+      return NextResponse.json({
+        success: true,
+        data: result,
+      })
+    } catch (error) {
+      logger.error(`[${requestId}] Error deleting document`, error)
+      return NextResponse.json({ error: 'Failed to delete document' }, { status: 500 })
+    }
+  }
+)

apps/sim/app/api/knowledge/[id]/documents/[documentId]/tag-definitions/route.ts

@@ -0,0 +1,205 @@
+import { createLogger } from '@sim/logger'
+import { generateId } from '@sim/utils/id'
+import { type NextRequest, NextResponse } from 'next/server'
+import { saveDocumentTagDefinitionsContract } from '@/lib/api/contracts/knowledge'
+import { parseRequest } from '@/lib/api/server'
+import { getSession } from '@/lib/auth'
+import { withRouteHandler } from '@/lib/core/utils/with-route-handler'
+import { SUPPORTED_FIELD_TYPES } from '@/lib/knowledge/constants'
+import {
+  cleanupUnusedTagDefinitions,
+  createOrUpdateTagDefinitionsBulk,
+  deleteAllTagDefinitions,
+  getDocumentTagDefinitions,
+} from '@/lib/knowledge/tags/service'
+import type { BulkTagDefinitionsData } from '@/lib/knowledge/tags/types'
+import { checkDocumentAccess, checkDocumentWriteAccess } from '@/app/api/knowledge/utils'
+
+export const dynamic = 'force-dynamic'
+
+const logger = createLogger('DocumentTagDefinitionsAPI')
+
+// GET /api/knowledge/[id]/documents/[documentId]/tag-definitions - Get tag definitions for a document
+export const GET = withRouteHandler(
+  async (req: NextRequest, { params }: { params: Promise<{ id: string; documentId: string }> }) => {
+    const requestId = generateId().slice(0, 8)
+    const { id: knowledgeBaseId, documentId } = await params
+
+    try {
+      logger.info(`[${requestId}] Getting tag definitions for document ${documentId}`)
+
+      const session = await getSession()
+      if (!session?.user?.id) {
+        return NextResponse.json({ error: 'Unauthorized' }, { status: 401 })
+      }
+
+      // Verify document exists and belongs to the knowledge base
+      const accessCheck = await checkDocumentAccess(knowledgeBaseId, documentId, session.user.id)
+      if (!accessCheck.hasAccess) {
+        if (accessCheck.notFound) {
+          logger.warn(
+            `[${requestId}] ${accessCheck.reason}: KB=${knowledgeBaseId}, Doc=${documentId}`
+          )
+          return NextResponse.json({ error: accessCheck.reason }, { status: 404 })
+        }
+        logger.warn(
+          `[${requestId}] User ${session.user.id} attempted unauthorized document access: ${accessCheck.reason}`
+        )
+        return NextResponse.json({ error: 'Unauthorized' }, { status: 401 })
+      }
+
+      const tagDefinitions = await getDocumentTagDefinitions(knowledgeBaseId)
+
+      logger.info(`[${requestId}] Retrieved ${tagDefinitions.length} tag definitions`)
+
+      return NextResponse.json({
+        success: true,
+        data: tagDefinitions,
+      })
+    } catch (error) {
+      logger.error(`[${requestId}] Error getting tag definitions`, error)
+      return NextResponse.json({ error: 'Failed to get tag definitions' }, { status: 500 })
+    }
+  }
+)
+
+// POST /api/knowledge/[id]/documents/[documentId]/tag-definitions - Create/update tag definitions
+export const POST = withRouteHandler(
+  async (req: NextRequest, context: { params: Promise<{ id: string; documentId: string }> }) => {
+    const requestId = generateId().slice(0, 8)
+    const { id: knowledgeBaseId, documentId } = await context.params
+
+    try {
+      logger.info(`[${requestId}] Creating/updating tag definitions for document ${documentId}`)
+
+      const session = await getSession()
+      if (!session?.user?.id) {
+        return NextResponse.json({ error: 'Unauthorized' }, { status: 401 })
+      }
+
+      // Verify document exists and user has write access
+      const accessCheck = await checkDocumentWriteAccess(
+        knowledgeBaseId,
+        documentId,
+        session.user.id
+      )
+      if (!accessCheck.hasAccess) {
+        if (accessCheck.notFound) {
+          logger.warn(
+            `[${requestId}] ${accessCheck.reason}: KB=${knowledgeBaseId}, Doc=${documentId}`
+          )
+          return NextResponse.json({ error: accessCheck.reason }, { status: 404 })
+        }
+        logger.warn(
+          `[${requestId}] User ${session.user.id} attempted unauthorized document write access: ${accessCheck.reason}`
+        )
+        return NextResponse.json({ error: 'Unauthorized' }, { status: 401 })
+      }
+
+      const parsed = await parseRequest(saveDocumentTagDefinitionsContract, req, context)
+      if (!parsed.success) return parsed.response
+
+      const validatedData = parsed.data.body
+
+      for (const def of validatedData.definitions) {
+        /**
+         * Defense-in-depth runtime check: the contract types `fieldType` as a plain
+         * string because tightening to the field-type enum cascades into UI form
+         * state types. Cast here to allow `includes` to accept the wider input.
+         */
+        if (!(SUPPORTED_FIELD_TYPES as readonly string[]).includes(def.fieldType)) {
+          return NextResponse.json(
+            { error: 'Invalid request data', details: `Unsupported field type: ${def.fieldType}` },
+            { status: 400 }
+          )
+        }
+      }
+
+      const bulkData: BulkTagDefinitionsData = {
+        definitions: validatedData.definitions.map((def) => ({
+          tagSlot: def.tagSlot,
+          displayName: def.displayName,
+          fieldType: def.fieldType,
+          originalDisplayName: def._originalDisplayName,
+        })),
+      }
+
+      const result = await createOrUpdateTagDefinitionsBulk(knowledgeBaseId, bulkData, requestId)
+
+      return NextResponse.json({
+        success: true,
+        data: {
+          created: result.created,
+          updated: result.updated,
+          errors: result.errors,
+        },
+      })
+    } catch (error) {
+      logger.error(`[${requestId}] Error creating/updating tag definitions`, error)
+      return NextResponse.json(
+        { error: 'Failed to create/update tag definitions' },
+        { status: 500 }
+      )
+    }
+  }
+)
+
+// DELETE /api/knowledge/[id]/documents/[documentId]/tag-definitions - Delete all tag definitions for a document
+export const DELETE = withRouteHandler(
+  async (req: NextRequest, { params }: { params: Promise<{ id: string; documentId: string }> }) => {
+    const requestId = generateId().slice(0, 8)
+    const { id: knowledgeBaseId, documentId } = await params
+    const { searchParams } = new URL(req.url)
+    const action = searchParams.get('action') // 'cleanup' or 'all'
+
+    try {
+      const session = await getSession()
+      if (!session?.user?.id) {
+        return NextResponse.json({ error: 'Unauthorized' }, { status: 401 })
+      }
+
+      // Verify document exists and user has write access
+      const accessCheck = await checkDocumentWriteAccess(
+        knowledgeBaseId,
+        documentId,
+        session.user.id
+      )
+      if (!accessCheck.hasAccess) {
+        if (accessCheck.notFound) {
+          logger.warn(
+            `[${requestId}] ${accessCheck.reason}: KB=${knowledgeBaseId}, Doc=${documentId}`
+          )
+          return NextResponse.json({ error: accessCheck.reason }, { status: 404 })
+        }
+        logger.warn(
+          `[${requestId}] User ${session.user.id} attempted unauthorized document write access: ${accessCheck.reason}`
+        )
+        return NextResponse.json({ error: 'Unauthorized' }, { status: 401 })
+      }
+
+      if (action === 'cleanup') {
+        // Just run cleanup
+        logger.info(`[${requestId}] Running cleanup for KB ${knowledgeBaseId}`)
+        const cleanedUpCount = await cleanupUnusedTagDefinitions(knowledgeBaseId, requestId)
+
+        return NextResponse.json({
+          success: true,
+          data: { cleanedUp: cleanedUpCount },
+        })
+      }
+      // Delete all tag definitions (original behavior)
+      logger.info(`[${requestId}] Deleting all tag definitions for KB ${knowledgeBaseId}`)
+
+      const deletedCount = await deleteAllTagDefinitions(knowledgeBaseId, requestId)
+
+      return NextResponse.json({
+        success: true,
+        message: 'Tag definitions deleted successfully',
+        data: { deleted: deletedCount },
+      })
+    } catch (error) {
+      logger.error(`[${requestId}] Error with tag definitions operation`, error)
+      return NextResponse.json({ error: 'Failed to process tag definitions' }, { status: 500 })
+    }
+  }
+)

apps/sim/app/api/knowledge/[id]/documents/route.test.ts

@@ -0,0 +1,598 @@
+/**
+ * Tests for knowledge base documents API route
+ *
+ * @vitest-environment node
+ */
+import { auditMock, authMockFns, createMockRequest, knowledgeApiUtilsMock } from '@sim/testing'
+import { afterEach, beforeEach, describe, expect, it, vi } from 'vitest'
+
+const { mockDbChain } = vi.hoisted(() => {
+  const mockDbChain = {
+    select: vi.fn().mockReturnThis(),
+    from: vi.fn().mockReturnThis(),
+    where: vi.fn().mockReturnThis(),
+    orderBy: vi.fn().mockReturnThis(),
+    limit: vi.fn().mockReturnThis(),
+    offset: vi.fn().mockReturnThis(),
+    insert: vi.fn().mockReturnThis(),
+    values: vi.fn().mockReturnThis(),
+    update: vi.fn().mockReturnThis(),
+    set: vi.fn().mockReturnThis(),
+    transaction: vi.fn(),
+  }
+  return { mockDbChain }
+})
+
+vi.mock('@sim/db', () => ({
+  db: mockDbChain,
+}))
+
+vi.mock('@/app/api/knowledge/utils', () => knowledgeApiUtilsMock)
+
+vi.mock('@/lib/knowledge/documents/service', () => ({
+  getDocuments: vi.fn(),
+  createSingleDocument: vi.fn(),
+  createDocumentRecords: vi.fn(),
+  processDocumentsWithQueue: vi.fn(),
+  getProcessingConfig: vi.fn(),
+  bulkDocumentOperation: vi.fn(),
+  updateDocument: vi.fn(),
+  deleteDocument: vi.fn(),
+  markDocumentAsFailedTimeout: vi.fn(),
+  retryDocumentProcessing: vi.fn(),
+  KnowledgeBaseFileOwnershipError: class KnowledgeBaseFileOwnershipError extends Error {},
+}))
+
+vi.mock('@/lib/billing/calculations/usage-monitor', () => ({
+  checkActorUsageLimits: vi.fn().mockResolvedValue({ isExceeded: false }),
+}))
+
+vi.mock('@sim/audit', () => auditMock)
+
+import {
+  createDocumentRecords,
+  createSingleDocument,
+  getDocuments,
+  getProcessingConfig,
+  processDocumentsWithQueue,
+} from '@/lib/knowledge/documents/service'
+import { GET, POST } from '@/app/api/knowledge/[id]/documents/route'
+import { checkKnowledgeBaseAccess, checkKnowledgeBaseWriteAccess } from '@/app/api/knowledge/utils'
+
+describe('Knowledge Base Documents API Route', () => {
+  const mockDocument = {
+    id: 'doc-123',
+    knowledgeBaseId: 'kb-123',
+    filename: 'test-document.pdf',
+    fileUrl: 'https://example.com/test-document.pdf',
+    fileSize: 1024,
+    mimeType: 'application/pdf',
+    chunkCount: 5,
+    tokenCount: 100,
+    characterCount: 500,
+    processingStatus: 'completed' as const,
+    processingStartedAt: new Date(),
+    processingCompletedAt: new Date(),
+    processingError: null,
+    enabled: true,
+    uploadedAt: new Date(),
+    tag1: null,
+    tag2: null,
+    tag3: null,
+    tag4: null,
+    tag5: null,
+    tag6: null,
+    tag7: null,
+    number1: null,
+    number2: null,
+    number3: null,
+    number4: null,
+    number5: null,
+    date1: null,
+    date2: null,
+    boolean1: null,
+    boolean2: null,
+    boolean3: null,
+    deletedAt: null,
+  }
+
+  const resetMocks = () => {
+    vi.clearAllMocks()
+    Object.values(mockDbChain).forEach((fn) => {
+      if (typeof fn === 'function') {
+        fn.mockClear().mockReset()
+        if (fn !== mockDbChain.transaction) {
+          fn.mockReturnThis()
+        }
+      }
+    })
+  }
+
+  beforeEach(() => {
+    resetMocks()
+
+    vi.stubGlobal('crypto', {
+      randomUUID: vi.fn().mockReturnValue('mock-uuid-1234-5678'),
+    })
+  })
+
+  afterEach(() => {
+    vi.clearAllMocks()
+  })
+
+  describe('GET /api/knowledge/[id]/documents', () => {
+    const mockParams = Promise.resolve({ id: 'kb-123' })
+
+    it('should retrieve documents successfully for authenticated user', async () => {
+      authMockFns.mockGetSession.mockResolvedValue({
+        user: { id: 'user-123', email: 'test@example.com' },
+      })
+      vi.mocked(checkKnowledgeBaseAccess).mockResolvedValue({
+        hasAccess: true,
+        knowledgeBase: { id: 'kb-123', userId: 'user-123' },
+      })
+
+      vi.mocked(getDocuments).mockResolvedValue({
+        documents: [mockDocument],
+        pagination: {
+          total: 1,
+          limit: 50,
+          offset: 0,
+          hasMore: false,
+        },
+      })
+
+      const req = createMockRequest('GET')
+      const response = await GET(req, { params: mockParams })
+      const data = await response.json()
+
+      expect(response.status).toBe(200)
+      expect(data.success).toBe(true)
+      expect(data.data.documents).toHaveLength(1)
+      expect(data.data.documents[0].id).toBe('doc-123')
+      expect(vi.mocked(checkKnowledgeBaseAccess)).toHaveBeenCalledWith('kb-123', 'user-123')
+      expect(vi.mocked(getDocuments)).toHaveBeenCalledWith(
+        'kb-123',
+        {
+          enabledFilter: undefined,
+          search: undefined,
+          limit: 50,
+          offset: 0,
+        },
+        expect.any(String)
+      )
+    })
+
+    it('should return documents with default filter', async () => {
+      authMockFns.mockGetSession.mockResolvedValue({
+        user: { id: 'user-123', email: 'test@example.com' },
+      })
+      vi.mocked(checkKnowledgeBaseAccess).mockResolvedValue({
+        hasAccess: true,
+        knowledgeBase: { id: 'kb-123', userId: 'user-123' },
+      })
+
+      vi.mocked(getDocuments).mockResolvedValue({
+        documents: [mockDocument],
+        pagination: {
+          total: 1,
+          limit: 50,
+          offset: 0,
+          hasMore: false,
+        },
+      })
+
+      const req = createMockRequest('GET')
+      const response = await GET(req, { params: mockParams })
+
+      expect(response.status).toBe(200)
+      expect(vi.mocked(getDocuments)).toHaveBeenCalledWith(
+        'kb-123',
+        {
+          enabledFilter: undefined,
+          search: undefined,
+          limit: 50,
+          offset: 0,
+        },
+        expect.any(String)
+      )
+    })
+
+    it('should filter documents by enabled status when requested', async () => {
+      authMockFns.mockGetSession.mockResolvedValue({
+        user: { id: 'user-123', email: 'test@example.com' },
+      })
+      vi.mocked(checkKnowledgeBaseAccess).mockResolvedValue({
+        hasAccess: true,
+        knowledgeBase: { id: 'kb-123', userId: 'user-123' },
+      })
+
+      vi.mocked(getDocuments).mockResolvedValue({
+        documents: [mockDocument],
+        pagination: {
+          total: 1,
+          limit: 50,
+          offset: 0,
+          hasMore: false,
+        },
+      })
+
+      const url = 'http://localhost:3000/api/knowledge/kb-123/documents?enabledFilter=disabled'
+      const req = new Request(url, { method: 'GET' }) as any
+
+      const response = await GET(req, { params: mockParams })
+
+      expect(response.status).toBe(200)
+      expect(vi.mocked(getDocuments)).toHaveBeenCalledWith(
+        'kb-123',
+        {
+          enabledFilter: 'disabled',
+          search: undefined,
+          limit: 50,
+          offset: 0,
+        },
+        expect.any(String)
+      )
+    })
+
+    it('should return unauthorized for unauthenticated user', async () => {
+      authMockFns.mockGetSession.mockResolvedValue(null)
+
+      const req = createMockRequest('GET')
+      const response = await GET(req, { params: mockParams })
+      const data = await response.json()
+
+      expect(response.status).toBe(401)
+      expect(data.error).toBe('Unauthorized')
+    })
+
+    it('should return not found for non-existent knowledge base', async () => {
+      authMockFns.mockGetSession.mockResolvedValue({
+        user: { id: 'user-123', email: 'test@example.com' },
+      })
+      vi.mocked(checkKnowledgeBaseAccess).mockResolvedValue({
+        hasAccess: false,
+        notFound: true,
+      })
+
+      const req = createMockRequest('GET')
+      const response = await GET(req, { params: mockParams })
+      const data = await response.json()
+
+      expect(response.status).toBe(404)
+      expect(data.error).toBe('Knowledge base not found')
+    })
+
+    it('should return unauthorized for knowledge base without access', async () => {
+      authMockFns.mockGetSession.mockResolvedValue({
+        user: { id: 'user-123', email: 'test@example.com' },
+      })
+      vi.mocked(checkKnowledgeBaseAccess).mockResolvedValue({ hasAccess: false })
+
+      const req = createMockRequest('GET')
+      const response = await GET(req, { params: mockParams })
+      const data = await response.json()
+
+      expect(response.status).toBe(401)
+      expect(data.error).toBe('Unauthorized')
+    })
+
+    it('should handle database errors', async () => {
+      authMockFns.mockGetSession.mockResolvedValue({
+        user: { id: 'user-123', email: 'test@example.com' },
+      })
+      vi.mocked(checkKnowledgeBaseAccess).mockResolvedValue({
+        hasAccess: true,
+        knowledgeBase: { id: 'kb-123', userId: 'user-123' },
+      })
+      vi.mocked(getDocuments).mockRejectedValue(new Error('Database error'))
+
+      const req = createMockRequest('GET')
+      const response = await GET(req, { params: mockParams })
+      const data = await response.json()
+
+      expect(response.status).toBe(500)
+      expect(data.error).toBe('Failed to fetch documents')
+    })
+  })
+
+  describe('POST /api/knowledge/[id]/documents - Single Document', () => {
+    const mockParams = Promise.resolve({ id: 'kb-123' })
+    const validDocumentData = {
+      filename: 'test-document.pdf',
+      fileUrl: 'https://example.com/test-document.pdf',
+      fileSize: 1024,
+      mimeType: 'application/pdf',
+    }
+
+    it('should create single document successfully', async () => {
+      authMockFns.mockGetSession.mockResolvedValue({
+        user: { id: 'user-123', email: 'test@example.com' },
+      })
+      vi.mocked(checkKnowledgeBaseWriteAccess).mockResolvedValue({
+        hasAccess: true,
+        knowledgeBase: { id: 'kb-123', userId: 'user-123' },
+      })
+
+      const createdDocument = {
+        id: 'doc-123',
+        knowledgeBaseId: 'kb-123',
+        filename: validDocumentData.filename,
+        fileUrl: validDocumentData.fileUrl,
+        fileSize: validDocumentData.fileSize,
+        mimeType: validDocumentData.mimeType,
+        chunkCount: 0,
+        tokenCount: 0,
+        characterCount: 0,
+        enabled: true,
+        uploadedAt: new Date(),
+        tag1: null,
+        tag2: null,
+        tag3: null,
+        tag4: null,
+        tag5: null,
+        tag6: null,
+        tag7: null,
+      }
+      vi.mocked(createSingleDocument).mockResolvedValue(createdDocument)
+
+      const req = createMockRequest('POST', validDocumentData)
+      const response = await POST(req, { params: mockParams })
+      const data = await response.json()
+
+      expect(response.status).toBe(200)
+      expect(data.success).toBe(true)
+      expect(data.data.filename).toBe(validDocumentData.filename)
+      expect(data.data.fileUrl).toBe(validDocumentData.fileUrl)
+      expect(vi.mocked(createSingleDocument)).toHaveBeenCalledWith(
+        validDocumentData,
+        'kb-123',
+        expect.any(String),
+        'user-123'
+      )
+    })
+
+    it('should validate single document data', async () => {
+      authMockFns.mockGetSession.mockResolvedValue({
+        user: { id: 'user-123', email: 'test@example.com' },
+      })
+      vi.mocked(checkKnowledgeBaseWriteAccess).mockResolvedValue({
+        hasAccess: true,
+        knowledgeBase: { id: 'kb-123', userId: 'user-123' },
+      })
+
+      const invalidData = {
+        filename: '', // Invalid: empty filename
+        fileUrl: 'invalid-url', // Invalid: not a valid URL
+        fileSize: 0, // Invalid: size must be > 0
+        mimeType: '', // Invalid: empty mime type
+      }
+
+      const req = createMockRequest('POST', invalidData)
+      const response = await POST(req, { params: mockParams })
+      const data = await response.json()
+
+      expect(response.status).toBe(400)
+      expect(data.error).toBe('Invalid request data')
+      expect(data.details).toBeDefined()
+    })
+  })
+
+  describe('POST /api/knowledge/[id]/documents - Bulk Documents', () => {
+    const mockParams = Promise.resolve({ id: 'kb-123' })
+    const validBulkData = {
+      bulk: true,
+      documents: [
+        {
+          filename: 'doc1.pdf',
+          fileUrl: 'https://example.com/doc1.pdf',
+          fileSize: 1024,
+          mimeType: 'application/pdf',
+        },
+        {
+          filename: 'doc2.pdf',
+          fileUrl: 'https://example.com/doc2.pdf',
+          fileSize: 2048,
+          mimeType: 'application/pdf',
+        },
+      ],
+      processingOptions: {
+        recipe: 'default',
+        lang: 'en',
+      },
+    }
+
+    it('should create bulk documents successfully', async () => {
+      authMockFns.mockGetSession.mockResolvedValue({
+        user: { id: 'user-123', email: 'test@example.com' },
+      })
+      vi.mocked(checkKnowledgeBaseWriteAccess).mockResolvedValue({
+        hasAccess: true,
+        knowledgeBase: { id: 'kb-123', userId: 'user-123' },
+      })
+
+      const createdDocuments = [
+        {
+          documentId: 'doc-1',
+          filename: 'doc1.pdf',
+          fileUrl: 'https://example.com/doc1.pdf',
+          fileSize: 1024,
+          mimeType: 'application/pdf',
+        },
+        {
+          documentId: 'doc-2',
+          filename: 'doc2.pdf',
+          fileUrl: 'https://example.com/doc2.pdf',
+          fileSize: 2048,
+          mimeType: 'application/pdf',
+        },
+      ]
+
+      vi.mocked(createDocumentRecords).mockResolvedValue(createdDocuments)
+      vi.mocked(processDocumentsWithQueue).mockResolvedValue(undefined)
+      vi.mocked(getProcessingConfig).mockReturnValue({
+        maxConcurrentDocuments: 8,
+        batchSize: 20,
+        delayBetweenBatches: 100,
+        delayBetweenDocuments: 0,
+      })
+
+      const req = createMockRequest('POST', validBulkData)
+      const response = await POST(req, { params: mockParams })
+      const data = await response.json()
+
+      expect(response.status).toBe(200)
+      expect(data.success).toBe(true)
+      expect(data.data.total).toBe(2)
+      expect(data.data.documentsCreated).toHaveLength(2)
+      expect(data.data.processingMethod).toBe('background')
+      expect(vi.mocked(createDocumentRecords)).toHaveBeenCalledWith(
+        validBulkData.documents,
+        'kb-123',
+        expect.any(String),
+        'user-123'
+      )
+      expect(vi.mocked(processDocumentsWithQueue)).toHaveBeenCalled()
+    })
+
+    it('should validate bulk document data', async () => {
+      authMockFns.mockGetSession.mockResolvedValue({
+        user: { id: 'user-123', email: 'test@example.com' },
+      })
+      vi.mocked(checkKnowledgeBaseWriteAccess).mockResolvedValue({
+        hasAccess: true,
+        knowledgeBase: { id: 'kb-123', userId: 'user-123' },
+      })
+
+      const invalidBulkData = {
+        bulk: true,
+        documents: [
+          {
+            filename: '', // Invalid: empty filename
+            fileUrl: 'invalid-url',
+            fileSize: 0,
+            mimeType: '',
+          },
+        ],
+        processingOptions: {
+          recipe: 'default',
+          lang: 'en',
+        },
+      }
+
+      const req = createMockRequest('POST', invalidBulkData)
+      const response = await POST(req, { params: mockParams })
+      const data = await response.json()
+
+      expect(response.status).toBe(400)
+      expect(data.error).toBe('Invalid request data')
+      expect(data.details).toBeDefined()
+    })
+
+    it('should handle processing errors gracefully', async () => {
+      authMockFns.mockGetSession.mockResolvedValue({
+        user: { id: 'user-123', email: 'test@example.com' },
+      })
+      vi.mocked(checkKnowledgeBaseWriteAccess).mockResolvedValue({
+        hasAccess: true,
+        knowledgeBase: { id: 'kb-123', userId: 'user-123' },
+      })
+
+      const createdDocuments = [
+        {
+          documentId: 'doc-1',
+          filename: 'doc1.pdf',
+          fileUrl: 'https://example.com/doc1.pdf',
+          fileSize: 1024,
+          mimeType: 'application/pdf',
+        },
+      ]
+
+      vi.mocked(createDocumentRecords).mockResolvedValue(createdDocuments)
+      vi.mocked(processDocumentsWithQueue).mockResolvedValue(undefined)
+      vi.mocked(getProcessingConfig).mockReturnValue({
+        maxConcurrentDocuments: 8,
+        batchSize: 20,
+        delayBetweenBatches: 100,
+        delayBetweenDocuments: 0,
+      })
+
+      const req = createMockRequest('POST', validBulkData)
+      const response = await POST(req, { params: mockParams })
+      const data = await response.json()
+
+      expect(response.status).toBe(200)
+      expect(data.success).toBe(true)
+    })
+  })
+
+  describe('POST /api/knowledge/[id]/documents - Authentication & Authorization', () => {
+    const mockParams = Promise.resolve({ id: 'kb-123' })
+    const validDocumentData = {
+      filename: 'test-document.pdf',
+      fileUrl: 'https://example.com/test-document.pdf',
+      fileSize: 1024,
+      mimeType: 'application/pdf',
+    }
+
+    it('should return unauthorized for unauthenticated user', async () => {
+      authMockFns.mockGetSession.mockResolvedValue(null)
+
+      const req = createMockRequest('POST', validDocumentData)
+      const response = await POST(req, { params: mockParams })
+      const data = await response.json()
+
+      expect(response.status).toBe(401)
+      expect(data.error).toBe('Unauthorized')
+    })
+
+    it('should return not found for non-existent knowledge base', async () => {
+      authMockFns.mockGetSession.mockResolvedValue({
+        user: { id: 'user-123', email: 'test@example.com' },
+      })
+      vi.mocked(checkKnowledgeBaseWriteAccess).mockResolvedValue({
+        hasAccess: false,
+        notFound: true,
+      })
+
+      const req = createMockRequest('POST', validDocumentData)
+      const response = await POST(req, { params: mockParams })
+      const data = await response.json()
+
+      expect(response.status).toBe(404)
+      expect(data.error).toBe('Knowledge base not found')
+    })
+
+    it('should return unauthorized for knowledge base without access', async () => {
+      authMockFns.mockGetSession.mockResolvedValue({
+        user: { id: 'user-123', email: 'test@example.com' },
+      })
+      vi.mocked(checkKnowledgeBaseWriteAccess).mockResolvedValue({ hasAccess: false })
+
+      const req = createMockRequest('POST', validDocumentData)
+      const response = await POST(req, { params: mockParams })
+      const data = await response.json()
+
+      expect(response.status).toBe(401)
+      expect(data.error).toBe('Unauthorized')
+    })
+
+    it('should handle database errors during creation', async () => {
+      authMockFns.mockGetSession.mockResolvedValue({
+        user: { id: 'user-123', email: 'test@example.com' },
+      })
+      vi.mocked(checkKnowledgeBaseWriteAccess).mockResolvedValue({
+        hasAccess: true,
+        knowledgeBase: { id: 'kb-123', userId: 'user-123' },
+      })
+      vi.mocked(createSingleDocument).mockRejectedValue(new Error('Database error'))
+
+      const req = createMockRequest('POST', validDocumentData)
+      const response = await POST(req, { params: mockParams })
+      const data = await response.json()
+
+      expect(response.status).toBe(500)
+      expect(data.error).toBe('Database error')
+    })
+  })
+})

apps/sim/app/api/knowledge/[id]/documents/route.ts

@@ -0,0 +1,438 @@
+import { AuditAction, AuditResourceType, recordAudit } from '@sim/audit'
+import { createLogger } from '@sim/logger'
+import { authorizeWorkflowByWorkspacePermission } from '@sim/platform-authz/workflow'
+import { getErrorMessage } from '@sim/utils/errors'
+import { generateId } from '@sim/utils/id'
+import { type NextRequest, NextResponse } from 'next/server'
+import {
+  bulkKnowledgeDocumentsContract,
+  createKnowledgeDocumentsContract,
+  listKnowledgeDocumentsQuerySchema,
+  parseDocumentTagFiltersParam,
+} from '@/lib/api/contracts/knowledge'
+import { parseRequest } from '@/lib/api/server'
+import { getSession } from '@/lib/auth'
+import { checkSessionOrInternalAuth } from '@/lib/auth/hybrid'
+import { checkActorUsageLimits } from '@/lib/billing/calculations/usage-monitor'
+import { withRouteHandler } from '@/lib/core/utils/with-route-handler'
+import {
+  bulkDocumentOperation,
+  bulkDocumentOperationByFilter,
+  createDocumentRecords,
+  createSingleDocument,
+  getDocuments,
+  getProcessingConfig,
+  KnowledgeBaseFileOwnershipError,
+  processDocumentsWithQueue,
+} from '@/lib/knowledge/documents/service'
+import type { TagFilterCondition } from '@/lib/knowledge/documents/tag-filter'
+import { captureServerEvent } from '@/lib/posthog/server'
+import { checkKnowledgeBaseAccess, checkKnowledgeBaseWriteAccess } from '@/app/api/knowledge/utils'
+
+const logger = createLogger('DocumentsAPI')
+
+export const GET = withRouteHandler(
+  async (req: NextRequest, { params }: { params: Promise<{ id: string }> }) => {
+    const requestId = generateId().slice(0, 8)
+    const { id: knowledgeBaseId } = await params
+
+    try {
+      const session = await getSession()
+      if (!session?.user?.id) {
+        logger.warn(`[${requestId}] Unauthorized documents access attempt`)
+        return NextResponse.json({ error: 'Unauthorized' }, { status: 401 })
+      }
+
+      const accessCheck = await checkKnowledgeBaseAccess(knowledgeBaseId, session.user.id)
+
+      if (!accessCheck.hasAccess) {
+        if ('notFound' in accessCheck && accessCheck.notFound) {
+          logger.warn(`[${requestId}] Knowledge base not found: ${knowledgeBaseId}`)
+          return NextResponse.json({ error: 'Knowledge base not found' }, { status: 404 })
+        }
+        logger.warn(
+          `[${requestId}] User ${session.user.id} attempted to access unauthorized knowledge base documents ${knowledgeBaseId}`
+        )
+        return NextResponse.json({ error: 'Unauthorized' }, { status: 401 })
+      }
+
+      const queryResult = listKnowledgeDocumentsQuerySchema.safeParse(
+        Object.fromEntries(new URL(req.url).searchParams.entries())
+      )
+      if (!queryResult.success) {
+        return NextResponse.json(
+          { error: 'Invalid query parameters', details: queryResult.error.issues },
+          { status: 400 }
+        )
+      }
+      const { enabledFilter, search, limit, offset, sortBy, sortOrder, tagFilters } =
+        queryResult.data
+
+      let parsedTagFilters: TagFilterCondition[] | undefined
+      try {
+        parsedTagFilters = parseDocumentTagFiltersParam(tagFilters) as
+          | TagFilterCondition[]
+          | undefined
+      } catch {
+        return NextResponse.json(
+          { error: 'tagFilters must be a valid JSON array' },
+          { status: 400 }
+        )
+      }
+
+      const result = await getDocuments(
+        knowledgeBaseId,
+        {
+          enabledFilter: enabledFilter || undefined,
+          search,
+          limit,
+          offset,
+          ...(sortBy && { sortBy }),
+          ...(sortOrder && { sortOrder }),
+          tagFilters: parsedTagFilters,
+        },
+        requestId
+      )
+
+      return NextResponse.json({
+        success: true,
+        data: {
+          documents: result.documents,
+          pagination: result.pagination,
+        },
+      })
+    } catch (error) {
+      logger.error(`[${requestId}] Error fetching documents`, error)
+      return NextResponse.json({ error: 'Failed to fetch documents' }, { status: 500 })
+    }
+  }
+)
+
+export const POST = withRouteHandler(
+  async (req: NextRequest, { params }: { params: Promise<{ id: string }> }) => {
+    const requestId = generateId().slice(0, 8)
+    const { id: knowledgeBaseId } = await params
+
+    try {
+      const auth = await checkSessionOrInternalAuth(req, { requireWorkflowId: false })
+      if (!auth.success || !auth.userId) {
+        logger.warn(`[${requestId}] Authentication failed: ${auth.error || 'Unauthorized'}`)
+        return NextResponse.json({ error: 'Unauthorized' }, { status: 401 })
+      }
+      const userId = auth.userId
+
+      const parsed = await parseRequest(
+        createKnowledgeDocumentsContract,
+        req,
+        { params },
+        {
+          validationErrorResponse: (error) => {
+            logger.warn(`[${requestId}] Invalid document creation request`, {
+              errors: error.issues,
+            })
+            return NextResponse.json(
+              { error: 'Invalid request data', details: error.issues },
+              { status: 400 }
+            )
+          },
+        }
+      )
+      if (!parsed.success) return parsed.response
+      const body = parsed.data.body
+      const workflowId = body.workflowId
+
+      logger.info(`[${requestId}] Knowledge base document creation request`, {
+        knowledgeBaseId,
+        workflowId,
+        hasWorkflowId: !!workflowId,
+        bulk: body.bulk === true,
+      })
+
+      if (workflowId) {
+        const authorization = await authorizeWorkflowByWorkspacePermission({
+          workflowId,
+          userId,
+          action: 'write',
+        })
+        if (!authorization.allowed) {
+          return NextResponse.json(
+            { error: authorization.message || 'Access denied' },
+            { status: authorization.status }
+          )
+        }
+      }
+
+      const accessCheck = await checkKnowledgeBaseWriteAccess(knowledgeBaseId, userId)
+
+      if (!accessCheck.hasAccess) {
+        if ('notFound' in accessCheck && accessCheck.notFound) {
+          logger.warn(`[${requestId}] Knowledge base not found: ${knowledgeBaseId}`)
+          return NextResponse.json({ error: 'Knowledge base not found' }, { status: 404 })
+        }
+        logger.warn(
+          `[${requestId}] User ${userId} attempted to create document in unauthorized knowledge base ${knowledgeBaseId}`
+        )
+        return NextResponse.json({ error: 'Unauthorized' }, { status: 401 })
+      }
+
+      const kbWorkspaceId = accessCheck.knowledgeBase?.workspaceId
+
+      // Gate KB indexing (pooled + per-member) before accepting work. Runs even for
+      // legacy KBs with no workspace — the uploader's pooled/frozen status is still
+      // enforced (per-member is simply skipped when there's no org workspace). The
+      // authoritative backstop also runs in processDocumentAsync for non-HTTP paths
+      // (connector/cron/retry).
+      const usage = await checkActorUsageLimits(userId, kbWorkspaceId)
+      if (usage.isExceeded) {
+        return NextResponse.json(
+          {
+            error: usage.message || 'Usage limit exceeded. Please upgrade your plan to continue.',
+          },
+          { status: 402 }
+        )
+      }
+
+      if (body.bulk === true) {
+        const createdDocuments = await createDocumentRecords(
+          body.documents,
+          knowledgeBaseId,
+          requestId,
+          userId
+        )
+
+        logger.info(
+          `[${requestId}] Starting controlled async processing of ${createdDocuments.length} documents`
+        )
+
+        try {
+          const { PlatformEvents } = await import('@/lib/core/telemetry')
+          PlatformEvents.knowledgeBaseDocumentsUploaded({
+            knowledgeBaseId,
+            documentsCount: createdDocuments.length,
+            uploadType: 'bulk',
+            recipe: body.processingOptions?.recipe,
+          })
+        } catch (_e) {
+          // Silently fail
+        }
+
+        captureServerEvent(
+          userId,
+          'knowledge_base_document_uploaded',
+          {
+            knowledge_base_id: knowledgeBaseId,
+            workspace_id: kbWorkspaceId ?? '',
+            document_count: createdDocuments.length,
+            upload_type: 'bulk',
+          },
+          {
+            ...(kbWorkspaceId ? { groups: { workspace: kbWorkspaceId } } : {}),
+            setOnce: { first_document_uploaded_at: new Date().toISOString() },
+          }
+        )
+
+        processDocumentsWithQueue(
+          createdDocuments,
+          knowledgeBaseId,
+          body.processingOptions ?? {},
+          requestId
+        ).catch((error: unknown) => {
+          logger.error(`[${requestId}] Critical error in document processing pipeline:`, error)
+        })
+
+        recordAudit({
+          workspaceId: accessCheck.knowledgeBase?.workspaceId ?? null,
+          actorId: userId,
+          actorName: auth.userName,
+          actorEmail: auth.userEmail,
+          action: AuditAction.DOCUMENT_UPLOADED,
+          resourceType: AuditResourceType.DOCUMENT,
+          resourceId: knowledgeBaseId,
+          resourceName: `${createdDocuments.length} document(s)`,
+          description: `Uploaded ${createdDocuments.length} document(s) to knowledge base "${knowledgeBaseId}"`,
+          metadata: {
+            knowledgeBaseName: accessCheck.knowledgeBase?.name,
+            fileCount: createdDocuments.length,
+          },
+          request: req,
+        })
+
+        return NextResponse.json({
+          success: true,
+          data: {
+            total: createdDocuments.length,
+            documentsCreated: createdDocuments.map((doc) => ({
+              documentId: doc.documentId,
+              filename: doc.filename,
+              status: 'pending',
+            })),
+            processingMethod: 'background',
+            processingConfig: {
+              maxConcurrentDocuments: getProcessingConfig().maxConcurrentDocuments,
+              batchSize: getProcessingConfig().batchSize,
+              totalBatches: Math.ceil(createdDocuments.length / getProcessingConfig().batchSize),
+            },
+          },
+        })
+      }
+
+      const { bulk: _bulk, workflowId: _workflowId, ...singleDocumentData } = body
+      const newDocument = await createSingleDocument(
+        singleDocumentData,
+        knowledgeBaseId,
+        requestId,
+        userId
+      )
+
+      try {
+        const { PlatformEvents } = await import('@/lib/core/telemetry')
+        PlatformEvents.knowledgeBaseDocumentsUploaded({
+          knowledgeBaseId,
+          documentsCount: 1,
+          uploadType: 'single',
+          mimeType: singleDocumentData.mimeType,
+          fileSize: singleDocumentData.fileSize,
+        })
+      } catch (_e) {
+        // Silently fail
+      }
+
+      captureServerEvent(
+        userId,
+        'knowledge_base_document_uploaded',
+        {
+          knowledge_base_id: knowledgeBaseId,
+          workspace_id: kbWorkspaceId ?? '',
+          document_count: 1,
+          upload_type: 'single',
+        },
+        {
+          ...(kbWorkspaceId ? { groups: { workspace: kbWorkspaceId } } : {}),
+          setOnce: { first_document_uploaded_at: new Date().toISOString() },
+        }
+      )
+
+      recordAudit({
+        workspaceId: accessCheck.knowledgeBase?.workspaceId ?? null,
+        actorId: userId,
+        actorName: auth.userName,
+        actorEmail: auth.userEmail,
+        action: AuditAction.DOCUMENT_UPLOADED,
+        resourceType: AuditResourceType.DOCUMENT,
+        resourceId: knowledgeBaseId,
+        resourceName: singleDocumentData.filename,
+        description: `Uploaded document "${singleDocumentData.filename}" to knowledge base "${knowledgeBaseId}"`,
+        metadata: {
+          knowledgeBaseName: accessCheck.knowledgeBase?.name,
+          fileName: singleDocumentData.filename,
+          fileType: singleDocumentData.mimeType,
+          fileSize: singleDocumentData.fileSize,
+        },
+        request: req,
+      })
+
+      return NextResponse.json({
+        success: true,
+        data: newDocument,
+      })
+    } catch (error) {
+      logger.error(`[${requestId}] Error creating document`, error)
+
+      if (error instanceof KnowledgeBaseFileOwnershipError) {
+        return NextResponse.json(
+          { error: 'File URL does not reference a file owned by this knowledge base' },
+          { status: 403 }
+        )
+      }
+
+      const errorMessage = getErrorMessage(error, 'Failed to create document')
+      const isStorageLimitError =
+        errorMessage.includes('Storage limit exceeded') || errorMessage.includes('storage limit')
+      const isMissingKnowledgeBase = errorMessage === 'Knowledge base not found'
+
+      return NextResponse.json(
+        { error: errorMessage },
+        { status: isMissingKnowledgeBase ? 404 : isStorageLimitError ? 413 : 500 }
+      )
+    }
+  }
+)
+
+export const PATCH = withRouteHandler(
+  async (req: NextRequest, { params }: { params: Promise<{ id: string }> }) => {
+    const requestId = generateId().slice(0, 8)
+    const { id: knowledgeBaseId } = await params
+
+    try {
+      const session = await getSession()
+      if (!session?.user?.id) {
+        logger.warn(`[${requestId}] Unauthorized bulk document operation attempt`)
+        return NextResponse.json({ error: 'Unauthorized' }, { status: 401 })
+      }
+
+      const accessCheck = await checkKnowledgeBaseWriteAccess(knowledgeBaseId, session.user.id)
+
+      if (!accessCheck.hasAccess) {
+        if ('notFound' in accessCheck && accessCheck.notFound) {
+          logger.warn(`[${requestId}] Knowledge base not found: ${knowledgeBaseId}`)
+          return NextResponse.json({ error: 'Knowledge base not found' }, { status: 404 })
+        }
+        logger.warn(
+          `[${requestId}] User ${session.user.id} attempted to perform bulk operation on unauthorized knowledge base ${knowledgeBaseId}`
+        )
+        return NextResponse.json({ error: 'Unauthorized' }, { status: 401 })
+      }
+
+      const parsed = await parseRequest(
+        bulkKnowledgeDocumentsContract,
+        req,
+        { params },
+        {
+          validationErrorResponse: (error) => {
+            logger.warn(`[${requestId}] Invalid bulk operation data`, { errors: error.issues })
+            return NextResponse.json(
+              { error: 'Invalid request data', details: error.issues },
+              { status: 400 }
+            )
+          },
+        }
+      )
+      if (!parsed.success) return parsed.response
+      const validatedData = parsed.data.body
+      const { operation, documentIds, selectAll, enabledFilter } = validatedData
+
+      try {
+        let result
+        if (selectAll) {
+          result = await bulkDocumentOperationByFilter(
+            knowledgeBaseId,
+            operation,
+            enabledFilter,
+            requestId
+          )
+        } else if (documentIds && documentIds.length > 0) {
+          result = await bulkDocumentOperation(knowledgeBaseId, operation, documentIds, requestId)
+        } else {
+          return NextResponse.json({ error: 'No documents specified' }, { status: 400 })
+        }
+
+        return NextResponse.json({
+          success: true,
+          data: {
+            operation,
+            successCount: result.successCount,
+            updatedDocuments: result.updatedDocuments,
+          },
+        })
+      } catch (error) {
+        if (error instanceof Error && error.message === 'No valid documents found to update') {
+          return NextResponse.json({ error: 'No valid documents found to update' }, { status: 404 })
+        }
+        throw error
+      }
+    } catch (error) {
+      logger.error(`[${requestId}] Error in bulk document operation`, error)
+      return NextResponse.json({ error: 'Failed to perform bulk operation' }, { status: 500 })
+    }
+  }
+)

apps/sim/app/api/knowledge/[id]/documents/upsert/route.test.ts

@@ -0,0 +1,116 @@
+/**
+ * Tests for knowledge base document upsert API route
+ *
+ * @vitest-environment node
+ */
+import {
+  auditMock,
+  createMockRequest,
+  hybridAuthMock,
+  hybridAuthMockFns,
+  knowledgeApiUtilsMock,
+} from '@sim/testing'
+import { beforeEach, describe, expect, it, vi } from 'vitest'
+
+const { mockDbChain } = vi.hoisted(() => {
+  const chain = {
+    select: vi.fn().mockReturnThis(),
+    from: vi.fn().mockReturnThis(),
+    where: vi.fn().mockReturnThis(),
+    limit: vi.fn().mockResolvedValue([]),
+  }
+  return { mockDbChain: chain }
+})
+
+vi.mock('@sim/db', () => ({ db: mockDbChain }))
+vi.mock('@/lib/auth/hybrid', () => hybridAuthMock)
+vi.mock('@/app/api/knowledge/utils', () => knowledgeApiUtilsMock)
+vi.mock('@sim/audit', () => auditMock)
+
+vi.mock('@/lib/billing/calculations/usage-monitor', () => ({
+  checkActorUsageLimits: vi.fn().mockResolvedValue({ isExceeded: false }),
+}))
+
+vi.mock('@/lib/knowledge/documents/service', () => ({
+  createDocumentRecords: vi.fn(),
+  deleteDocument: vi.fn(),
+  getProcessingConfig: vi.fn().mockReturnValue({ maxConcurrentDocuments: 1, batchSize: 1 }),
+  processDocumentsWithQueue: vi.fn(),
+  KnowledgeBaseFileOwnershipError: class KnowledgeBaseFileOwnershipError extends Error {},
+}))
+
+import { createDocumentRecords, processDocumentsWithQueue } from '@/lib/knowledge/documents/service'
+import { POST } from '@/app/api/knowledge/[id]/documents/upsert/route'
+import { checkKnowledgeBaseWriteAccess } from '@/app/api/knowledge/utils'
+
+describe('POST /api/knowledge/[id]/documents/upsert', () => {
+  const params = Promise.resolve({ id: 'kb-123' })
+
+  beforeEach(() => {
+    vi.clearAllMocks()
+    mockDbChain.select.mockReturnThis()
+    mockDbChain.from.mockReturnThis()
+    mockDbChain.where.mockReturnThis()
+    mockDbChain.limit.mockResolvedValue([])
+
+    hybridAuthMockFns.mockCheckSessionOrInternalAuth.mockResolvedValue({
+      success: true,
+      userId: 'user-1',
+      authType: 'session',
+      userName: 'Test User',
+      userEmail: 'test@example.com',
+    })
+
+    vi.mocked(checkKnowledgeBaseWriteAccess).mockResolvedValue({
+      hasAccess: true,
+      knowledgeBase: { id: 'kb-123', userId: 'user-1', workspaceId: 'ws-1', name: 'KB' },
+    } as any)
+
+    vi.mocked(createDocumentRecords).mockResolvedValue([
+      { documentId: 'doc-new', filename: 'note.txt' },
+    ] as any)
+    vi.mocked(processDocumentsWithQueue).mockResolvedValue(undefined as any)
+  })
+
+  const baseBody = {
+    filename: 'note.txt',
+    fileSize: 11,
+    mimeType: 'text/plain',
+  }
+
+  it('accepts a data: URI', async () => {
+    const req = createMockRequest('POST', {
+      ...baseBody,
+      fileUrl: 'data:text/plain;base64,SGVsbG8gd29ybGQ=',
+    })
+    const res = await POST(req, { params })
+    expect(res.status).toBe(200)
+    expect(createDocumentRecords).toHaveBeenCalled()
+  })
+
+  it('accepts an https URL', async () => {
+    const req = createMockRequest('POST', {
+      ...baseBody,
+      fileUrl: 'https://example.com/note.txt',
+    })
+    const res = await POST(req, { params })
+    expect(res.status).toBe(200)
+    expect(createDocumentRecords).toHaveBeenCalled()
+  })
+
+  it.each([
+    ['absolute local path', '/etc/passwd'],
+    ['app config path', '/app/.env'],
+    ['file:// URL', 'file:///etc/passwd'],
+    ['relative serve path', '/api/files/serve/kb/foo.pdf'],
+    ['ftp URL', 'ftp://example.com/file.pdf'],
+    ['parent traversal', '../../etc/passwd'],
+    ['windows path', 'C:\\Windows\\System32\\config\\SAM'],
+  ])('rejects %s with 400 and never invokes the pipeline', async (_label, fileUrl) => {
+    const req = createMockRequest('POST', { ...baseBody, fileUrl })
+    const res = await POST(req, { params })
+    expect(res.status).toBe(400)
+    expect(createDocumentRecords).not.toHaveBeenCalled()
+    expect(processDocumentsWithQueue).not.toHaveBeenCalled()
+  })
+})

apps/sim/app/api/knowledge/[id]/documents/upsert/route.ts

@@ -0,0 +1,258 @@
+import { AuditAction, AuditResourceType, recordAudit } from '@sim/audit'
+import { db } from '@sim/db'
+import { document } from '@sim/db/schema'
+import { createLogger } from '@sim/logger'
+import { authorizeWorkflowByWorkspacePermission } from '@sim/platform-authz/workflow'
+import { getErrorMessage } from '@sim/utils/errors'
+import { generateId } from '@sim/utils/id'
+import { and, eq, isNull } from 'drizzle-orm'
+import { type NextRequest, NextResponse } from 'next/server'
+import { upsertKnowledgeDocumentContract } from '@/lib/api/contracts/knowledge'
+import { parseRequest } from '@/lib/api/server'
+import { checkSessionOrInternalAuth } from '@/lib/auth/hybrid'
+import { checkActorUsageLimits } from '@/lib/billing/calculations/usage-monitor'
+import { withRouteHandler } from '@/lib/core/utils/with-route-handler'
+import {
+  createDocumentRecords,
+  deleteDocument,
+  getProcessingConfig,
+  KnowledgeBaseFileOwnershipError,
+  processDocumentsWithQueue,
+} from '@/lib/knowledge/documents/service'
+import { checkKnowledgeBaseWriteAccess } from '@/app/api/knowledge/utils'
+
+const logger = createLogger('DocumentUpsertAPI')
+
+export const POST = withRouteHandler(
+  async (req: NextRequest, context: { params: Promise<{ id: string }> }) => {
+    const requestId = generateId().slice(0, 8)
+    const { id: knowledgeBaseId } = await context.params
+
+    try {
+      const parsed = await parseRequest(upsertKnowledgeDocumentContract, req, context)
+      if (!parsed.success) return parsed.response
+      const validatedData = parsed.data.body
+
+      logger.info(`[${requestId}] Knowledge base document upsert request`, {
+        knowledgeBaseId,
+        hasDocumentId: !!validatedData.documentId,
+        filename: validatedData.filename,
+      })
+
+      const auth = await checkSessionOrInternalAuth(req, { requireWorkflowId: false })
+      if (!auth.success || !auth.userId) {
+        logger.warn(`[${requestId}] Authentication failed: ${auth.error || 'Unauthorized'}`)
+        return NextResponse.json({ error: 'Unauthorized' }, { status: 401 })
+      }
+      const userId = auth.userId
+
+      if (validatedData.workflowId) {
+        const authorization = await authorizeWorkflowByWorkspacePermission({
+          workflowId: validatedData.workflowId,
+          userId,
+          action: 'write',
+        })
+        if (!authorization.allowed) {
+          return NextResponse.json(
+            { error: authorization.message || 'Access denied' },
+            { status: authorization.status }
+          )
+        }
+      }
+
+      const accessCheck = await checkKnowledgeBaseWriteAccess(knowledgeBaseId, userId)
+
+      if (!accessCheck.hasAccess) {
+        if ('notFound' in accessCheck && accessCheck.notFound) {
+          logger.warn(`[${requestId}] Knowledge base not found: ${knowledgeBaseId}`)
+          return NextResponse.json({ error: 'Knowledge base not found' }, { status: 404 })
+        }
+        logger.warn(
+          `[${requestId}] User ${userId} attempted to upsert document in unauthorized knowledge base ${knowledgeBaseId}`
+        )
+        return NextResponse.json({ error: 'Unauthorized' }, { status: 401 })
+      }
+
+      // Gate usage before any create/delete so an over-limit upsert is rejected up
+      // front and never deletes the existing (already-indexed) document. Runs even
+      // for legacy KBs with no workspace — the uploader's pooled/frozen status is
+      // still enforced (per-member is skipped when there's no org workspace).
+      const kbWorkspaceId = accessCheck.knowledgeBase?.workspaceId
+      const usage = await checkActorUsageLimits(userId, kbWorkspaceId)
+      if (usage.isExceeded) {
+        return NextResponse.json(
+          {
+            error: usage.message || 'Usage limit exceeded. Please upgrade your plan to continue.',
+          },
+          { status: 402 }
+        )
+      }
+
+      let existingDocumentId: string | null = null
+      let isUpdate = false
+
+      if (validatedData.documentId) {
+        const existingDoc = await db
+          .select({ id: document.id })
+          .from(document)
+          .where(
+            and(
+              eq(document.id, validatedData.documentId),
+              eq(document.knowledgeBaseId, knowledgeBaseId),
+              isNull(document.deletedAt)
+            )
+          )
+          .limit(1)
+
+        if (existingDoc.length > 0) {
+          existingDocumentId = existingDoc[0].id
+        }
+      } else {
+        const docsByFilename = await db
+          .select({ id: document.id })
+          .from(document)
+          .where(
+            and(
+              eq(document.filename, validatedData.filename),
+              eq(document.knowledgeBaseId, knowledgeBaseId),
+              isNull(document.deletedAt)
+            )
+          )
+          .limit(1)
+
+        if (docsByFilename.length > 0) {
+          existingDocumentId = docsByFilename[0].id
+        }
+      }
+
+      if (existingDocumentId) {
+        isUpdate = true
+        logger.info(
+          `[${requestId}] Found existing document ${existingDocumentId}, creating replacement before deleting old`
+        )
+      }
+
+      const createdDocuments = await createDocumentRecords(
+        [
+          {
+            filename: validatedData.filename,
+            fileUrl: validatedData.fileUrl,
+            fileSize: validatedData.fileSize,
+            mimeType: validatedData.mimeType,
+            ...(validatedData.documentTagsData && {
+              documentTagsData: validatedData.documentTagsData,
+            }),
+          },
+        ],
+        knowledgeBaseId,
+        requestId,
+        userId
+      )
+
+      const firstDocument = createdDocuments[0]
+      if (!firstDocument) {
+        logger.error(`[${requestId}] createDocumentRecords returned empty array unexpectedly`)
+        return NextResponse.json({ error: 'Failed to create document record' }, { status: 500 })
+      }
+
+      if (existingDocumentId) {
+        try {
+          await deleteDocument(existingDocumentId, requestId)
+        } catch (deleteError) {
+          logger.error(
+            `[${requestId}] Failed to delete old document ${existingDocumentId}, rolling back new record`,
+            deleteError
+          )
+          await deleteDocument(firstDocument.documentId, requestId).catch(() => {})
+          return NextResponse.json(
+            { error: 'Failed to replace existing document' },
+            { status: 500 }
+          )
+        }
+      }
+
+      processDocumentsWithQueue(
+        createdDocuments,
+        knowledgeBaseId,
+        validatedData.processingOptions ?? {},
+        requestId
+      ).catch((error: unknown) => {
+        logger.error(`[${requestId}] Critical error in document processing pipeline:`, error)
+      })
+
+      try {
+        const { PlatformEvents } = await import('@/lib/core/telemetry')
+        PlatformEvents.knowledgeBaseDocumentsUploaded({
+          knowledgeBaseId,
+          documentsCount: 1,
+          uploadType: 'single',
+          recipe: validatedData.processingOptions?.recipe,
+        })
+      } catch (_e) {
+        // Silently fail
+      }
+
+      recordAudit({
+        workspaceId: accessCheck.knowledgeBase?.workspaceId ?? null,
+        actorId: userId,
+        actorName: auth.userName,
+        actorEmail: auth.userEmail,
+        action: isUpdate ? AuditAction.DOCUMENT_UPDATED : AuditAction.DOCUMENT_UPLOADED,
+        resourceType: AuditResourceType.DOCUMENT,
+        resourceId: knowledgeBaseId,
+        resourceName: validatedData.filename,
+        description: isUpdate
+          ? `Upserted (replaced) document "${validatedData.filename}" in knowledge base "${knowledgeBaseId}"`
+          : `Upserted (created) document "${validatedData.filename}" in knowledge base "${knowledgeBaseId}"`,
+        metadata: {
+          knowledgeBaseName: accessCheck.knowledgeBase?.name,
+          fileName: validatedData.filename,
+          fileType: validatedData.mimeType,
+          fileSize: validatedData.fileSize,
+          previousDocumentId: existingDocumentId,
+          isUpdate,
+        },
+        request: req,
+      })
+
+      return NextResponse.json({
+        success: true,
+        data: {
+          documentsCreated: [
+            {
+              documentId: firstDocument.documentId,
+              filename: firstDocument.filename,
+              status: 'pending',
+            },
+          ],
+          isUpdate,
+          previousDocumentId: existingDocumentId,
+          processingMethod: 'background',
+          processingConfig: {
+            maxConcurrentDocuments: getProcessingConfig().maxConcurrentDocuments,
+            batchSize: getProcessingConfig().batchSize,
+          },
+        },
+      })
+    } catch (error) {
+      logger.error(`[${requestId}] Error upserting document`, error)
+
+      if (error instanceof KnowledgeBaseFileOwnershipError) {
+        return NextResponse.json(
+          { error: 'File URL does not reference a file owned by this knowledge base' },
+          { status: 403 }
+        )
+      }
+
+      const errorMessage = getErrorMessage(error, 'Failed to upsert document')
+      const isStorageLimitError =
+        errorMessage.includes('Storage limit exceeded') || errorMessage.includes('storage limit')
+      const isMissingKnowledgeBase = errorMessage === 'Knowledge base not found'
+
+      return NextResponse.json(
+        { error: errorMessage },
+        { status: isMissingKnowledgeBase ? 404 : isStorageLimitError ? 413 : 500 }
+      )
+    }
+  }
+)

apps/sim/app/api/knowledge/[id]/next-available-slot/route.ts

@@ -0,0 +1,77 @@
+import { createLogger } from '@sim/logger'
+import { generateId } from '@sim/utils/id'
+import { type NextRequest, NextResponse } from 'next/server'
+import { nextAvailableSlotContract } from '@/lib/api/contracts/knowledge'
+import { parseRequest } from '@/lib/api/server'
+import { getSession } from '@/lib/auth'
+import { withRouteHandler } from '@/lib/core/utils/with-route-handler'
+import { getNextAvailableSlot, getTagDefinitions } from '@/lib/knowledge/tags/service'
+import { checkKnowledgeBaseAccess } from '@/app/api/knowledge/utils'
+
+const logger = createLogger('NextAvailableSlotAPI')
+
+// GET /api/knowledge/[id]/next-available-slot - Get the next available tag slot for a knowledge base and field type
+export const GET = withRouteHandler(
+  async (req: NextRequest, context: { params: Promise<{ id: string }> }) => {
+    const requestId = generateId().slice(0, 8)
+    const parsed = await parseRequest(nextAvailableSlotContract, req, context)
+    if (!parsed.success) {
+      return NextResponse.json({ error: 'fieldType parameter is required' }, { status: 400 })
+    }
+    const { id: knowledgeBaseId } = parsed.data.params
+    const { fieldType } = parsed.data.query
+
+    try {
+      logger.info(
+        `[${requestId}] Getting next available slot for knowledge base ${knowledgeBaseId}, fieldType: ${fieldType}`
+      )
+
+      const session = await getSession()
+      if (!session?.user?.id) {
+        return NextResponse.json({ error: 'Unauthorized' }, { status: 401 })
+      }
+
+      const accessCheck = await checkKnowledgeBaseAccess(knowledgeBaseId, session.user.id)
+      if (!accessCheck.hasAccess) {
+        return NextResponse.json(
+          { error: accessCheck.notFound ? 'Not found' : 'Forbidden' },
+          { status: accessCheck.notFound ? 404 : 403 }
+        )
+      }
+
+      // Get existing definitions once and reuse
+      const existingDefinitions = await getTagDefinitions(knowledgeBaseId)
+      const usedSlots = existingDefinitions
+        .filter((def) => def.fieldType === fieldType)
+        .map((def) => def.tagSlot)
+
+      // Create a map for efficient lookup and pass to avoid redundant query
+      const existingBySlot = new Map(existingDefinitions.map((def) => [def.tagSlot as string, def]))
+      const nextAvailableSlot = await getNextAvailableSlot(
+        knowledgeBaseId,
+        fieldType,
+        existingBySlot
+      )
+
+      logger.info(
+        `[${requestId}] Next available slot for fieldType ${fieldType}: ${nextAvailableSlot}`
+      )
+
+      const result = {
+        nextAvailableSlot,
+        fieldType,
+        usedSlots,
+        totalSlots: 7,
+        availableSlots: nextAvailableSlot ? 7 - usedSlots.length : 0,
+      }
+
+      return NextResponse.json({
+        success: true,
+        data: result,
+      })
+    } catch (error) {
+      logger.error(`[${requestId}] Error getting next available slot`, error)
+      return NextResponse.json({ error: 'Failed to get next available slot' }, { status: 500 })
+    }
+  }
+)

apps/sim/app/api/knowledge/[id]/restore/route.ts

@@ -0,0 +1,67 @@
+import { createLogger } from '@sim/logger'
+import { getErrorMessage } from '@sim/utils/errors'
+import { type NextRequest, NextResponse } from 'next/server'
+import { restoreKnowledgeBaseContract } from '@/lib/api/contracts/knowledge'
+import { parseRequest } from '@/lib/api/server'
+import { checkSessionOrInternalAuth } from '@/lib/auth/hybrid'
+import { generateRequestId } from '@/lib/core/utils/request'
+import { withRouteHandler } from '@/lib/core/utils/with-route-handler'
+import {
+  getRestorableKnowledgeBase,
+  performRestoreKnowledgeBase,
+} from '@/lib/knowledge/orchestration'
+import { getUserEntityPermissions } from '@/lib/workspaces/permissions/utils'
+
+const logger = createLogger('RestoreKnowledgeBaseAPI')
+
+export const POST = withRouteHandler(
+  async (request: NextRequest, context: { params: Promise<{ id: string }> }) => {
+    const requestId = generateRequestId()
+    const parsed = await parseRequest(restoreKnowledgeBaseContract, request, context)
+    if (!parsed.success) return parsed.response
+    const { id } = parsed.data.params
+
+    try {
+      const auth = await checkSessionOrInternalAuth(request, { requireWorkflowId: false })
+      if (!auth.success || !auth.userId) {
+        return NextResponse.json({ error: 'Unauthorized' }, { status: 401 })
+      }
+
+      const kb = await getRestorableKnowledgeBase(id)
+
+      if (!kb) {
+        return NextResponse.json({ error: 'Knowledge base not found' }, { status: 404 })
+      }
+
+      if (kb.workspaceId) {
+        const permission = await getUserEntityPermissions(auth.userId, 'workspace', kb.workspaceId)
+        if (permission !== 'admin' && permission !== 'write') {
+          return NextResponse.json({ error: 'Insufficient permissions' }, { status: 403 })
+        }
+      } else if (kb.userId !== auth.userId) {
+        return NextResponse.json({ error: 'Unauthorized' }, { status: 401 })
+      }
+
+      const result = await performRestoreKnowledgeBase({
+        knowledgeBaseId: id,
+        userId: auth.userId,
+        requestId,
+      })
+      if (!result.success) {
+        const status =
+          result.errorCode === 'not_found' ? 404 : result.errorCode === 'conflict' ? 409 : 500
+        return NextResponse.json({ error: result.error }, { status })
+      }
+
+      logger.info(`[${requestId}] Restored knowledge base ${id}`)
+
+      return NextResponse.json({ success: true })
+    } catch (error) {
+      logger.error(`[${requestId}] Error restoring knowledge base ${id}`, error)
+      return NextResponse.json(
+        { error: getErrorMessage(error, 'Internal server error') },
+        { status: 500 }
+      )
+    }
+  }
+)

apps/sim/app/api/knowledge/[id]/route.test.ts

@@ -0,0 +1,463 @@
+/**
+ * Tests for knowledge base by ID API route
+ *
+ * @vitest-environment node
+ */
+import { auditMock, authMockFns, createMockRequest, knowledgeApiUtilsMock } from '@sim/testing'
+import { afterEach, beforeEach, describe, expect, it, vi } from 'vitest'
+
+const { mockDbChain } = vi.hoisted(() => {
+  const mockDbChain = {
+    select: vi.fn().mockReturnThis(),
+    from: vi.fn().mockReturnThis(),
+    where: vi.fn().mockReturnThis(),
+    limit: vi.fn().mockReturnThis(),
+    update: vi.fn().mockReturnThis(),
+    set: vi.fn().mockReturnThis(),
+  }
+  return { mockDbChain }
+})
+
+vi.mock('@sim/db', () => ({
+  db: mockDbChain,
+}))
+
+vi.mock('@sim/audit', () => auditMock)
+
+vi.mock('@/lib/knowledge/service', async (importOriginal) => {
+  const actual = await importOriginal<typeof import('@/lib/knowledge/service')>()
+  return {
+    ...actual,
+    getKnowledgeBaseById: vi.fn(),
+    updateKnowledgeBase: vi.fn(),
+    deleteKnowledgeBase: vi.fn(),
+    KnowledgeBasePermissionError: actual.KnowledgeBasePermissionError,
+  }
+})
+
+vi.mock('@/app/api/knowledge/utils', () => knowledgeApiUtilsMock)
+
+import {
+  deleteKnowledgeBase,
+  getKnowledgeBaseById,
+  KnowledgeBasePermissionError,
+  updateKnowledgeBase,
+} from '@/lib/knowledge/service'
+import { DELETE, GET, PUT } from '@/app/api/knowledge/[id]/route'
+import { checkKnowledgeBaseAccess, checkKnowledgeBaseWriteAccess } from '@/app/api/knowledge/utils'
+
+describe('Knowledge Base By ID API Route', () => {
+  const mockKnowledgeBase = {
+    id: 'kb-123',
+    userId: 'user-123',
+    name: 'Test Knowledge Base',
+    description: 'Test description',
+    tokenCount: 100,
+    embeddingModel: 'text-embedding-3-small',
+    embeddingDimension: 1536,
+    chunkingConfig: { maxSize: 1024, minSize: 100, overlap: 200 },
+    createdAt: new Date(),
+    updatedAt: new Date(),
+    workspaceId: null,
+    deletedAt: null,
+  }
+
+  const resetMocks = () => {
+    vi.clearAllMocks()
+    Object.values(mockDbChain).forEach((fn) => {
+      if (typeof fn === 'function') {
+        fn.mockClear().mockReset().mockReturnThis()
+      }
+    })
+  }
+
+  beforeEach(() => {
+    vi.clearAllMocks()
+
+    vi.stubGlobal('crypto', {
+      randomUUID: vi.fn().mockReturnValue('mock-uuid-1234-5678'),
+    })
+  })
+
+  afterEach(() => {
+    vi.clearAllMocks()
+  })
+
+  describe('GET /api/knowledge/[id]', () => {
+    const mockParams = Promise.resolve({ id: 'kb-123' })
+
+    it('should retrieve knowledge base successfully for authenticated user', async () => {
+      authMockFns.mockGetSession.mockResolvedValue({
+        user: { id: 'user-123', email: 'test@example.com' },
+      })
+
+      vi.mocked(checkKnowledgeBaseAccess).mockResolvedValueOnce({
+        hasAccess: true,
+        knowledgeBase: { id: 'kb-123', userId: 'user-123' },
+      })
+
+      vi.mocked(getKnowledgeBaseById).mockResolvedValueOnce(mockKnowledgeBase)
+
+      const req = createMockRequest('GET')
+      const response = await GET(req, { params: mockParams })
+      const data = await response.json()
+
+      expect(response.status).toBe(200)
+      expect(data.success).toBe(true)
+      expect(data.data.id).toBe('kb-123')
+      expect(data.data.name).toBe('Test Knowledge Base')
+      expect(checkKnowledgeBaseAccess).toHaveBeenCalledWith('kb-123', 'user-123')
+      expect(getKnowledgeBaseById).toHaveBeenCalledWith('kb-123')
+    })
+
+    it('should return unauthorized for unauthenticated user', async () => {
+      authMockFns.mockGetSession.mockResolvedValue(null)
+
+      const req = createMockRequest('GET')
+      const response = await GET(req, { params: mockParams })
+      const data = await response.json()
+
+      expect(response.status).toBe(401)
+      expect(data.error).toBe('Unauthorized')
+    })
+
+    it('should return not found for non-existent knowledge base', async () => {
+      authMockFns.mockGetSession.mockResolvedValue({
+        user: { id: 'user-123', email: 'test@example.com' },
+      })
+
+      vi.mocked(checkKnowledgeBaseAccess).mockResolvedValueOnce({
+        hasAccess: false,
+        notFound: true,
+      })
+
+      const req = createMockRequest('GET')
+      const response = await GET(req, { params: mockParams })
+      const data = await response.json()
+
+      expect(response.status).toBe(404)
+      expect(data.error).toBe('Knowledge base not found')
+    })
+
+    it('should return unauthorized for knowledge base owned by different user', async () => {
+      authMockFns.mockGetSession.mockResolvedValue({
+        user: { id: 'user-123', email: 'test@example.com' },
+      })
+
+      vi.mocked(checkKnowledgeBaseAccess).mockResolvedValueOnce({
+        hasAccess: false,
+        notFound: false,
+      })
+
+      const req = createMockRequest('GET')
+      const response = await GET(req, { params: mockParams })
+      const data = await response.json()
+
+      expect(response.status).toBe(401)
+      expect(data.error).toBe('Unauthorized')
+    })
+
+    it('should return not found when service returns null', async () => {
+      authMockFns.mockGetSession.mockResolvedValue({
+        user: { id: 'user-123', email: 'test@example.com' },
+      })
+
+      vi.mocked(checkKnowledgeBaseAccess).mockResolvedValueOnce({
+        hasAccess: true,
+        knowledgeBase: { id: 'kb-123', userId: 'user-123' },
+      })
+
+      vi.mocked(getKnowledgeBaseById).mockResolvedValueOnce(null)
+
+      const req = createMockRequest('GET')
+      const response = await GET(req, { params: mockParams })
+      const data = await response.json()
+
+      expect(response.status).toBe(404)
+      expect(data.error).toBe('Knowledge base not found')
+    })
+
+    it('should handle database errors', async () => {
+      authMockFns.mockGetSession.mockResolvedValue({
+        user: { id: 'user-123', email: 'test@example.com' },
+      })
+
+      vi.mocked(checkKnowledgeBaseAccess).mockRejectedValueOnce(new Error('Database error'))
+
+      const req = createMockRequest('GET')
+      const response = await GET(req, { params: mockParams })
+      const data = await response.json()
+
+      expect(response.status).toBe(500)
+      expect(data.error).toBe('Failed to fetch knowledge base')
+    })
+  })
+
+  describe('PUT /api/knowledge/[id]', () => {
+    const mockParams = Promise.resolve({ id: 'kb-123' })
+    const validUpdateData = {
+      name: 'Updated Knowledge Base',
+      description: 'Updated description',
+    }
+
+    it('should update knowledge base successfully', async () => {
+      authMockFns.mockGetSession.mockResolvedValue({
+        user: { id: 'user-123', email: 'test@example.com' },
+      })
+
+      resetMocks()
+
+      vi.mocked(checkKnowledgeBaseWriteAccess).mockResolvedValueOnce({
+        hasAccess: true,
+        knowledgeBase: { id: 'kb-123', userId: 'user-123' },
+      })
+
+      const updatedKnowledgeBase = { ...mockKnowledgeBase, ...validUpdateData }
+      vi.mocked(updateKnowledgeBase).mockResolvedValueOnce(updatedKnowledgeBase)
+
+      const req = createMockRequest('PUT', validUpdateData)
+      const response = await PUT(req, { params: mockParams })
+      const data = await response.json()
+
+      expect(response.status).toBe(200)
+      expect(data.success).toBe(true)
+      expect(data.data.name).toBe('Updated Knowledge Base')
+      expect(checkKnowledgeBaseWriteAccess).toHaveBeenCalledWith('kb-123', 'user-123')
+      expect(updateKnowledgeBase).toHaveBeenCalledWith(
+        'kb-123',
+        {
+          name: validUpdateData.name,
+          description: validUpdateData.description,
+          workspaceId: undefined,
+          chunkingConfig: undefined,
+        },
+        expect.any(String),
+        { actorUserId: 'user-123' }
+      )
+    })
+
+    it('returns 403 when service rejects a cross-workspace transfer', async () => {
+      authMockFns.mockGetSession.mockResolvedValue({
+        user: { id: 'attacker', email: 'a@example.com' },
+      })
+
+      resetMocks()
+
+      vi.mocked(checkKnowledgeBaseWriteAccess).mockResolvedValueOnce({
+        hasAccess: true,
+        knowledgeBase: { id: 'kb-123', userId: 'user-123', workspaceId: 'ws-current' },
+      })
+
+      vi.mocked(updateKnowledgeBase).mockRejectedValueOnce(
+        new KnowledgeBasePermissionError('User does not have permission on the target workspace')
+      )
+
+      const req = createMockRequest('PUT', { workspaceId: 'ws-target' })
+      const response = await PUT(req, { params: mockParams })
+      const data = await response.json()
+
+      expect(response.status).toBe(403)
+      expect(data.error).toBe('User does not have permission on the target workspace')
+    })
+
+    it('returns 403 when service rejects clearing workspaceId', async () => {
+      authMockFns.mockGetSession.mockResolvedValue({
+        user: { id: 'user-123', email: 'test@example.com' },
+      })
+
+      resetMocks()
+
+      vi.mocked(checkKnowledgeBaseWriteAccess).mockResolvedValueOnce({
+        hasAccess: true,
+        knowledgeBase: { id: 'kb-123', userId: 'user-123', workspaceId: 'ws-current' },
+      })
+
+      vi.mocked(updateKnowledgeBase).mockRejectedValueOnce(
+        new KnowledgeBasePermissionError('Knowledge base workspace cannot be cleared')
+      )
+
+      const req = createMockRequest('PUT', { workspaceId: null })
+      const response = await PUT(req, { params: mockParams })
+      const data = await response.json()
+
+      expect(response.status).toBe(403)
+      expect(data.error).toBe('Knowledge base workspace cannot be cleared')
+    })
+
+    it('should return unauthorized for unauthenticated user', async () => {
+      authMockFns.mockGetSession.mockResolvedValue(null)
+
+      const req = createMockRequest('PUT', validUpdateData)
+      const response = await PUT(req, { params: mockParams })
+      const data = await response.json()
+
+      expect(response.status).toBe(401)
+      expect(data.error).toBe('Unauthorized')
+    })
+
+    it('should return not found for non-existent knowledge base', async () => {
+      authMockFns.mockGetSession.mockResolvedValue({
+        user: { id: 'user-123', email: 'test@example.com' },
+      })
+
+      resetMocks()
+
+      vi.mocked(checkKnowledgeBaseWriteAccess).mockResolvedValueOnce({
+        hasAccess: false,
+        notFound: true,
+      })
+
+      const req = createMockRequest('PUT', validUpdateData)
+      const response = await PUT(req, { params: mockParams })
+      const data = await response.json()
+
+      expect(response.status).toBe(404)
+      expect(data.error).toBe('Knowledge base not found')
+    })
+
+    it('should validate update data', async () => {
+      authMockFns.mockGetSession.mockResolvedValue({
+        user: { id: 'user-123', email: 'test@example.com' },
+      })
+
+      resetMocks()
+
+      vi.mocked(checkKnowledgeBaseWriteAccess).mockResolvedValueOnce({
+        hasAccess: true,
+        knowledgeBase: { id: 'kb-123', userId: 'user-123' },
+      })
+
+      const invalidData = {
+        name: '',
+      }
+
+      const req = createMockRequest('PUT', invalidData)
+      const response = await PUT(req, { params: mockParams })
+      const data = await response.json()
+
+      expect(response.status).toBe(400)
+      expect(data.error).toBe('Validation error')
+      expect(data.details).toBeDefined()
+    })
+
+    it('should handle database errors during update', async () => {
+      authMockFns.mockGetSession.mockResolvedValue({
+        user: { id: 'user-123', email: 'test@example.com' },
+      })
+
+      vi.mocked(checkKnowledgeBaseWriteAccess).mockResolvedValueOnce({
+        hasAccess: true,
+        knowledgeBase: { id: 'kb-123', userId: 'user-123' },
+      })
+
+      vi.mocked(updateKnowledgeBase).mockRejectedValueOnce(new Error('Database error'))
+
+      const req = createMockRequest('PUT', validUpdateData)
+      const response = await PUT(req, { params: mockParams })
+      const data = await response.json()
+
+      expect(response.status).toBe(500)
+      expect(data.error).toBe('Failed to update knowledge base')
+    })
+  })
+
+  describe('DELETE /api/knowledge/[id]', () => {
+    const mockParams = Promise.resolve({ id: 'kb-123' })
+
+    it('should delete knowledge base successfully', async () => {
+      authMockFns.mockGetSession.mockResolvedValue({
+        user: { id: 'user-123', email: 'test@example.com' },
+      })
+
+      resetMocks()
+
+      vi.mocked(checkKnowledgeBaseWriteAccess).mockResolvedValueOnce({
+        hasAccess: true,
+        knowledgeBase: { id: 'kb-123', userId: 'user-123' },
+      })
+
+      vi.mocked(deleteKnowledgeBase).mockResolvedValueOnce(undefined)
+
+      const req = createMockRequest('DELETE')
+      const response = await DELETE(req, { params: mockParams })
+      const data = await response.json()
+
+      expect(response.status).toBe(200)
+      expect(data.success).toBe(true)
+      expect(data.data.message).toBe('Knowledge base deleted successfully')
+      expect(checkKnowledgeBaseWriteAccess).toHaveBeenCalledWith('kb-123', 'user-123')
+      expect(deleteKnowledgeBase).toHaveBeenCalledWith('kb-123', expect.any(String))
+    })
+
+    it('should return unauthorized for unauthenticated user', async () => {
+      authMockFns.mockGetSession.mockResolvedValue(null)
+
+      const req = createMockRequest('DELETE')
+      const response = await DELETE(req, { params: mockParams })
+      const data = await response.json()
+
+      expect(response.status).toBe(401)
+      expect(data.error).toBe('Unauthorized')
+    })
+
+    it('should return not found for non-existent knowledge base', async () => {
+      authMockFns.mockGetSession.mockResolvedValue({
+        user: { id: 'user-123', email: 'test@example.com' },
+      })
+
+      resetMocks()
+
+      vi.mocked(checkKnowledgeBaseWriteAccess).mockResolvedValueOnce({
+        hasAccess: false,
+        notFound: true,
+      })
+
+      const req = createMockRequest('DELETE')
+      const response = await DELETE(req, { params: mockParams })
+      const data = await response.json()
+
+      expect(response.status).toBe(404)
+      expect(data.error).toBe('Knowledge base not found')
+    })
+
+    it('should return unauthorized for knowledge base owned by different user', async () => {
+      authMockFns.mockGetSession.mockResolvedValue({
+        user: { id: 'user-123', email: 'test@example.com' },
+      })
+
+      resetMocks()
+
+      vi.mocked(checkKnowledgeBaseWriteAccess).mockResolvedValueOnce({
+        hasAccess: false,
+        notFound: false,
+      })
+
+      const req = createMockRequest('DELETE')
+      const response = await DELETE(req, { params: mockParams })
+      const data = await response.json()
+
+      expect(response.status).toBe(401)
+      expect(data.error).toBe('Unauthorized')
+    })
+
+    it('should handle database errors during delete', async () => {
+      authMockFns.mockGetSession.mockResolvedValue({
+        user: { id: 'user-123', email: 'test@example.com' },
+      })
+
+      vi.mocked(checkKnowledgeBaseWriteAccess).mockResolvedValueOnce({
+        hasAccess: true,
+        knowledgeBase: { id: 'kb-123', userId: 'user-123' },
+      })
+
+      vi.mocked(deleteKnowledgeBase).mockRejectedValueOnce(new Error('Database error'))
+
+      const req = createMockRequest('DELETE')
+      const response = await DELETE(req, { params: mockParams })
+      const data = await response.json()
+
+      expect(response.status).toBe(500)
+      expect(data.error).toBe('Failed to delete knowledge base')
+    })
+  })
+})

apps/sim/app/api/knowledge/[id]/route.ts

@@ -0,0 +1,220 @@
+import { AuditAction, AuditResourceType, recordAudit } from '@sim/audit'
+import { createLogger } from '@sim/logger'
+import { type NextRequest, NextResponse } from 'next/server'
+import { updateKnowledgeBaseContract } from '@/lib/api/contracts/knowledge'
+import { parseRequest } from '@/lib/api/server'
+import { checkSessionOrInternalAuth } from '@/lib/auth/hybrid'
+import { PlatformEvents } from '@/lib/core/telemetry'
+import { generateRequestId } from '@/lib/core/utils/request'
+import { withRouteHandler } from '@/lib/core/utils/with-route-handler'
+import {
+  deleteKnowledgeBase,
+  getKnowledgeBaseById,
+  KnowledgeBaseConflictError,
+  KnowledgeBasePermissionError,
+  updateKnowledgeBase,
+} from '@/lib/knowledge/service'
+import { checkKnowledgeBaseAccess, checkKnowledgeBaseWriteAccess } from '@/app/api/knowledge/utils'
+
+const logger = createLogger('KnowledgeBaseByIdAPI')
+
+export const GET = withRouteHandler(
+  async (_request: NextRequest, { params }: { params: Promise<{ id: string }> }) => {
+    const requestId = generateRequestId()
+    const { id } = await params
+
+    try {
+      const auth = await checkSessionOrInternalAuth(_request, { requireWorkflowId: false })
+      if (!auth.success || !auth.userId) {
+        logger.warn(`[${requestId}] Unauthorized knowledge base access attempt`)
+        return NextResponse.json({ error: 'Unauthorized' }, { status: 401 })
+      }
+      const userId = auth.userId
+
+      const accessCheck = await checkKnowledgeBaseAccess(id, userId)
+
+      if (!accessCheck.hasAccess) {
+        if ('notFound' in accessCheck && accessCheck.notFound) {
+          logger.warn(`[${requestId}] Knowledge base not found: ${id}`)
+          return NextResponse.json({ error: 'Knowledge base not found' }, { status: 404 })
+        }
+        logger.warn(
+          `[${requestId}] User ${userId} attempted to access unauthorized knowledge base ${id}`
+        )
+        return NextResponse.json({ error: 'Unauthorized' }, { status: 401 })
+      }
+
+      const knowledgeBaseData = await getKnowledgeBaseById(id)
+
+      if (!knowledgeBaseData) {
+        return NextResponse.json({ error: 'Knowledge base not found' }, { status: 404 })
+      }
+
+      logger.info(`[${requestId}] Retrieved knowledge base: ${id} for user ${userId}`)
+
+      return NextResponse.json({
+        success: true,
+        data: knowledgeBaseData,
+      })
+    } catch (error) {
+      logger.error(`[${requestId}] Error fetching knowledge base`, error)
+      return NextResponse.json({ error: 'Failed to fetch knowledge base' }, { status: 500 })
+    }
+  }
+)
+
+export const PUT = withRouteHandler(
+  async (req: NextRequest, context: { params: Promise<{ id: string }> }) => {
+    const requestId = generateRequestId()
+    const { id } = await context.params
+
+    try {
+      const auth = await checkSessionOrInternalAuth(req, { requireWorkflowId: false })
+      if (!auth.success || !auth.userId) {
+        logger.warn(`[${requestId}] Unauthorized knowledge base update attempt`)
+        return NextResponse.json({ error: 'Unauthorized' }, { status: 401 })
+      }
+      const userId = auth.userId
+
+      const accessCheck = await checkKnowledgeBaseWriteAccess(id, userId)
+
+      if (!accessCheck.hasAccess) {
+        if ('notFound' in accessCheck && accessCheck.notFound) {
+          logger.warn(`[${requestId}] Knowledge base not found: ${id}`)
+          return NextResponse.json({ error: 'Knowledge base not found' }, { status: 404 })
+        }
+        logger.warn(
+          `[${requestId}] User ${userId} attempted to update unauthorized knowledge base ${id}`
+        )
+        return NextResponse.json({ error: 'Unauthorized' }, { status: 401 })
+      }
+
+      const parsed = await parseRequest(updateKnowledgeBaseContract, req, context)
+      if (!parsed.success) return parsed.response
+
+      const validatedData = parsed.data.body
+
+      const updatedKnowledgeBase = await updateKnowledgeBase(
+        id,
+        {
+          name: validatedData.name,
+          description: validatedData.description,
+          workspaceId: validatedData.workspaceId,
+          chunkingConfig: validatedData.chunkingConfig,
+        },
+        requestId,
+        { actorUserId: userId }
+      )
+
+      logger.info(`[${requestId}] Knowledge base updated: ${id} for user ${userId}`)
+
+      recordAudit({
+        workspaceId: accessCheck.knowledgeBase.workspaceId ?? null,
+        actorId: userId,
+        actorName: auth.userName,
+        actorEmail: auth.userEmail,
+        action: AuditAction.KNOWLEDGE_BASE_UPDATED,
+        resourceType: AuditResourceType.KNOWLEDGE_BASE,
+        resourceId: id,
+        resourceName: validatedData.name ?? updatedKnowledgeBase.name,
+        description: `Updated knowledge base "${validatedData.name ?? updatedKnowledgeBase.name}"`,
+        metadata: {
+          updatedFields: Object.keys(validatedData).filter(
+            (k) => validatedData[k as keyof typeof validatedData] !== undefined
+          ),
+          ...(validatedData.name && { newName: validatedData.name }),
+          ...(validatedData.description !== undefined && {
+            description: validatedData.description,
+          }),
+          ...(validatedData.chunkingConfig && {
+            chunkMaxSize: validatedData.chunkingConfig.maxSize,
+            chunkMinSize: validatedData.chunkingConfig.minSize,
+            chunkOverlap: validatedData.chunkingConfig.overlap,
+          }),
+        },
+        request: req,
+      })
+
+      return NextResponse.json({
+        success: true,
+        data: updatedKnowledgeBase,
+      })
+    } catch (error) {
+      if (error instanceof KnowledgeBaseConflictError) {
+        return NextResponse.json({ error: error.message }, { status: 409 })
+      }
+      if (error instanceof KnowledgeBasePermissionError) {
+        logger.warn(`[${requestId}] Forbidden knowledge base update on ${id}: ${error.message}`)
+        return NextResponse.json({ error: error.message }, { status: 403 })
+      }
+
+      logger.error(`[${requestId}] Error updating knowledge base`, error)
+      return NextResponse.json({ error: 'Failed to update knowledge base' }, { status: 500 })
+    }
+  }
+)
+
+export const DELETE = withRouteHandler(
+  async (_request: NextRequest, { params }: { params: Promise<{ id: string }> }) => {
+    const requestId = generateRequestId()
+    const { id } = await params
+
+    try {
+      const auth = await checkSessionOrInternalAuth(_request, { requireWorkflowId: false })
+      if (!auth.success || !auth.userId) {
+        logger.warn(`[${requestId}] Unauthorized knowledge base delete attempt`)
+        return NextResponse.json({ error: 'Unauthorized' }, { status: 401 })
+      }
+      const userId = auth.userId
+
+      const accessCheck = await checkKnowledgeBaseWriteAccess(id, userId)
+
+      if (!accessCheck.hasAccess) {
+        if ('notFound' in accessCheck && accessCheck.notFound) {
+          logger.warn(`[${requestId}] Knowledge base not found: ${id}`)
+          return NextResponse.json({ error: 'Knowledge base not found' }, { status: 404 })
+        }
+        logger.warn(
+          `[${requestId}] User ${userId} attempted to delete unauthorized knowledge base ${id}`
+        )
+        return NextResponse.json({ error: 'Unauthorized' }, { status: 401 })
+      }
+
+      await deleteKnowledgeBase(id, requestId)
+
+      try {
+        PlatformEvents.knowledgeBaseDeleted({
+          knowledgeBaseId: id,
+        })
+      } catch {
+        // Telemetry should not fail the operation
+      }
+
+      logger.info(`[${requestId}] Knowledge base deleted: ${id} for user ${userId}`)
+
+      recordAudit({
+        workspaceId: accessCheck.knowledgeBase.workspaceId ?? null,
+        actorId: userId,
+        actorName: auth.userName,
+        actorEmail: auth.userEmail,
+        action: AuditAction.KNOWLEDGE_BASE_DELETED,
+        resourceType: AuditResourceType.KNOWLEDGE_BASE,
+        resourceId: id,
+        resourceName: accessCheck.knowledgeBase.name,
+        description: `Deleted knowledge base "${accessCheck.knowledgeBase.name || id}"`,
+        metadata: {
+          knowledgeBaseName: accessCheck.knowledgeBase.name,
+        },
+        request: _request,
+      })
+
+      return NextResponse.json({
+        success: true,
+        data: { message: 'Knowledge base deleted successfully' },
+      })
+    } catch (error) {
+      logger.error(`[${requestId}] Error deleting knowledge base`, error)
+      return NextResponse.json({ error: 'Failed to delete knowledge base' }, { status: 500 })
+    }
+  }
+)

apps/sim/app/api/knowledge/[id]/tag-definitions/[tagId]/route.ts

@@ -0,0 +1,52 @@
+import { createLogger } from '@sim/logger'
+import { generateId } from '@sim/utils/id'
+import { type NextRequest, NextResponse } from 'next/server'
+import { deleteTagDefinitionContract } from '@/lib/api/contracts/knowledge'
+import { parseRequest } from '@/lib/api/server'
+import { checkSessionOrInternalAuth } from '@/lib/auth/hybrid'
+import { withRouteHandler } from '@/lib/core/utils/with-route-handler'
+import { deleteTagDefinition } from '@/lib/knowledge/tags/service'
+import { checkKnowledgeBaseWriteAccess } from '@/app/api/knowledge/utils'
+
+export const dynamic = 'force-dynamic'
+
+const logger = createLogger('TagDefinitionAPI')
+
+// DELETE /api/knowledge/[id]/tag-definitions/[tagId] - Delete a tag definition
+export const DELETE = withRouteHandler(
+  async (req: NextRequest, context: { params: Promise<{ id: string; tagId: string }> }) => {
+    const requestId = generateId().slice(0, 8)
+    const parsed = await parseRequest(deleteTagDefinitionContract, req, context)
+    if (!parsed.success) return parsed.response
+    const { id: knowledgeBaseId, tagId } = parsed.data.params
+
+    try {
+      logger.info(
+        `[${requestId}] Deleting tag definition ${tagId} from knowledge base ${knowledgeBaseId}`
+      )
+
+      const auth = await checkSessionOrInternalAuth(req, { requireWorkflowId: false })
+      if (!auth.success || !auth.userId) {
+        return NextResponse.json({ error: 'Unauthorized' }, { status: 401 })
+      }
+
+      const accessCheck = await checkKnowledgeBaseWriteAccess(knowledgeBaseId, auth.userId)
+      if (!accessCheck.hasAccess) {
+        return NextResponse.json(
+          { error: accessCheck.notFound ? 'Not found' : 'Forbidden' },
+          { status: accessCheck.notFound ? 404 : 403 }
+        )
+      }
+
+      const deletedTag = await deleteTagDefinition(knowledgeBaseId, tagId, requestId)
+
+      return NextResponse.json({
+        success: true,
+        message: `Tag definition "${deletedTag.displayName}" deleted successfully`,
+      })
+    } catch (error) {
+      logger.error(`[${requestId}] Error deleting tag definition`, error)
+      return NextResponse.json({ error: 'Failed to delete tag definition' }, { status: 500 })
+    }
+  }
+)

apps/sim/app/api/knowledge/[id]/tag-definitions/route.ts

@@ -0,0 +1,113 @@
+import { createLogger } from '@sim/logger'
+import { generateId } from '@sim/utils/id'
+import { type NextRequest, NextResponse } from 'next/server'
+import { createTagDefinitionContract } from '@/lib/api/contracts/knowledge'
+import { parseRequest } from '@/lib/api/server'
+import { AuthType, checkSessionOrInternalAuth } from '@/lib/auth/hybrid'
+import { withRouteHandler } from '@/lib/core/utils/with-route-handler'
+import { SUPPORTED_FIELD_TYPES } from '@/lib/knowledge/constants'
+import { createTagDefinition, getTagDefinitions } from '@/lib/knowledge/tags/service'
+import { checkKnowledgeBaseWriteAccess } from '@/app/api/knowledge/utils'
+
+export const dynamic = 'force-dynamic'
+
+const logger = createLogger('KnowledgeBaseTagDefinitionsAPI')
+
+// GET /api/knowledge/[id]/tag-definitions - Get all tag definitions for a knowledge base
+export const GET = withRouteHandler(
+  async (req: NextRequest, { params }: { params: Promise<{ id: string }> }) => {
+    const requestId = generateId().slice(0, 8)
+    const { id: knowledgeBaseId } = await params
+
+    try {
+      logger.info(`[${requestId}] Getting tag definitions for knowledge base ${knowledgeBaseId}`)
+
+      const auth = await checkSessionOrInternalAuth(req, { requireWorkflowId: false })
+      if (!auth.success) {
+        return NextResponse.json({ error: auth.error || 'Unauthorized' }, { status: 401 })
+      }
+
+      // For session auth, verify KB access. Internal JWT is trusted.
+      if (auth.authType === AuthType.SESSION && auth.userId) {
+        const accessCheck = await checkKnowledgeBaseWriteAccess(knowledgeBaseId, auth.userId)
+        if (!accessCheck.hasAccess) {
+          return NextResponse.json(
+            { error: accessCheck.notFound ? 'Not found' : 'Forbidden' },
+            { status: accessCheck.notFound ? 404 : 403 }
+          )
+        }
+      }
+
+      const tagDefinitions = await getTagDefinitions(knowledgeBaseId)
+
+      logger.info(
+        `[${requestId}] Retrieved ${tagDefinitions.length} tag definitions (${auth.authType})`
+      )
+
+      return NextResponse.json({
+        success: true,
+        data: tagDefinitions,
+      })
+    } catch (error) {
+      logger.error(`[${requestId}] Error getting tag definitions`, error)
+      return NextResponse.json({ error: 'Failed to get tag definitions' }, { status: 500 })
+    }
+  }
+)
+
+// POST /api/knowledge/[id]/tag-definitions - Create a new tag definition
+export const POST = withRouteHandler(
+  async (req: NextRequest, context: { params: Promise<{ id: string }> }) => {
+    const requestId = generateId().slice(0, 8)
+    const { id: knowledgeBaseId } = await context.params
+
+    try {
+      logger.info(`[${requestId}] Creating tag definition for knowledge base ${knowledgeBaseId}`)
+
+      const auth = await checkSessionOrInternalAuth(req, { requireWorkflowId: false })
+      if (!auth.success) {
+        return NextResponse.json({ error: auth.error || 'Unauthorized' }, { status: 401 })
+      }
+
+      // For session auth, verify KB access. Internal JWT is trusted.
+      if (auth.authType === AuthType.SESSION && auth.userId) {
+        const accessCheck = await checkKnowledgeBaseWriteAccess(knowledgeBaseId, auth.userId)
+        if (!accessCheck.hasAccess) {
+          return NextResponse.json(
+            { error: accessCheck.notFound ? 'Not found' : 'Forbidden' },
+            { status: accessCheck.notFound ? 404 : 403 }
+          )
+        }
+      }
+
+      const parsed = await parseRequest(createTagDefinitionContract, req, context)
+      if (!parsed.success) return parsed.response
+
+      const validatedData = parsed.data.body
+      if (!(SUPPORTED_FIELD_TYPES as readonly string[]).includes(validatedData.fieldType)) {
+        return NextResponse.json(
+          { error: 'Invalid request data', details: 'Invalid field type' },
+          { status: 400 }
+        )
+      }
+
+      const newTagDefinition = await createTagDefinition(
+        {
+          knowledgeBaseId,
+          tagSlot: validatedData.tagSlot,
+          displayName: validatedData.displayName,
+          fieldType: validatedData.fieldType,
+        },
+        requestId
+      )
+
+      return NextResponse.json({
+        success: true,
+        data: newTagDefinition,
+      })
+    } catch (error) {
+      logger.error(`[${requestId}] Error creating tag definition`, error)
+      return NextResponse.json({ error: 'Failed to create tag definition' }, { status: 500 })
+    }
+  }
+)

apps/sim/app/api/knowledge/[id]/tag-usage/route.ts

@@ -0,0 +1,56 @@
+import { createLogger } from '@sim/logger'
+import { generateId } from '@sim/utils/id'
+import { type NextRequest, NextResponse } from 'next/server'
+import { getTagUsageContract } from '@/lib/api/contracts/knowledge'
+import { parseRequest } from '@/lib/api/server'
+import { getSession } from '@/lib/auth'
+import { withRouteHandler } from '@/lib/core/utils/with-route-handler'
+import { getTagUsage } from '@/lib/knowledge/tags/service'
+import { checkKnowledgeBaseAccess } from '@/app/api/knowledge/utils'
+
+export const dynamic = 'force-dynamic'
+
+const logger = createLogger('TagUsageAPI')
+
+// GET /api/knowledge/[id]/tag-usage - Get usage statistics for all tag definitions
+export const GET = withRouteHandler(
+  async (req: NextRequest, context: { params: Promise<{ id: string }> }) => {
+    const requestId = generateId().slice(0, 8)
+    const parsed = await parseRequest(getTagUsageContract, req, context)
+    if (!parsed.success) return parsed.response
+    const { id: knowledgeBaseId } = parsed.data.params
+
+    try {
+      logger.info(
+        `[${requestId}] Getting tag usage statistics for knowledge base ${knowledgeBaseId}`
+      )
+
+      const session = await getSession()
+      if (!session?.user?.id) {
+        return NextResponse.json({ error: 'Unauthorized' }, { status: 401 })
+      }
+
+      const accessCheck = await checkKnowledgeBaseAccess(knowledgeBaseId, session.user.id)
+      if (!accessCheck.hasAccess) {
+        return NextResponse.json(
+          { error: accessCheck.notFound ? 'Not found' : 'Forbidden' },
+          { status: accessCheck.notFound ? 404 : 403 }
+        )
+      }
+
+      const usageStats = await getTagUsage(knowledgeBaseId, requestId)
+
+      logger.info(
+        `[${requestId}] Retrieved usage statistics for ${usageStats.length} tag definitions`
+      )
+
+      return NextResponse.json({
+        success: true,
+        data: usageStats,
+      })
+    } catch (error) {
+      logger.error(`[${requestId}] Error getting tag usage statistics`, error)
+      return NextResponse.json({ error: 'Failed to get tag usage statistics' }, { status: 500 })
+    }
+  }
+)

apps/sim/app/api/knowledge/connectors/sync/route.ts

@@ -0,0 +1,112 @@
+import { db } from '@sim/db'
+import { knowledgeBase, knowledgeConnector } from '@sim/db/schema'
+import { createLogger } from '@sim/logger'
+import { and, asc, eq, inArray, isNull, lte } from 'drizzle-orm'
+import { type NextRequest, NextResponse } from 'next/server'
+import { verifyCronAuth } from '@/lib/auth/internal'
+import { mapWithConcurrency } from '@/lib/core/utils/concurrency'
+import { generateRequestId } from '@/lib/core/utils/request'
+import { withRouteHandler } from '@/lib/core/utils/with-route-handler'
+import { dispatchSync } from '@/lib/knowledge/connectors/sync-engine'
+
+export const dynamic = 'force-dynamic'
+
+const logger = createLogger('ConnectorSyncSchedulerAPI')
+
+/**
+ * Per-tick cap on sync dispatches. Ordered by oldest `nextSyncAt` first so
+ * connectors beyond the cap are picked up by the next tick, not starved.
+ */
+const MAX_DISPATCHES_PER_TICK = 200
+
+/** Each dispatch does a joined SELECT + conditional UPDATE against the shared pool. */
+const DISPATCH_CONCURRENCY = 10
+
+/**
+ * Cron endpoint that checks for connectors due for sync and dispatches sync jobs.
+ * Should be called every 5 minutes by an external cron service.
+ */
+export const GET = withRouteHandler(async (request: NextRequest) => {
+  const requestId = generateRequestId()
+  logger.info(`[${requestId}] Connector sync scheduler triggered`)
+
+  const authError = verifyCronAuth(request, 'Connector sync scheduler')
+  if (authError) {
+    return authError
+  }
+
+  try {
+    const now = new Date()
+
+    const STALE_SYNC_TTL_MS = 120 * 60 * 1000
+    const staleCutoff = new Date(now.getTime() - STALE_SYNC_TTL_MS)
+
+    const recoveredConnectors = await db
+      .update(knowledgeConnector)
+      .set({
+        status: 'error',
+        lastSyncError: 'Sync timed out (stale lock recovered)',
+        nextSyncAt: new Date(now.getTime() + 10 * 60 * 1000),
+        updatedAt: now,
+      })
+      .where(
+        and(
+          eq(knowledgeConnector.status, 'syncing'),
+          lte(knowledgeConnector.updatedAt, staleCutoff),
+          isNull(knowledgeConnector.archivedAt),
+          isNull(knowledgeConnector.deletedAt)
+        )
+      )
+      .returning({ id: knowledgeConnector.id })
+
+    if (recoveredConnectors.length > 0) {
+      logger.warn(
+        `[${requestId}] Recovered ${recoveredConnectors.length} stale syncing connectors`,
+        { ids: recoveredConnectors.map((c) => c.id) }
+      )
+    }
+
+    const dueConnectors = await db
+      .select({
+        id: knowledgeConnector.id,
+      })
+      .from(knowledgeConnector)
+      .innerJoin(knowledgeBase, eq(knowledgeConnector.knowledgeBaseId, knowledgeBase.id))
+      .where(
+        and(
+          inArray(knowledgeConnector.status, ['active', 'error']),
+          lte(knowledgeConnector.nextSyncAt, now),
+          isNull(knowledgeConnector.archivedAt),
+          isNull(knowledgeConnector.deletedAt),
+          isNull(knowledgeBase.deletedAt)
+        )
+      )
+      .orderBy(asc(knowledgeConnector.nextSyncAt))
+      .limit(MAX_DISPATCHES_PER_TICK)
+
+    logger.info(`[${requestId}] Found ${dueConnectors.length} connectors due for sync`)
+
+    if (dueConnectors.length === 0) {
+      return NextResponse.json({
+        success: true,
+        message: 'No connectors due for sync',
+        count: 0,
+      })
+    }
+
+    await mapWithConcurrency(dueConnectors, DISPATCH_CONCURRENCY, (connector) =>
+      dispatchSync(connector.id, { requestId }).catch((error) => {
+        logger.error(`[${requestId}] Failed to dispatch sync for connector ${connector.id}`, error)
+      })
+    )
+
+    return NextResponse.json({
+      success: true,
+      message: `Dispatched ${dueConnectors.length} connector sync(s)`,
+      count: dueConnectors.length,
+    })
+  } catch (error) {
+    logger.error(`[${requestId}] Connector sync scheduler error`, error)
+    return NextResponse.json({ error: 'Internal server error' }, { status: 500 })
+  }
+})

apps/sim/app/api/knowledge/route.test.ts

@@ -0,0 +1,232 @@
+/**
+ * Tests for knowledge base API route
+ *
+ * @vitest-environment node
+ */
+import {
+  auditMock,
+  authMockFns,
+  createMockRequest,
+  permissionsMock,
+  permissionsMockFns,
+} from '@sim/testing'
+import { afterEach, beforeEach, describe, expect, it, vi } from 'vitest'
+
+const { mockDbChain } = vi.hoisted(() => {
+  const mockDbChain = {
+    select: vi.fn().mockReturnThis(),
+    from: vi.fn().mockReturnThis(),
+    leftJoin: vi.fn().mockReturnThis(),
+    where: vi.fn().mockReturnThis(),
+    groupBy: vi.fn().mockReturnThis(),
+    orderBy: vi.fn().mockResolvedValue([]),
+    limit: vi.fn().mockResolvedValue([]),
+    insert: vi.fn().mockReturnThis(),
+    values: vi.fn().mockResolvedValue(undefined),
+  }
+  return { mockDbChain }
+})
+
+vi.mock('@sim/db', () => ({
+  db: mockDbChain,
+}))
+
+vi.mock('@sim/audit', () => auditMock)
+
+vi.mock('@/lib/workspaces/permissions/utils', () => permissionsMock)
+
+import { GET, POST } from '@/app/api/knowledge/route'
+
+describe('Knowledge Base API Route', () => {
+  beforeEach(() => {
+    vi.clearAllMocks()
+
+    Object.values(mockDbChain).forEach((fn) => {
+      if (typeof fn === 'function') {
+        fn.mockClear()
+        if (fn !== mockDbChain.orderBy && fn !== mockDbChain.values && fn !== mockDbChain.limit) {
+          fn.mockReturnThis()
+        }
+      }
+    })
+
+    permissionsMockFns.mockGetUserEntityPermissions.mockResolvedValue('admin')
+
+    vi.stubGlobal('crypto', {
+      randomUUID: vi.fn().mockReturnValue('mock-uuid-1234-5678'),
+    })
+  })
+
+  afterEach(() => {
+    vi.clearAllMocks()
+  })
+
+  describe('GET /api/knowledge', () => {
+    it('should return unauthorized for unauthenticated user', async () => {
+      authMockFns.mockGetSession.mockResolvedValue(null)
+
+      const req = createMockRequest('GET')
+      const response = await GET(req)
+      const data = await response.json()
+
+      expect(response.status).toBe(401)
+      expect(data.error).toBe('Unauthorized')
+    })
+
+    it('should handle database errors', async () => {
+      authMockFns.mockGetSession.mockResolvedValue({
+        user: { id: 'user-123', email: 'test@example.com' },
+      })
+      mockDbChain.orderBy.mockRejectedValue(new Error('Database error'))
+
+      const req = createMockRequest('GET')
+      const response = await GET(req)
+      const data = await response.json()
+
+      expect(response.status).toBe(500)
+      expect(data.error).toBe('Failed to fetch knowledge bases')
+    })
+  })
+
+  describe('POST /api/knowledge', () => {
+    const validKnowledgeBaseData = {
+      name: 'Test Knowledge Base',
+      description: 'Test description',
+      workspaceId: 'test-workspace-id',
+      chunkingConfig: {
+        maxSize: 1024,
+        minSize: 100,
+        overlap: 200,
+      },
+    }
+
+    it('should create knowledge base successfully', async () => {
+      authMockFns.mockGetSession.mockResolvedValue({
+        user: { id: 'user-123', email: 'test@example.com' },
+      })
+
+      const req = createMockRequest('POST', validKnowledgeBaseData)
+      const response = await POST(req)
+      const data = await response.json()
+
+      expect(response.status).toBe(200)
+      expect(data.success).toBe(true)
+      expect(data.data.name).toBe(validKnowledgeBaseData.name)
+      expect(data.data.description).toBe(validKnowledgeBaseData.description)
+      expect(mockDbChain.insert).toHaveBeenCalled()
+    })
+
+    it('should return unauthorized for unauthenticated user', async () => {
+      authMockFns.mockGetSession.mockResolvedValue(null)
+
+      const req = createMockRequest('POST', validKnowledgeBaseData)
+      const response = await POST(req)
+      const data = await response.json()
+
+      expect(response.status).toBe(401)
+      expect(data.error).toBe('Unauthorized')
+    })
+
+    it('should validate required fields', async () => {
+      authMockFns.mockGetSession.mockResolvedValue({
+        user: { id: 'user-123', email: 'test@example.com' },
+      })
+
+      const req = createMockRequest('POST', { description: 'Missing name' })
+      const response = await POST(req)
+      const data = await response.json()
+
+      expect(response.status).toBe(400)
+      expect(data.error).toBe('Invalid request data')
+      expect(data.details).toBeDefined()
+    })
+
+    it('should require workspaceId', async () => {
+      authMockFns.mockGetSession.mockResolvedValue({
+        user: { id: 'user-123', email: 'test@example.com' },
+      })
+
+      const req = createMockRequest('POST', { name: 'Test KB' })
+      const response = await POST(req)
+      const data = await response.json()
+
+      expect(response.status).toBe(400)
+      expect(data.error).toBe('Invalid request data')
+      expect(data.details).toBeDefined()
+    })
+
+    it('returns 403 when user lacks permission on target workspace', async () => {
+      authMockFns.mockGetSession.mockResolvedValue({
+        user: { id: 'attacker', email: 'a@example.com' },
+      })
+      permissionsMockFns.mockGetUserEntityPermissions.mockResolvedValueOnce('read')
+
+      const req = createMockRequest('POST', validKnowledgeBaseData)
+      const response = await POST(req)
+      const data = await response.json()
+
+      expect(response.status).toBe(403)
+      expect(data.error).toBe(
+        'User does not have permission to create knowledge bases in this workspace'
+      )
+      expect(mockDbChain.insert).not.toHaveBeenCalled()
+    })
+
+    it('should validate chunking config constraints', async () => {
+      authMockFns.mockGetSession.mockResolvedValue({
+        user: { id: 'user-123', email: 'test@example.com' },
+      })
+
+      const invalidData = {
+        name: 'Test KB',
+        workspaceId: 'test-workspace-id',
+        chunkingConfig: {
+          maxSize: 100, // 100 tokens = 400 characters
+          minSize: 500, // Invalid: minSize (500 chars) > maxSize (400 chars)
+          overlap: 50,
+        },
+      }
+
+      const req = createMockRequest('POST', invalidData)
+      const response = await POST(req)
+      const data = await response.json()
+
+      expect(response.status).toBe(400)
+      expect(data.error).toBe('Invalid request data')
+    })
+
+    it('should use default values for optional fields', async () => {
+      authMockFns.mockGetSession.mockResolvedValue({
+        user: { id: 'user-123', email: 'test@example.com' },
+      })
+
+      const minimalData = { name: 'Test KB', workspaceId: 'test-workspace-id' }
+      const req = createMockRequest('POST', minimalData)
+      const response = await POST(req)
+      const data = await response.json()
+
+      expect(response.status).toBe(200)
+      expect(data.data.embeddingModel).toBe('text-embedding-3-small')
+      expect(data.data.embeddingDimension).toBe(1536)
+      expect(data.data.chunkingConfig).toEqual({
+        maxSize: 1024,
+        minSize: 100,
+        overlap: 200,
+      })
+    })
+
+    it('should handle database errors during creation', async () => {
+      authMockFns.mockGetSession.mockResolvedValue({
+        user: { id: 'user-123', email: 'test@example.com' },
+      })
+      mockDbChain.values.mockRejectedValue(new Error('Database error'))
+
+      const req = createMockRequest('POST', validKnowledgeBaseData)
+      const response = await POST(req)
+      const data = await response.json()
+
+      expect(response.status).toBe(500)
+      expect(data.error).toBe('Failed to create knowledge base')
+    })
+  })
+})

apps/sim/app/api/knowledge/route.ts

@@ -0,0 +1,173 @@
+import { AuditAction, AuditResourceType, recordAudit } from '@sim/audit'
+import { createLogger } from '@sim/logger'
+import { type NextRequest, NextResponse } from 'next/server'
+import {
+  createKnowledgeBaseContract,
+  listKnowledgeBasesQuerySchema,
+} from '@/lib/api/contracts/knowledge'
+import { parseRequest } from '@/lib/api/server'
+import { getSession } from '@/lib/auth'
+import { PlatformEvents } from '@/lib/core/telemetry'
+import { generateRequestId } from '@/lib/core/utils/request'
+import { withRouteHandler } from '@/lib/core/utils/with-route-handler'
+import { EMBEDDING_DIMENSIONS, getConfiguredEmbeddingModel } from '@/lib/knowledge/embeddings'
+import {
+  createKnowledgeBase,
+  getKnowledgeBases,
+  KnowledgeBaseConflictError,
+  KnowledgeBasePermissionError,
+  type KnowledgeBaseScope,
+} from '@/lib/knowledge/service'
+import { captureServerEvent } from '@/lib/posthog/server'
+
+const logger = createLogger('KnowledgeBaseAPI')
+
+export const GET = withRouteHandler(async (req: NextRequest) => {
+  const requestId = generateRequestId()
+
+  try {
+    const session = await getSession()
+    if (!session?.user?.id) {
+      logger.warn(`[${requestId}] Unauthorized knowledge base access attempt`)
+      return NextResponse.json({ error: 'Unauthorized' }, { status: 401 })
+    }
+
+    const { searchParams } = new URL(req.url)
+    const query = listKnowledgeBasesQuerySchema.safeParse({
+      workspaceId: searchParams.get('workspaceId') ?? undefined,
+      scope: searchParams.get('scope') ?? undefined,
+    })
+    if (!query.success) {
+      return NextResponse.json(
+        { error: 'Invalid query parameters', details: query.error.issues },
+        { status: 400 }
+      )
+    }
+    const { workspaceId, scope } = query.data
+
+    const knowledgeBasesWithCounts = await getKnowledgeBases(
+      session.user.id,
+      workspaceId,
+      scope as KnowledgeBaseScope
+    )
+
+    return NextResponse.json({
+      success: true,
+      data: knowledgeBasesWithCounts,
+    })
+  } catch (error) {
+    logger.error(`[${requestId}] Error fetching knowledge bases`, error)
+    return NextResponse.json({ error: 'Failed to fetch knowledge bases' }, { status: 500 })
+  }
+})
+
+export const POST = withRouteHandler(async (req: NextRequest) => {
+  const requestId = generateRequestId()
+
+  try {
+    const session = await getSession()
+    if (!session?.user?.id) {
+      logger.warn(`[${requestId}] Unauthorized knowledge base creation attempt`)
+      return NextResponse.json({ error: 'Unauthorized' }, { status: 401 })
+    }
+
+    const parsed = await parseRequest(
+      createKnowledgeBaseContract,
+      req,
+      {},
+      {
+        validationErrorResponse: (error) => {
+          logger.warn(`[${requestId}] Invalid knowledge base data`, { errors: error.issues })
+          return NextResponse.json(
+            { error: 'Invalid request data', details: error.issues },
+            { status: 400 }
+          )
+        },
+      }
+    )
+    if (!parsed.success) return parsed.response
+
+    const validatedData = parsed.data.body
+
+    try {
+      const embeddingModel = getConfiguredEmbeddingModel()
+
+      const createData = {
+        ...validatedData,
+        userId: session.user.id,
+        embeddingModel,
+        embeddingDimension: EMBEDDING_DIMENSIONS,
+      }
+
+      const newKnowledgeBase = await createKnowledgeBase(createData, requestId)
+
+      try {
+        PlatformEvents.knowledgeBaseCreated({
+          knowledgeBaseId: newKnowledgeBase.id,
+          name: validatedData.name,
+          workspaceId: validatedData.workspaceId,
+        })
+      } catch {
+        // Telemetry should not fail the operation
+      }
+
+      captureServerEvent(
+        session.user.id,
+        'knowledge_base_created',
+        {
+          knowledge_base_id: newKnowledgeBase.id,
+          workspace_id: validatedData.workspaceId,
+          name: validatedData.name,
+        },
+        {
+          groups: { workspace: validatedData.workspaceId },
+          setOnce: { first_kb_created_at: new Date().toISOString() },
+        }
+      )
+
+      logger.info(
+        `[${requestId}] Knowledge base created: ${newKnowledgeBase.id} for user ${session.user.id}`
+      )
+
+      recordAudit({
+        workspaceId: validatedData.workspaceId,
+        actorId: session.user.id,
+        actorName: session.user.name,
+        actorEmail: session.user.email,
+        action: AuditAction.KNOWLEDGE_BASE_CREATED,
+        resourceType: AuditResourceType.KNOWLEDGE_BASE,
+        resourceId: newKnowledgeBase.id,
+        resourceName: validatedData.name,
+        description: `Created knowledge base "${validatedData.name}"`,
+        metadata: {
+          name: validatedData.name,
+          description: validatedData.description,
+          embeddingModel,
+          embeddingDimension: EMBEDDING_DIMENSIONS,
+          chunkingStrategy: validatedData.chunkingConfig.strategy,
+          chunkMaxSize: validatedData.chunkingConfig.maxSize,
+          chunkMinSize: validatedData.chunkingConfig.minSize,
+          chunkOverlap: validatedData.chunkingConfig.overlap,
+        },
+        request: req,
+      })
+
+      return NextResponse.json({
+        success: true,
+        data: newKnowledgeBase,
+      })
+    } catch (createError) {
+      if (createError instanceof KnowledgeBaseConflictError) {
+        return NextResponse.json({ error: createError.message }, { status: 409 })
+      }
+      if (createError instanceof KnowledgeBasePermissionError) {
+        logger.warn(`[${requestId}] Forbidden knowledge base creation: ${createError.message}`)
+        return NextResponse.json({ error: createError.message }, { status: 403 })
+      }
+      throw createError
+    }
+  } catch (error) {
+    logger.error(`[${requestId}] Error creating knowledge base`, error)
+    return NextResponse.json({ error: 'Failed to create knowledge base' }, { status: 500 })
+  }
+})

apps/sim/app/api/knowledge/search/route.ts

@@ -0,0 +1,546 @@
+import { createLogger } from '@sim/logger'
+import { authorizeWorkflowByWorkspacePermission } from '@sim/platform-authz/workflow'
+import { getErrorMessage } from '@sim/utils/errors'
+import { type NextRequest, NextResponse } from 'next/server'
+import { knowledgeSearchBodySchema } from '@/lib/api/contracts/knowledge'
+import { parseJsonBody, validationErrorResponse } from '@/lib/api/server'
+import { AuthType, checkSessionOrInternalAuth } from '@/lib/auth/hybrid'
+import { checkActorUsageLimits } from '@/lib/billing/calculations/usage-monitor'
+import { PlatformEvents } from '@/lib/core/telemetry'
+import { generateRequestId } from '@/lib/core/utils/request'
+import { withRouteHandler } from '@/lib/core/utils/with-route-handler'
+import { ALL_TAG_SLOTS } from '@/lib/knowledge/constants'
+import { getEmbeddingModelInfo } from '@/lib/knowledge/embedding-models'
+import { rerank } from '@/lib/knowledge/reranker'
+import { getDocumentTagDefinitions } from '@/lib/knowledge/tags/service'
+import { buildUndefinedTagsError, validateTagValue } from '@/lib/knowledge/tags/utils'
+import type { StructuredFilter } from '@/lib/knowledge/types'
+import { estimateTokenCount } from '@/lib/tokenization/estimators'
+import {
+  generateSearchEmbedding,
+  getDocumentMetadataByIds,
+  getQueryStrategy,
+  handleTagAndVectorSearch,
+  handleTagOnlySearch,
+  handleVectorOnlySearch,
+  type SearchResult,
+} from '@/app/api/knowledge/search/utils'
+import { checkKnowledgeBaseAccess, type KnowledgeBaseAccessResult } from '@/app/api/knowledge/utils'
+import { getRerankModelPricing } from '@/providers/models'
+import { calculateCost } from '@/providers/utils'
+
+const logger = createLogger('VectorSearchAPI')
+
+export const POST = withRouteHandler(async (request: NextRequest) => {
+  const requestId = generateRequestId()
+
+  try {
+    const parsedBody = await parseJsonBody(request)
+    if (!parsedBody.success) return parsedBody.response
+    const body = parsedBody.data as Record<string, unknown>
+    const { workflowId, skipUsageBilling, ...searchParams } = body
+
+    const auth = await checkSessionOrInternalAuth(request, { requireWorkflowId: false })
+    if (!auth.success || !auth.userId) {
+      return NextResponse.json({ error: 'Unauthorized' }, { status: 401 })
+    }
+    const userId = auth.userId
+
+    // Only the internal workflow tool may suppress route metering (it rolls the
+    // cost into the executor's usage instead). Session/API-key callers cannot set
+    // skipUsageBilling to dodge their own embedding/reranker charge.
+    const shouldMeter = !(skipUsageBilling === true && auth.authType === AuthType.INTERNAL_JWT)
+
+    if (workflowId) {
+      const authorization = await authorizeWorkflowByWorkspacePermission({
+        workflowId: workflowId as string,
+        userId,
+        action: 'read',
+      })
+      if (!authorization.allowed) {
+        return NextResponse.json(
+          { error: authorization.message || 'Access denied' },
+          { status: authorization.status }
+        )
+      }
+    }
+
+    const validation = knowledgeSearchBodySchema.safeParse(searchParams)
+    if (!validation.success) return validationErrorResponse(validation.error)
+    const validatedData = validation.data
+
+    const knowledgeBaseIds = Array.isArray(validatedData.knowledgeBaseIds)
+      ? validatedData.knowledgeBaseIds
+      : [validatedData.knowledgeBaseIds]
+
+    const accessChecks = await Promise.all(
+      knowledgeBaseIds.map((kbId) => checkKnowledgeBaseAccess(kbId, userId))
+    )
+    const accessibleKbIds: string[] = knowledgeBaseIds.filter(
+      (_, idx) => accessChecks[idx]?.hasAccess
+    )
+
+    let structuredFilters: StructuredFilter[] = []
+
+    if (validatedData.tagFilters && accessibleKbIds.length > 0) {
+      const kbTagDefs = await Promise.all(
+        accessibleKbIds.map(async (kbId) => ({
+          kbId,
+          tagDefs: await getDocumentTagDefinitions(kbId),
+        }))
+      )
+
+      const displayNameToTagDef: Record<string, { tagSlot: string; fieldType: string }> = {}
+      for (const { kbId, tagDefs } of kbTagDefs) {
+        const perKbMap = new Map(
+          tagDefs.map((def) => [
+            def.displayName,
+            { tagSlot: def.tagSlot, fieldType: def.fieldType },
+          ])
+        )
+
+        for (const filter of validatedData.tagFilters) {
+          const current = perKbMap.get(filter.tagName)
+          if (!current) {
+            if (accessibleKbIds.length > 1) {
+              return NextResponse.json(
+                {
+                  error: `Tag "${filter.tagName}" does not exist in all selected knowledge bases. Search those knowledge bases separately.`,
+                },
+                { status: 400 }
+              )
+            }
+            continue
+          }
+
+          const existing = displayNameToTagDef[filter.tagName]
+          if (
+            existing &&
+            (existing.tagSlot !== current.tagSlot || existing.fieldType !== current.fieldType)
+          ) {
+            return NextResponse.json(
+              {
+                error: `Tag "${filter.tagName}" is not mapped consistently across the selected knowledge bases. Search those knowledge bases separately.`,
+              },
+              { status: 400 }
+            )
+          }
+
+          displayNameToTagDef[filter.tagName] = current
+        }
+
+        logger.debug(`[${requestId}] Loaded tag definitions for KB ${kbId}`, {
+          tagCount: tagDefs.length,
+        })
+      }
+
+      const undefinedTags: string[] = []
+      const typeErrors: string[] = []
+
+      for (const filter of validatedData.tagFilters) {
+        const tagDef = displayNameToTagDef[filter.tagName]
+
+        if (!tagDef) {
+          undefinedTags.push(filter.tagName)
+          continue
+        }
+
+        const validationError = validateTagValue(
+          filter.tagName,
+          String(filter.value),
+          tagDef.fieldType
+        )
+        if (validationError) {
+          typeErrors.push(validationError)
+        }
+      }
+
+      if (undefinedTags.length > 0 || typeErrors.length > 0) {
+        const errorParts: string[] = []
+
+        if (undefinedTags.length > 0) {
+          errorParts.push(buildUndefinedTagsError(undefinedTags))
+        }
+
+        if (typeErrors.length > 0) {
+          errorParts.push(...typeErrors)
+        }
+
+        return NextResponse.json({ error: errorParts.join('\n') }, { status: 400 })
+      }
+
+      structuredFilters = validatedData.tagFilters.map((filter) => {
+        const tagDef = displayNameToTagDef[filter.tagName]!
+        const tagSlot = tagDef.tagSlot
+        const fieldType = tagDef.fieldType
+
+        logger.debug(
+          `[${requestId}] Structured filter: ${filter.tagName} -> ${tagSlot} (${fieldType}) ${filter.operator} ${filter.value}`
+        )
+
+        return {
+          tagSlot,
+          fieldType,
+          operator: filter.operator,
+          value: filter.value,
+          valueTo: filter.valueTo,
+        }
+      })
+    }
+
+    if (accessibleKbIds.length === 0) {
+      return NextResponse.json(
+        { error: 'Knowledge base not found or access denied' },
+        { status: 404 }
+      )
+    }
+
+    const accessibleKbs = accessChecks
+      .filter((ac): ac is KnowledgeBaseAccessResult => Boolean(ac?.hasAccess))
+      .map((ac) => ac.knowledgeBase)
+    const workspaceId = accessibleKbs[0]?.workspaceId
+
+    const useReranker = validatedData.rerankerEnabled && Boolean(validatedData.query?.trim())
+    const rerankerModel = useReranker ? validatedData.rerankerModel : null
+
+    const hasQuery = validatedData.query && validatedData.query.trim().length > 0
+    const embeddingModels = Array.from(new Set(accessibleKbs.map((kb) => kb.embeddingModel)))
+    if (hasQuery && embeddingModels.length > 1) {
+      return NextResponse.json(
+        {
+          error:
+            'Selected knowledge bases use different embedding models and cannot be searched together. Search them separately.',
+        },
+        { status: 400 }
+      )
+    }
+    const queryEmbeddingModel = embeddingModels[0]
+
+    const inaccessibleKbIds = knowledgeBaseIds.filter((id) => !accessibleKbIds.includes(id))
+
+    if (inaccessibleKbIds.length > 0) {
+      return NextResponse.json(
+        { error: `Knowledge bases not found or access denied: ${inaccessibleKbIds.join(', ')}` },
+        { status: 404 }
+      )
+    }
+
+    // Gate the actor before incurring hosted embedding cost, unless this is the
+    // internal workflow tool (already gated at preprocessing, rolls cost up). Tag-only
+    // search is free, so only the query path is gated.
+    if (shouldMeter && hasQuery) {
+      const usage = await checkActorUsageLimits(userId, workspaceId)
+      if (usage.isExceeded) {
+        return NextResponse.json(
+          { error: usage.message || 'Usage limit exceeded. Please upgrade your plan to continue.' },
+          { status: 402 }
+        )
+      }
+    }
+
+    const queryEmbeddingPromise = hasQuery
+      ? generateSearchEmbedding(validatedData.query!, queryEmbeddingModel, workspaceId)
+      : Promise.resolve(null)
+
+    if (workflowId) {
+      const authorization = await authorizeWorkflowByWorkspacePermission({
+        workflowId: workflowId as string,
+        userId,
+        action: 'read',
+      })
+      const workflowWorkspaceId = authorization.workflow?.workspaceId ?? null
+      if (
+        workflowWorkspaceId &&
+        accessChecks.some(
+          (accessCheck) =>
+            accessCheck?.hasAccess && accessCheck.knowledgeBase?.workspaceId !== workflowWorkspaceId
+        )
+      ) {
+        return NextResponse.json(
+          { error: 'Knowledge base does not belong to the workflow workspace' },
+          { status: 400 }
+        )
+      }
+    }
+
+    let results: SearchResult[]
+
+    const hasFilters = structuredFilters && structuredFilters.length > 0
+
+    /** Oversample vector results when reranking so the reranker has more to choose from.
+     * Cap at 100 to bound Cohere request cost (1 search unit = ≤100 docs). When the caller
+     * supplies `rerankerInputCount`, honor it but never let it drop below `topK`
+     * (which would defeat the purpose) or exceed 100 (which would split into >1 search units). */
+    const rawInputCount = validatedData.rerankerInputCount
+    if (useReranker && rawInputCount !== undefined && rawInputCount < validatedData.topK) {
+      logger.warn(
+        `[${requestId}] rerankerInputCount (${rawInputCount}) is below topK (${validatedData.topK}); raising to topK`
+      )
+    }
+    const candidateTopK = useReranker
+      ? rawInputCount !== undefined
+        ? Math.min(100, Math.max(validatedData.topK, rawInputCount))
+        : Math.min(100, validatedData.topK * 4)
+      : validatedData.topK
+
+    if (!hasQuery && hasFilters) {
+      results = await handleTagOnlySearch({
+        knowledgeBaseIds: accessibleKbIds,
+        topK: validatedData.topK,
+        structuredFilters,
+      })
+    } else if (hasQuery && hasFilters) {
+      logger.debug(`[${requestId}] Executing tag + vector search with filters:`, structuredFilters)
+      const strategy = getQueryStrategy(accessibleKbIds.length, candidateTopK)
+      const queryVector = JSON.stringify((await queryEmbeddingPromise)?.embedding ?? null)
+
+      results = await handleTagAndVectorSearch({
+        knowledgeBaseIds: accessibleKbIds,
+        topK: candidateTopK,
+        structuredFilters,
+        queryVector,
+        distanceThreshold: strategy.distanceThreshold,
+      })
+    } else if (hasQuery && !hasFilters) {
+      const strategy = getQueryStrategy(accessibleKbIds.length, candidateTopK)
+      const queryVector = JSON.stringify((await queryEmbeddingPromise)?.embedding ?? null)
+
+      results = await handleVectorOnlySearch({
+        knowledgeBaseIds: accessibleKbIds,
+        topK: candidateTopK,
+        queryVector,
+        distanceThreshold: strategy.distanceThreshold,
+      })
+    } else {
+      return NextResponse.json(
+        {
+          error:
+            'Please provide either a search query or tag filters to search your knowledge base',
+        },
+        { status: 400 }
+      )
+    }
+
+    /** Optional Cohere rerank pass on top of vector results.
+     * `rerankBilled` = Cohere was successfully called (even with 0 results) and we owe the search unit. */
+    const rerankedScores = new Map<string, number>()
+    let rerankBilled = false
+    let rerankIsBYOK = false
+    if (useReranker && rerankerModel && results.length > 0) {
+      const candidateCount = results.length
+      try {
+        const { results: ranked, isBYOK } = await rerank(
+          validatedData.query!,
+          results.map((r) => ({ id: r.id, text: r.content })),
+          {
+            model: rerankerModel,
+            topN: validatedData.topK,
+            workspaceId,
+            apiKey: validatedData.rerankerApiKey,
+          }
+        )
+        rerankBilled = true
+        rerankIsBYOK = isBYOK
+        if (ranked.length === 0) {
+          logger.warn(
+            `[${requestId}] Reranker returned 0 results; falling back to vector ordering`,
+            { model: rerankerModel, candidateCount }
+          )
+          results = results.slice(0, validatedData.topK)
+        } else {
+          const idToResult = new Map(results.map((r) => [r.id, r]))
+          results = ranked
+            .map((r) => idToResult.get(r.item.id))
+            .filter((r): r is SearchResult => Boolean(r))
+          for (const r of ranked) rerankedScores.set(r.item.id, r.relevanceScore)
+          logger.info(`[${requestId}] Reranked ${candidateCount} → ${results.length} results`, {
+            model: rerankerModel,
+          })
+        }
+      } catch (error) {
+        logger.warn(`[${requestId}] Reranker failed; falling back to vector ordering`, {
+          error: getErrorMessage(error, 'Unknown error'),
+          model: rerankerModel,
+          candidateCount,
+          workspaceId,
+        })
+        results = results.slice(0, validatedData.topK)
+      }
+    } else if (useReranker) {
+      results = results.slice(0, validatedData.topK)
+    }
+
+    let cost = null
+    let tokenCount = null
+    if (hasQuery) {
+      try {
+        tokenCount = estimateTokenCount(
+          validatedData.query!,
+          getEmbeddingModelInfo(queryEmbeddingModel).tokenizerProvider
+        )
+        // BYOK query embeddings incur no Sim cost, so don't bill (or roll up) them.
+        const queryEmbeddingResult = await queryEmbeddingPromise
+        if (!queryEmbeddingResult?.isBYOK) {
+          cost = calculateCost(queryEmbeddingModel, tokenCount.count, 0, false)
+        }
+      } catch (error) {
+        logger.warn(`[${requestId}] Failed to calculate cost for search query`, {
+          error: getErrorMessage(error, 'Unknown error'),
+        })
+      }
+    }
+
+    /** Add Cohere rerank cost (1 search unit per successful call, since we cap candidates ≤100).
+     * Bill on every successful API response — Cohere charges even when 0 results are returned. */
+    let rerankerCost = 0
+    if (rerankBilled && rerankerModel && !rerankIsBYOK) {
+      const pricing = getRerankModelPricing(rerankerModel)
+      if (pricing) {
+        rerankerCost = pricing.perSearchUnit
+        if (cost) {
+          cost = {
+            ...cost,
+            input: cost.input + rerankerCost,
+            total: cost.total + rerankerCost,
+          }
+        } else {
+          cost = {
+            input: rerankerCost,
+            output: 0,
+            total: rerankerCost,
+            pricing: { input: 0, output: 0, updatedAt: pricing.updatedAt },
+          }
+        }
+      } else {
+        logger.warn(`[${requestId}] No pricing entry for rerank model ${rerankerModel}`)
+      }
+    }
+
+    // Record query-embedding + reranker cost for standalone callers (UI, copilot,
+    // guardrail RAG). The workflow tool sets skipUsageBilling and rolls the cost
+    // up via the executor instead, so this never double-bills; BYOK already
+    // resolved to 0 above.
+    if (shouldMeter && workspaceId && cost && cost.total > 0) {
+      const { recordUsage } = await import('@/lib/billing/core/usage-log')
+      await recordUsage({
+        userId,
+        workspaceId,
+        entries: [
+          {
+            category: 'model',
+            source: 'knowledge-base',
+            description: queryEmbeddingModel,
+            cost: cost.total,
+            sourceReference: `kb-search:${requestId}`,
+          },
+        ],
+      }).catch((billingError) => {
+        logger.error(`[${requestId}] Failed to record KB search usage`, { error: billingError })
+      })
+    }
+
+    const tagDefsResults = await Promise.all(
+      accessibleKbIds.map(async (kbId) => {
+        try {
+          const tagDefs = await getDocumentTagDefinitions(kbId)
+          const map: Record<string, string> = {}
+          tagDefs.forEach((def) => {
+            map[def.tagSlot] = def.displayName
+          })
+          return { kbId, map }
+        } catch (error) {
+          logger.warn(`[${requestId}] Failed to fetch tag definitions for display mapping:`, error)
+          return { kbId, map: {} as Record<string, string> }
+        }
+      })
+    )
+    const tagDefinitionsMap: Record<string, Record<string, string>> = {}
+    tagDefsResults.forEach(({ kbId, map }) => {
+      tagDefinitionsMap[kbId] = map
+    })
+
+    const documentIds = results.map((result) => result.documentId)
+    const documentMetadataMap = await getDocumentMetadataByIds(documentIds)
+
+    try {
+      PlatformEvents.knowledgeBaseSearched({
+        knowledgeBaseId: accessibleKbIds[0],
+        resultsCount: results.length,
+        workspaceId: workspaceId || undefined,
+      })
+    } catch {
+      // Telemetry should not fail the operation
+    }
+
+    return NextResponse.json({
+      success: true,
+      data: {
+        results: results.map((result) => {
+          const kbTagMap = tagDefinitionsMap[result.knowledgeBaseId] || {}
+          logger.debug(
+            `[${requestId}] Result KB: ${result.knowledgeBaseId}, available mappings:`,
+            kbTagMap
+          )
+
+          const tags: Record<string, any> = {}
+
+          ALL_TAG_SLOTS.forEach((slot) => {
+            const tagValue = (result as any)[slot]
+            if (tagValue !== null && tagValue !== undefined) {
+              const displayName = kbTagMap[slot] || slot
+              logger.debug(
+                `[${requestId}] Mapping ${slot}="${tagValue}" -> "${displayName}"="${tagValue}"`
+              )
+              tags[displayName] = tagValue
+            }
+          })
+
+          const rerankerScore = rerankedScores.get(result.id)
+          const docMeta = documentMetadataMap[result.documentId]
+          return {
+            documentId: result.documentId,
+            documentName: docMeta?.filename || undefined,
+            sourceUrl: docMeta?.sourceUrl ?? null,
+            content: result.content,
+            chunkIndex: result.chunkIndex,
+            metadata: tags,
+            similarity: hasQuery ? 1 - result.distance : 1,
+            ...(rerankerScore !== undefined && { rerankerScore }),
+          }
+        }),
+        query: validatedData.query || '',
+        knowledgeBaseIds: accessibleKbIds,
+        knowledgeBaseId: accessibleKbIds[0],
+        topK: validatedData.topK,
+        totalResults: results.length,
+        ...(cost
+          ? {
+              cost: {
+                input: cost.input,
+                output: cost.output,
+                total: cost.total,
+                tokens: {
+                  prompt: tokenCount?.count ?? 0,
+                  completion: 0,
+                  total: tokenCount?.count ?? 0,
+                },
+                model: queryEmbeddingModel,
+                pricing: cost.pricing,
+                ...(rerankBilled && !rerankIsBYOK
+                  ? { rerankerCost, rerankerModel, rerankerSearchUnits: 1 }
+                  : {}),
+              },
+            }
+          : {}),
+      },
+    })
+  } catch (error) {
+    return NextResponse.json(
+      {
+        error: 'Failed to perform vector search',
+        message: getErrorMessage(error, 'Unknown error'),
+      },
+      { status: 500 }
+    )
+  }
+})

apps/sim/app/api/knowledge/search/utils.test.ts

@@ -0,0 +1,408 @@
+/**
+ * Tests for knowledge search utility functions
+ * Focuses on testing core functionality with simplified mocking
+ *
+ * @vitest-environment node
+ */
+import { createEnvMock } from '@sim/testing'
+import { mockNextFetchResponse } from '@sim/testing/mocks'
+import { beforeEach, describe, expect, it, vi } from 'vitest'
+
+vi.mock('drizzle-orm')
+vi.mock('@/lib/knowledge/documents/utils', () => ({
+  retryWithExponentialBackoff: (fn: any) => fn(),
+}))
+
+vi.mock('@/lib/core/config/env', () => createEnvMock())
+
+import {
+  generateSearchEmbedding,
+  handleTagAndVectorSearch,
+  handleTagOnlySearch,
+  handleVectorOnlySearch,
+} from '@/app/api/knowledge/search/utils'
+
+describe('Knowledge Search Utils', () => {
+  beforeEach(() => {
+    vi.clearAllMocks()
+  })
+
+  describe('handleTagOnlySearch', () => {
+    it('should throw error when no filters provided', async () => {
+      const params = {
+        knowledgeBaseIds: ['kb-123'],
+        topK: 10,
+        structuredFilters: [],
+      }
+
+      await expect(handleTagOnlySearch(params)).rejects.toThrow(
+        'Tag filters are required for tag-only search'
+      )
+    })
+
+    it('should accept valid parameters for tag-only search', async () => {
+      const params = {
+        knowledgeBaseIds: ['kb-123'],
+        topK: 10,
+        structuredFilters: [{ tagSlot: 'tag1', fieldType: 'text', operator: 'eq', value: 'api' }],
+      }
+
+      // This test validates the function accepts the right parameters
+      // The actual database interaction is tested via route tests
+      expect(params.knowledgeBaseIds).toEqual(['kb-123'])
+      expect(params.topK).toBe(10)
+      expect(params.structuredFilters).toHaveLength(1)
+    })
+  })
+
+  describe('handleVectorOnlySearch', () => {
+    it('should throw error when queryVector not provided', async () => {
+      const params = {
+        knowledgeBaseIds: ['kb-123'],
+        topK: 10,
+        distanceThreshold: 0.8,
+      }
+
+      await expect(handleVectorOnlySearch(params)).rejects.toThrow(
+        'Query vector and distance threshold are required for vector-only search'
+      )
+    })
+
+    it('should throw error when distanceThreshold not provided', async () => {
+      const params = {
+        knowledgeBaseIds: ['kb-123'],
+        topK: 10,
+        queryVector: JSON.stringify([0.1, 0.2, 0.3]),
+      }
+
+      await expect(handleVectorOnlySearch(params)).rejects.toThrow(
+        'Query vector and distance threshold are required for vector-only search'
+      )
+    })
+
+    it('should accept valid parameters for vector-only search', async () => {
+      const params = {
+        knowledgeBaseIds: ['kb-123'],
+        topK: 10,
+        queryVector: JSON.stringify([0.1, 0.2, 0.3]),
+        distanceThreshold: 0.8,
+      }
+
+      // This test validates the function accepts the right parameters
+      expect(params.knowledgeBaseIds).toEqual(['kb-123'])
+      expect(params.topK).toBe(10)
+      expect(params.queryVector).toBe(JSON.stringify([0.1, 0.2, 0.3]))
+      expect(params.distanceThreshold).toBe(0.8)
+    })
+  })
+
+  describe('handleTagAndVectorSearch', () => {
+    it('should throw error when no filters provided', async () => {
+      const params = {
+        knowledgeBaseIds: ['kb-123'],
+        topK: 10,
+        structuredFilters: [],
+        queryVector: JSON.stringify([0.1, 0.2, 0.3]),
+        distanceThreshold: 0.8,
+      }
+
+      await expect(handleTagAndVectorSearch(params)).rejects.toThrow(
+        'Tag filters are required for tag and vector search'
+      )
+    })
+
+    it('should throw error when queryVector not provided', async () => {
+      const params = {
+        knowledgeBaseIds: ['kb-123'],
+        topK: 10,
+        structuredFilters: [{ tagSlot: 'tag1', fieldType: 'text', operator: 'eq', value: 'api' }],
+        distanceThreshold: 0.8,
+      }
+
+      await expect(handleTagAndVectorSearch(params)).rejects.toThrow(
+        'Query vector and distance threshold are required for tag and vector search'
+      )
+    })
+
+    it('should throw error when distanceThreshold not provided', async () => {
+      const params = {
+        knowledgeBaseIds: ['kb-123'],
+        topK: 10,
+        structuredFilters: [{ tagSlot: 'tag1', fieldType: 'text', operator: 'eq', value: 'api' }],
+        queryVector: JSON.stringify([0.1, 0.2, 0.3]),
+      }
+
+      await expect(handleTagAndVectorSearch(params)).rejects.toThrow(
+        'Query vector and distance threshold are required for tag and vector search'
+      )
+    })
+
+    it('should accept valid parameters for tag and vector search', async () => {
+      const params = {
+        knowledgeBaseIds: ['kb-123'],
+        topK: 10,
+        structuredFilters: [{ tagSlot: 'tag1', fieldType: 'text', operator: 'eq', value: 'api' }],
+        queryVector: JSON.stringify([0.1, 0.2, 0.3]),
+        distanceThreshold: 0.8,
+      }
+
+      // This test validates the function accepts the right parameters
+      expect(params.knowledgeBaseIds).toEqual(['kb-123'])
+      expect(params.topK).toBe(10)
+      expect(params.structuredFilters).toHaveLength(1)
+      expect(params.queryVector).toBe(JSON.stringify([0.1, 0.2, 0.3]))
+      expect(params.distanceThreshold).toBe(0.8)
+    })
+  })
+
+  describe('generateSearchEmbedding', () => {
+    it('should use Azure OpenAI when KB-specific config is provided', async () => {
+      const { env } = await import('@/lib/core/config/env')
+      Object.keys(env).forEach((key) => delete (env as any)[key])
+      Object.assign(env, {
+        AZURE_OPENAI_API_KEY: 'test-azure-key',
+        AZURE_OPENAI_ENDPOINT: 'https://test.openai.azure.com',
+        AZURE_OPENAI_API_VERSION: '2024-12-01-preview',
+        KB_OPENAI_MODEL_NAME: 'text-embedding-ada-002',
+        OPENAI_API_KEY: 'test-openai-key',
+      })
+
+      mockNextFetchResponse({
+        json: {
+          data: [{ embedding: [0.1, 0.2, 0.3] }],
+          usage: { prompt_tokens: 1, total_tokens: 1 },
+        },
+      })
+
+      const result = await generateSearchEmbedding('test query')
+
+      expect(vi.mocked(fetch)).toHaveBeenCalledWith(
+        'https://test.openai.azure.com/openai/deployments/text-embedding-ada-002/embeddings?api-version=2024-12-01-preview',
+        expect.objectContaining({
+          headers: expect.objectContaining({
+            'api-key': 'test-azure-key',
+          }),
+        })
+      )
+      expect(result.embedding).toEqual([0.1, 0.2, 0.3])
+
+      // Clean up
+      Object.keys(env).forEach((key) => delete (env as any)[key])
+    })
+
+    it('should fallback to OpenAI when no KB Azure config provided', async () => {
+      const { env } = await import('@/lib/core/config/env')
+      Object.keys(env).forEach((key) => delete (env as any)[key])
+      Object.assign(env, {
+        OPENAI_API_KEY: 'test-openai-key',
+      })
+
+      mockNextFetchResponse({
+        json: {
+          data: [{ embedding: [0.1, 0.2, 0.3] }],
+          usage: { prompt_tokens: 1, total_tokens: 1 },
+        },
+      })
+
+      const result = await generateSearchEmbedding('test query')
+
+      expect(vi.mocked(fetch)).toHaveBeenCalledWith(
+        'https://api.openai.com/v1/embeddings',
+        expect.objectContaining({
+          headers: expect.objectContaining({
+            Authorization: 'Bearer test-openai-key',
+          }),
+        })
+      )
+      expect(result.embedding).toEqual([0.1, 0.2, 0.3])
+
+      // Clean up
+      Object.keys(env).forEach((key) => delete (env as any)[key])
+    })
+
+    it('falls back to OpenAI when AZURE_OPENAI_API_VERSION is not set', async () => {
+      const { env } = await import('@/lib/core/config/env')
+      Object.keys(env).forEach((key) => delete (env as any)[key])
+      Object.assign(env, {
+        AZURE_OPENAI_API_KEY: 'test-azure-key',
+        AZURE_OPENAI_ENDPOINT: 'https://test.openai.azure.com',
+        KB_OPENAI_MODEL_NAME: 'custom-embedding-model',
+        OPENAI_API_KEY: 'test-openai-key',
+      })
+
+      mockNextFetchResponse({
+        json: {
+          data: [{ embedding: [0.1, 0.2, 0.3] }],
+          usage: { prompt_tokens: 1, total_tokens: 1 },
+        },
+      })
+
+      await generateSearchEmbedding('test query')
+
+      expect(vi.mocked(fetch)).toHaveBeenCalledWith(
+        'https://api.openai.com/v1/embeddings',
+        expect.any(Object)
+      )
+
+      // Clean up
+      Object.keys(env).forEach((key) => delete (env as any)[key])
+    })
+
+    it('should use custom model name when provided in Azure config', async () => {
+      const { env } = await import('@/lib/core/config/env')
+      Object.keys(env).forEach((key) => delete (env as any)[key])
+      Object.assign(env, {
+        AZURE_OPENAI_API_KEY: 'test-azure-key',
+        AZURE_OPENAI_ENDPOINT: 'https://test.openai.azure.com',
+        AZURE_OPENAI_API_VERSION: '2024-12-01-preview',
+        KB_OPENAI_MODEL_NAME: 'custom-embedding-model',
+        OPENAI_API_KEY: 'test-openai-key',
+      })
+
+      mockNextFetchResponse({
+        json: {
+          data: [{ embedding: [0.1, 0.2, 0.3] }],
+          usage: { prompt_tokens: 1, total_tokens: 1 },
+        },
+      })
+
+      await generateSearchEmbedding('test query', 'text-embedding-3-small')
+
+      expect(vi.mocked(fetch)).toHaveBeenCalledWith(
+        'https://test.openai.azure.com/openai/deployments/custom-embedding-model/embeddings?api-version=2024-12-01-preview',
+        expect.any(Object)
+      )
+
+      // Clean up
+      Object.keys(env).forEach((key) => delete (env as any)[key])
+    })
+
+    it('should throw error when no API configuration provided', async () => {
+      const { env } = await import('@/lib/core/config/env')
+      Object.keys(env).forEach((key) => delete (env as any)[key])
+
+      await expect(generateSearchEmbedding('test query')).rejects.toThrow(
+        'OPENAI_API_KEY is not configured'
+      )
+    })
+
+    it('should handle Azure OpenAI API errors properly', async () => {
+      const { env } = await import('@/lib/core/config/env')
+      Object.keys(env).forEach((key) => delete (env as any)[key])
+      Object.assign(env, {
+        AZURE_OPENAI_API_KEY: 'test-azure-key',
+        AZURE_OPENAI_ENDPOINT: 'https://test.openai.azure.com',
+        AZURE_OPENAI_API_VERSION: '2024-12-01-preview',
+        KB_OPENAI_MODEL_NAME: 'text-embedding-ada-002',
+      })
+
+      mockNextFetchResponse({
+        ok: false,
+        status: 404,
+        statusText: 'Not Found',
+        text: 'Deployment not found',
+      })
+
+      await expect(generateSearchEmbedding('test query')).rejects.toThrow('Embedding API failed')
+
+      // Clean up
+      Object.keys(env).forEach((key) => delete (env as any)[key])
+    })
+
+    it('should handle OpenAI API errors properly', async () => {
+      const { env } = await import('@/lib/core/config/env')
+      Object.keys(env).forEach((key) => delete (env as any)[key])
+      Object.assign(env, {
+        OPENAI_API_KEY: 'test-openai-key',
+      })
+
+      mockNextFetchResponse({
+        ok: false,
+        status: 429,
+        statusText: 'Too Many Requests',
+        text: 'Rate limit exceeded',
+      })
+
+      await expect(generateSearchEmbedding('test query')).rejects.toThrow('Embedding API failed')
+
+      // Clean up
+      Object.keys(env).forEach((key) => delete (env as any)[key])
+    })
+
+    it('should include correct request body for Azure OpenAI', async () => {
+      const { env } = await import('@/lib/core/config/env')
+      Object.keys(env).forEach((key) => delete (env as any)[key])
+      Object.assign(env, {
+        AZURE_OPENAI_API_KEY: 'test-azure-key',
+        AZURE_OPENAI_ENDPOINT: 'https://test.openai.azure.com',
+        AZURE_OPENAI_API_VERSION: '2024-12-01-preview',
+        KB_OPENAI_MODEL_NAME: 'text-embedding-ada-002',
+      })
+
+      mockNextFetchResponse({
+        json: {
+          data: [{ embedding: [0.1, 0.2, 0.3] }],
+          usage: { prompt_tokens: 1, total_tokens: 1 },
+        },
+      })
+
+      await generateSearchEmbedding('test query')
+
+      expect(vi.mocked(fetch)).toHaveBeenCalledWith(
+        expect.any(String),
+        expect.objectContaining({
+          body: JSON.stringify({
+            input: ['test query'],
+            encoding_format: 'float',
+            dimensions: 1536,
+          }),
+        })
+      )
+
+      // Clean up
+      Object.keys(env).forEach((key) => delete (env as any)[key])
+    })
+
+    it('should include correct request body for OpenAI', async () => {
+      const { env } = await import('@/lib/core/config/env')
+      Object.keys(env).forEach((key) => delete (env as any)[key])
+      Object.assign(env, {
+        OPENAI_API_KEY: 'test-openai-key',
+      })
+
+      mockNextFetchResponse({
+        json: {
+          data: [{ embedding: [0.1, 0.2, 0.3] }],
+          usage: { prompt_tokens: 1, total_tokens: 1 },
+        },
+      })
+
+      await generateSearchEmbedding('test query', 'text-embedding-3-small')
+
+      expect(vi.mocked(fetch)).toHaveBeenCalledWith(
+        expect.any(String),
+        expect.objectContaining({
+          body: JSON.stringify({
+            input: ['test query'],
+            model: 'text-embedding-3-small',
+            encoding_format: 'float',
+            dimensions: 1536,
+          }),
+        })
+      )
+
+      // Clean up
+      Object.keys(env).forEach((key) => delete (env as any)[key])
+    })
+  })
+
+  describe('getDocumentMetadataByIds', () => {
+    it('should handle empty input gracefully', async () => {
+      const { getDocumentMetadataByIds } = await import('./utils')
+
+      const result = await getDocumentMetadataByIds([])
+
+      expect(result).toEqual({})
+    })
+  })
+})

apps/sim/app/api/knowledge/search/utils.ts

@@ -0,0 +1,539 @@
+import { db } from '@sim/db'
+import { document, embedding } from '@sim/db/schema'
+import { and, eq, inArray, isNull, sql } from 'drizzle-orm'
+import type { StructuredFilter } from '@/lib/knowledge/types'
+
+export interface DocumentMetadata {
+  filename: string
+  sourceUrl: string | null
+}
+
+/**
+ * Batch-fetch display metadata for documents referenced by search results.
+ * Excludes documents that are user-excluded, archived, or soft-deleted —
+ * mirrors the visibility filters applied inside the search SQL itself, so
+ * the lookup will never surface metadata for a row a caller could not have
+ * legitimately matched. Returns a map keyed by document id; missing ids
+ * indicate the document is no longer visible and should be skipped.
+ */
+export async function getDocumentMetadataByIds(
+  documentIds: string[]
+): Promise<Record<string, DocumentMetadata>> {
+  if (documentIds.length === 0) {
+    return {}
+  }
+
+  const uniqueIds = [...new Set(documentIds)]
+  const documents = await db
+    .select({
+      id: document.id,
+      filename: document.filename,
+      sourceUrl: document.sourceUrl,
+    })
+    .from(document)
+    .where(
+      and(
+        inArray(document.id, uniqueIds),
+        eq(document.userExcluded, false),
+        isNull(document.archivedAt),
+        isNull(document.deletedAt)
+      )
+    )
+
+  const map: Record<string, DocumentMetadata> = {}
+  documents.forEach((doc) => {
+    map[doc.id] = { filename: doc.filename, sourceUrl: doc.sourceUrl ?? null }
+  })
+
+  return map
+}
+
+export interface SearchResult {
+  id: string
+  content: string
+  documentId: string
+  chunkIndex: number
+  // Text tags
+  tag1: string | null
+  tag2: string | null
+  tag3: string | null
+  tag4: string | null
+  tag5: string | null
+  tag6: string | null
+  tag7: string | null
+  // Number tags (5 slots)
+  number1: number | null
+  number2: number | null
+  number3: number | null
+  number4: number | null
+  number5: number | null
+  // Date tags (2 slots)
+  date1: Date | null
+  date2: Date | null
+  // Boolean tags (3 slots)
+  boolean1: boolean | null
+  boolean2: boolean | null
+  boolean3: boolean | null
+  distance: number
+  knowledgeBaseId: string
+}
+
+export interface SearchParams {
+  knowledgeBaseIds: string[]
+  topK: number
+  structuredFilters?: StructuredFilter[]
+  queryVector?: string
+  distanceThreshold?: number
+}
+
+// Use shared embedding utility
+export { generateSearchEmbedding } from '@/lib/knowledge/embeddings'
+
+/** All valid tag slot keys */
+const TAG_SLOT_KEYS = [
+  // Text tags (7 slots)
+  'tag1',
+  'tag2',
+  'tag3',
+  'tag4',
+  'tag5',
+  'tag6',
+  'tag7',
+  // Number tags (5 slots)
+  'number1',
+  'number2',
+  'number3',
+  'number4',
+  'number5',
+  // Date tags (2 slots)
+  'date1',
+  'date2',
+  // Boolean tags (3 slots)
+  'boolean1',
+  'boolean2',
+  'boolean3',
+] as const
+
+type TagSlotKey = (typeof TAG_SLOT_KEYS)[number]
+
+function isTagSlotKey(key: string): key is TagSlotKey {
+  return TAG_SLOT_KEYS.includes(key as TagSlotKey)
+}
+
+/** Common fields selected for search results */
+const getSearchResultFields = (distanceExpr: any) => ({
+  id: embedding.id,
+  content: embedding.content,
+  documentId: embedding.documentId,
+  chunkIndex: embedding.chunkIndex,
+  // Text tags
+  tag1: embedding.tag1,
+  tag2: embedding.tag2,
+  tag3: embedding.tag3,
+  tag4: embedding.tag4,
+  tag5: embedding.tag5,
+  tag6: embedding.tag6,
+  tag7: embedding.tag7,
+  // Number tags (5 slots)
+  number1: embedding.number1,
+  number2: embedding.number2,
+  number3: embedding.number3,
+  number4: embedding.number4,
+  number5: embedding.number5,
+  // Date tags (2 slots)
+  date1: embedding.date1,
+  date2: embedding.date2,
+  // Boolean tags (3 slots)
+  boolean1: embedding.boolean1,
+  boolean2: embedding.boolean2,
+  boolean3: embedding.boolean3,
+  distance: distanceExpr,
+  knowledgeBaseId: embedding.knowledgeBaseId,
+})
+
+/**
+ * Build a single SQL condition for a filter
+ */
+function buildFilterCondition(filter: StructuredFilter, embeddingTable: any) {
+  const { tagSlot, fieldType, operator, value, valueTo } = filter
+
+  if (!isTagSlotKey(tagSlot)) {
+    return null
+  }
+
+  const column = embeddingTable[tagSlot]
+  if (!column) return null
+
+  // Handle text operators
+  if (fieldType === 'text') {
+    const stringValue = String(value)
+    switch (operator) {
+      case 'eq':
+        return sql`LOWER(${column}) = LOWER(${stringValue})`
+      case 'neq':
+        return sql`LOWER(${column}) != LOWER(${stringValue})`
+      case 'contains':
+        return sql`LOWER(${column}) LIKE LOWER(${`%${stringValue}%`})`
+      case 'not_contains':
+        return sql`LOWER(${column}) NOT LIKE LOWER(${`%${stringValue}%`})`
+      case 'starts_with':
+        return sql`LOWER(${column}) LIKE LOWER(${`${stringValue}%`})`
+      case 'ends_with':
+        return sql`LOWER(${column}) LIKE LOWER(${`%${stringValue}`})`
+      default:
+        return sql`LOWER(${column}) = LOWER(${stringValue})`
+    }
+  }
+
+  // Handle number operators
+  if (fieldType === 'number') {
+    const numValue = typeof value === 'number' ? value : Number.parseFloat(String(value))
+    if (Number.isNaN(numValue)) return null
+
+    switch (operator) {
+      case 'eq':
+        return sql`${column} = ${numValue}`
+      case 'neq':
+        return sql`${column} != ${numValue}`
+      case 'gt':
+        return sql`${column} > ${numValue}`
+      case 'gte':
+        return sql`${column} >= ${numValue}`
+      case 'lt':
+        return sql`${column} < ${numValue}`
+      case 'lte':
+        return sql`${column} <= ${numValue}`
+      case 'between':
+        if (valueTo !== undefined) {
+          const numValueTo =
+            typeof valueTo === 'number' ? valueTo : Number.parseFloat(String(valueTo))
+          if (Number.isNaN(numValueTo)) return sql`${column} = ${numValue}`
+          return sql`${column} >= ${numValue} AND ${column} <= ${numValueTo}`
+        }
+        return sql`${column} = ${numValue}`
+      default:
+        return sql`${column} = ${numValue}`
+    }
+  }
+
+  // Handle date operators - expects YYYY-MM-DD format from frontend
+  if (fieldType === 'date') {
+    const dateStr = String(value)
+    // Validate YYYY-MM-DD format
+    if (!/^\d{4}-\d{2}-\d{2}$/.test(dateStr)) {
+      return null
+    }
+
+    switch (operator) {
+      case 'eq':
+        return sql`${column}::date = ${dateStr}::date`
+      case 'neq':
+        return sql`${column}::date != ${dateStr}::date`
+      case 'gt':
+        return sql`${column}::date > ${dateStr}::date`
+      case 'gte':
+        return sql`${column}::date >= ${dateStr}::date`
+      case 'lt':
+        return sql`${column}::date < ${dateStr}::date`
+      case 'lte':
+        return sql`${column}::date <= ${dateStr}::date`
+      case 'between':
+        if (valueTo !== undefined) {
+          const dateStrTo = String(valueTo)
+          if (!/^\d{4}-\d{2}-\d{2}$/.test(dateStrTo)) {
+            return sql`${column}::date = ${dateStr}::date`
+          }
+          return sql`${column}::date >= ${dateStr}::date AND ${column}::date <= ${dateStrTo}::date`
+        }
+        return sql`${column}::date = ${dateStr}::date`
+      default:
+        return sql`${column}::date = ${dateStr}::date`
+    }
+  }
+
+  // Handle boolean operators
+  if (fieldType === 'boolean') {
+    const boolValue = value === true || value === 'true'
+    switch (operator) {
+      case 'eq':
+        return sql`${column} = ${boolValue}`
+      case 'neq':
+        return sql`${column} != ${boolValue}`
+      default:
+        return sql`${column} = ${boolValue}`
+    }
+  }
+
+  // Fallback to equality
+  return sql`${column} = ${value}`
+}
+
+/**
+ * Build SQL conditions from structured filters with operator support
+ * - Same tag multiple times: OR logic
+ * - Different tags: AND logic
+ */
+function getStructuredTagFilters(filters: StructuredFilter[], embeddingTable: any) {
+  // Group filters by tagSlot
+  const filtersBySlot = new Map<string, StructuredFilter[]>()
+  for (const filter of filters) {
+    const slot = filter.tagSlot
+    if (!filtersBySlot.has(slot)) {
+      filtersBySlot.set(slot, [])
+    }
+    filtersBySlot.get(slot)!.push(filter)
+  }
+
+  // Build conditions: OR within same slot, AND across different slots
+  const conditions: ReturnType<typeof sql>[] = []
+
+  for (const [slot, slotFilters] of filtersBySlot) {
+    const slotConditions = slotFilters
+      .map((f) => buildFilterCondition(f, embeddingTable))
+      .filter((c): c is ReturnType<typeof sql> => c !== null)
+
+    if (slotConditions.length === 0) continue
+
+    if (slotConditions.length === 1) {
+      // Single condition for this slot
+      conditions.push(slotConditions[0])
+    } else {
+      // Multiple conditions for same slot - OR them together
+      conditions.push(sql`(${sql.join(slotConditions, sql` OR `)})`)
+    }
+  }
+
+  return conditions
+}
+
+export function getQueryStrategy(kbCount: number, topK: number) {
+  const useParallel = kbCount > 4 || (kbCount > 2 && topK > 50)
+  const distanceThreshold = kbCount > 3 ? 0.8 : 1.0
+  const parallelLimit = Math.ceil(topK / kbCount) + 5
+
+  return {
+    useParallel,
+    distanceThreshold,
+    parallelLimit,
+    singleQueryOptimized: kbCount <= 2,
+  }
+}
+
+async function executeTagFilterQuery(
+  knowledgeBaseIds: string[],
+  structuredFilters: StructuredFilter[]
+): Promise<{ id: string }[]> {
+  const tagFilterConditions = getStructuredTagFilters(structuredFilters, embedding)
+
+  if (knowledgeBaseIds.length === 1) {
+    return await db
+      .select({ id: embedding.id })
+      .from(embedding)
+      .innerJoin(document, eq(embedding.documentId, document.id))
+      .where(
+        and(
+          eq(embedding.knowledgeBaseId, knowledgeBaseIds[0]),
+          eq(embedding.enabled, true),
+          eq(document.enabled, true),
+          eq(document.processingStatus, 'completed'),
+          eq(document.userExcluded, false),
+          isNull(document.archivedAt),
+          isNull(document.deletedAt),
+          ...tagFilterConditions
+        )
+      )
+  }
+  return await db
+    .select({ id: embedding.id })
+    .from(embedding)
+    .innerJoin(document, eq(embedding.documentId, document.id))
+    .where(
+      and(
+        inArray(embedding.knowledgeBaseId, knowledgeBaseIds),
+        eq(embedding.enabled, true),
+        eq(document.enabled, true),
+        eq(document.processingStatus, 'completed'),
+        eq(document.userExcluded, false),
+        isNull(document.archivedAt),
+        isNull(document.deletedAt),
+        ...tagFilterConditions
+      )
+    )
+}
+
+async function executeVectorSearchOnIds(
+  embeddingIds: string[],
+  queryVector: string,
+  topK: number,
+  distanceThreshold: number
+): Promise<SearchResult[]> {
+  if (embeddingIds.length === 0) {
+    return []
+  }
+
+  return await db
+    .select(
+      getSearchResultFields(
+        sql<number>`${embedding.embedding} <=> ${queryVector}::vector`.as('distance')
+      )
+    )
+    .from(embedding)
+    .innerJoin(document, eq(embedding.documentId, document.id))
+    .where(
+      and(
+        inArray(embedding.id, embeddingIds),
+        eq(document.enabled, true),
+        eq(document.processingStatus, 'completed'),
+        eq(document.userExcluded, false),
+        isNull(document.archivedAt),
+        isNull(document.deletedAt),
+        sql`${embedding.embedding} <=> ${queryVector}::vector < ${distanceThreshold}`
+      )
+    )
+    .orderBy(sql`${embedding.embedding} <=> ${queryVector}::vector`)
+    .limit(topK)
+}
+
+export async function handleTagOnlySearch(params: SearchParams): Promise<SearchResult[]> {
+  const { knowledgeBaseIds, topK, structuredFilters } = params
+
+  if (!structuredFilters || structuredFilters.length === 0) {
+    throw new Error('Tag filters are required for tag-only search')
+  }
+
+  const strategy = getQueryStrategy(knowledgeBaseIds.length, topK)
+  const tagFilterConditions = getStructuredTagFilters(structuredFilters, embedding)
+
+  if (strategy.useParallel) {
+    // Parallel approach for many KBs
+    const parallelLimit = Math.ceil(topK / knowledgeBaseIds.length) + 5
+
+    const queryPromises = knowledgeBaseIds.map(async (kbId) => {
+      return await db
+        .select(getSearchResultFields(sql<number>`0`.as('distance')))
+        .from(embedding)
+        .innerJoin(document, eq(embedding.documentId, document.id))
+        .where(
+          and(
+            eq(embedding.knowledgeBaseId, kbId),
+            eq(embedding.enabled, true),
+            eq(document.enabled, true),
+            eq(document.processingStatus, 'completed'),
+            eq(document.userExcluded, false),
+            isNull(document.archivedAt),
+            isNull(document.deletedAt),
+            ...tagFilterConditions
+          )
+        )
+        .limit(parallelLimit)
+    })
+
+    const parallelResults = await Promise.all(queryPromises)
+    return parallelResults.flat().slice(0, topK)
+  }
+  // Single query for fewer KBs
+  return await db
+    .select(getSearchResultFields(sql<number>`0`.as('distance')))
+    .from(embedding)
+    .innerJoin(document, eq(embedding.documentId, document.id))
+    .where(
+      and(
+        inArray(embedding.knowledgeBaseId, knowledgeBaseIds),
+        eq(embedding.enabled, true),
+        eq(document.enabled, true),
+        eq(document.processingStatus, 'completed'),
+        eq(document.userExcluded, false),
+        isNull(document.archivedAt),
+        isNull(document.deletedAt),
+        ...tagFilterConditions
+      )
+    )
+    .limit(topK)
+}
+
+export async function handleVectorOnlySearch(params: SearchParams): Promise<SearchResult[]> {
+  const { knowledgeBaseIds, topK, queryVector, distanceThreshold } = params
+
+  if (!queryVector || !distanceThreshold) {
+    throw new Error('Query vector and distance threshold are required for vector-only search')
+  }
+
+  const strategy = getQueryStrategy(knowledgeBaseIds.length, topK)
+
+  const distanceExpr = sql<number>`${embedding.embedding} <=> ${queryVector}::vector`.as('distance')
+
+  if (strategy.useParallel) {
+    // Parallel approach for many KBs
+    const parallelLimit = Math.ceil(topK / knowledgeBaseIds.length) + 5
+
+    const queryPromises = knowledgeBaseIds.map(async (kbId) => {
+      return await db
+        .select(getSearchResultFields(distanceExpr))
+        .from(embedding)
+        .innerJoin(document, eq(embedding.documentId, document.id))
+        .where(
+          and(
+            eq(embedding.knowledgeBaseId, kbId),
+            eq(embedding.enabled, true),
+            eq(document.enabled, true),
+            eq(document.processingStatus, 'completed'),
+            eq(document.userExcluded, false),
+            isNull(document.archivedAt),
+            isNull(document.deletedAt),
+            sql`${embedding.embedding} <=> ${queryVector}::vector < ${distanceThreshold}`
+          )
+        )
+        .orderBy(sql`${embedding.embedding} <=> ${queryVector}::vector`)
+        .limit(parallelLimit)
+    })
+
+    const parallelResults = await Promise.all(queryPromises)
+    const allResults = parallelResults.flat()
+    return allResults.sort((a, b) => a.distance - b.distance).slice(0, topK)
+  }
+  // Single query for fewer KBs
+  return await db
+    .select(getSearchResultFields(distanceExpr))
+    .from(embedding)
+    .innerJoin(document, eq(embedding.documentId, document.id))
+    .where(
+      and(
+        inArray(embedding.knowledgeBaseId, knowledgeBaseIds),
+        eq(embedding.enabled, true),
+        eq(document.enabled, true),
+        eq(document.processingStatus, 'completed'),
+        eq(document.userExcluded, false),
+        isNull(document.archivedAt),
+        isNull(document.deletedAt),
+        sql`${embedding.embedding} <=> ${queryVector}::vector < ${distanceThreshold}`
+      )
+    )
+    .orderBy(sql`${embedding.embedding} <=> ${queryVector}::vector`)
+    .limit(topK)
+}
+
+export async function handleTagAndVectorSearch(params: SearchParams): Promise<SearchResult[]> {
+  const { knowledgeBaseIds, topK, structuredFilters, queryVector, distanceThreshold } = params
+
+  if (!structuredFilters || structuredFilters.length === 0) {
+    throw new Error('Tag filters are required for tag and vector search')
+  }
+  if (!queryVector || !distanceThreshold) {
+    throw new Error('Query vector and distance threshold are required for tag and vector search')
+  }
+
+  // Step 1: Filter by tags first
+  const tagFilteredIds = await executeTagFilterQuery(knowledgeBaseIds, structuredFilters)
+
+  if (tagFilteredIds.length === 0) {
+    return []
+  }
+
+  // Step 2: Perform vector search only on tag-filtered results
+  return await executeVectorSearchOnIds(
+    tagFilteredIds.map((r) => r.id),
+    queryVector,
+    topK,
+    distanceThreshold
+  )
+}

apps/sim/app/api/knowledge/utils.test.ts

@@ -0,0 +1,413 @@
+/**
+ * @vitest-environment node
+ *
+ * Knowledge Utils Unit Tests
+ *
+ * This file contains unit tests for the knowledge base utility functions,
+ * including access checks, document processing, and embedding generation.
+ */
+import { createEnvMock } from '@sim/testing'
+import { beforeEach, describe, expect, it, vi } from 'vitest'
+
+vi.mock('drizzle-orm', () => ({
+  and: (...args: any[]) => args,
+  eq: (...args: any[]) => args,
+  isNull: () => true,
+  sql: (strings: TemplateStringsArray, ...expr: any[]) => ({ strings, expr }),
+}))
+
+vi.mock('@/lib/core/config/env', () => createEnvMock({ OPENAI_API_KEY: 'test-key' }))
+
+vi.mock('@/lib/knowledge/documents/utils', () => ({
+  retryWithExponentialBackoff: (fn: any) => fn(),
+}))
+
+vi.mock('@/lib/workspaces/utils', () => ({
+  getWorkspaceBilledAccountUserId: vi.fn().mockResolvedValue('user1'),
+}))
+
+vi.mock('@/lib/knowledge/documents/document-processor', () => ({
+  processDocument: vi.fn().mockResolvedValue({
+    chunks: [
+      {
+        text: 'alpha',
+        tokenCount: 1,
+        metadata: { startIndex: 0, endIndex: 4 },
+      },
+      {
+        text: 'beta',
+        tokenCount: 1,
+        metadata: { startIndex: 5, endIndex: 8 },
+      },
+    ],
+    metadata: {
+      filename: 'dummy',
+      fileSize: 10,
+      mimeType: 'text/plain',
+      characterCount: 9,
+      tokenCount: 3,
+      chunkCount: 2,
+      processingMethod: 'file-parser',
+    },
+  }),
+}))
+
+const dbOps: {
+  order: string[]
+  insertRecords: any[][]
+  updatePayloads: any[]
+} = {
+  order: [],
+  insertRecords: [],
+  updatePayloads: [],
+}
+
+let kbRows: any[] = []
+let docRows: any[] = []
+let chunkRows: any[] = []
+
+function resetDatasets() {
+  kbRows = []
+  docRows = []
+  chunkRows = []
+}
+
+vi.stubGlobal(
+  'fetch',
+  vi.fn().mockResolvedValue({
+    ok: true,
+    json: async () => ({
+      data: [
+        { embedding: [0.1, 0.2], index: 0 },
+        { embedding: [0.3, 0.4], index: 1 },
+      ],
+      usage: { prompt_tokens: 2, total_tokens: 2 },
+    }),
+  })
+)
+
+vi.mock('@sim/db', async () => {
+  const { schemaMock } = (await import('@sim/testing')) as typeof import('@sim/testing')
+  const tableNameFor = (table: any) => {
+    if (table === schemaMock.knowledgeBase) return 'knowledge_base'
+    if (table === schemaMock.document) return 'document'
+    if (table === schemaMock.embedding) return 'embedding'
+    return ''
+  }
+  const selectBuilder = {
+    from(table: any) {
+      return {
+        where() {
+          return {
+            limit(n: number) {
+              const tableName = tableNameFor(table)
+
+              if (tableName === 'knowledge_base') {
+                return Promise.resolve(kbRows.slice(0, n))
+              }
+              if (tableName === 'document') {
+                return Promise.resolve(docRows.slice(0, n))
+              }
+              if (tableName === 'embedding') {
+                return Promise.resolve(chunkRows.slice(0, n))
+              }
+
+              return Promise.resolve([])
+            },
+          }
+        },
+        innerJoin() {
+          // document × knowledge_base context JOIN — return the first kb and
+          // doc row merged (covers processDocumentAsync's prefetch).
+          return {
+            leftJoin: () => ({
+              where: () => ({
+                limit: (n: number) =>
+                  Promise.resolve(
+                    kbRows.length > 0 && docRows.length > 0
+                      ? [
+                          { ...kbRows[0], ...docRows[0], billedAccountUserId: 'billing-user-1' },
+                        ].slice(0, n)
+                      : []
+                  ),
+              }),
+            }),
+            where: () => ({
+              limit: (n: number) =>
+                Promise.resolve(
+                  kbRows.length > 0 && docRows.length > 0
+                    ? [{ ...kbRows[0], ...docRows[0] }].slice(0, n)
+                    : []
+                ),
+            }),
+          }
+        },
+      }
+    },
+  }
+
+  return {
+    db: {
+      select: vi.fn(() => selectBuilder),
+      update: (table: any) => ({
+        set: (payload: any) => ({
+          where: () => {
+            const tableName = tableNameFor(table)
+            if (tableName === 'knowledge_base') {
+              dbOps.order.push('updateKb')
+              dbOps.updatePayloads.push(payload)
+            } else if (tableName === 'document') {
+              if (payload.processingStatus !== 'processing') {
+                dbOps.order.push('updateDoc')
+                dbOps.updatePayloads.push(payload)
+              }
+            }
+            return Promise.resolve()
+          },
+        }),
+      }),
+      delete: () => ({
+        where: () => Promise.resolve(),
+      }),
+      insert: () => ({
+        values: (records: any) => {
+          dbOps.order.push('insert')
+          dbOps.insertRecords.push(records)
+          return Promise.resolve()
+        },
+      }),
+      transaction: vi.fn(async (fn: any) => {
+        await fn({
+          select: () => ({
+            from: () => ({
+              innerJoin: () => ({
+                where: () => ({
+                  limit: () => Promise.resolve([{ id: 'doc1' }]),
+                }),
+              }),
+              where: () => ({
+                limit: () => Promise.resolve([{}]),
+              }),
+            }),
+          }),
+          delete: () => ({
+            where: () => Promise.resolve(),
+          }),
+          insert: () => ({
+            values: (records: any) => {
+              dbOps.order.push('insert')
+              dbOps.insertRecords.push(records)
+              return Promise.resolve()
+            },
+          }),
+          update: () => ({
+            set: (payload: any) => ({
+              where: () => {
+                dbOps.updatePayloads.push(payload)
+                const label = payload.processingStatus !== undefined ? 'updateDoc' : 'updateKb'
+                dbOps.order.push(label)
+                return Promise.resolve()
+              },
+            }),
+          }),
+        })
+      }),
+    },
+    document: {},
+    knowledgeBase: {},
+    embedding: {},
+  }
+})
+
+import { processDocumentAsync } from '@/lib/knowledge/documents/service'
+import { generateEmbeddings } from '@/lib/knowledge/embeddings'
+import {
+  checkChunkAccess,
+  checkDocumentAccess,
+  checkKnowledgeBaseAccess,
+} from '@/app/api/knowledge/utils'
+
+describe('Knowledge Utils', () => {
+  beforeEach(() => {
+    dbOps.order.length = 0
+    dbOps.insertRecords.length = 0
+    dbOps.updatePayloads.length = 0
+    resetDatasets()
+    vi.clearAllMocks()
+  })
+
+  describe('processDocumentAsync', () => {
+    it.concurrent('should insert embeddings before updating document counters', async () => {
+      kbRows.push({
+        id: 'kb1',
+        userId: 'user1',
+        workspaceId: 'workspace1',
+        embeddingModel: 'text-embedding-3-small',
+        chunkingConfig: { maxSize: 1024, minSize: 1, overlap: 200 },
+      })
+      docRows.push({ id: 'doc1', knowledgeBaseId: 'kb1' })
+
+      await processDocumentAsync(
+        'kb1',
+        'doc1',
+        {
+          filename: 'file.txt',
+          fileUrl: 'https://example.com/file.txt',
+          fileSize: 10,
+          mimeType: 'text/plain',
+        },
+        {}
+      )
+
+      // Embeddings are inserted first, then the document counter update. A
+      // usage_log billing insert (recordUsage) may trail after updateDoc and is
+      // irrelevant to this ordering invariant, so assert position rather than
+      // exact array equality.
+      expect(dbOps.order[0]).toBe('insert')
+      expect(dbOps.order.indexOf('updateDoc')).toBeGreaterThan(0)
+
+      expect(dbOps.updatePayloads[0]).toMatchObject({
+        processingStatus: 'completed',
+        chunkCount: 2,
+      })
+
+      expect(dbOps.insertRecords[0].length).toBe(2)
+    })
+  })
+
+  describe('checkKnowledgeBaseAccess', () => {
+    it.concurrent('should return success for owner', async () => {
+      kbRows.push({ id: 'kb1', userId: 'user1' })
+      const result = await checkKnowledgeBaseAccess('kb1', 'user1')
+
+      expect(result.hasAccess).toBe(true)
+    })
+
+    it('should return notFound when knowledge base is missing', async () => {
+      const result = await checkKnowledgeBaseAccess('missing', 'user1')
+
+      expect(result.hasAccess).toBe(false)
+      expect('notFound' in result && result.notFound).toBe(true)
+    })
+  })
+
+  describe('checkDocumentAccess', () => {
+    it.concurrent('should return unauthorized when user mismatch', async () => {
+      kbRows.push({ id: 'kb1', userId: 'owner' })
+      const result = await checkDocumentAccess('kb1', 'doc1', 'intruder')
+
+      expect(result.hasAccess).toBe(false)
+      if ('reason' in result) {
+        expect(result.reason).toBe('Unauthorized knowledge base access')
+      }
+    })
+  })
+
+  describe('checkChunkAccess', () => {
+    it.concurrent('should fail when document is not completed', async () => {
+      kbRows.push({ id: 'kb1', userId: 'user1' })
+      docRows.push({ id: 'doc1', knowledgeBaseId: 'kb1', processingStatus: 'processing' })
+
+      const result = await checkChunkAccess('kb1', 'doc1', 'chunk1', 'user1')
+
+      expect(result.hasAccess).toBe(false)
+      if ('reason' in result) {
+        expect(result.reason).toContain('Document is not ready')
+      }
+    })
+
+    it('should return success for valid access', async () => {
+      kbRows.push({ id: 'kb1', userId: 'user1' })
+      docRows.push({ id: 'doc1', knowledgeBaseId: 'kb1', processingStatus: 'completed' })
+      chunkRows.push({ id: 'chunk1', documentId: 'doc1' })
+
+      const result = await checkChunkAccess('kb1', 'doc1', 'chunk1', 'user1')
+
+      expect(result.hasAccess).toBe(true)
+      if ('chunk' in result) {
+        expect(result.chunk.id).toBe('chunk1')
+      }
+    })
+  })
+
+  describe('generateEmbeddings', () => {
+    it.concurrent('should return same length as input', async () => {
+      const result = await generateEmbeddings(['a', 'b'])
+
+      expect(result.embeddings.length).toBe(2)
+    })
+
+    it('should use Azure OpenAI when Azure config is provided', async () => {
+      const { env } = await import('@/lib/core/config/env')
+      Object.keys(env).forEach((key) => delete (env as any)[key])
+      Object.assign(env, {
+        AZURE_OPENAI_API_KEY: 'test-azure-key',
+        AZURE_OPENAI_ENDPOINT: 'https://test.openai.azure.com',
+        AZURE_OPENAI_API_VERSION: '2024-12-01-preview',
+        KB_OPENAI_MODEL_NAME: 'text-embedding-ada-002',
+        OPENAI_API_KEY: 'test-openai-key',
+      })
+
+      const fetchSpy = vi.mocked(fetch)
+      fetchSpy.mockResolvedValueOnce({
+        ok: true,
+        json: async () => ({
+          data: [{ embedding: [0.1, 0.2], index: 0 }],
+          usage: { prompt_tokens: 1, total_tokens: 1 },
+        }),
+      } as any)
+
+      await generateEmbeddings(['test text'])
+
+      expect(fetchSpy).toHaveBeenCalledWith(
+        'https://test.openai.azure.com/openai/deployments/text-embedding-ada-002/embeddings?api-version=2024-12-01-preview',
+        expect.objectContaining({
+          headers: expect.objectContaining({
+            'api-key': 'test-azure-key',
+          }),
+        })
+      )
+
+      Object.keys(env).forEach((key) => delete (env as any)[key])
+    })
+
+    it('should fallback to OpenAI when no Azure config provided', async () => {
+      const { env } = await import('@/lib/core/config/env')
+      Object.keys(env).forEach((key) => delete (env as any)[key])
+      Object.assign(env, {
+        OPENAI_API_KEY: 'test-openai-key',
+      })
+
+      const fetchSpy = vi.mocked(fetch)
+      fetchSpy.mockResolvedValueOnce({
+        ok: true,
+        json: async () => ({
+          data: [{ embedding: [0.1, 0.2], index: 0 }],
+          usage: { prompt_tokens: 1, total_tokens: 1 },
+        }),
+      } as any)
+
+      await generateEmbeddings(['test text'])
+
+      expect(fetchSpy).toHaveBeenCalledWith(
+        'https://api.openai.com/v1/embeddings',
+        expect.objectContaining({
+          headers: expect.objectContaining({
+            Authorization: 'Bearer test-openai-key',
+          }),
+        })
+      )
+
+      Object.keys(env).forEach((key) => delete (env as any)[key])
+    })
+
+    it('should throw error when no API configuration provided', async () => {
+      const { env } = await import('@/lib/core/config/env')
+      Object.keys(env).forEach((key) => delete (env as any)[key])
+
+      await expect(generateEmbeddings(['test text'])).rejects.toThrow(
+        'OPENAI_API_KEY is not configured'
+      )
+    })
+  })
+})

apps/sim/app/api/knowledge/utils.ts

@@ -0,0 +1,389 @@
+import { db } from '@sim/db'
+import { document, embedding, knowledgeBase } from '@sim/db/schema'
+import { and, eq, isNull } from 'drizzle-orm'
+import { getUserEntityPermissions } from '@/lib/workspaces/permissions/utils'
+
+interface KnowledgeBaseData {
+  id: string
+  userId: string
+  workspaceId?: string | null
+  name: string
+  description?: string | null
+  tokenCount: number
+  embeddingModel: string
+  embeddingDimension: number
+  chunkingConfig: unknown
+  deletedAt?: Date | null
+  createdAt: Date
+  updatedAt: Date
+}
+
+interface DocumentData {
+  id: string
+  knowledgeBaseId: string
+  filename: string
+  fileUrl: string
+  fileSize: number
+  mimeType: string
+  chunkCount: number
+  tokenCount: number
+  characterCount: number
+  processingStatus: string
+  processingStartedAt?: Date | null
+  processingCompletedAt?: Date | null
+  processingError?: string | null
+  enabled: boolean
+  deletedAt?: Date | null
+  uploadedAt: Date
+  // Text tags
+  tag1?: string | null
+  tag2?: string | null
+  tag3?: string | null
+  tag4?: string | null
+  tag5?: string | null
+  tag6?: string | null
+  tag7?: string | null
+  // Number tags (5 slots)
+  number1?: number | null
+  number2?: number | null
+  number3?: number | null
+  number4?: number | null
+  number5?: number | null
+  // Date tags (2 slots)
+  date1?: Date | null
+  date2?: Date | null
+  // Boolean tags (3 slots)
+  boolean1?: boolean | null
+  boolean2?: boolean | null
+  boolean3?: boolean | null
+  // Connector fields
+  connectorId?: string | null
+  sourceUrl?: string | null
+  externalId?: string | null
+}
+
+interface EmbeddingData {
+  id: string
+  knowledgeBaseId: string
+  documentId: string
+  chunkIndex: number
+  chunkHash: string
+  content: string
+  contentLength: number
+  tokenCount: number
+  embedding?: number[] | null
+  embeddingModel: string
+  startOffset: number
+  endOffset: number
+  // Text tags
+  tag1?: string | null
+  tag2?: string | null
+  tag3?: string | null
+  tag4?: string | null
+  tag5?: string | null
+  tag6?: string | null
+  tag7?: string | null
+  // Number tags (5 slots)
+  number1?: number | null
+  number2?: number | null
+  number3?: number | null
+  number4?: number | null
+  number5?: number | null
+  // Date tags (2 slots)
+  date1?: Date | null
+  date2?: Date | null
+  // Boolean tags (3 slots)
+  boolean1?: boolean | null
+  boolean2?: boolean | null
+  boolean3?: boolean | null
+  enabled: boolean
+  createdAt: Date
+  updatedAt: Date
+}
+
+export interface KnowledgeBaseAccessResult {
+  hasAccess: true
+  knowledgeBase: Pick<
+    KnowledgeBaseData,
+    'id' | 'userId' | 'workspaceId' | 'name' | 'embeddingModel'
+  >
+}
+
+interface KnowledgeBaseAccessDenied {
+  hasAccess: false
+  notFound?: boolean
+  reason?: string
+}
+
+export type KnowledgeBaseAccessCheck = KnowledgeBaseAccessResult | KnowledgeBaseAccessDenied
+
+interface DocumentAccessResult {
+  hasAccess: true
+  document: DocumentData
+  knowledgeBase: Pick<
+    KnowledgeBaseData,
+    'id' | 'userId' | 'workspaceId' | 'name' | 'embeddingModel'
+  >
+}
+
+interface DocumentAccessDenied {
+  hasAccess: false
+  notFound?: boolean
+  reason: string
+}
+
+export type DocumentAccessCheck = DocumentAccessResult | DocumentAccessDenied
+
+interface ChunkAccessResult {
+  hasAccess: true
+  chunk: EmbeddingData
+  document: DocumentData
+  knowledgeBase: Pick<
+    KnowledgeBaseData,
+    'id' | 'userId' | 'workspaceId' | 'name' | 'embeddingModel'
+  >
+}
+
+interface ChunkAccessDenied {
+  hasAccess: false
+  notFound?: boolean
+  reason: string
+}
+
+export type ChunkAccessCheck = ChunkAccessResult | ChunkAccessDenied
+
+/**
+ * Resolve knowledge-base access for a user, gated by read or write permission.
+ *
+ * Read (`requireWrite: false`) grants on any workspace permission; write
+ * (`requireWrite: true`) requires `write`/`admin`. Legacy non-workspace KBs grant
+ * to the owning user in both modes.
+ */
+async function resolveKnowledgeBaseAccess(
+  knowledgeBaseId: string,
+  userId: string,
+  requireWrite: boolean
+): Promise<KnowledgeBaseAccessCheck> {
+  const kb = await db
+    .select({
+      id: knowledgeBase.id,
+      userId: knowledgeBase.userId,
+      workspaceId: knowledgeBase.workspaceId,
+      name: knowledgeBase.name,
+      embeddingModel: knowledgeBase.embeddingModel,
+    })
+    .from(knowledgeBase)
+    .where(and(eq(knowledgeBase.id, knowledgeBaseId), isNull(knowledgeBase.deletedAt)))
+    .limit(1)
+
+  if (kb.length === 0) {
+    return { hasAccess: false, notFound: true }
+  }
+
+  const kbData = kb[0]
+
+  if (kbData.workspaceId) {
+    // Workspace KB: use workspace permissions only
+    const userPermission = await getUserEntityPermissions(userId, 'workspace', kbData.workspaceId)
+    const permitted = requireWrite
+      ? userPermission === 'write' || userPermission === 'admin'
+      : userPermission !== null
+    return permitted ? { hasAccess: true, knowledgeBase: kbData } : { hasAccess: false }
+  }
+
+  // Legacy non-workspace KB: allow owner access
+  if (kbData.userId === userId) {
+    return { hasAccess: true, knowledgeBase: kbData }
+  }
+
+  return { hasAccess: false }
+}
+
+/**
+ * Check if a user has read access to a knowledge base.
+ */
+export async function checkKnowledgeBaseAccess(
+  knowledgeBaseId: string,
+  userId: string
+): Promise<KnowledgeBaseAccessCheck> {
+  return resolveKnowledgeBaseAccess(knowledgeBaseId, userId, false)
+}
+
+/**
+ * Check if a user has write access to a knowledge base.
+ *
+ * Write access is granted if:
+ * 1. KB has a workspace: user has write or admin permissions on that workspace
+ * 2. KB has no workspace (legacy): user owns the KB directly
+ */
+export async function checkKnowledgeBaseWriteAccess(
+  knowledgeBaseId: string,
+  userId: string
+): Promise<KnowledgeBaseAccessCheck> {
+  return resolveKnowledgeBaseAccess(knowledgeBaseId, userId, true)
+}
+
+/**
+ * Resolve document access within a knowledge base, gated by read or write
+ * permission on the KB (see {@link resolveKnowledgeBaseAccess}).
+ */
+async function resolveDocumentAccess(
+  knowledgeBaseId: string,
+  documentId: string,
+  userId: string,
+  requireWrite: boolean
+): Promise<DocumentAccessCheck> {
+  const kbAccess = await resolveKnowledgeBaseAccess(knowledgeBaseId, userId, requireWrite)
+
+  if (!kbAccess.hasAccess) {
+    return {
+      hasAccess: false,
+      notFound: kbAccess.notFound,
+      reason: kbAccess.notFound ? 'Knowledge base not found' : 'Unauthorized knowledge base access',
+    }
+  }
+
+  const doc = await db
+    .select()
+    .from(document)
+    .where(
+      and(
+        eq(document.id, documentId),
+        eq(document.knowledgeBaseId, knowledgeBaseId),
+        eq(document.userExcluded, false),
+        isNull(document.archivedAt),
+        isNull(document.deletedAt)
+      )
+    )
+    .limit(1)
+
+  if (doc.length === 0) {
+    return { hasAccess: false, notFound: true, reason: 'Document not found' }
+  }
+
+  return {
+    hasAccess: true,
+    document: doc[0] as DocumentData,
+    knowledgeBase: kbAccess.knowledgeBase!,
+  }
+}
+
+/**
+ * Check if a user has read access to a document within a knowledge base.
+ */
+export async function checkDocumentAccess(
+  knowledgeBaseId: string,
+  documentId: string,
+  userId: string
+): Promise<DocumentAccessCheck> {
+  return resolveDocumentAccess(knowledgeBaseId, documentId, userId, false)
+}
+
+/**
+ * Check if a user has write access to a specific document.
+ * Write access is granted if user has write access to the knowledge base.
+ */
+export async function checkDocumentWriteAccess(
+  knowledgeBaseId: string,
+  documentId: string,
+  userId: string
+): Promise<DocumentAccessCheck> {
+  return resolveDocumentAccess(knowledgeBaseId, documentId, userId, true)
+}
+
+/**
+ * Resolve chunk access within a document/knowledge base, gated by read or write
+ * permission on the KB. The document must exist and be fully processed
+ * (`processingStatus === 'completed'`) before its chunks are accessible.
+ */
+async function resolveChunkAccess(
+  knowledgeBaseId: string,
+  documentId: string,
+  chunkId: string,
+  userId: string,
+  requireWrite: boolean
+): Promise<ChunkAccessCheck> {
+  const kbAccess = await resolveKnowledgeBaseAccess(knowledgeBaseId, userId, requireWrite)
+
+  if (!kbAccess.hasAccess) {
+    return {
+      hasAccess: false,
+      notFound: kbAccess.notFound,
+      reason: kbAccess.notFound ? 'Knowledge base not found' : 'Unauthorized knowledge base access',
+    }
+  }
+
+  const doc = await db
+    .select()
+    .from(document)
+    .where(
+      and(
+        eq(document.id, documentId),
+        eq(document.knowledgeBaseId, knowledgeBaseId),
+        eq(document.userExcluded, false),
+        isNull(document.archivedAt),
+        isNull(document.deletedAt)
+      )
+    )
+    .limit(1)
+
+  if (doc.length === 0) {
+    return { hasAccess: false, notFound: true, reason: 'Document not found' }
+  }
+
+  const docData = doc[0] as DocumentData
+
+  // Chunks are only accessible once the document has finished processing.
+  if (docData.processingStatus !== 'completed') {
+    return {
+      hasAccess: false,
+      reason: `Document is not ready for access (status: ${docData.processingStatus})`,
+    }
+  }
+
+  const chunk = await db
+    .select()
+    .from(embedding)
+    .where(and(eq(embedding.id, chunkId), eq(embedding.documentId, documentId)))
+    .limit(1)
+
+  if (chunk.length === 0) {
+    return { hasAccess: false, notFound: true, reason: 'Chunk not found' }
+  }
+
+  return {
+    hasAccess: true,
+    chunk: chunk[0] as EmbeddingData,
+    document: docData,
+    knowledgeBase: kbAccess.knowledgeBase!,
+  }
+}
+
+/**
+ * Check if a user has read access to a chunk within a document and knowledge base.
+ */
+export async function checkChunkAccess(
+  knowledgeBaseId: string,
+  documentId: string,
+  chunkId: string,
+  userId: string
+): Promise<ChunkAccessCheck> {
+  return resolveChunkAccess(knowledgeBaseId, documentId, chunkId, userId, false)
+}
+
+/**
+ * Check if a user has write access to a chunk.
+ *
+ * Mirrors {@link checkChunkAccess} but requires write/admin on the knowledge
+ * base's workspace (or KB ownership for legacy KBs), matching the permission
+ * needed to create chunks. Used for chunk mutation (update and delete) so those
+ * operations require the same permission as creation rather than read.
+ */
+export async function checkChunkWriteAccess(
+  knowledgeBaseId: string,
+  documentId: string,
+  chunkId: string,
+  userId: string
+): Promise<ChunkAccessCheck> {
+  return resolveChunkAccess(knowledgeBaseId, documentId, chunkId, userId, true)
+}