v28

latestOpenAPI 3.1.0Apache-2.0raw.githubusercontent.com2026-07-082940159.9 KB
Taxonomy

Start a taxonomy run

Starts a manual taxonomy generation run for a field or directory scope. Hub validates that the scope has enough embedded text feedback (below the configured minimum returns 400 with an "insufficient data" validation error), creates the run, and hands it to the taxonomy compute service. Omit scope_type for the existing field scope behavior; use scope_type=directory with tenant_id only to generate one taxonomy over all text feedback in the directory.

Idempotent per scope: if a run is already pending or running for the same scope, the existing run is returned with in_progress: true (HTTP 200) instead of starting a new one; a newly created run returns HTTP 202 with in_progress: false. While a tenant data purge runs for the same tenant_id, the request is rejected with HTTP 409 (code tenant_write_conflict) and may be retried. Requires Hub embeddings and the taxonomy service to be configured; otherwise returns 503.

post/v1/taxonomy/runs

Request body

scope_type'field' | 'directory'

Taxonomy input scope. field covers one (source_type, source_id, field_id) field scope. directory covers all text feedback records for the tenant/directory and must not include source_type, source_id, or field_id.

tenant_idstring required
source_typestring

Required for field scope; omit for directory scope.

source_idstring

Optional for field scope; empty or omitted is the canonical "no source" bucket. Omit for directory scope.

field_idstring

Required for field scope; omit for directory scope.

field_labelstring

Optional human-readable field label.

actor_idstring

Optional identifier of the actor starting the run.

Response

A run for this scope is already in progress; the existing run is returned.

in_progressboolean required

True when an existing pending/running run for the scope was returned instead of starting a new one.