> For clean Markdown of any page, append .md to the page URL. > For a complete documentation index, see https://tieback.io/docs/llms.txt. > For AI client integration (Claude Code, Cursor, etc.), connect to the MCP server at https://tieback.io/docs/_mcp/server. # API: Search > Query Global Search programmatically to find products, tokens, batches, passports and exports across your workspace, with brand-scoped results. > **Programmatic access — early access** > > The > > **tie*back*** > > API is available to selected workspaces during early access. Endpoints in production today are > authenticated with an authenticated session. Standalone API-key access is being onboarded per > workspace. Contact > > **tie*back*** > > to enable API credentials for your workspace. ## Overview **tie*back*** 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 | Category | What's Searched | Example Query | | ----------------- | ----------------------------------------------------------------------------------- | ------------------------------------------------------- | | **Products** | Product name (all languages), SKU, description, attribute values, GTIN | `Winter Gloves`, `GL4-123`, `steel grey` | | **Passports** | Passport ID (prefix match), SKU (prefix match), GTIN (exact), Batch ID (exact UUID) | `8e5ac812`, `GL4-123`, `5060999100063` | | **Tokens** | Token serial number (prefix match, minimum 4 characters) | `13250d12` | | **Batches** | Batch ID (prefix match) | `dd8b80e5` | | **Exports** | Export ID or export group ID (exact UUID match) | `dd8b80e5-bb33-4c1a-...` | | **Resolver URLs** | Full GS1 Digital Link or resolver URL, parsed automatically | `https://brand.tieback.io/01/5060999100063/21/13250d12` | --- ## 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/`), the serial is extracted and used to find the matching token. * If the URL contains only a GTIN (`/01/`), 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: | Input Pattern | What's Searched | | ---------------------------------------------------- | ---------------------------------------------- | | Letters, spaces, hyphens only (e.g. `winter gloves`) | Products only | | Numeric (8, 12–14 digits) | Products (GTIN match) + Passports (GTIN match) | | UUID format | Products, passports, batches, exports | | Mixed alphanumeric (e.g. `GL4-123`, `13250d12`) | Products + passports + tokens + batches | | GS1 Digital Link URL | Parsed into GTIN/serial, then routed | ### 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 ```json { "ok": true, "items": [ { "type": "product | passport | token | batch | export", "id": "uuid", "primary_label": "text", "secondary_label": "text | null", "status": "text | null", "route": "/products/{id}", "created_at": "timestamptz" } ], "has_more": true, "next_cursor_created_at": "timestamptz | null", "next_cursor_id": "uuid | null" } ``` Results are grouped by type in a fixed display order: **Products → Passports → Tokens → Batches → Exports**. --- ## Constraints | Rule | Value | | -------------------- | ----------------------------------------------------------------- | | Minimum query length | 2 characters | | Token serial minimum | 4 characters | | Statement timeout | 1 second | | Pagination | Cursor-based | | Security | Workspace-scoped, only objects within your workspace are returned | ## Related Docs * [Global Search](/product-module/global-search) * [API: Products](/api-reference/api-products) * [API: Minting](/api-reference/api-minting) * [API: Credentials](/api-reference/api-credentials)