---
title: "Deterministic CFIHOS classification of a single legend entry"
method: POST
path: "/api/v0/semantic-catalog/classify-legend-entry"
tags: ["semantic-catalog"]
---

# Deterministic CFIHOS classification of a single legend entry

`POST /api/v0/semantic-catalog/classify-legend-entry`

Returns the entry with ``cfihos_*`` fields populated using the deterministic seed map + ISA-5.1 parser + catalog name search. Stateless; no DB hit. Frontend uses this during legend auto-populate and after a user edits an entry's name.

## Request body

- ClassifyLegendRequest — Same shape as LegendEntry; we also accept a ``transcription`` hint for ISA-letter classification of instrument-tag entries.
  - `id` string, required
  - `name` string, required
  - `class` string, required
  - `subtype` string, nullable
  - `source_bbox` BoundingBox
    - `x0` integer, required
    - `y0` integer, required
    - `x1` integer, required
    - `y1` integer, required
    - `dpi` integer
    - `class_name` string, nullable
    - `text` string, nullable
    - `confidence` number, nullable
  - `source_node_id` string, nullable
  - `source_crop_url` string, nullable
  - `confidence` number
  - `cfihos_tag_class_code` string, nullable
  - `cfihos_equipment_class_code` string, nullable
  - `cfihos_version` string, nullable
  - `cfihos_source` 'deterministic_map' | 'name_match' | 'isa_letter_code' | 'llm' | 'template_applied' | 'user_pinned', nullable
  - `cfihos_confidence` number, nullable
  - `transcription` string, nullable

## Response `200`

Successful Response

- LegendEntry — One row in a document's Legend. ``entry_class`` / ``subtype`` are the canonical pair the entry maps to — same vocabulary the registry uses for nodes and annotations, so a display-layer lookup can match by equality without a second translation step. ``source_bbox`` and ``source_node_id`` are optional provenance: when set, they record the symbol the user picked when creating the entry (so the UI can render a thumbnail and re-focus on the seeding detection). Entries built from an uploaded legend image or from a template library leave ``source_node_id`` empty. The ``cfihos_*`` fields link the entry to CFIHOS reference data. All are optional — a legend works without them — but when set they drive the Semantic Object modal, the enriched Excel export columns, and downstream interop exports (ISO 15926, POSC CAESAR equivalents via the catalog mapping). ``source_crop_url`` is the renderable URL for the entry's representative crop, for entries that have no page-image coordinate frame to crop in — i.e. those built from an uploaded legend image. The remap pipeline's ``build_templates`` prefers this when set, since ``source_bbox`` indexes into the page image (the wrong coordinate system for an uploaded crop). Pick-from-drawing entries leave it unset and rely on ``source_bbox`` instead. The field holds either a ``data:image/png;base64,...`` URL (produced by the pure extractor for use in tests / scripts) or an ``http(s)://...`` storage URL (produced by the Hyrex task after it uploads the crop to ``users/{user}/{doc}/legend_crops/ {entry_id}.png``). Both render in ``<img src>`` and both decode cleanly in ``build_templates``; the task swaps from data URL to storage URL before persisting so grounding_data stays lean.
  - `id` string, required
  - `name` string, required
  - `class` string, required
  - `subtype` string, nullable
  - `source_bbox` BoundingBox
    - `x0` integer, required
    - `y0` integer, required
    - `x1` integer, required
    - `y1` integer, required
    - `dpi` integer
    - `class_name` string, nullable
    - `text` string, nullable
    - `confidence` number, nullable
  - `source_node_id` string, nullable
  - `source_crop_url` string, nullable
  - `confidence` number
  - `cfihos_tag_class_code` string, nullable
  - `cfihos_equipment_class_code` string, nullable
  - `cfihos_version` string, nullable
  - `cfihos_source` 'deterministic_map' | 'name_match' | 'isa_letter_code' | 'llm' | 'template_applied' | 'user_pinned', nullable
  - `cfihos_confidence` number, nullable

## Other responses

- `422` — Validation Error

---

[API](https://skmtc.dev/outerport/apis/outerport-api.md) · [All operations](https://skmtc.dev/outerport/apis/outerport-api/llms.txt) · [OpenAPI document](https://skmtc-service-production.skmtc.workers.dev/v1/apis/outerport/outerport-api/revisions/f565b46daaea/schema)