> ## Documentation Index > Fetch the complete documentation index at: https://docs.impellabs.tech/llms.txt > Use this file to discover all available pages before exploring further. # Knowledge > Add documents and websites, organize them in groups, manage facts and conflicts, and search. Knowledge is what your agents know about your business. It has four parts: * **Documents**: files and websites that ImpelLabs reads into searchable parts. * **Groups**: sets of documents and facts. An agent reads the groups you connect to it. * **Facts**: short values such as an address or an opening time. * **Conflicts**: two claims about the same fact that disagree. A person decides which is right. All routes are under `https://api.impellabs.tech/api/v1`. Send `Authorization: Bearer imp_...` on each request. See [Authentication](https://docs.impellabs.tech/api/authentication.md) and [Conventions](https://docs.impellabs.tech/api/conventions.md). The API reference lists every field. ## Who can do what A token acts as the person who made it. | Action | Who | | - | - | | Read documents, groups, facts, conflicts, sites | A person with the right to see knowledge. Others get `403` with `You cannot see knowledge.` | | Add a document or site, make a group | A person with the right to edit knowledge. | | Change or remove a document, group or fact | An owner, an admin, or the person who added it. | | Decide a conflict, or publish or retract a published fact | An owner or an admin. | A group that a person may not see answers `404` with `This knowledge group does not exist.` A group has a `visibility`: | Value | Who sees it | | - | - | | `personal` | Only the person who made it. | | `chosen` | The people and departments in `shared_members` and `shared_departments`. Owners and admins see it too. | | `workspace` | Everyone. | An agent that is connected to a group reads it even when its owner cannot see the group. ## Add a file 1. `POST /files` with a multipart `file`. The reply is `201` with the file: `id`, `name`, `content_type`, `size`, `status`. 2. `POST /knowledge/documents` with `{ "file_id": "" }`. ImpelLabs reads the text and splits it into parts. The reply is `201` with the document. ```bash theme={null} curl -X POST "https://api.impellabs.tech/api/v1/files" \ -H "Authorization: Bearer imp_..." \ -F "file=@price-list.pdf" curl -X POST "https://api.impellabs.tech/api/v1/knowledge/documents" \ -H "Authorization: Bearer imp_..." \ -H "Content-Type: application/json" \ -d '{"file_id": "9a3e6b10-1d2c-4f5a-8b7c-6e5d4c3b2a10"}' ``` ```json theme={null} { "id": "d17c0e44-8a52-4b0f-9c31-2f6a7b8c9d01", "kind": "file", "ref": "9a3e6b10-1d2c-4f5a-8b7c-6e5d4c3b2a10", "title": "price-list.pdf", "chunks": 12, "note": "", "tags": [], "created_at": "2026-01-12T09:30:00+00:00" } ``` | Status | Cause | | - | - | | `400` | `file_id` is not an id, the file is not in your workspace, or the file has no text. | | `403` | You cannot add knowledge. | `GET /files` lists the file library (`q`, `status`, `kind`, `sort`, `order`, `page`, `page_size`). `GET /files/{file_id}/info` adds a text preview. `POST /files/{file_id}/retry` reads a failed file again; any other file answers `409`. A file that cannot be read is rejected with `400` and a reason. ## Documents * `GET /knowledge/documents` lists the documents you may see. `kind` is `file` or `website`. * `PATCH /knowledge/documents/{document_id}` with `{ "tags": [...] }` sets the sensitive-data tags of the source. The tags are `personal`, `health` and `payment`. * `DELETE /knowledge/documents/{document_id}` archives the document and answers `204`. ## Add a website 1. `POST /knowledge/sites/discover` with `{ "url": "
" }` finds the pages of the site. 2. `POST /knowledge/sites/read` with `{ "url", "pages": [...], "group_id"? }` reads the pages you choose. The reading runs in the background. Use `group_id` to file the result in a group you may change. 3. `GET /knowledge/sites` shows each site (`id`, `site`, `title`, `pages`, `blocks`, `groups`) and `reading`, the reads that are not done. An address that ImpelLabs may not read answers `400` with `This address cannot be read`. ```bash theme={null} curl -X POST "https://api.impellabs.tech/api/v1/knowledge/sites/discover" \ -H "Authorization: Bearer imp_..." \ -H "Content-Type: application/json" \ -d '{"url": "https://www.example.org"}' ``` `POST /knowledge/groups/{group_id}/deep-scan` with `{ "url": "" }` reads one page for facts and files them in the group. `GET /knowledge/groups/{group_id}/sources` lists what the group was built from. ## Groups `GET /knowledge/groups` lists the groups you see. `archived=1` lists archived groups. `POST /knowledge/groups` makes a group. | Field | Meaning | | - | - | | `title` | Required, 100 characters at most. A title that exists answers `400`. | | `about` | 500 characters at most. | | `visibility` | `personal`, `chosen` or `workspace`. | | `shared_members`, `shared_departments` | Ids. Required for `chosen`: send at least one person or department. | ```bash theme={null} curl -X POST "https://api.impellabs.tech/api/v1/knowledge/groups" \ -H "Authorization: Bearer imp_..." \ -H "Content-Type: application/json" \ -d '{"title": "Prices", "about": "Current prices and offers.", "visibility": "workspace"}' ``` The reply is `201`: ```json theme={null} { "id": "4c8b2e10-7d5a-4f63-a1b9-0e8d7c6b5a42", "title": "Prices", "about": "Current prices and offers.", "sites": [], "cards": 0, "items": [], "owner": "a2c4f1d0-6b3e-4a7d-9e52-1c0b8d7e6f10", "mine": true, "archived": false, "can_change": true, "agents": [], "visibility": "workspace", "shared_members": [], "shared_departments": [], "created_at": "2026-01-12T09:35:00+00:00", "updated_at": "2026-01-12T09:35:00+00:00" } ``` * `GET`, `PATCH` and `DELETE /knowledge/groups/{group_id}`. `DELETE` archives the group and its items. * `POST /knowledge/groups/{group_id}/restore` brings an archived group back with its items. * `POST /knowledge/groups/{group_id}/items` with `{ "document_id" }` or `{ "fact_key" }` files an item in the group. The reply is `201` with the group. * `DELETE /knowledge/groups/{group_id}/items/{item_id}` takes an item out. The reply is `204`. To let an agent read a group, put the group id in the agent's `knowledge_groups`. See [Agents](https://docs.impellabs.tech/api/agents.md). ## Facts A fact has a `key`, a `value` and a `source`. * `PATCH /knowledge/facts/{key}` with `{ "value": "" }` sets a new value. It has 2000 characters at most. * `DELETE /knowledge/facts/{key}` archives the fact. ## Conflicts and published facts * `GET /knowledge/conflicts` lists open conflicts. `status` shows others. Each conflict has `id`, `status`, `fact`, `key` and `claims`; each claim has `id`, `value`, `said_by`, `confidence`, `when` and `quote`. * `POST /knowledge/conflicts/{conflict_id}/resolve` with `{ "action", "claim_id"?, "text"? }`. `action` is `select` (the default; use `claim_id`), `edit` (use `text`), `delete` or `keep_both`. An owner or an admin only. * `GET /knowledge/published-facts` lists published facts. `status` filters them. * `POST /knowledge/published-facts` with `{ "claim_id" }` publishes a claim. An owner or an admin only. * `POST /knowledge/published-facts/{fact_id}/retract` with `{ "note"? }` retracts a published fact. ```bash theme={null} curl -X POST "https://api.impellabs.tech/api/v1/knowledge/conflicts/6f1a9d20-3b4c-4e5d-8a7f-9c0b1d2e3f40/resolve" \ -H "Authorization: Bearer imp_..." \ -H "Content-Type: application/json" \ -d '{"action": "select", "claim_id": "0b7e5d30-2c4a-4f81-93d6-1a2b3c4d5e60"}' ``` ## Questions your agents could not answer `GET /knowledge/unanswered` lists the questions that agents could not answer. `status` is `open` (the default), `resolved` or `dismissed`. `agent` filters by agent. The reply is `{ "questions": [...], "open": }`. * `POST /knowledge/unanswered/{question_id}/draft` drafts an answer from your knowledge. Nothing is saved. * `POST /knowledge/unanswered/{question_id}/answer` with `{ "text", "group_ids"? }` saves the answer as a fact and files it in the groups. * `POST /knowledge/unanswered/{question_id}/dismiss` closes the question. ## Search `GET /search` searches across what the person may see. | Query | Meaning | | - | - | | `q` | The words. At least two characters, 200 at most. | | `kind` | One kind or several, separated by commas: `cases`, `contacts`, `records`, `files`, `knowledge`, `tasks`, `chats`. | | `limit` | Hits for each kind. The default is 5. The maximum is 20. | ```bash theme={null} curl "https://api.impellabs.tech/api/v1/search?q=opening%20hours&kind=knowledge,cases&limit=5" \ -H "Authorization: Bearer imp_..." ``` The reply is `{ "q": "...", "groups": [ { "kind", "label", "items": [ ... ] } ] }`. With fewer than two characters, `groups` is empty. ## Memories A memory is a short line that someone keeps, of 300 characters at most. `GET` and `POST /memories` are your own and private. `PATCH` and `DELETE /memories/{memory_id}` change one. `PUT /memories/settings` with `{ "on": true }` or `false` turns your memories on or off. `GET` and `POST /contacts/{contact_id}/memories`, and `DELETE /contacts/{contact_id}/memories/{memory_id}`, hold what your agents remember about a customer. Memories of an agent are on [Agents](https://docs.impellabs.tech/api/agents.md). This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.