Knowledge Base

Semantic search across the knowledge base

get/v1/public/knowledge-base/search

Returns the top matching chunks ranked by hybrid (semantic + keyword) score. Use this from external AI agents or MCP clients to ground answers in your KB.

curl -X GET "https://api.cognizy.ai/api/v1/public/knowledge-base/search?query=how%20do%20I%20reset%20my%20password" \
  -H "Authorization: Bearer $COGNIZY_API_KEY"

List knowledge bases

get/v1/public/knowledge-base

Returns all knowledge bases in the organization, with document counts.

curl -X GET "https://api.cognizy.ai/api/v1/public/knowledge-base" \
  -H "Authorization: Bearer $COGNIZY_API_KEY"

Create a knowledge base

post/v1/public/knowledge-base

Accepts Idempotency-Key

Creates a new KB. Plan limits apply (RagService enforces this — returns 403 when the org is at its knowledgeBases quota).

curl -X POST "https://api.cognizy.ai/api/v1/public/knowledge-base" \
  -H "Authorization: Bearer $COGNIZY_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: $(uuidgen)" \
  -d '{
  "name": "Maria Souza",
  "description": "texto"
}'

Get a knowledge base

get/v1/public/knowledge-base/{id}

Returns one KB with metadata and document count.

curl -X GET "https://api.cognizy.ai/api/v1/public/knowledge-base/<id>" \
  -H "Authorization: Bearer $COGNIZY_API_KEY"

List documents in a knowledge base

get/v1/public/knowledge-base/{id}/documents

Lists documents inside a KB with their titles, source URLs, use counts, and timestamps. Use this to avoid duplicating content before adding a new document.

curl -X GET "https://api.cognizy.ai/api/v1/public/knowledge-base/<id>/documents" \
  -H "Authorization: Bearer $COGNIZY_API_KEY"

Add a document to a knowledge base

post/v1/public/knowledge-base/{id}/documents

Accepts Idempotency-Key

Adds a new document, chunks it, generates embeddings, and stores them in pgvector. Same pipeline as the in-app upload. Returns the created document row (without chunks). Subsequent search_knowledge_base calls will surface this content immediately — RAG cache is invalidated automatically.

curl -X POST "https://api.cognizy.ai/api/v1/public/knowledge-base/<id>/documents" \
  -H "Authorization: Bearer $COGNIZY_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: $(uuidgen)" \
  -d '{
  "title": "texto",
  "content": "texto",
  "sourceUrl": "https://example.com"
}'

Get a document

get/v1/public/knowledge-base/documents/{documentId}

Returns the full document content. Useful to read existing material before suggesting an update.

curl -X GET "https://api.cognizy.ai/api/v1/public/knowledge-base/documents/<documentId>" \
  -H "Authorization: Bearer $COGNIZY_API_KEY"

Update a document

patch/v1/public/knowledge-base/documents/{documentId}

Accepts Idempotency-Key

Partial update of a document. Provide any combination of title, content, sourceUrl. When content changes, the document is re-chunked and re-embedded automatically — useCount and feedback stats are preserved. Renaming into a title that already exists in the KB returns 409 (unique constraint).

curl -X PATCH "https://api.cognizy.ai/api/v1/public/knowledge-base/documents/<documentId>" \
  -H "Authorization: Bearer $COGNIZY_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: $(uuidgen)" \
  -d '{
  "title": "texto",
  "content": "texto",
  "sourceUrl": "https://example.com"
}'

Delete a document

delete/v1/public/knowledge-base/documents/{documentId}

Removes a document and its chunks (cascade via Prisma). RAG cache is invalidated automatically. Idempotent — succeeds with 204 even if the document was already gone (P2025 swallowed).

curl -X DELETE "https://api.cognizy.ai/api/v1/public/knowledge-base/documents/<documentId>" \
  -H "Authorization: Bearer $COGNIZY_API_KEY"

Bulk add or upsert documents

post/v1/public/knowledge-base/{id}/documents/bulk

Accepts Idempotency-Key

Adds many documents in one request. Upsert-by-title: a doc whose title already exists in the KB is UPDATED with the new content; others are created. Returns counts of created/updated/skipped (skipped includes invalid items and intra-batch title duplicates). Use this for migrations, JSON imports, or batch material generated by an LLM. Cap: 200 items per call.

curl -X POST "https://api.cognizy.ai/api/v1/public/knowledge-base/<id>/documents/bulk" \
  -H "Authorization: Bearer $COGNIZY_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: $(uuidgen)" \
  -d '{
  "documents": [
    {
      "title": "texto",
      "content": "texto",
      "sourceUrl": "https://example.com"
    }
  ]
}'