Copy page

Configure your account

Knowledge

Knowledge is the facts an agent looks up instead of remembering: prices, hours, policies, product sheets, procedures. You organize it in collections. A collection holds documents, and an agent searches only the collections you grant it. Prices and policies belong here, not in the prompt, because you can change a document without touching the agent.

The examples use this client:

Code
import { Lelemon } from '@lelemon-ai/sdk';

const lelemon = new Lelemon({ apiKey: process.env.LELEMON_API_KEY });

Create a collection

A collection is a name and an optional description. Group documents by the topic the agent needs together, such as "Prices" or "Warranty".

Expected: 201 with documentCount: 0. The collection is this object:

KnowledgeCollectionobject, 7 fields

• objectenumrequired

  knowledge_collection

• idstringrequired

  Example kbc_2LpX0x8bVw1TqS9mYp3RkL

• namestringrequired

  Example FAQ

• descriptionstring or nullrequired
• documentCountintegerrequired

  Documents in any status.

• createdAtstring (date-time)required
• updatedAtstring (date-time)required

Add a document

A document is text. Send it as JSON in text, or upload a file as multipart in file: PDF, DOCX, TXT or MD, up to 15 MB. Send either one, not both. name is the name you see; for a file it defaults to the file name.

Sending the same name again replaces the document and processes it again, so a nightly sync can repeat the same call. Expected: 201 with status: "processing".

KnowledgeDocumentobject, 11 fields

• objectenumrequired

  knowledge_document

• idstringrequired

  Example kbd_02y0e5MANqacVbmtn1YyeJ

• collectionIdstringrequired

  Example kbc_2LpX0x8bVw1TqS9mYp3RkL

• namestringrequired

  Example faq.pdf

• mimeTypestringrequired

  Example application/pdf

• sizeBytesintegerrequired
• statusenumrequired

  processingreadyfailed

• chunkCountintegerrequired

  Searchable passages.

• errorKnowledgeDocumentError or nullrequired

  Set when status is failed.

  KnowledgeDocumentError2 fields

  • codeenumrequired

    text_extraction_failedno_text_foundembedding_failedprocessing_failedenqueue_failed

  • messagestringrequired
• createdAtstring (date-time)required
• updatedAtstring (date-time)required

Follow the ingestion

A document starts as processing. Lelemon extracts its text, cuts it into passages and indexes them. The agent finds a document only when its status is ready.

status	Meaning
processing	Being read and indexed
ready	Searchable. chunkCount counts the passages
failed	Not searchable. error.code says why

error.code	Cause and fix
text_extraction_failed	The file could not be read. Check that it opens and is not protected, then upload it again
no_text_found	The file has no text, for example a scanned image. Upload a version with text
embedding_failed	The text could not be indexed. Upload it again
processing_failed	The processing stopped. Upload it again
enqueue_failed	The job could not be queued. Upload it again

You are told in two ways. Subscribe a webhook endpoint to knowledge_document.ready and knowledge_document.failed, or read the document until the status changes:

Reading one document also returns its content, the text the agent searches, once it is ready. Lists do not carry the content.

Give a collection to an agent

An agent uses only the collections you grant it. PUT /v2/agents/{id}/knowledge-collections/{collectionId} grants one and DELETE on the same path revokes it. Both are safe to repeat, and the agent uses the change from its next answer.

Expected: the grant answers granted: true. Granting needs knowledge:write. One collection can feed many agents, and one agent can hold many collections.

List and read

GET /v2/knowledge-collections lists collections newest first. GET /v2/knowledge-collections/{id}/documents lists the documents newest first, without their content, and filters by status. Lists follow the pagination rules.

Search the knowledge

POST /v2/knowledge-collections/search runs the search your agents use, by meaning and by exact words, and returns the passages with the collection and document each one comes from. Use it to check what an agent would find, or to let a tool such as Claude look up an answer. It needs knowledge:read, changes nothing and is safe to repeat.

Without collectionIds it searches every collection of the organization, except the ones the internal assistant of the dashboard reads. limit is up to 10 and defaults to 5. score is the closeness in meaning, from 0 to 1, and is null for a passage found only by its exact words. An empty data means nothing answers it.

Update

Rename a collection or change its description with PATCH /v2/knowledge-collections/{id}. PATCH a document to rename it or replace its text; new text processes the document again.

Code
await lelemon.knowledgeCollections.update(collection.id, { description: 'Prices and policies, updated monthly.' });
await lelemon.knowledgeCollections.documents.update(collection.id, document.id, {
  text: 'Cleaning: 38.000 CLP. Check-up: 25.000 CLP.',
});

Delete

DELETE /v2/knowledge-collections/{id}/documents/{docId} answers 204 and the agent stops finding the document right away. DELETE /v2/knowledge-collections/{id} deletes the collection with its documents and removes it from every agent that had it. Documents kept by a connected source, and the collection that source feeds, answer 409 resource_in_use.

Code
await lelemon.knowledgeCollections.documents.delete(collection.id, document.id);
await lelemon.knowledgeCollections.delete(collection.id);

Errors you will meet

Error	Cause
400 invalid_request	The body has neither text nor file, or both; param is text
403 scope_missing	The key lacks knowledge:write or knowledge:read
404 not_found	The collection, document or agent does not exist in this mode
503 service_unavailable	The search cannot run right now; retry in a moment
409 resource_in_use	A connected source keeps the document or feeds the collection
413 payload_too_large	The file is larger than 15 MB
422 unsupported_file_type	The file type is not PDF, DOCX, TXT or MD

All codes are in the error catalog.

Good practice

• One topic per document, with headings. The agent finds passages, so a document that mixes prices and warranty gives worse answers than two documents.
• Write facts the way a customer asks about them: "Cleaning costs 35.000 CLP" finds better than a table without a title.
• Use a stable name per document and re-send it when the source changes.
• Subscribe to knowledge_document.failed so a broken upload does not go unnoticed.
• Keep what the agent must never say out of the collection: the agent can quote anything it finds.

What's next

• Agents to give the collection to an agent and write the prompt that uses it.
• Receive events to be told when a document is ready.