Start a taxonomy run

POST/v1/taxonomy/runs

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.

Body ParametersExpand Collapse

tenant_id: string

minLength1

maxLength255

actor_id: optional string

Optional identifier of the actor starting the run.

minLength1

maxLength255

field_id: optional string

Required for field scope; omit for directory scope.

minLength1

maxLength255

field_label: optional string

Optional human-readable field label.

scope_type: optional "field" or "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.

Accepts one of the following:

"field"

"directory"

source_id: optional string

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

maxLength255

source_type: optional string

Required for field scope; omit for directory scope.

minLength1

maxLength255

ReturnsExpand Collapse

in_progress: boolean

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

run: Run { id, cluster_count, created_at, 17 more }

A persisted taxonomy generation run.

id: string

formatuuid

cluster_count: number

formatint64

created_at: string

formatdate-time

embedding_count: number

formatint64

field_id: string

node_count: number

formatint64

record_count: number

formatint64

scope_type: "field" or "directory"

Accepts one of the following:

"field"

"directory"

source_id: string

Empty string is the canonical "no source" bucket.

source_type: string

status: "pending" or "running" or "succeeded" or 2 more

Lifecycle state of a taxonomy run. Allowed transitions are pending -> running|failed|canceled and running -> succeeded|failed|canceled.

Accepts one of the following:

"pending"

"running"

"succeeded"

"failed"

"canceled"

tenant_id: string

updated_at: string

formatdate-time

error: optional string

Sanitized failure message; present on failed runs.

error_code: optional "insufficient_data" or "service_unavailable" or "generation_failed" or 2 more

Machine-readable reason a taxonomy run failed or a prerequisite was not met.

Accepts one of the following:

"insufficient_data"

"service_unavailable"

"generation_failed"

"invalid_output"

"internal_error"

field_label: optional string

Human-readable field label; absent when unknown.

finished_at: optional string

formatdate-time

metrics: optional map[unknown]

Opaque run metrics recorded by the taxonomy service.

params: optional map[unknown]

Opaque run parameters recorded by Hub.

started_at: optional string

formatdate-time

Start a taxonomy run

curl http://localhost:8080/v1/taxonomy/runs \
    -H 'Content-Type: application/json' \
    -H "Authorization: Bearer $HUB_API_KEY" \
    -d '{
          "tenant_id": "org-123"
        }'

{
  "in_progress": true,
  "run": {
    "id": "182bd5e5-6e1a-4fe4-a799-aa6d9a6ab26e",
    "cluster_count": 0,
    "created_at": "2019-12-27T18:11:19.117Z",
    "embedding_count": 0,
    "field_id": "field_id",
    "node_count": 0,
    "record_count": 0,
    "scope_type": "field",
    "source_id": "source_id",
    "source_type": "source_type",
    "status": "pending",
    "tenant_id": "tenant_id",
    "updated_at": "2019-12-27T18:11:19.117Z",
    "error": "error",
    "error_code": "insufficient_data",
    "field_label": "field_label",
    "finished_at": "2019-12-27T18:11:19.117Z",
    "metrics": {
      "foo": "bar"
    },
    "params": {
      "foo": "bar"
    },
    "started_at": "2019-12-27T18:11:19.117Z"
  }
}

Returns Examples

{
  "in_progress": true,
  "run": {
    "id": "182bd5e5-6e1a-4fe4-a799-aa6d9a6ab26e",
    "cluster_count": 0,
    "created_at": "2019-12-27T18:11:19.117Z",
    "embedding_count": 0,
    "field_id": "field_id",
    "node_count": 0,
    "record_count": 0,
    "scope_type": "field",
    "source_id": "source_id",
    "source_type": "source_type",
    "status": "pending",
    "tenant_id": "tenant_id",
    "updated_at": "2019-12-27T18:11:19.117Z",
    "error": "error",
    "error_code": "insufficient_data",
    "field_label": "field_label",
    "finished_at": "2019-12-27T18:11:19.117Z",
    "metrics": {
      "foo": "bar"
    },
    "params": {
      "foo": "bar"
    },
    "started_at": "2019-12-27T18:11:19.117Z"
  }
}