canonical: https://jentic.com/apis/cognitivefashion.github.io/ibm-ai-for-fashion-api

# Cognitivefashion IBM Research AI for Fashion API

Jentic publishes the only available OpenAPI specification for IBM Research AI for Fashion API, keeping it validated and agent-ready. The API provides catalog management, visual search, visual browse, and text search tailored to fashion product datasets. Agents can index a product catalog, query it by image or natural-language description, and retrieve visually similar products from a customer-provided image. It is designed for retailers, marketplaces, and shopping assistants that need product discovery grounded in real apparel imagery.

## For AI agents

Index fashion product catalogs and run visual or text-based product search to find similar items from a customer image or query.

## Scope

Does not handle payment processing, order fulfillment, or general image recognition outside fashion - use for fashion product catalog and visual or text search only.

## Capabilities

- Create and delete fashion product catalogs scoped per tenant
- Index individual products with images, attributes, and metadata for search
- Run visual search against an uploaded image to retrieve visually similar fashion items
- Run text search across catalog products using natural-language fashion vocabulary
- Browse visually related products from an existing catalog item identifier
- Build and refresh the visual search index after catalog changes

## Use cases

### Visual Product Discovery for Shoppers

Let shoppers upload an inspiration photo and surface visually similar items from a retailer's catalog. The API ranks catalog products by visual similarity using deep learning models trained on fashion imagery, returning matching product ids and metadata. Integration takes a few hours once a catalog has been indexed via the visual_search_index endpoint.

Example prompt: POST a customer photo to `/catalog/{catalog_name}/visual_search` and return the top five matching product ids with their stored attributes

### Catalog Management for Fashion Retailers

Maintain a structured catalog of fashion products with consistent attributes, images, and identifiers. Use the catalog and product endpoints to add, update, or remove SKUs, then trigger reindexing so visual and text search stay current. Suitable for mid-size retailers managing thousands of products who need search backed by fashion-specific models.

Example prompt: Create a catalog named summer-2026, add ten products via `/catalog/{catalog_name}/products/{id}`, then call POST `/catalog/{catalog_name}/visual_search_index` to build the index

### Natural-Language Fashion Search

Let customers describe what they are looking for in plain language and return matching products. The text search endpoint understands fashion vocabulary such as silhouette, neckline, and pattern terms, returning ranked product results. Useful for chat-based shopping assistants and on-site search bars.

Example prompt: Call GET `/catalog/{catalog_name}/text_search` with the query v-neck red maxi dress and return the top product matches

### AI Shopping Agent via Jentic

Build an AI agent that handles fashion shopping queries end to end by combining visual and text search through Jentic. Jentic resolves the right operation from an intent like find a dress similar to this image, executes the call with stored credentials, and returns structured product results the agent can present to the user.

Example prompt: Through Jentic, search for visually similar fashion products and return the top three matches with image urls and product attributes

## Key endpoints

| Method | Path | Description |
| --- | --- | --- |
| POST | `/catalog/{catalog_name}` | Create a new fashion product catalog |
| POST | `/catalog/{catalog_name}/products/{id}` | Add a product to a catalog |
| POST | `/catalog/{catalog_name}/visual_search_index` | Build the visual search index for a catalog |
| POST | `/catalog/{catalog_name}/visual_search` | Find visually similar products from an uploaded image |
| GET | `/catalog/{catalog_name}/text_search` | Search catalog products by natural-language query |
| GET | `/catalog/{catalog_name}/visual_browse/{id}/{image_id}` | Browse visually related products from a catalog item |

## Key resources

- **Catalog** — Create, retrieve, and delete fashion product catalogs
- **Product** — Add, update, retrieve, and delete individual products inside a catalog
- **Visual Search Index** — Build and manage the visual similarity index over a catalog
- **Visual Search** — Find visually similar products from an uploaded image
- **Visual Browse** — Retrieve visually related products from an existing catalog item
- **Text Search** — Query catalog products by natural-language fashion descriptions

## Why Jentic

- **Setup:** Wiring the IBM Research AI for Fashion API by hand means sending its API-key header, targeting api.cognitivefashion.com/v1, and threading the catalog name through every index, search, and browse call yourself. Through Jentic you install once, import the IBM Research AI for Fashion API from the API Directory, store the key once, and your agent calls it.
- **Permission scoping:** The Fashion API puts the catalog name in the URL path (`/catalog/{catalog_name}/...`), so a rule can pin your agent to one catalog: it builds the visual search index, runs visual and text search, and browses products within that catalog and nothing else. You choose the operations it may call, so adding or overwriting products is only in the allowed set if you add it.
- **Credential handling:** Your IBM Cognitive Fashion API key is stored once, encrypted, by your own Jentic One instance and injected at execution time. It never enters the agent's prompt, logs, or context.
- **Discovery method:** Agents search Jentic by intent such as 'find visually similar fashion products' or 'search a fashion catalog by text', and Jentic returns the matching operation with its input schema so the agent calls the right endpoint without browsing the reference docs.

## Related APIs

- **Clarifai API** — General-purpose visual recognition with custom-trained fashion models
- **Imagga API** — Image tagging, categorization, and visual similarity for any product imagery
- **Cloudinary Upload API** — Store and transform the product images you index into the fashion catalog

## FAQ

### Why is there no official OpenAPI spec for IBM Research AI for Fashion API?

IBM does not publish an OpenAPI specification for this research API. Jentic generates and maintains this spec so that AI agents and developers can call the IBM Research AI for Fashion API via structured tooling. It is validated against the live API and kept up to date. Get started with Jentic One, the self-hosted execution layer.

### What authentication does the IBM Research AI for Fashion API use?

The API uses an API key sent as a request header. When called through Jentic, the key is stored in your encrypted Jentic One instance and is never exposed to the agent context - the agent receives a scoped execution token instead.

### Can I run image-based search against my own product catalog with this API?

Yes. Create a catalog with POST `/catalog/{catalog_name}`, add products with POST `/catalog/{catalog_name}/products/{id}`, build the index with POST `/catalog/{catalog_name}/visual_search_index`, then call POST `/catalog/{catalog_name}/visual_search` with a customer image to retrieve visually similar items.

### What are the rate limits for the IBM Research AI for Fashion API?

The OpenAPI spec does not declare per-endpoint rate limits. Limits are enforced by the IBM Cognitive Fashion service and depend on the tier provisioned for your API key - consult the service contract attached to your key for exact thresholds.

### How do I run a fashion text search with this API through Jentic?

Install the SDK with pip install jentic, then search Jentic for the operation using a query like search fashion catalog by text, load the schema for GET `/catalog/{catalog_name}/text_search`, and execute the call with your catalog name and query string.

### Does the API support visual browsing from an existing catalog item?

Yes. GET `/catalog/{catalog_name}/visual_browse/{id}/{image_id}` returns visually related products from a specific image attached to a catalog product, which is useful for related-item recommendations on product detail pages.

### Can I limit what my agent is allowed to do with the IBM Research AI for Fashion API?

Yes. Because Jentic One is self-hosted, your own rules decide which operations and credentials the agent may use. Since the catalog name sits in the URL path (`/catalog/{catalog_name}/...`), you can pin the agent to a single catalog and allow only the operations you choose, such as building the visual search index and running visual search, text search, and visual browse within that catalog. Write operations like adding or overwriting products are included only if you explicitly add them to the allowed set.