API overview and authentication
Overview of MXP REST APIs and how to authenticate
All MXP services expose REST APIs over HTTP/HTTPS. This section documents the publicly consumed endpoints from each service.
Services with REST APIs
| Service | Base path | Port (local) | Description |
|---|---|---|---|
| Discovery | / | 8080 | Primary search, recommendations, autocomplete |
| VAIS C-API | / | 8082 | Google Retail API proxy — search, autocomplete, visual search |
| Vector Search | / | 8083 | Semantic embedding-based search |
| Recommendation System (predict) | / | 8084 | Real-time recommendation inference |
| Recommendation System (edit) | / | 8080 | Recommendation model configuration |
| Merch Rule Service | / | 8085 | Rule management API (also consumed by Merch Module UI) |
Authentication
MXP uses OAuth2 with Google IDP as the identity provider. The Auth Service validates tokens on behalf of all services.
Obtaining a token
curl -X POST https://oauth2.googleapis.com/token \
-d "grant_type=urn:ietf:params:oauth:grant-type:jwt-bearer" \
-d "assertion=<signed-jwt>"Using the token
Pass the bearer token in the Authorization header:
curl -X POST http://<discovery-host>/search \
-H "Authorization: Bearer <token>" \
-H "Content-Type: application/json" \
-d '{ ... }'Tenant context
Most endpoints require a tenant parameter (in the request body or as a query param) that identifies which tenant configuration to load. Tenant configurations are stored as JSON files in GCS under gs://<bucket>/<tenant-name>/.
Required per-tenant files:
| File | Purpose |
|---|---|
attribute_configuration.json | Field schema for the tenant's product catalog |
autocomplete_configuration.json | Autocomplete rules and boost settings |
crs_config.json | Cloud Retail Search configuration |
global_configuration.json | Global tenant settings |
user_group_configuration.json | User group and personalization settings |
API reference pages
- Search API — Discovery service: product search, autocomplete, visual search
- Recommendations API — Recommendation System predict service