API Reference

The OntoKit API is a RESTful JSON API. Interactive documentation is available at:

Swagger UI: http://localhost:8000/docs
ReDoc: http://localhost:8000/redoc

Base URL

http://localhost:8000/api/v1

Authentication

Most endpoints require authentication via Bearer token:

curl -H "Authorization: Bearer <access_token>" \
  http://localhost:8000/api/v1/projects

See Authentication for details on obtaining tokens.

Common Response Codes

Code	Description
200	Success
201	Created
204	No Content (successful deletion)
400	Bad Request (validation error)
401	Unauthorized (missing/invalid token)
403	Forbidden (insufficient permissions)
404	Not Found
429	Too Many Requests (rate limited, includes `Retry-After` header)
500	Internal Server Error

Health Check

GET /health

Check if the API is running.

Response:

{
  "status": "healthy"
}

Projects

List Projects

GET /api/v1/projects

List projects accessible to the current user.

Query Parameters:

Parameter	Type	Default	Description
`skip`	int	0	Pagination offset
`limit`	int	20	Max results (1-100)
`filter`	string	null	Filter: `public`, `mine`, or null for all accessible

Response:

{
  "items": [
    {
      "id": "uuid",
      "name": "Project Name",
      "description": "Optional description",
      "is_public": true,
      "owner_id": "user-id",
      "owner": {
        "id": "user-id",
        "name": "User Name",
        "email": "user@example.com"
      },
      "created_at": "2024-01-01T00:00:00Z",
      "updated_at": "2024-01-02T00:00:00Z",
      "member_count": 3,
      "user_role": "owner"
    }
  ],
  "total": 1,
  "skip": 0,
  "limit": 20
}

Create Project

POST /api/v1/projects

Create a new project. Requires authentication.

Request Body:

{
  "name": "My Project",
  "description": "Optional description",
  "is_public": false
}

Response: 201 Created with the created project.

Get Project

GET /api/v1/projects/{project_id}

Get a project by ID.

Response: Project object or 403 if private and user lacks access.

Update Project

PATCH /api/v1/projects/{project_id}

Update project settings. Requires owner or admin role.

Request Body:

{
  "name": "New Name",
  "description": "New description",
  "is_public": true
}

All fields are optional.

Delete Project

DELETE /api/v1/projects/{project_id}

Delete a project. Requires owner role.

Response: 204 No Content

Project Members

List Members

GET /api/v1/projects/{project_id}/members

List members of a project. Requires membership.

Response:

{
  "items": [
    {
      "id": "uuid",
      "project_id": "uuid",
      "user_id": "user-id",
      "role": "owner",
      "user": {
        "id": "user-id",
        "name": "User Name",
        "email": "user@example.com"
      },
      "created_at": "2024-01-01T00:00:00Z"
    }
  ],
  "total": 1
}

Add Member

POST /api/v1/projects/{project_id}/members

Add a member to a project. Requires owner or admin role.

Request Body:

{
  "user_id": "user-id-to-add",
  "role": "editor"
}

Roles: admin, editor, viewer (cannot add as owner)

Update Member Role

PATCH /api/v1/projects/{project_id}/members/{user_id}

Update a member's role. Requires owner or admin role.

Request Body:

{
  "role": "admin"
}

Remove Member

DELETE /api/v1/projects/{project_id}/members/{user_id}

Remove a member from a project. Owner/admin can remove others; users can remove themselves.

Response: 204 No Content

Authentication Endpoints

Request Device Code

POST /api/v1/auth/device/code

Start the OAuth2 Device Authorization flow.

Request Body:

{
  "client_id": "your-client-id"
}

Response:

{
  "device_code": "...",
  "user_code": "ABCD-1234",
  "verification_uri": "http://localhost:8080/device",
  "expires_in": 600,
  "interval": 5
}

Poll for Token

POST /api/v1/auth/device/token

Poll for the access token after user authorization.

Request Body:

{
  "client_id": "your-client-id",
  "device_code": "..."
}

Response (success):

{
  "access_token": "...",
  "token_type": "Bearer",
  "expires_in": 3600,
  "refresh_token": "..."
}

Response (pending):

{
  "error": "authorization_pending"
}

Refresh Token

POST /api/v1/auth/token/refresh?refresh_token={token}

Refresh an access token.

Ontologies

