API Reference

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
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
}

---

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

Currently, there is no rate limiting in development mode. Production deployments should implement rate limiting at the infrastructure level (e.g., nginx, API gateway).

Next Steps

• Authentication - How to authenticate
• Development - Development workflow