## Start

**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 Parameters

- `tenant_id: string`

- `actor_id: optional string`

  Optional identifier of the actor starting the run.

- `field_id: optional string`

  Required for field scope; omit for directory scope.

- `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.

  - `"field"`

  - `"directory"`

- `source_id: optional string`

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

- `source_type: optional string`

  Required for field scope; omit for directory scope.

### Returns

- `in_progress: boolean`

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

- `run: Run`

  A persisted taxonomy generation run.

  - `id: string`

  - `cluster_count: number`

  - `created_at: string`

  - `embedding_count: number`

  - `field_id: string`

  - `node_count: number`

  - `record_count: number`

  - `scope_type: "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.

    - `"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.

    - `"pending"`

    - `"running"`

    - `"succeeded"`

    - `"failed"`

    - `"canceled"`

  - `tenant_id: string`

  - `updated_at: string`

  - `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.

    - `"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`

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

### Example

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