Knora API Reference

Knora is an institutional memory system that captures, structures, and makes queryable everything a company knows. Arabic-first, bilingual (AR+EN), provider-agnostic AI layer.

Base URL

Production:  https://api.knora.io/api/v1
Local:       http://localhost:5001/api/v1

All endpoints are prefixed with /api/v1. Breaking changes ship under /api/v2.

Authentication

Two mechanisms, used depending on the caller.

JWT Bearer Tokens — for user sessions. Obtain via /auth/login or /auth/register.

Authorization: Bearer <access_token>

Token	Lifetime	Delivery
Access token	1 hour	JSON body (access_token)
Refresh token	30 days	httpOnly cookie (knora_refresh_token, path /)

API Keys — for scripts and integrations (Growth plan+). Created via POST /api-keys, prefixed kn_.

Authorization: Bearer kn_<key>

Rate-limited to 60 req/min per key.

JWT claims:

Claim	Type	Description
sub	UUID	User ID
role	string	member / manager / admin
email	string	User email
org_id	UUID	Organization ID
org_plan	string	trial / starter / growth / enterprise
is_org_owner	bool	Whether the user owns the organization

Roles

Roles are hierarchical — each inherits all permissions below it.

Role	Level	Capabilities
member	1	Read, create, flag entries
manager	2	+ verify entries, manage tags/departments, view analytics
admin	3	+ member management (invite, role change, removal)

The org owner (is_org_owner: true) has implicit admin rights and exclusive access to billing.

Plans

Ordered: trial < starter < growth < enterprise.

Plan	Price	Users	Integrations	Key gates
trial	Free (14 days)	30	3	Basic capture and query
starter	$49/mo	30	3	Manual entry, voice, documents
growth	$149/mo	150	Unlimited	API keys, interviews, analytics, bulk ops, graph
enterprise	$399/mo	Unlimited	Unlimited	SSO, BYOK LLM, dedicated support

Subscription guard: All authenticated routes (except Auth and Billing) require an active subscription. Expired trials and deactivated accounts get 402 SUBSCRIPTION_REQUIRED.

Plan upgrade errors include details.required_plan and details.feature.

Pagination

List endpoints accept page (default 1) and per_page (default 20, max 100). Response:

{
  "items": [...],
  "pagination": { "page": 1, "per_page": 20, "total": 150, "total_pages": 8, "has_next": true, "has_prev": false }
}

Values outside range are silently clamped. All pagination is offset-based.

Filtering

Query parameters. UUID lists support both repeated params and comma-separated:

GET /knowledge/?tag_ids=<uuid1>&tag_ids=<uuid2>&status=active
GET /knowledge/?tag_ids=<uuid1>,<uuid2>&status=active

Results default to reverse chronological order unless documented otherwise.

Errors

Every error uses this envelope:

{
  "error": {
    "code": "SNAKE_CASE_CODE",
    "message": "Human-readable description.",
    "details": {}
  }
}

Status	Meaning
200	Success
201	Created
202	Accepted (async job enqueued)
204	No content
400	Bad request
401	Missing or invalid auth
402	Subscription required or expired
403	Insufficient role or plan
404	Not found
409	Conflict
413	Payload too large
422	Validation error
429	Rate limited

Rate Limits

Scope	Limit
/auth/register, /auth/login, /auth/google	10/min/IP
/auth/invite, /auth/refresh	20/min/IP
API key requests	60/min/key
All other endpoints	Infrastructure limits only

Endpoint Reference

Legend: None = public, JWT = any authenticated user, Role = minimum role required, Plan = minimum plan.

Auth /api/v1/auth