Note: Ontology endpoints are currently in development.

List Ontologies

GET /api/v1/ontologies

Create Ontology

POST /api/v1/ontologies

Get Ontology

GET /api/v1/ontologies/{ontology_id}

Supports content negotiation via Accept header:

text/turtle (default)
application/rdf+xml
application/ld+json

Update Ontology

PUT /api/v1/ontologies/{ontology_id}

Delete Ontology

DELETE /api/v1/ontologies/{ontology_id}

Import Ontology

POST /api/v1/ontologies/{ontology_id}/import

Upload an ontology file (multipart form data).

Export Ontology

GET /api/v1/ontologies/{ontology_id}/export?format=turtle

Search

Full-Text Search

GET /api/v1/search?q={query}

SPARQL Query

POST /api/v1/search/sparql

Request Body:

{
  "query": "SELECT ?s ?p ?o WHERE { ?s ?p ?o } LIMIT 10",
  "timeout": 30
}

Suggestions

The suggestion workflow allows users (especially those with the suggester role) to make ontology edits in isolated branches that require review before merging.

Create Session

POST /api/v1/projects/{project_id}/suggestions/sessions

Create a new suggestion session with a dedicated branch. Requires authentication.

Response: 201 Created with session details including session ID and beacon token.

Save to Session

PUT /api/v1/projects/{project_id}/suggestions/sessions/{session_id}/save

Save ontology content to a suggestion session's branch. Requires authentication.

Submit Session

POST /api/v1/projects/{project_id}/suggestions/sessions/{session_id}/submit

Submit a suggestion session, creating a pull request for review. Requires authentication.

List My Sessions

GET /api/v1/projects/{project_id}/suggestions/sessions

List the current user's suggestion sessions for a project. Requires authentication.

Discard Session

POST /api/v1/projects/{project_id}/suggestions/sessions/{session_id}/discard

Discard a suggestion session and delete its branch. Requires authentication.

Response: 204 No Content

Beacon Save

POST /api/v1/projects/{project_id}/suggestions/beacon?token={beacon_token}

Handle a sendBeacon flush with token-based authentication (no Authorization header needed). Used for saving edits when the browser tab is closing.

List Pending (Review)

GET /api/v1/projects/{project_id}/suggestions/pending

List pending suggestion sessions awaiting review. Requires editor/admin/owner role.

Approve Session

POST /api/v1/projects/{project_id}/suggestions/sessions/{session_id}/approve

Approve a suggestion session and merge its PR. Requires editor/admin/owner role.

Response: 204 No Content

Reject Session

POST /api/v1/projects/{project_id}/suggestions/sessions/{session_id}/reject

Reject a suggestion session with a reason. Requires editor/admin/owner role.

Request Body:

{
  "reason": "Explanation for rejection"
}

Request Changes

POST /api/v1/projects/{project_id}/suggestions/sessions/{session_id}/request-changes

Request changes on a suggestion session with feedback. Requires editor/admin/owner role.

Resubmit Session

POST /api/v1/projects/{project_id}/suggestions/sessions/{session_id}/resubmit

Resubmit a suggestion session after addressing requested changes. Requires authentication (original suggester).

Semantic Search

