Skip to main content

​
Overview

ondoki exposes a REST API at /api/v1/ built with FastAPI. Interactive documentation is available when the server is running:
  • Swagger UI: http://your-server:8000/docs
  • OpenAPI JSON: http://your-server:8000/openapi.json

​
Authentication

Most API endpoints require authentication. ondoki supports three auth methods:
MethodUse CaseHeader
Session cookieWeb browser (set via /auth/login)Automatic (cookie)
Bearer tokenDesktop app, CLIAuthorization: Bearer <access_token>
API keyMCP server, external integrationsAuthorization: Bearer ondoki_<key>

​
Login

curl -X POST https://your-server/api/v1/auth/login \
  -H "Content-Type: application/json" \
  -d '{"email": "[email protected]", "password": "your-password"}'
Returns user info and sets a session cookie.

​
OAuth 2.0 PKCE (Desktop)

For desktop and CLI clients, use the PKCE flow:
  1. GET /api/v1/auth/authorize?response_type=code&code_challenge=<challenge>&redirect_uri=<uri>
  2. User authenticates in browser
  3. POST /api/v1/auth/token with authorization code and code verifier
  4. Returns access_token and refresh_token

​
Key Endpoint Groups

​
Documents

MethodEndpointDescription
GET/documents/filteredList documents with filtering and sorting
POST/documents/Create a new document
GET/documents/{id}Get document details
PUT/documents/{id}Update document content
DELETE/documents/{id}Soft delete
POST/documents/{id}/shareGenerate public share link
POST/documents/{id}/duplicateDuplicate document
PUT/documents/{id}/moveMove to folder

​
Workflows (Process Recording)

MethodEndpointDescription
POST/process-recording/session/createCreate upload session
POST/process-recording/session/{id}/metadataUpload metadata
POST/process-recording/session/{id}/imageUpload step screenshot
POST/process-recording/session/{id}/finalizeFinalize workflow
GET/process-recording/workflows/filteredList with filtering
GET/process-recording/{id}/exportExport as PDF/Markdown
POST/process-recording/steps/{id}/annotateAI-annotate a step
MethodEndpointDescription
GET/search/unified-v2Hybrid search (FTS + semantic)
Query parameters: q (query), project_id, limit

​
AI / Chat

MethodEndpointDescription
POST/chat/chat/completionsLLM chat (streaming via SSE)
POST/chat/inlineInline AI editor commands
GET/chat/modelsList available models
GET/chat/configCurrent LLM configuration

​
Projects

MethodEndpointDescription
POST/projects/Create project
GET/projects/{user_id}List user’s projects
PUT/projects/{id}Update project
DELETE/projects/{id}Delete project (owner only)
POST/projects/{id}/membersAdd member
PUT/projects/{id}/members/{user_id}Update role
DELETE/projects/{id}/members/{user_id}Remove member

​
Folders

MethodEndpointDescription
GET/folders/List folders
POST/folders/Create folder
PUT/folders/{id}Update folder
DELETE/folders/{id}Delete folder
GET/folders/{id}/treeGet folder tree

​
Knowledge Base

MethodEndpointDescription
POST/knowledge/uploadUpload knowledge file
GET/knowledge/sourcesList knowledge sources
DELETE/knowledge/sources/{id}Delete knowledge source

​
Sharing

MethodEndpointDescription
POST/shared/shareShare resource with user
GET/shared/sharesList received shares
DELETE/shared/shares/{id}Revoke share

​
Audit Log

MethodEndpointDescription
GET/audit/logsQuery audit logs
GET/audit/logs/exportExport as CSV

​
Analytics

MethodEndpointDescription
GET/analytics/top-accessedMost viewed resources
GET/analytics/access-by-channelUsage by channel
GET/analytics/staleUnused resources
GET/analytics/queriesRecent searches
GET/analytics/gapsKnowledge gaps

​
Video Import

MethodEndpointDescription
POST/video-import/uploadUpload video file
GET/video-import/status/{session_id}Processing status
GET/video-import/jobs/{job_id}Job status

​
Git Sync

MethodEndpointDescription
GET/git-sync/{project_id}Get config
PUT/git-sync/{project_id}Set/update config
DELETE/git-sync/{project_id}Remove config
POST/git-sync/{project_id}/exportTrigger export

​
MCP Keys

MethodEndpointDescription
GET/mcp/projects/{id}/mcp-keysList API keys
POST/mcp/projects/{id}/mcp-keysCreate API key
DELETE/mcp/projects/{id}/mcp-keys/{key_id}Revoke key

​
Health

MethodEndpointDescription
GET/healthHealth check
GET/readyReadiness check (DB connectivity)

​
Error Format

API errors return JSON: 
{
  "detail": "Error message describing what went wrong"
}
HTTP status codes follow standard conventions:
CodeMeaning
200Success
201Created
400Bad request
401Unauthorized
403Forbidden
404Not found
422Validation error
429Rate limited
500Internal server error

​
Rate Limiting

The chat endpoint (/chat/chat/completions) is rate-limited to prevent abuse. Other endpoints are not rate-limited by default but can be limited at the reverse proxy level.