OCTOGEN_PLATFORM_API_KEY, and you can search products by keyword and facet, find products similar to a source product, and look up any product by URL — all backed by Pydantic models so your IDE can autocomplete every field.
Installation
1
Install the package
Requires Python 3.11 or later. Install To work on the SDK itself, clone the public
octogen-ai-sdk from PyPI. This page documents version 0.11.0.octogen-dev repository and run uv sync in sdks/python.2
Set your API key
The client reads your key from the You can also pass
OCTOGEN_PLATFORM_API_KEY environment variable automatically.api_key= directly to the constructor if you prefer to manage secrets yourself (see Authentication below).Authentication
OctogenClient resolves your API key in this order:
- The
api_keyconstructor argument, if provided. - The
OCTOGEN_PLATFORM_API_KEYenvironment variable. - The deprecated
OCTO_API_KEYenvironment variable. Reading it raises aDeprecationWarningonce, and support will be removed. SetOCTOGEN_PLATFORM_API_KEYinstead.
MissingAPIKeyError immediately — before any network request is made. Every request then sends the key as Authorization: Bearer <api-key>.
Client constructor
These examples set the StoreRouter base URL explicitly, including when you use an SDK release that predates the domain migration.OctogenClient accepts the following keyword-only arguments:
Using the client as an async context manager
Useasync with to ensure the underlying HTTP connection pool is closed when you are done:
await client.aclose() when finished.
Methods
lookup_product
resolution_mode="index_only" when your integration requires indexed identity and catalog context.
MerchantProductUrlLookupResponse
retrieve_product and retrieve_products
uuid from search or lookup. Index-only and not billed. An older id resolves to the product; store the result’s uuid. A product the merchant stopped offering still comes back, with is_active=False and last_deactivated_at. retrieve_products takes 1–50 ids and returns one result per id, in request order. Requires octogen-ai-sdk 0.12.0 or later.
retrieve_product raises OctogenNotFoundError (detail == "product_not_found") for an unknown id, a product that left the index, or a product outside your key’s catalog access. In a batch, the same cases are status="not_found".
Returns: ProductRetrieveResult / ProductRetrieveBatchResponse (results: list[ProductRetrieveResult])
search_products
catalogs. Each keyword controls one thing and is sent under the same wire name. See POST /products/search for the full field semantics.
Returns:
ProgrammaticProductSearchPage, a MerchantProductListPage subclass.
Each
MerchantProductListItem includes uuid, catalog_key, product_url, title, brand, current_price, original_price, primary_image, images, rating, is_active, optional match scores, and updated_at. It also carries the deprecated image_url.
primary_image and each entry in images are MerchantProductImageMetadataView models with url, cdn_url, width, height, size_bytes, and mime_type. Prefer the hosted copy and fall back to the merchant URL:
Local validation
The SDK checks the contradictions the API would refuse and raisespydantic.ValidationError before sending a request:
understand=False,relax=True, or a non-emptyomit_generated_facetswithoutq.omit_generated_facetsalso requiresunderstandto stay on, and so doesrelax=Trueunless at least one facet is sent withrelaxable=True.- A facet name repeated within
facetsorexclude_facets, or a name in bothfacetsandomit_generated_facets. - More than 50 entries in
facets,exclude_facets, oromit_generated_facets. - A negative price or
price_min > price_max. - Brand quality outside 1–6, or
brand_quality_min > brand_quality_max. similar_to_brandsthat is empty, has more than 10 names, or has a blank name.
catalogs list or a blank key raises ValueError, and a bare string raises TypeError. The server remains the source of truth for everything else, such as unknown facet names.
Removed in 0.5.0
These keywords were deprecated in 0.4.0 and are gone in 0.5.0, because the API now rejects them with a422. Passing one to search_products raises TypeError.
text_search_query’s retrieval tuning (search_id, ranking_text, embedding columns, similarity weights, search_after, browse_menu_uuid, compact_mode) has no replacement on /v1 search.
more_like_this_products
source_url or source_uuid. Omit catalogs to search all active crawled catalogs, or pass 1–100 catalog keys to keep the results within those catalogs.
Returns:
ProgrammaticMoreLikeThisResponse
Complete example
The following example searches all active crawled catalogs for women’s linen dresses and prints each result with its brand and price:Faceted search
UseFacet objects to filter by brand, gender, color, category, and other attributes. Pass a list of facets to the facets parameter of search_products.
Facet instances — the SDK coerces them automatically:
Pagination
Whennext_cursor is not None in a response, pass it back verbatim as cursor, with the same other arguments, to retrieve the following page. A cursor the API cannot use returns 400 with detail "invalid cursor"; restart from page 1 without cursor. Pages don’t overlap, but a product can repeat if the catalog changes between requests, so de-duplicate by uuid.
Error handling
All SDK errors inherit fromOctogenError. HTTP errors inherit from OctogenAPIError, which exposes status_code, detail, and response attributes.
OctogenAuthenticationError — 401
OctogenAuthenticationError — 401
Raised when your API key is missing, malformed, or has been revoked. Check that
OCTOGEN_PLATFORM_API_KEY is set correctly and that the key is still active in StoreRouter Platform.OctogenForbiddenError — 403
OctogenForbiddenError — 403
Raised when a valid key attempts an action it is not authorized for — for example, accessing a catalog that has not been granted to your organization.
OctogenNotFoundError — 404
OctogenNotFoundError — 404
Raised when a catalog or product URL cannot be found. For
lookup_product, verify the URL belongs to a catalog your key can access.OctogenValidationError — 422
OctogenValidationError — 422
Raised when the API rejects a request due to invalid parameters. The
detail attribute contains the validation error list from the API. search_products catches many invalid combinations locally and raises pydantic.ValidationError before sending a request.OctogenConnectionError
OctogenConnectionError
Raised when the SDK cannot reach the API — for example, due to a network timeout or DNS failure. Does not have a
status_code.OctogenAPIError to handle all HTTP errors in one place:
BigQuery subscribe (optional)
If StoreRouter shares a catalog with you over BigQuery Analytics Hub, the SDK can subscribe to the listing and create a linked dataset in your own Google Cloud project, so you can query the catalog with SQL. See the Subscribe to a catalog in BigQuery guide for the full walkthrough. This helper uses your Google Cloud Application Default Credentials — not yourOCTOGEN_PLATFORM_API_KEY — so it lives behind an optional bigquery extra:
octogen-bq-subscribe CLI (dry-run by default; --apply to subscribe) and the octogen-bq-autosubscribe cron helper for keeping linked datasets current as new listings become available:
subscribe_to_listing
OctogenClient). Idempotent — an existing subscription to the same listing in destination_project is returned as-is.
Returns:
BigQuerySubscriptionResult with listing_resource, linked_project, linked_dataset, state, already_subscribed, subscription_name, and a ready-to-run sample_query.
Two BigQuery error types extend
OctogenError: OctogenBigQueryError (base) and OctogenBigQueryAccessPendingError, raised when StoreRouter’s IAM grant on the listing hasn’t propagated yet. Because the grant is asynchronous, catch the access-pending error and retry after a few minutes.Brand directory, profiles, and browsing
Use Python SDK 0.16.0 or later for the lightweight profile contract.get_brand_details returns BrandDetailsView; it no longer returns coverage. Request that independently with get_brand_coverage.
total respect your customer’s catalog scope. Follow next_offset through short or empty projected pages; total counts source rows. Offset 11976 is the final supported start. See brand browsing.
OctogenNotFoundError means an unknown brand. A server error is a failure, not an empty directory or missing profile. Load coverage separately when the profile must remain available during a snapshot failure. For manual ETag revalidation, use the HTTP directory example.