Knowledge

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 and Conventions. 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

POST /files with a multipart file. The reply is 201 with the file: id, name, content_type, size, status.
POST /knowledge/documents with { "file_id": "<id>" }. ImpelLabs reads the text and splits it into parts. The reply is 201 with the document.

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"}'

{
  "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

POST /knowledge/sites/discover with { "url": "<address>" } finds the pages of the site.
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.
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.

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": "<one page>" } 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.

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:

{
  "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.

Facts

A fact has a key, a value and a source.

PATCH /knowledge/facts/{key} with { "value": "<text>" } 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.

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": <number> }.

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.

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.

Get started

Resources

Events

Build

API reference