Method	Path	Description	Auth	Plan
POST	/auth/register	Register + create org	None	—
POST	/auth/login	Email + password login	None	—
POST	/auth/google	Google OAuth login/register	None	—
POST	/auth/forgot-password	Initiate password reset	None	—
POST	/auth/reset-password	Complete password reset	None	—
POST	/auth/accept-invite	Accept team invitation	None	—
POST	/auth/refresh	Refresh access token	Cookie	—
POST	/auth/logout	Blocklist tokens + clear cookie	JWT	Any
GET	/auth/me	Current user profile	JWT	Any
PUT	/auth/me	Update profile	JWT	Any
POST	/auth/invite	Invite a member	JWT (admin/manager)	Any
GET	/auth/members	List org members	JWT	Any
PATCH	/auth/members/:user_id	Change member role	JWT (admin)	Any
DELETE	/auth/members/:user_id	Deactivate member	JWT (admin)	Any

Organizations /api/v1/organizations

Method	Path	Description	Auth	Plan
GET	/organizations/plans	List available plans	None	—
GET	/organizations/me	Current org profile	JWT	Any
GET	/organizations/me/limits	Resource usage vs limits	JWT	Any
PATCH	/organizations/me	Update org settings	JWT (admin/owner)	Any
GET	/organizations/byok	Get BYOK LLM config	JWT (admin/owner)	Enterprise
PUT	/organizations/byok	Set BYOK LLM config	JWT (admin/owner)	Enterprise
DELETE	/organizations/byok	Remove BYOK config	JWT (admin/owner)	Enterprise
POST	/organizations/byok/test	Test BYOK credentials	JWT (admin/owner)	Enterprise
GET	/organizations/sso	Get SSO config	JWT (admin/owner)	Enterprise
PUT	/organizations/sso	Configure SSO	JWT (admin/owner)	Enterprise
POST	/organizations/sso/test	Test SSO config	JWT (admin/owner)	Enterprise
DELETE	/organizations/sso	Remove SSO	JWT (admin/owner)	Enterprise
GET	/organizations/locations	List locations	JWT	Any
POST	/organizations/locations	Create location	JWT (manager+)	Growth+
PUT	/organizations/locations/:id	Update location	JWT (manager+)	Any
DELETE	/organizations/locations/:id	Delete location	JWT (manager+)	Any

Knowledge /api/v1/knowledge

Method	Path	Description	Auth	Plan
GET	/knowledge/	List entries (paginated, filterable)	JWT	Any
POST	/knowledge/	Create entry	JWT	Any
GET	/knowledge/:id	Get entry with relations	JWT	Any
PUT	/knowledge/:id	Update entry (creates version)	JWT	Any
DELETE	/knowledge/:id	Archive entry	JWT	Any
POST	/knowledge/:id/verify	Mark as verified	JWT (manager+)	Any
POST	/knowledge/:id/needs-review	Flag for review	JWT	Any
GET	/knowledge/:id/versions	Version history	JWT	Any
POST	/knowledge/:id/relate	Link entries	JWT	Any
DELETE	/knowledge/:id/relate/:related_id	Unlink entries	JWT	Any
POST	/knowledge/bulk-import	Bulk import	JWT	Growth+
GET	/knowledge/export	Export entries as JSON	JWT	Growth+
GET	/knowledge/tags	List tags	JWT	Any
POST	/knowledge/tags	Create tag	JWT (manager+)	Any
DELETE	/knowledge/tags/:tag_id	Delete tag	JWT (manager+)	Any
GET	/knowledge/departments	List departments	JWT	Any
POST	/knowledge/departments	Create department	JWT (manager+)	Any
PUT	/knowledge/departments/:id	Update department	JWT (manager+)	Any
POST	/knowledge/departments/classify	Auto-classify entries	JWT (manager+)	Any
GET	/knowledge/categories	List categories	JWT	Growth+
POST	/knowledge/categories	Create category	JWT (manager+)	Growth+
PUT	/knowledge/categories/:id	Update category	JWT (manager+)	Growth+
DELETE	/knowledge/categories/:id	Deactivate category	JWT (manager+)	Growth+
GET	/knowledge/categories/:id/path	Category ancestor path	JWT	Growth+

Query /api/v1/query

