AI.md

Knowledge bases

A knowledge base holds documents an AI agent can search during a call (its built-in search_knowledge tool). Documents are pasted text, a web page, or an uploaded text file. Each document is split into chunks and embedded; it is processing until that finishes. Attach knowledge bases to an agent with agent.knowledge_base_ids (up to 5) on the voice app.

Auth, errors, paging and idempotency work as described in the overview.

Base URL: https://api.contactivity.io/v1/projects/{project_id}

Method	Path	Scope	Purpose
GET	`/knowledge-bases`	`apps:read`	List knowledge bases
POST	`/knowledge-bases`	`apps:write`	Create one
GET	`/knowledge-bases/{id}`	`apps:read`	Fetch one with its documents
PATCH	`/knowledge-bases/{id}`	`apps:write`	Rename or describe it
DELETE	`/knowledge-bases/{id}`	`apps:write`	Archive it (excluded from search)
POST	`/knowledge-bases/{id}/documents`	`apps:write`	Add a document
DELETE	`/knowledge-bases/{id}/documents/{doc_id}`	`apps:write`	Archive a document
GET	`/knowledge-bases/{id}/search?q=`	`apps:read`	The 5 closest chunks

Limits: 20 knowledge bases per project, 100 documents per knowledge base, 1,000,000 characters per document.

Objects

Knowledge base:

Field	Type	Notes
`id`	string	`kb_…`
`name`	string	1-100 characters
`description`	string	Up to 1000 characters
`documents`	integer, or array	A count in list/create/update responses; the document objects (oldest first) on fetch
`created_at`, `updated_at`	timestamp

Document:

Field	Type	Notes
`id`	string	`kbd_…`
`name`	string	Up to 200 characters (longer names are cut)
`source`	string	`text`, `url` or `file`
`source_url`	string or null	For `url`
`content_type`	string or null	e.g. `text/plain`, `text/html`
`status`	string	`processing`, `ready` or `error`
`error`	string or null	Why ingest failed
`chars`, `chunks`	integer or null	Size once ingested
`created_at`	timestamp

Create, update, archive

curl https://api.contactivity.io/v1/projects/$PROJECT_ID/knowledge-bases \
  -H "Authorization: Bearer $CONTACTIVITY_API_KEY" \
  -H "Content-Type: application/json" -H "Idempotency-Key: $(uuidgen)" \
  -d '{"name": "Clinic FAQ", "description": "Opening hours, parking, insurance"}'

Field	Type	Required	Limits
`name`	string	create: yes	1-100 characters
`description`	string	no	up to 1000 characters

POST returns 201. PATCH /knowledge-bases/{id} takes the same fields; fields left out keep their values. DELETE archives the knowledge base (its documents leave search) and returns 204; it is refused while an AI agent's draft lists the knowledge base.

Errors: 400 invalid_parameter (name, description, or the 20-per-project limit), 400 unknown_parameter, 400 invalid_json, 404 not_found, 409 conflict (delete: used by an agent).

Add a document

JSON with name and text, or url (and optional name, default the URL). Exactly one of text or url.

curl https://api.contactivity.io/v1/projects/$PROJECT_ID/knowledge-bases/kb_us1_abc/documents \
  -H "Authorization: Bearer $CONTACTIVITY_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"name": "Hours", "text": "We are open Monday to Friday, 8 am to 6 pm."}'

Or upload a file (multipart/form-data, field file, optional name): UTF-8 .txt, .md, .csv, .json, .html or .htm, up to 5 MB. HTML is reduced to its text. PDF and DOCX are not supported yet.

curl https://api.contactivity.io/v1/projects/$PROJECT_ID/knowledge-bases/kb_us1_abc/documents \
  -H "Authorization: Bearer $CONTACTIVITY_API_KEY" \
  -F file=@faq.md

Returns 202 with the document in processing. Fetch the knowledge base to see it become ready (or error).

Errors: 400 invalid_parameter (name, url, file; neither or both of text and url; empty or too long document; 100-document limit), 400 unknown_parameter, 400 invalid_json, 404 not_found, 503 service_unavailable (could not queue the document; add it again).

DELETE /knowledge-bases/{id}/documents/{doc_id} archives the document (excluded from search) and returns 204. Errors: 404 not_found, 409 archived.

Search

GET /knowledge-bases/{id}/search?q=... returns the 5 chunks closest to q (1-1000 characters), best first, as one page: {data: [{document, content, score}], has_more: false, next_cursor: null}. score is the cosine similarity. Use it to check what an agent will find.

curl -G https://api.contactivity.io/v1/projects/$PROJECT_ID/knowledge-bases/kb_us1_abc/search \
  -H "Authorization: Bearer $CONTACTIVITY_API_KEY" \
  --data-urlencode "q=when are you open"

Errors: 400 invalid_parameter (q), 404 not_found, 502 upstream_error (the embedding provider failed).