Searching Products

Master product retrieval using Trustana's powerful search API with BSON query operators, complex filtering, and pagination. Product search uses MongoDB-style query syntax for precise and flexible product discovery.

API Overview

Product search in Trustana uses a POST endpoint with JSON body containing filter criteria, pagination, and sorting options. This approach enables complex queries using BSON operators for precise product filtering.

Integration Pre-requisites

Before searching products, ensure you understand the same requirements as other API operations:

Attribute Key Mapping:

Search queries can filter by any attribute key that exists in your account configuration
Use POST /v1/attributes/search to discover available attribute keys for filtering
Attribute filtering requires exact key names as configured in your account

Query Structure Understanding:

Uses MongoDB-style BSON operators for filtering
Supports complex nested queries on attributes
Requires understanding of operator types for different data formats

Performance Considerations:

Use indexed fields (skuId, supplierSku, createdAt) for optimal performance
Limit result sets with appropriate pagination
Avoid overly complex regex patterns on large datasets

See Configuration Flow for attribute configuration and Getting Started for account setup.

Basic Search Structure

All product searches use the POST endpoint with a structured JSON body:

Search Request Format

curl -X POST https://api.trustana.com/v1/products/search \
  -H "X-API-Key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "filter": {
      // Filter criteria using BSON operators
    },
    "pagination": {
      "limit": 10,
      "offset": 0
    },
    "sort": {
      "field": "createdAt",
      "order": "DESC"
    }
  }'

Empty Search (Get All Products)

curl -X POST https://api.trustana.com/v1/products/search \
  -H "X-API-Key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "filter": {},
    "pagination": {
      "limit": 20,
      "offset": 0
    },
    "sort": {
      "field": "createdAt",
      "order": "DESC"
    }
  }'

BSON Query Operators

Trustana's search API uses MongoDB-style BSON operators for flexible and powerful querying. Understanding these operators is essential for effective product searches.

Equality Operators

Operator	Description	Example	Use Case
`$eq`	Equals (exact match)	`{"supplierSku": {"$eq": "PRODUCT-001"}}`	Find specific product
`$ne`	Not equals	`{"attributes": [{"key": {"$eq": "brand"}, "value": {"$ne": "Unknown"}}]}`	Exclude specific values

Comparison Operators

Operator	Description	Example	Use Case
`$gt`	Greater than	`{"createdAt": {"$gt": 1640995200000}}`	Products created after date
`$gte`	Greater than or equal	`{"attributes": [{"key": {"$eq": "price"}, "value": {"$gte": "100"}}]}`	Price range filtering
`$lt`	Less than	`{"updatedAt": {"$lt": 1672531200000}}`	Products updated before date
`$lte`	Less than or equal	`{"attributes": [{"key": {"$eq": "inventory"}, "value": {"$lte": "10"}}]}`	Low stock filtering

Array Operators

Operator	Description	Example	Use Case
`$in`	Value in array	`{"productCategories": {"$in": ["Electronics", "Mobile"]}}`	Multiple categories
`$nin`	Value not in array	`{"skuId": {"$nin": ["TR001", "TR002"]}}`	Exclude specific products

Existence & Pattern Operators

Operator	Description	Example	Use Case
`$exists`	Field exists	`{"attributes": [{"key": {"$eq": "media"}, "value": {"$exists": true}}]}`	Products with images
`$regex`	Regular expression	`{"attributes": [{"key": {"$eq": "name"}, "value": {"$regex": "iPhone"}}]}`	Text pattern matching

Filter Types & Examples

Simple Product Lookup

Find by Supplier SKU:

curl -X POST https://api.trustana.com/v1/products/search \
  -H "X-API-Key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "filter": {
      "supplierSku": {
        "$eq": "INTERNAL-APPLE-15PM-001"
      }
    }
  }'

Find by Trustana SKU ID:

curl -X POST https://api.trustana.com/v1/products/search \
  -H "X-API-Key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "filter": {
      "skuId": {
        "$eq": "TR08214816"
      }
    }
  }'

Keyword Search

Search across product content:

