Home

OntoKit API

Welcome to the OntoKit API documentation. OntoKit is a collaborative OWL ontology curation platform with real-time editing and Git integration.

Overview

The OntoKit API is a FastAPI-based backend service that provides:

• RESTful API for managing ontologies, classes, properties, and individuals
• Project management with public/private visibility and team collaboration
• Authentication via Zitadel (OpenID Connect) with role-based access control
• Real-time collaboration support via WebSockets
• Suggestion workflow for review-based ontology editing (suggester role)
• Semantic search with configurable embedding providers (local, OpenAI, Voyage)
• Quality analysis — consistency checks, duplicate detection, cross-references
• Analytics — project activity, contributor stats, entity history
• Normalization — automated ontology formatting and structural improvements
• Upstream sync — synchronize with GitHub repositories
• Notifications system for project activity
• Object storage integration with MinIO for ontology files
• Background jobs via ARQ + Redis for long-running operations

Quick Links

• Prerequisites - What you need before starting
• Installation - Step-by-step setup guide
• Configuration - Environment variables reference
• Development - Running the development server
• Database - Database setup and migrations
• Authentication - Zitadel OIDC setup
• API Reference - API endpoints documentation
• Project Structure - Codebase organization
• Versioning and Releases - Version management and release workflow
• Troubleshooting - Common issues and solutions

Tech Stack

Component	Technology
Framework	FastAPI (Python 3.11+)
Database	PostgreSQL 17 + SQLAlchemy 2.0 (async)
Migrations	Alembic
Cache / Queue	Redis + ARQ (background jobs)
Object Storage	MinIO (S3-compatible)
Authentication	Zitadel (OIDC)
Ontology Processing	RDFLib, OWLReady2
Semantic Search	pgvector + sentence-transformers / OpenAI / Voyage
Rate Limiting	slowapi
Package Manager	uv

Deployment Modes

OntoKit supports two deployment configurations:

Mode	Compose File	Best For
Full Docker	compose.yaml	Quick start, CI/CD, testing
Hybrid	compose.prod.yaml	Development with IDE debugging, production

Quick Start (Full Docker)

Everything runs in Docker containers:

# 1. Clone the repository
git clone https://github.com/JohnRDOrazio/ontokit-api.git
cd ontokit-api

# 2. Start all services (including API)
docker compose up -d

# 3. Run database migrations
docker compose exec api alembic upgrade head

# 4. Configure Zitadel authentication (creates OIDC apps, updates .env files)
./scripts/setup-zitadel.sh --update-env

# 5. Recreate API/worker containers to pick up new credentials
docker compose up -d --force-recreate api worker

The API is available at http://localhost:8000 with interactive docs at http://localhost:8000/docs.

Quick Start (Hybrid Mode)

Infrastructure in Docker, API on host for development:

# 1. Clone the repository
git clone https://github.com/JohnRDOrazio/ontokit-api.git
cd ontokit-api

# 2. Start infrastructure services
docker compose -f compose.prod.yaml up -d

# 3. Create Python virtual environment
python -m venv .venv
source .venv/bin/activate  # On Windows: .venv\Scripts\activate

# 4. Install dependencies (requires uv: https://docs.astral.sh/uv/)
make setup

# 5. Configure environment
cp .env.example .env

# 6. Configure Zitadel authentication (creates OIDC apps, updates .env files)
./scripts/setup-zitadel.sh --update-env

# 7. Run database migrations
alembic upgrade head

# 8. Start the development server
uvicorn ontokit.main:app --reload

Service URLs

Service	URL
OntoKit API	http://localhost:8000
API Docs (Swagger)	http://localhost:8000/docs
API Docs (ReDoc)	http://localhost:8000/redoc
Zitadel Console	http://localhost:8080/ui/console
MinIO Console	http://localhost:9001
Mailpit (Email Testing)	http://localhost:8025

Default Zitadel Admin: [email protected] / Admin123!

Related Projects

• ontokit-web - Next.js frontend application
• ontokit-deploy - Production deployment configuration