Method	Path	Description	Auth	Plan
POST	/query/ask	RAG question answering + citations	JWT	Any
GET	/query/search	Semantic search (no LLM)	JWT	Any
GET	/query/history	Caller's query history	JWT	Any
GET	/query/gaps	Unresolved knowledge gaps	JWT (manager+)	Any
POST	/query/gaps/:gap_id/resolve	Resolve gap with entry link	JWT (manager+)	Any
GET	/query/analytics	Query statistics	JWT (admin+)	Growth+

Capture — Voice /api/v1/capture/voice

Method	Path	Description	Auth	Plan
POST	/capture/voice/upload	Upload audio, async Whisper transcription	JWT	Any
GET	/capture/voice/jobs	List voice capture jobs	JWT	Any
GET	/capture/voice/jobs/:job_id	Get job status	JWT	Any
POST	/capture/voice/transcribe	Sync transcription (no job created)	JWT	Growth+

Capture — Documents /api/v1/capture/documents

Method	Path	Description	Auth	Plan
POST	/capture/documents/upload	Upload document, async parsing	JWT	Starter+
GET	/capture/documents/jobs	List document jobs	JWT	Starter+
GET	/capture/documents/jobs/:job_id	Get job status	JWT	Starter+

Capture — Manual /api/v1/capture/manual

Method	Path	Description	Auth	Plan
POST	/capture/manual/	Create manual entry (sync)	JWT	Any

Capture — Interviews /api/v1/capture/interviews

Method	Path	Description	Auth	Plan
GET	/capture/interviews/templates	List templates	JWT	Growth+
POST	/capture/interviews/templates	Create template	JWT (manager+)	Growth+
GET	/capture/interviews/templates/:id	Get template	JWT	Growth+
PUT	/capture/interviews/templates/:id	Update template	JWT (manager+)	Growth+
DELETE	/capture/interviews/templates/:id	Deactivate template	JWT (manager+)	Growth+
POST	/capture/interviews/sessions	Start session	JWT	Growth+
GET	/capture/interviews/sessions	List sessions	JWT	Growth+
GET	/capture/interviews/sessions/:id	Get session + answers	JWT	Growth+
POST	/capture/interviews/sessions/:id/answers	Submit answer	JWT	Growth+
POST	/capture/interviews/sessions/:id/complete	Complete session	JWT	Growth+
DELETE	/capture/interviews/sessions/:id	Cancel session	JWT	Growth+
POST	/capture/interviews/shift-logs	Create shift log	JWT	Growth+
GET	/capture/interviews/shift-logs	List shift logs	JWT	Growth+
GET	/capture/interviews/shift-logs/:id	Get shift log	JWT	Growth+
PUT	/capture/interviews/shift-logs/:id	Update draft	JWT	Growth+
POST	/capture/interviews/shift-logs/:id/submit	Submit + extract	JWT	Growth+

Integrations /api/v1/integrations

Method	Path	Description	Auth	Plan
GET	/integrations/connectors	List connector types + schemas	JWT (manager+)	Any
GET	/integrations/	List org integrations	JWT (manager+)	Any
POST	/integrations/	Create integration	JWT (admin)	Any
DELETE	/integrations/:id	Delete integration	JWT (admin)	Any
GET	/integrations/:id/health	Connection health check	JWT (manager+)	Any
GET	/integrations/:id/connection-health	Live credential probe	JWT (manager+)	Any
POST	/integrations/:id/sync	Trigger sync	JWT (admin)	Any
GET	/integrations/:id/history	Sync history	JWT (manager+)	Any
GET	/integrations/:id/preview	Preview import volume	JWT (manager+)	Any
GET	/integrations/oauth/start	Start OAuth flow	JWT (admin)	Any
GET	/integrations/oauth/callback	OAuth provider callback	None	—
POST	/integrations/webhook/:id/receive	Inbound webhook payload	HMAC	—

Connector types: slack, google_drive, gmail, notion, github, webhook

Analytics /api/v1/analytics

