API reference

Knowledge

Give your bots source material to answer from. Add text, a URL, or upload files; Hania chunks, embeds, and indexes them for retrieval. Read endpoints need knowledge:read; adding and deleting need knowledge:write.

Endpoints

Method & path	Ability	Notes
`GET /api/v1/knowledge`	`knowledge:read`	List (no pagination; metadata filters)
`GET /api/v1/knowledge/{id}`	`knowledge:read`	Active sources only
`GET /api/v1/knowledge/stats`	`knowledge:read`	Counts by type and status
`POST /api/v1/knowledge`	`knowledge:write`	JSON or multipart (see below)
`DELETE /api/v1/knowledge/{id}`	`knowledge:write`	`?type=hard` \| `soft` (default `soft`)

The knowledge object

id, tenant_id, bot_id, title, content, content_type (text | uploaded_file | url), optional source_filename, optional source_url, metadata, processing_status, status (active | inactive), created_at, updated_at. processing_status is one of pending, processing, completed, failed — poll until completed before relying on retrieval.

Add text or a URL (JSON)

POST /api/v1/knowledge with a JSON body returns the full knowledge object.

Field	Notes
`content_type`	Required. `text` or `url`.
`title`	Required for `text`.
`content`	Required for `text` (≤ 50,000 chars).
`url`	Required for `url`.
`bot_id`, `metadata`	Optional.

curl https://app.hania.ai/api/v1/knowledge \
  -H "Authorization: Bearer $HANIA_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "content_type": "url", "url": "https://help.example.com", "bot_id": "b1f2c3d4-…" }'

Upload files (multipart)

POST /api/v1/knowledge as multipart/form-data with one or more file parts (1–5 files, ≤ 5 MB each; .txt, .pdf, .docx, .md, .html, .htm), plus optional title, bot_id, and metadata. The response reports per-file results:

{
  "created": [{ "id": "…", "filename": "policy.pdf", "title": "Policy" }],
  "errors":  [{ "filename": "huge.pdf", "reason": "exceeds 5 MB" }]
}

Stats

GET /api/v1/knowledge/stats → { total_knowledge_bases, by_type: { text, uploaded_file, url }, by_status: { pending, processing, completed, failed } }.

Delete

DELETE /api/v1/knowledge/{id} soft-deletes by default (recoverable). Pass ?type=hard to permanently remove the source and its embeddings.