API: Search

Overview

Global Search provides instant, workspace-scoped lookup across all core object types. Search is available via the Spotlight command bar (⌘K / Ctrl+K) and programmatically via the search_brand_objects_v2 RPC.

Search is read-only and respects workspace-level access controls automatically.

What You Can Search For

How Search Behaves

Product Search (Semantic)

Product queries match across multiple fields simultaneously:

• Product name — matches across all configured locales
• SKU — partial match (e.g. GL4 matches GL4-123)
• Description — partial match on product description text
• Attribute values — matches any product attribute value (e.g. china, steel grey)
• GTIN — exact match on 8, 12, 13, or 14-digit identifiers

Results display the product name as the primary label and SKU as the secondary label.

Passport Search (Structural)

Passport queries match against the denormalized search/read model on passport_lifecycle_states:

• Passport ID: Prefix match on the passport lifecycle anchor UUID.
• SKU: Left-anchored prefix match on the denormalized product SKU.
• Batch ID: Exact UUID match against the passport’s mint_batch_id.
• GTIN: Exact match against the denormalized product GTIN.

Passport search is enabled for uuid, gtin, and alnum query routes. Pure alphabetic (alpha) queries do not trigger passport search to avoid unbounded free-text scans.

Results display the product name as the primary label and SKU as the secondary label. Status is shown as Draft, Published, or Revoked.

Passport results navigate to the passport detail page (/passports/{mint_batch_id}).

Identifier Lookup (Structural)

Structured identifiers are routed to the appropriate object type:

• Token serial: Prefix match (minimum 4 characters). Searching 13250d12 finds tokens whose serial starts with that value.
• Batch ID: Prefix match on the batch identifier.
• Export ID: Exact UUID match against export records.
• UUID: Pasting a full UUID searches across products, passports, batches, and exports simultaneously.

GS1 Digital Link / Resolver URL Parsing

When you paste a GS1 Digital Link URL, the system extracts the relevant identifiers automatically:

• If the URL contains a serial (/21/<serial>), the serial is extracted and used to find the matching token.
• If the URL contains only a GTIN (/01/<GTIN>), the GTIN is extracted and used to find the matching product and passport.

Example:

Input:  https://acme.tieback.io/01/5060999100063/21/13250d12
Result: Token matching serial "13250d12"

Input:  https://acme.tieback.io/01/5060999100063
Result: Product matching GTIN "5060999100063" + Passport matching GTIN

The resolver URL itself is not stored or searched as a string — only the extracted identifiers are used.

Query Routing

The system automatically classifies your query and routes it to the appropriate search branches:

Result Navigation

• Product results navigate to the product detail page
• Passport results navigate to the passport detail page
• Token results navigate to the token detail page
• Batch results navigate to the batch detail page
• Export results navigate to the exports view

Response Shape

1
{
2
  "ok": true,
3
  "items": [
4
    {
5
      "type": "product | passport | token | batch | export",
6
      "id": "uuid",
7
      "primary_label": "text",
8
      "secondary_label": "text | null",
9
      "status": "text | null",
10
      "route": "/products/{id}",
11
      "created_at": "timestamptz"
12
    }
13
  ],
14
  "has_more": true,
15
  "next_cursor_created_at": "timestamptz | null",
16
  "next_cursor_id": "uuid | null"
17
}

Results are grouped by type in a fixed display order: Products → Passports → Tokens → Batches → Exports.

Constraints