canonical: https://jentic.com/apis/askmiso.com/askmiso

# Askmiso Miso API

Miso is a personalisation and search platform that trains machine-learning engines on a site's interaction logs, product catalogue, and user data to power recommendations, search, and Q&A. The API exposes 26 endpoints across products, users, interactions, search, recommendations, ask, experiments, and bulk operations. Authentication is via an api_key query parameter, with separate Secret and Publishable keys for backend and client-side use.

## For AI agents

Power product personalisation - recommendations, search, Q&A, and interaction tracking - through Miso's machine-learning APIs.

## Scope

Does not handle payments, customer support, or content authoring - use for recommendations, personalised search, Q&A, and interaction tracking only.

## Capabilities

- Upload product or content catalogue records and update them in bulk
- Stream user interaction events into Miso to train recommendation engines
- Run personalised search queries with autocomplete and multi-get support
- Generate recommendations for a given user or product context
- Run Q&A queries against the trained Ask engine
- Send experiment events to compare engine variants
- Bulk upload, read, and delete users, products, and interactions

## Use cases

### Catalogue Sync and Personalised Search

Keep Miso's index in sync with the live product catalogue using POST `/v1/products` and bulk delete via POST `/v1/products/_delete`, then power site search with POST `/v1/search/search` and autocomplete via POST `/v1/search/autocomplete.` Suitable for e-commerce and content sites that want personalised relevance ranking trained on real user behaviour.

Example prompt: Upload 500 new products to Miso via POST `/v1/products` and verify the index returns them in a search for a relevant query

### Real-Time Recommendation Serving

Stream user interaction events via POST `/v1/interactions` so Miso's engines stay current, then call the Recommendation APIs to serve personalised results on product pages and home feeds. Reduces the data-engineering work needed to maintain a recommendations pipeline compared to building one in-house.

Example prompt: Send a 'product_detail_page_view' interaction for user_id 'u_42' on product_id 'p_99' and then fetch recommendations for that user

### Generative Q&A Over Product Catalogue

Use the Ask APIs to answer customer questions against the Miso-trained Q&A engine. Pair with the Search APIs to ground responses in actual catalogue content. Useful for storefront chat assistants where answers must reference real products.

Example prompt: Submit a question 'Which running shoes are best for trails under £100?' to the Miso Ask API and return the cited products

### AI Agent for Personalisation Operations

An agent integrated through Jentic can refresh the Miso catalogue when products change, monitor interaction throughput, and call recommendations for ad-hoc personalised emails - without holding the Secret API key. Jentic isolates the key in its vault and the agent uses Jentic's intent search to navigate the 26 Miso endpoints.

Example prompt: Through Jentic, refresh the Miso product catalogue from the latest CMS export and trigger a recommendation request for a sample user

## Key endpoints

| Method | Path | Description |
| --- | --- | --- |
| POST | `/v1/products` | Upload product or content records |
| POST | `/v1/products/_delete` | Bulk delete products |
| POST | `/v1/interactions` | Upload user interaction events |
| POST | `/v1/users` | Upload user records |
| POST | `/v1/search/search` | Run a personalised search |
| POST | `/v1/search/autocomplete` | Run autocomplete suggestions |
| POST | `/v1/search/mget` | Multi-get product details by IDs |
| POST | `/v1/experiments/{experiment_id_or_slug}/events` | Send an experiment event |

## Key resources

- **Products** — Upload, read, and delete catalogue products and content
- **Users** — Manage user records used for personalisation
- **Interactions** — Stream and delete user interaction events
- **Search** — Personalised search, autocomplete, and multi-get
- **Recommendations** — Generate recommendations for a user or context
- **Ask** — Run generative Q&A queries against the Miso engine
- **Experiments** — Send experiment events for A/B comparisons

## Why Jentic

- **Setup:** Wiring Miso by hand means handling its API-key query parameter across its recommendation, search, and interaction endpoints. Through Jentic you install once, import the Miso API from the API Directory, store the key once, and your agent calls it while Jentic appends the key.
- **Permission scoping:** Most Miso operations carry their target in the request body rather than a URL path, so limit the agent to the operations it needs, such as search or interaction tracking. You choose the operations it may call, so product deletion is not included unless you add it.
- **Credential handling:** Your Miso secret API key is stored once, encrypted, by your own Jentic One instance and appended as the api_key query parameter at execution time. It never enters the agent's prompt, logs, or context.
- **Discovery method:** Agents search Jentic by intent such as 'get Miso recommendations for a user', and Jentic returns the matching operation with its input schema so the agent calls the right endpoint without browsing the reference docs.

## Related APIs

- **Algolia** — Algolia is a managed search platform with broader index features; Miso emphasises ML-trained personalisation on top of search.
- **Meilisearch** — Meilisearch is a self-hostable open-source search engine, an alternative when Miso's personalisation is not needed.
- **Segment** — Segment captures user events from across the stack and can fan them out to Miso's interaction endpoints.

## FAQ

### What authentication does the Miso API use?

The API uses an api_key query parameter. Miso issues a Secret API Key for backend calls and a Publishable API Key for client-side use. When called through Jentic, the secret key is stored in your Jentic One instance and appended to requests at execution time.

### Can I run personalised search through the Miso API?

Yes. POST `/v1/search/search` runs a personalised search query, POST `/v1/search/autocomplete` provides typeahead suggestions, and POST `/v1/search/mget` retrieves multiple products by ID. All search results are ranked using the engine trained on your interactions and catalogue.

### How do I keep my Miso product catalogue in sync?

POST `/v1/products` uploads or updates product/content records, GET `/v1/products/{product_id}` reads a single product, and POST `/v1/products/_delete` handles bulk deletions. POST `/v1/products/_ids` returns the current list of indexed product IDs, useful for diffing against a CMS export.

### What are the rate limits for the Miso API?

The OpenAPI specification does not publish explicit rate limits. Miso is designed for high-throughput interaction ingestion - implement client-side batching for `/v1/interactions` and exponential backoff on HTTP 429 responses for search and recommendation calls.

### How do I stream user interactions through Jentic?

Search Jentic for 'send a Miso user interaction event' and POST `/v1/interactions` will be returned. Load the operation schema, supply the user_id, product_id, and interaction type, and execute. Jentic handles the api_key query parameter automatically.

### Can I limit what my agent is allowed to do with the Miso API?

Yes. Because you run Jentic One yourself, you decide which Miso operations your agent may call, so you can allow read and serving operations like POST `/v1/search/search`, POST `/v1/search/autocomplete`, and POST `/v1/interactions` while withholding destructive ones. Most Miso operations carry their target in the request body rather than a URL path, so scoping happens at the operation level: product deletion via POST `/v1/products/_delete` is only reachable if you explicitly grant it. Your own rules govern which operations and which stored credentials the agent can use, and the Miso secret API key stays out of the agent's prompt and logs.