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": 100,
      "offset": 0
    },
    "sort": {
      "field": "createdAt",
      "order": "DESC"
    }
  }'

Empty Search

Returns the first page of all products in your account. Use offset to paginate through the full catalog.

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": 500,
      "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	`{"attributes": [{"key": {"$eq": "productCategory"}, "value": {"$in": ["13", "14"]}}]}`	Multiple categories
`$nin`	Value not in array	`{"skuId": {"$nin": ["TR001", "TR002"]}}`	Exclude specific products

Existence & Pattern Operators

Operator	Description	Example	Use Case
`$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:

For a single known skuId, use the dedicated GET endpoint instead — it is more direct and returns the full product object:

curl -X GET https://api.trustana.com/v1/products/TR08214816 \
  -H "X-API-Key: YOUR_API_KEY"

See Product Details for the full response structure.

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

Filter by enrichment status using nested object syntax:

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": 500, "offset": 0 },
    "sort": { "field": "dataEnrichment.completedAt", "order": "DESC" }
  }'

Available status values: FINISHED, IN_PROGRESS, FAILED, QUEUED, SKIPPED

Combine with completedAt to narrow results to a specific time window:

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"] },
        "completedAt": { "$gte": 1766088553738 }
      }
    },
    "pagination": { "limit": 500, "offset": 0 },
    "sort": { "field": "dataEnrichment.completedAt", "order": "DESC" }
  }'

completedAt is a Unix timestamp in milliseconds.

Combine enrichment status with completion rate to find finished products above a completion threshold:

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"] }
      },
      "attributeSummary": {
        "enrichableCompletionRate": { "$gte": 80.0 }
      }
    },
    "pagination": {
      "limit": 20,
      "offset": 0
    },
    "sort": {
      "field": "dataEnrichment.completedAt",
      "order": "DESC"
    }
  }'

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"
        }
      }
    ]
  }
}

Valid values for dropdown and multi-select attributes are defined in your account configuration. Query POST /v1/attributes/search and check the option.values field on the relevant attribute to get the accepted enum values before filtering.

Single option:

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

Multiple options:

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

TREE_NODE Attributes (Category)

Product category is stored as the productCategory attribute with a taxonomy node ID as its value. Retrieve category IDs from GET /v1/taxonomies.

Products in specific categories:

{
  "filter": {
    "attributes": [
      {
        "key": { "$eq": "productCategory" },
        "value": { "$in": ["13", "14"] }
      }
    ]
  }
}

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": {
      "attributes": [
        {
          "key": { "$eq": "productCategory" },
          "value": { "$in": ["13"] }
        },
        {
          "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": {
      "attributes": [
        {
          "key": { "$eq": "productCategory" },
          "value": { "$in": ["15"] }
        },
        {
          "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": 500,   // Max 500 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

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

Pagination Best Practices

Limit Results: Use up to 500 items per request for bulk operations; use smaller pages (20–50) for interactive use
Progressive Loading: Load additional pages as needed
Sort Consistency: Always include sort criteria for consistent results
Monitor Performance: Track query response times

Good Practice: Validate Search Results

When using broad or dynamic filters, check the total field in the response to confirm the result count aligns with your expectations before processing. This is especially important in automation workflows where downstream actions (tagging, exporting, updating) depend on the search scope. A result set that is significantly larger than anticipated may indicate that filter criteria need to be refined.

Good Practice: Verify Complex Filters Client-Side

For complex filter criteria — particularly when combining multiple attribute filters or filtering on nested fields like dataEnrichment.status — it is good practice to verify that returned products fully meet your criteria in your application code. This ensures your processing logic handles only the products you intend to work with.

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: Filter by productCategory attribute using taxonomy IDs from GET /v1/taxonomies
Existence Checks: Use $exists efficiently for optional attributes

Common Use Cases

Enrichment Status Operations

Find products not yet enriched ("Not Started" in UI):

Products that have never been submitted for enrichment have no dataEnrichment field in their data — the UI displays these as "Not Started".

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": { "$exists": false }
      }
    },
    "pagination": { "limit": 500, "offset": 0 },
    "sort": { "field": "createdAt", "order": "DESC" }
  }'

Find products ready for review:

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": 500, "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"] },
        "completedAt": { "$gte": 1766088553738 }
      }
    },
    "pagination": { "limit": 500, "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 500 items per request",
    "details": {
      "requested_limit": 1000,
      "max_limit": 500
    }
  }
}

API Overview​

Basic Search Structure​

Search Request Format​

Empty Search​

BSON Query Operators​

Equality Operators​

Comparison Operators​

Array Operators​

Existence & Pattern Operators​

Filter Types & Examples​

Simple Product Lookup​

Keyword Search​

Enrichment Status Filtering​

Date Range Filtering​

Attribute-Based Filtering​

Attribute Type Filtering Guide​

TEXT & LONG_TEXT Attributes​

NUMBER & PRICE Attributes​

DROPDOWN & MULTI_SELECT Attributes​

TREE_NODE Attributes (Category)​

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​

Pagination Best Practices​

Good Practice: Validate Search Results​

Good Practice: Verify Complex Filters Client-Side​

Query Optimization Tips​

Common Use Cases​

Recently Updated Products​

Enrichment Status Operations​

Error Handling​

Invalid Query Structure​

Invalid Operator​

Pagination Limits​