Advanced Usage

This page covers API-first workflows and power-user features.

Notebook examples

The repository includes notebook examples:

notebook_docs/API_Examples.ipynb
notebook_docs/Processing_Annotations.ipynb

These are useful for bulk project creation, export processing, and automation.

REST API basics

Base path: /api/

Common endpoints:

GET/POST /api/project-annotate-entities/
GET/POST /api/datasets/
GET/POST /api/modelpacks/
GET/POST /api/concept-dbs/
GET/POST /api/vocabs/

Authentication

Local auth token: POST /api/api-token-auth/
OIDC bearer token (if enabled): send Authorization: Bearer <token>

Project Admin API endpoints

Modern project-admin UI uses dedicated endpoints:

GET /api/project-admin/projects/
POST /api/project-admin/projects/create/
GET/PUT/DELETE /api/project-admin/projects/<project_id>/
POST /api/project-admin/projects/<project_id>/clone/
POST /api/project-admin/projects/<project_id>/reset/

Metrics APIs

GET/POST /api/metrics-job/ (list jobs / submit new report)
DELETE /api/metrics-job/<report_id>/ (remove report job)
GET/PUT /api/metrics/<report_id>/ (fetch report / rename report)

Only compatible projects should be combined (same underlying model configuration) when generating reports.

Concept exploration and filter export

Use the Concepts view (/model-explore) to:

browse hierarchy paths,
choose parent concepts,
generate and export JSON filter lists for project CUI filters.

Related API endpoints:

POST /api/generate-concept-filter/
POST /api/generate-concept-filter-json/
GET /api/model-concept-children/<cdb_id>/

Remote model service projects

Projects can use a remote MedCAT model service instead of local model loading by setting:

use_model_service = true
model_service_url = <service-base-url>

Operational note: train-on-submit updates are not applied for remote model service projects.

Python client

For scripting and CI pipelines, see client.md and the mctclient package.