Tagging API

Retrend’s tagging API lets you run AI classification to assign broadtype and subtype to products, then review and apply results in batches. The flow:

1. Check coverage and in-flight work with /v2/tagging/status.
2. List batches or drill into a batch to review items.
3. Apply or reject a batch (optionally limit to specific product IDs); cancel if you need to stop a run.

All endpoints require organization-id and x-session headers. Include kiosk headers when calling from kiosk clients.

Status overview

GET /v2/tagging/status

Returns aggregate metrics:

• percent_broadtyped, percent_subtyped (0–100)
• open_candidates_count (products missing subtype)
• in_progress_batches_count

Use this for dashboards and to decide whether to queue more tagging.

Batch list and detail

• GET /v2/tagging/batches?q=gin&run_type=broadtype&status=active&page=1&page_size=20
• GET /v2/tagging/batches/{batch_id}

List returns items of BatchListItem with states (is_ready, is_active, is_done), counts, timestamps, and run_type (broadtype, subtype, or recipe). next_page is provided when more results exist.

Detail returns richer state (is_ready, is_active, is_done), timestamps (created_at, active_at, done_at), items_count, run_type, and optional ai_batch_id.

Batch items

GET /v2/tagging/batches/{batch_id}/items?page=1&page_size=50

Returns items: each has id, optional pid, and proposed assignment text. Use this to render review UIs. next_page is provided when more items exist.

Approvals and transitions

Apply

POST /v2/tagging/batches/{batch_id}/apply

Optional body (BatchApplyRequest):

• pids (array of product UUIDs) to apply only a subset; omit to apply all.

Reject

POST /v2/tagging/batches/{batch_id}/reject

Rejects the batch without applying assignments.

Cancel

POST /v2/tagging/batches/{batch_id}/cancel

Stops processing for an in-progress batch.

All three return BatchTransitionResponse with the batch id and new status (applied, rejected, or canceled).

Implementation tips

• Filter by run_type to separate broadtype vs. subtype workstreams.
• Use paging (page, page_size) when previewing items to keep UIs responsive.
• Apply subsets (pids) when you need partial rollout; rerun later for the rest.
• Surface assignment text during human review; after apply, remember to refresh product records to pick up new taxonomy.