curl -X POST https://api.trustana.com/v1/products/search \
  -H "X-API-Key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "filter": {
      "keyword": "iPhone 15 Pro"
    },
    "pagination": {
      "limit": 10,
      "offset": 0
    }
  }'

Enrichment Status Filtering

Find products by enrichment completion status:

curl -X POST https://api.trustana.com/v1/products/search \
  -H "X-API-Key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "filter": {
      "dataEnrichment.status": {
        "$in": ["FINISHED"]
      }
    },
    "pagination": {
      "limit": 50,
      "offset": 0
    },
    "sort": {
      "field": "dataEnrichment.completedAt",
      "order": "DESC"
    }
  }'

Find products with multiple enrichment statuses:

curl -X POST https://api.trustana.com/v1/products/search \
  -H "X-API-Key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "filter": {
      "dataEnrichment.status": {
        "$in": ["FINISHED", "FAILED", "IN_PROGRESS"]
      }
    },
    "pagination": {
      "limit": 25,
      "offset": 0
    },
    "sort": {
      "field": "updatedAt",
      "order": "DESC"
    }
  }'

Combine enrichment status with completion rate filtering:

curl -X POST https://api.trustana.com/v1/products/search \
  -H "X-API-Key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "filter": {
      "dataEnrichment.status": {
        "$eq": "FINISHED"
      },
      "attributeSummary.enrichableCompletionRate": {
        "$gte": 80.0
      }
    },
    "pagination": {
      "limit": 20,
      "offset": 0
    },
    "sort": {
      "field": "dataEnrichment.completedAt",
      "order": "DESC"
    }
  }'

Category Filtering

Products in specific categories:

curl -X POST https://api.trustana.com/v1/products/search \
  -H "X-API-Key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "filter": {
      "productCategories": ["Electronics", "Mobile Devices"]
    },
    "pagination": {
      "limit": 25,
      "offset": 0
    }
  }'

Date Range Filtering

Recently created products:

curl -X POST https://api.trustana.com/v1/products/search \
  -H "X-API-Key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "filter": {
      "createdAt": {
        "$gte": 1704067200000,
        "$lte": 1706745600000
      }
    },
    "sort": {
      "field": "createdAt",
      "order": "DESC"
    }
  }'

Attribute-Based Filtering

Attribute filtering uses nested queries to search within the product's attribute array. This is the most powerful feature for custom product searches.

Attribute Type Filtering Guide

TEXT & LONG_TEXT Attributes

Exact match:

{
  "filter": {
    "attributes": [
      {
        "key": {
          "$eq": "brand"
        },
        "value": {
          "$eq": "Apple"
        }
      }
    ]
  }
}

Pattern matching:

{
  "filter": {
    "attributes": [
      {
        "key": {
          "$eq": "name"
        },
        "value": {
          "$regex": "iPhone.*Pro"
        }
      }
    ]
  }
}

NUMBER & PRICE Attributes

Price range filtering:

{
  "filter": {
    "attributes": [
      {
        "key": {
          "$eq": "price"
        },
        "value": {
          "$gte": "500",
          "$lte": "1500"
        }
      }
    ]
  }
}

Inventory level:

{
  "filter": {
    "attributes": [
      {
        "key": {
          "$eq": "inventory"
        },
        "value": {
          "$lte": "10"
        }
      }
    ]
  }
}

Single option:

{
  "filter": {
    "attributes": [
      {
        "key": {
          "$eq": "color"
        },
        "value": {
          "$eq": "Blue"
        }
      }
    ]
  }
}

Multiple options:

{
  "filter": {
    "attributes": [
      {
        "key": {
          "$eq": "size"
        },
        "value": {
          "$in": ["Medium", "Large", "XL"]
        }
      }
    ]
  }
}

MEDIA_GALLERY Attributes

Products with images:

{
  "filter": {
    "attributes": [
      {
        "key": {
          "$eq": "media"
        },
        "value": {
          "$exists": true
        }
      }
    ]
  }
}

Specific image count:

{
  "filter": {
    "attributes": [
      {
        "key": {
          "$eq": "media"
        },
        "value": {
          "$size": 3
        }
      }
    ]
  }
}

