The Product Directory API lets you connect your product catalog to Text so the AI Agent can recommend real, in-stock products during customer conversations, and present them as interactive product cards in chat. It's built for headless storefronts and custom-built stores that don't have a plugin to connect.
Product Directory vs. AI Knowledge Sources
The Product Directory and your Knowledge Sources are two separate entities, managed and updated independently. Keeping them apart means you can change prices, stock, and availability through the API without touching your support content, and without waiting for a knowledge base re-scan.
Uploading your Product Catalog
You can set up and maintain your entire product catalog connection through this API, from the initial import to subsequent changes, without any additional integrations.
Before you start, make sure you have the following:
A personal access token (PAT) and your Text account ID — both are shown together when you create the token, see below,
A ready JSON file describing your products,
Your AI agent set up - it's what actually uses the catalog once it's uploaded, though creating the catalog itself doesn't require the agent to be active
Get your personal access token
While in Text, go to Settings → Integrations → API access, then open the Personal access tokens tab, and click +New Token.
After naming the token, you will need to set its scopes. For this method, you will need to unwrap the Account & Organization scope list, and then set My account -> Account details scope to view (accounts--my:ro). Next, push the Create token button, and a confirmation screen will show your Account ID, scopes, and the token together - save both now, since the token won't be visible again after you close the window. For the full authentication walkthrough, see the personal access tokens guide.
You can copy the plain token (use it as the password, with your account ID as the username, in Basic authentication) or switch to the Base64-encoded token tab to get the two already combined and ready to drop straight into the Authorization header.
Upload your product catalog
Step 1: Prepare your catalog file. Your file is a JSON array of product objects. Each product needs:
Field | Required | Description |
|---|---|---|
id | Yes | Unique product identifier |
title | Yes | Product name |
description | Yes | Product description |
url | Yes | Product page URL |
currency | Yes | Currency code applied to all variant prices (e.g. USD) |
categories | Yes | At least one category |
tags | No | Free-form tags |
images | Yes | At least one image (url, optional alt_text) |
attributes | Yes | At least one {key, value} pair - more meaningful attributes produce better search results |
variants | Yes | At least one variant (id, title, sku, options, available, price) |
The example products.json build is available in the method's documentation for reference.
Step 2: Upload the files.
The filename must end in .json. Maximum size: 50MB
Send a POST request with your file once it's ready:
curl --request POST \
--url https://api.text.com/product-directory/v1/catalogs/imports \
--header 'Authorization: Basic <encoded-value>' \
--header 'Content-Type: multipart/form-data' \
--form file='@example-file'A successful request returns a 202 with a job_id:
{ "job_id": "550e8400-e29b-41d4-a716-446655440000" }A "202" response means the import was queued - it doesn't mean every product passed validation. Invalid products are skipped, not rejected, and counted separately in the next step.
Step 3: Check the import status. Poll the job using its newly acquired ID to see how it's progressing:
curl --request GET \
--url https://api.text.com/product-directory/v1/catalogs/imports/{job_id} \
--header 'Authorization: Basic <encoded-value>'The response includes status (pending, processing, done, or failed), total number of products in the uploaded file, indexed_count, failed_count, and skipped_count (products unchanged since the last import).
Of course, it will also inform of the current progress, start time, and completion time if the process was finished before sending the import status request.
Once it's done, the AI Agent can search your catalog with semantic search, filter out anything unavailable, and present matches as product cards in chat - including variant selection and add-to-cart.
Step 4: Equip your AI agent with the catalog
Once the import is ready, while in Text, head to the Team tab on the left side panel, and then choose the AI agent you'd like to Recommend Products. From there, move to the Skills tab and select the Recommend products skill; there, you can choose the directory the AI agent will use for recommendations and enable the skill.
After choosing the right store or catalog, you can enable the skill for the AI agent to start recommending your products, starting with the next chat.
To confirm the connection worked, check the number of products shown on the skill tile. It should match your catalog's product_count from Get catalog details. If it's zero or lower than expected, check your last import for failures before assuming the connection is broken.
Frequently asked questions
No. This API exists for stores that don't have one of Text's native ecommerce integrations, including headless and custom-built storefronts.
No. Upload just the products that are new or changed. Text updates any product that matches an existing id and adds any product with a new one.
Send a DELETE request to /v1/catalogs/{catalog_id}/products/{product_id} with the product's ID. It's idempotent, so deleting a product that has already been removed still returns success. To hide it temporarily instead, set its variant's available field to false in your next upload.
Currently, only one catalog can be imported through this API per organization, so every AI agent using it draws from the same uploaded catalog. If you also have a Shopify store connected, you're not limited to that: each AI agent's Skills settings let you choose whether it uses your Shopify catalog or the one uploaded through this API.
What's next?
Once your catalog is imported and the Recommend products skill is enabled, your AI agent starts surfacing real, in-stock products the moment a customer asks, with no extra configuration needed beyond picking the right catalog.
If you're also sending completed orders back to Text, pair this with sales tracking so agents and reports can see the full picture, from recommendation to purchase.
To have the AI agent do more than recommend products, like checking order status or applying discount logic, look into building custom skills on top of this integration.
For the full set of Text APIs, guides, and authentication references, see the Text documentation.