REST API

SkeinRank currently exposes two HTTP surfaces:

1. the lightweight runtime/server package for local extraction and reranking experiments;
2. the governance API used by the platform beta, console, bindings, jobs, snapshots, and runtime search.

For product-level application integration, start with the API integration guide.

Lightweight server package

The lightweight server package exposes a small HTTP surface for extraction and retrieval experiments:

Method	Path	Purpose
GET	/healthz	Basic health check.
GET	/diagnostics	Diagnostic information for the lightweight server.
POST	/v1/attributes/extract	Extract and canonicalize attributes from text.
POST	/v1/rerank/es	Run an Elasticsearch-oriented reranking flow.

Use this path when you want the smallest API surface around the core package.

Governance API health and observability

The governance API includes health, readiness, metrics, and platform summary endpoints.

Method	Path	Purpose
GET	/livez	Liveness check.
GET	/healthz	Basic API health check.
GET	/readyz	Readiness check for dependencies.
GET	/metrics	Prometheus-compatible metrics when enabled.
GET	/v1/dashboard/summary	Dashboard command-center summary used by the console.
GET	/v1/snapshots/summary	Runtime snapshot audit summary used by the console.

Auth and API access

Method	Path	Purpose
POST	/v1/auth/login	Exchange username/password for a bearer token.
POST	/v1/auth/logout	Revoke the current bearer token.
GET	/v1/auth/me	Return the current user and role.
GET	/v1/auth/api-tokens	List masked personal API tokens for the current user.
POST	/v1/auth/api-tokens	Create a copy-once personal API token.
GET	/v1/auth/service-accounts	List service accounts. Admin role required.
POST	/v1/auth/service-accounts	Create a service account. Admin role required.
POST	/v1/auth/service-accounts/{account_name}/tokens	Create a copy-once service account token. Admin role required.

Runtime search API

These are the endpoints an external application is most likely to call.

Method	Path	Purpose
POST	/v1/text/canonicalize	Canonicalize text using a profile or binding context.
POST	/v1/query/plan	Preview canonical query, matched aliases, and Elasticsearch DSL without executing search.
POST	/v1/search	Execute binding-aware runtime search against Elasticsearch.
POST	/v1/search/multi	Execute search across multiple binding contexts and merge hits.

Recommended production request shape:

{
  "binding_id": 42,
  "query": "k8s pg timeout",
  "size": 10,
  "canonical_boost": 3.0
}

Use the API integration guide for examples and application patterns.

Governance control-plane API

The governance API also exposes control-plane endpoints for console workflows. Common groups include:

Group	Example paths	Purpose
Profiles and terms	/v1/governance/profiles, /v1/governance/profiles/{profile_name}/terms	Manage terminology profiles, canonical terms, and aliases.
Suggestions	/v1/governance/profiles/{profile_name}/suggestions	Create, review, approve, reject, and refresh evidence for suggestions.
Guardrails	/v1/governance/global-stop-list, /v1/governance/profiles/{profile_name}/stop-list	Manage global and profile-scoped stop lists.
Elasticsearch bindings	/v1/governance/elasticsearch/bindings	Create bindings and list runtime search contexts.
Dry-runs and evidence	/v1/governance/elasticsearch/bindings/{binding_id}/dry-run, /v1/governance/elasticsearch/bindings/{binding_id}/evidence	Preview enrichment and collect evidence from indexed documents.
Enrichment jobs	/v1/governance/elasticsearch/bindings/{binding_id}/jobs	Start and operate enrichment jobs for a binding.

Local OpenAPI UI

When the governance API is running locally, FastAPI exposes interactive schema docs:

http://127.0.0.1:8010/docs
http://127.0.0.1:8010/redoc

Use those local pages for exact schemas while the beta API is still evolving. This website keeps the public documentation focused on stable integration patterns and product concepts.