Complex Multi-Criteria Searches

Fashion Retailer Example

Finding blue dresses in medium size, priced between $100-300:

curl -X POST https://api.trustana.com/v1/products/search \
  -H "X-API-Key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "filter": {
      "productCategories": ["Fashion", "Dresses"],
      "attributes": [
        {
          "key": {
            "$eq": "color"
          },
          "value": {
            "$eq": "Blue"
          }
        },
        {
          "key": {
            "$eq": "size"
          },
          "value": {
            "$eq": "Medium"
          }
        },
        {
          "key": {
            "$eq": "price"
          },
          "value": {
            "$gte": "100",
            "$lte": "300"
          }
        }
      ]
    },
    "pagination": {
      "limit": 20,
      "offset": 0
    },
    "sort": {
      "field": "createdAt",
      "order": "DESC"
    }
  }'

Electronics Inventory Example

Finding Apple products with low inventory and enriched content:

curl -X POST https://api.trustana.com/v1/products/search \
  -H "X-API-Key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "filter": {
      "productCategories": ["Electronics"],
      "attributes": [
        {
          "key": {
            "$eq": "brand"
          },
          "value": {
            "$eq": "Apple"
          }
        },
        {
          "key": {
            "$eq": "inventory"
          },
          "value": {
            "$lte": "5"
          }
        },
        {
          "key": {
            "$eq": "smartShortDesp"
          },
          "value": {
            "$exists": true
          }
        }
      ]
    },
    "sort": {
      "field": "updatedAt",
      "order": "DESC"
    }
  }'

Pagination & Sorting

Pagination Structure

{
  "pagination": {
    "limit": 50,    // Max 100 items per request
    "offset": 0     // Starting position (0-based)
  }
}

Page Navigation:

Page 1: "offset": 0, "limit": 20
Page 2: "offset": 20, "limit": 20
Page 3: "offset": 40, "limit": 20

Sorting Options

{
  "sort": {
    "field": "createdAt",     // Field to sort by
    "order": "DESC"           // ASC or DESC
  }
}

Available Sort Fields:

createdAt: Product creation timestamp
updatedAt: Last modification timestamp
supplierSku: Your product identifier
skuId: Trustana product identifier

Response Format

Basic Search Response

{
  "errorCode": 0,
  "data": {
    "products": [
      {
        "id": "68e51e0bf52b9762b67b7de9",
        "skuId": "TR08214816",
        "supplierSku": "INTERNAL-APPLE-15PM-001",
        "createdAt": 1759845899057,
        "updatedAt": 1759845899157,
        "attributeSummary": {
          "enrichableTotal": 48,
          "enrichableCompleted": 3,
          "enrichableCompletionRate": 6.25
        },
        "attributes": [
          {
            "key": "name",
            "value": "Apple iPhone 15 Pro Max"
          },
          {
            "key": "brand",
            "value": "Apple"
          },
          {
            "key": "price",
            "value": "1199.99"
          }
        ]
      }
    ],
    "pagination": {
      "limit": 20,
      "offset": 0,
      "total": 1,
      "hasMore": false
    }
  }
}

Response Fields Explained

products: Array of matching products
id: MongoDB document identifier
skuId: Trustana-generated unique identifier
supplierSku: Your internal product identifier
attributes: Array of all product attributes
attributeSummary: Enrichment progress metrics
pagination.total: Total matching products count
pagination.hasMore: Whether more results exist

Performance & Best Practices

Efficient Query Patterns

▶️ Use Indexed Fields

// Fast: Uses indexed fields
{
  "filter": {
    "supplierSku": {"$eq": "PRODUCT-001"},
    "createdAt": {"$gte": 1704067200000}
  }
}

▶️ Specific Attribute Queries

// Good: Specific attribute lookup
{
  "filter": {
    "attributes": [
      {
        "key": {"$eq": "brand"},
        "value": {"$eq": "Apple"}
      }
    ]
  }
}

❌ Avoid Complex Regex