Method	Path	Description	Auth	Plan
GET	/analytics/bus-factor/	Org-wide risk summary	JWT (manager+)	Growth+
GET	/analytics/bus-factor/person/:user_id	Per-person score	JWT (manager+)	Growth+
GET	/analytics/bus-factor/department/:dept_id	Per-department score	JWT (manager+)	Growth+
GET	/analytics/bus-factor/critical	Critical-risk only	JWT (manager+)	Growth+
GET	/analytics/staleness/	Stale entries list	JWT (manager+)	Growth+
GET	/analytics/staleness/stats	Staleness stats	JWT (manager+)	Growth+
POST	/analytics/staleness/check	Trigger staleness check	JWT (admin+)	Growth+

Dashboard /api/v1/dashboard

Method	Path	Description	Auth	Plan
GET	/dashboard/overview	Summary stats + health score	JWT (manager+)	Growth+
GET	/dashboard/health	Health score only	JWT (manager+)	Growth+
GET	/dashboard/activity	Recent activity feed	JWT (manager+)	Growth+
GET	/dashboard/departments	Per-department stats	JWT (manager+)	Growth+
GET	/dashboard/trending	Top queries	JWT (manager+)	Growth+

Graph /api/v1/graph

Method	Path	Description	Auth	Plan
GET	/graph	Full knowledge graph (paginated)	JWT	Growth+
GET	/graph/entry/:id	Entry subgraph	JWT	Growth+
GET	/graph/clusters	Tag-based clusters	JWT	Growth+
POST	/graph/auto-link	Enqueue auto-linking	JWT (manager+)	Growth+
GET	/graph/auto-link/:task_id	Auto-link task status	JWT	Growth+
GET	/graph/stats	Graph statistics	JWT	Growth+

Billing /api/v1/billing

Method	Path	Description	Auth	Plan
GET	/billing/plans	List plans + pricing	None	—
POST	/billing/checkout	Create Stripe Checkout session	JWT (owner)	Any
POST	/billing/portal	Create Stripe Portal session	JWT (owner)	Any
GET	/billing/overview	Subscription + usage	JWT	Any
GET	/billing/status	Subscription status	JWT	Any
GET	/billing/usage	Usage vs limits	JWT	Any
GET	/billing/preview-change	Preview plan change proration	JWT (owner)	Any
POST	/billing/change-plan	Change subscription plan	JWT (owner)	Any
POST	/billing/cancel	Cancel subscription	JWT (owner)	Any
POST	/billing/reactivate	Undo pending cancellation	JWT (owner)	Any
POST	/billing/webhook	Stripe webhook receiver	Stripe sig	—

External API /api/v1

Method	Path	Description	Auth	Plan
GET	/api-keys	List API keys (metadata only)	JWT (manager+)	Growth+
POST	/api-keys	Create API key (shown once)	JWT (manager+)	Growth+
GET	/api-keys/usage	API key usage stats	JWT (manager+)	Growth+
DELETE	/api-keys/:key_id	Revoke API key	JWT (manager+)	Growth+
GET	/webhooks	List webhook endpoints	JWT (manager+)	Growth+
POST	/webhooks	Register webhook endpoint	JWT (manager+)	Growth+
DELETE	/webhooks/:id	Remove webhook	JWT (manager+)	Growth+
GET	/external/query	Query via API key	API key	Growth+
GET	/external/knowledge	List entries via API key	API key	Growth+

Webhook events: knowledge.created, knowledge.updated, knowledge.deleted, member.invited, member.removed, query.asked

Module Documentation

Each module doc covers request/response schemas, error codes, and curl examples.

Module	File
Auth	auth.md
Organizations	organizations.md
Knowledge	knowledge.md
Query	query.md
Capture — Voice	capture-voice.md
Capture — Documents	capture-documents.md
Capture — Manual	capture-manual.md
Capture — Interviews	capture-interviews.md
Integrations	integrations.md
Analytics	analytics.md
Dashboard	dashboard.md
Graph	graph.md
Billing	billing.md
External API	external-api.md