Vector-based semantic search using entity embeddings. Requires embedding generation to be configured and run first (see #Embeddings).

Search by Text

GET /api/v1/projects/{project_id}/search/semantic?q={query}

Search entities using semantic similarity.

Query Parameters:

Parameter	Type	Default	Description
`q`	string	(required)	Search query
`branch`	string	null	Branch to search (defaults to project default)
`limit`	int	20	Max results
`threshold`	float	0.3	Minimum similarity score

Find Similar Entities

GET /api/v1/projects/{project_id}/entities/{iri}/similar

Find entities semantically similar to a given entity.

Query Parameters:

Parameter	Type	Default	Description
`branch`	string	null	Branch to search
`limit`	int	10	Max results
`threshold`	float	0.5	Minimum similarity score

Rank Suggestions

POST /api/v1/projects/{project_id}/entities/rank-suggestions

Rank candidate entities by similarity to a context entity. Requires authentication.

Embeddings

Configure and manage vector embeddings for semantic search and duplicate detection.

Get Embedding Config

GET /api/v1/projects/{project_id}/embeddings/config

Get embedding configuration for a project. Requires authentication.

Update Embedding Config

PUT /api/v1/projects/{project_id}/embeddings/config

Update embedding provider and model configuration. Requires authentication.

Supported providers: local (sentence-transformers), openai, voyage.

Generate Embeddings

POST /api/v1/projects/{project_id}/embeddings/generate

Trigger background embedding generation for all entities. Requires authentication.

Query Parameters:

Parameter	Type	Default	Description
`branch`	string	null	Branch to embed (defaults to project default)

Response: 202 Accepted with job ID for polling.

Get Embedding Status

GET /api/v1/projects/{project_id}/embeddings/status

Get embedding generation status and coverage percentage. Requires authentication.

Clear Embeddings

DELETE /api/v1/projects/{project_id}/embeddings

Clear all embeddings for a project. Requires authentication.

Response: 204 No Content

Quality

Ontology quality analysis tools including consistency checks, duplicate detection, and cross-reference analysis.

Get Entity Cross-References

GET /api/v1/projects/{project_id}/entities/{iri}/references

Get all cross-references to a specific entity (where it is used as an object).

Query Parameters:

Parameter	Type	Default	Description
`branch`	string	null	Branch to analyze

Trigger Consistency Check

POST /api/v1/projects/{project_id}/quality/check

Run consistency checks and cache the result. Requires authentication.

Query Parameters:

Parameter	Type	Default	Description
`branch`	string	null	Branch to check

Get Quality Job Result

GET /api/v1/projects/{project_id}/quality/jobs/{job_id}

Get consistency check results by job ID.

Get Cached Consistency Issues

GET /api/v1/projects/{project_id}/quality/issues

Get cached consistency check results (from last run).

Detect Duplicates

POST /api/v1/projects/{project_id}/quality/duplicates

Detect duplicate entities based on label similarity (uses embeddings if available). Requires authentication.

Query Parameters:

Parameter	Type	Default	Description
`branch`	string	null	Branch to check
`threshold`	float	0.85	Minimum similarity threshold

Analytics

Project activity tracking and contributor statistics.

Project Activity

GET /api/v1/projects/{project_id}/analytics/activity

Get project activity over time (commits, edits, etc.).

Query Parameters:

Parameter	Type	Default	Description
`days`	int	30	Number of days of history

Entity History

GET /api/v1/projects/{project_id}/analytics/entity/{iri}/history

Get change history for a specific entity.

Query Parameters:

Parameter	Type	Default	Description
`branch`	string	null	Branch to check
`limit`	int	50	Max results

Hot Entities

GET /api/v1/projects/{project_id}/analytics/hot-entities

Get most frequently edited entities in the last 30 days.

Query Parameters:

Parameter	Type	Default	Description
`limit`	int	20	Max results

Contributors

GET /api/v1/projects/{project_id}/analytics/contributors

Get contributor statistics for a project.

Query Parameters:

Parameter	Type	Default	Description
`days`	int	30	Number of days of history

Normalization

Ontology normalization checks and applies formatting/structural improvements to ontology files.

Get Normalization Status

GET /api/v1/projects/{project_id}/normalization/status

Get cached normalization status (no expensive re-check).

Refresh Normalization Status

POST /api/v1/projects/{project_id}/normalization/refresh

Queue a background job to re-check normalization status.

Response: 202 Accepted with job ID.

Run Normalization

POST /api/v1/projects/{project_id}/normalization

Apply normalization to the project ontology. Requires authentication.

Request Body:

{
  "dry_run": true,
  "branch": null
}

Set dry_run to true to preview changes without applying them.

Queue Normalization Job

POST /api/v1/projects/{project_id}/normalization/queue

Queue normalization as a background job (for large ontologies). Requires authentication.

Response: 202 Accepted with job ID.

Get Job Status

GET /api/v1/projects/{project_id}/normalization/jobs/{job_id}

Get status of a normalization background job.

List Recent Jobs

GET /api/v1/projects/{project_id}/normalization/jobs

List recent normalization jobs for a project.

Get Normalization History

GET /api/v1/projects/{project_id}/normalization/history

Get normalization run history with reports.

Query Parameters:

Parameter	Type	Default	Description
`limit`	int	10	Max results
`include_dry_runs`	bool	false	Include dry-run results

Get Normalization Run

GET /api/v1/projects/{project_id}/normalization/runs/{run_id}

Get details of a specific normalization run.

Notifications

User notification system for project activity (PR reviews, join requests, etc.).

List Notifications

GET /api/v1/notifications

List notifications for the current user. Requires authentication.

Query Parameters:

Parameter	Type	Default	Description
`unread_only`	bool	false	Only return unread notifications

Mark Notification Read

POST /api/v1/notifications/{notification_id}/read

Mark a single notification as read. Requires authentication.

Response: 204 No Content

Mark All Read

POST /api/v1/notifications/read-all

Mark all notifications as read. Requires authentication.

Response: 204 No Content

Upstream Sync

Synchronize project ontologies with upstream GitHub repositories.

Get Sync Config

GET /api/v1/projects/{project_id}/upstream-sync

Get upstream sync configuration. Returns null if none exists. Requires authentication.

Save Sync Config

PUT /api/v1/projects/{project_id}/upstream-sync

Create or update upstream sync configuration (PUT upsert). Requires authentication.

Delete Sync Config

DELETE /api/v1/projects/{project_id}/upstream-sync

Remove upstream sync configuration. Requires authentication.

Response: 204 No Content

Trigger Sync Check

POST /api/v1/projects/{project_id}/upstream-sync/check

Trigger a manual upstream sync check (enqueues background job). Requires authentication.

Response: 202 Accepted with job ID.

Get Sync Job Status

GET /api/v1/projects/{project_id}/upstream-sync/jobs/{job_id}

Get status of a background upstream check job. Requires authentication.

Get Sync History

GET /api/v1/projects/{project_id}/upstream-sync/history

Get sync event history for a project. Requires authentication.

Query Parameters:

Parameter	Type	Default	Description
`limit`	int	20	Max results

Join Requests

Users can request to join public projects they don't have access to.

Get Pending Summary

GET /api/v1/projects/join-requests/pending-summary

Get a summary of pending join requests across all projects the user manages. Requires authentication.

Create Join Request

POST /api/v1/projects/{project_id}/join-requests

Submit a request to join a public project. Requires authentication.

Response: 201 Created

Get My Join Request

GET /api/v1/projects/{project_id}/join-requests/mine

Check the current user's join request status for a project. Requires authentication.

List Join Requests

GET /api/v1/projects/{project_id}/join-requests

List join requests for a project. Requires admin/owner role.

Query Parameters:

Parameter	Type	Default	Description
`status_filter`	string	null	Filter by status

Approve Join Request

POST /api/v1/projects/{project_id}/join-requests/{request_id}/approve

Approve a join request. Requires admin/owner role.

Decline Join Request

POST /api/v1/projects/{project_id}/join-requests/{request_id}/decline

Decline a join request. Requires admin/owner role.

Withdraw Join Request

DELETE /api/v1/projects/{project_id}/join-requests/{request_id}

Withdraw a pending join request (requester only). Requires authentication.

Response: 204 No Content

User Settings

User-level settings and GitHub token management.

Get GitHub Token Status

GET /api/v1/users/me/github-token

Check if the authenticated user has a stored GitHub token. Requires authentication.

Save GitHub Token

POST /api/v1/users/me/github-token

Validate and store an encrypted GitHub Personal Access Token. Requires authentication.

Response: 201 Created

Delete GitHub Token

DELETE /api/v1/users/me/github-token

Remove stored GitHub token. Requires authentication.

Response: 204 No Content

List GitHub Repos

GET /api/v1/users/me/github-repos

List GitHub repos accessible to the user's stored PAT. Requires authentication.

Query Parameters:

Parameter	Type	Default	Description
`q`	string	null	Search filter
`page`	int	1	Page number
`per_page`	int	30	Results per page

Search Users

GET /api/v1/users/search?q={query}

Search Zitadel users by username, email, or name (for member autocomplete). Requires authentication.

Query Parameters:

Parameter	Type	Default	Description
`q`	string	(required)	Search query
`limit`	int	10	Max results

Error Responses

All errors follow this format:

{
  "detail": "Error message describing what went wrong"
}

For validation errors:

{
  "detail": [
    {
      "loc": ["body", "name"],
      "msg": "field required",
      "type": "value_error.missing"
    }
  ]
}

Rate Limiting

The API includes built-in rate limiting via slowapi. Rate-limited responses return 429 Too Many Requests with a Retry-After header indicating when to retry.