// Slow: Complex regex on large datasets
{
  "filter": {
    "attributes": [
      {
        "key": {"$eq": "description"},
        "value": {"$regex": ".*complex.*pattern.*"}
      }
    ]
  }
}

Pagination Best Practices

Limit Results: Use appropriate page sizes (10-50 items)
Progressive Loading: Load additional pages as needed
Sort Consistency: Always include sort criteria for consistent results
Monitor Performance: Track query response times

Query Optimization Tips

Filter Order: Place most selective filters first
Attribute Specificity: Use exact key matches when possible
Date Ranges: Use timestamp ranges instead of text date patterns
Category Filtering: Use category arrays for better performance
Existence Checks: Use $exists efficiently for optional attributes

Common Use Cases

Category-Based Searches

Products in multiple categories:

curl -X POST https://api.trustana.com/v1/products/search \
  -H "X-API-Key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "filter": {
      "productCategories": ["Electronics", "Mobile", "Smartphones"]
    },
    "pagination": {
      "limit": 100,
      "offset": 0
    }
  }'

Enrichment Status Operations

Find products ready for publication (high completion rate):

curl -X POST https://api.trustana.com/v1/products/search \
  -H "X-API-Key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "filter": {
      "dataEnrichment.status": {
        "$eq": "FINISHED"
      },
      "attributeSummary.enrichableCompletionRate": {
        "$gte": 90.0
      }
    },
    "pagination": {
      "limit": 50,
      "offset": 0
    },
    "sort": {
      "field": "dataEnrichment.completedAt",
      "order": "DESC"
    }
  }'

Identify products needing enrichment retry:

curl -X POST https://api.trustana.com/v1/products/search \
  -H "X-API-Key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "filter": {
      "dataEnrichment.status": {
        "$in": ["FAILED"]
      },
      "dataEnrichment.completedAt": {
        "$gte": 1722934566131
      }
    },
    "pagination": {
      "limit": 25,
      "offset": 0
    },
    "sort": {
      "field": "dataEnrichment.completedAt",
      "order": "DESC"
    }
  }'

Error Handling

Invalid Query Structure

{
  "errorCode": 400,
  "error": {
    "code": "invalid_query_structure",
    "message": "Filter syntax error in attribute query",
    "details": {
      "field": "attributes[0].key",
      "expected": "object with BSON operators",
      "received": "string"
    }
  }
}

Invalid Operator

{
  "errorCode": 400,
  "error": {
    "code": "unsupported_operator",
    "message": "Operator '$invalid' is not supported",
    "supported_operators": ["$eq", "$ne", "$gt", "$gte", "$lt", "$lte", "$in", "$nin", "$exists", "$regex"]
  }
}

Pagination Limits

{
  "errorCode": 400,
  "error": {
    "code": "pagination_limit_exceeded",
    "message": "Limit cannot exceed 100 items per request",
    "details": {
      "requested_limit": 500,
      "max_limit": 100
    }
  }
}

API Overview​

Basic Search Structure​

Search Request Format​

Empty Search (Get All Products)​

BSON Query Operators​

Equality Operators​

Comparison Operators​

Array Operators​

Existence & Pattern Operators​

Filter Types & Examples​

Simple Product Lookup​

Keyword Search​

Enrichment Status Filtering​

Category Filtering​

Date Range Filtering​

Attribute-Based Filtering​

Attribute Type Filtering Guide​

TEXT & LONG_TEXT Attributes​

NUMBER & PRICE Attributes​

DROPDOWN & MULTI_SELECT Attributes​

MEDIA_GALLERY Attributes​

Complex Multi-Criteria Searches​

Fashion Retailer Example​

Electronics Inventory Example​

Pagination & Sorting​

Pagination Structure​

Sorting Options​

Response Format​

Basic Search Response​

Response Fields Explained​

Performance & Best Practices​

Efficient Query Patterns​

Pagination Best Practices​

Query Optimization Tips​

Common Use Cases​

Category-Based Searches​

Recently Updated Products​

Enrichment Status Operations​

Error Handling​

Invalid Query Structure​

Invalid Operator​

Pagination Limits​