When integrating Tweakwise into your systems, you can interact with our APIs to control your setup. We provide two interfaces for these backend operations: the legacy Backend API (designed specifically for catalog management) and the new App API (designed for complete instance configuration).
Note: This article focuses exclusively on instance management. For frontend storefront queries (like search and recommendations), please refer to the Delivery API documentation.
Transition Backend API to App APIIf you have an existing integration using the legacy Backend API, you should migrate to the new App API. This ensures your integration is future-proofed and grants you access to all newly developed features and configurations.
Implementation
Both APIs are designed for backend operations, but they handle different scopes of your Tweakwise architecture.
- Backend API (Legacy): Originally designed specifically for managing your catalog (products and categories). While fully functional for these specific tasks, this API is in maintenance mode. It will not receive new endpoints or updates.
- App API: This is our modern, comprehensive instance management API. It encompasses all existing catalog management endpoints from the legacy backend, plus every new configuration feature we build. You use this for managing your entire instance, including advanced settings like Recommendation configurations.
Follow these steps to configure your integration:
Step 1: Choose Your Base URL
We strongly advise routing all new backend configuration and instance management requests to the App API.
- App API URL (Recommended):
https://app-api.tweakwise.com - Legacy Backend API URL:
https://navigator-api.tweakwise.com
Step 2: Set Up Authentication
Authentication is exactly the same for both the Legacy management endpoints and the App API.
Authorization is handled via your unique instancekey and access token.
Important Considerations
- Feature Availability: Newly developed management capabilities and configurations are exclusively released on the App API architecture.
- Migration: Your existing legacy endpoints will continue to work. However, to leverage new features, you must point new development to
app-api.tweakwise.com. - Delivery API Distinction: Do not confuse these management APIs with the Delivery API. The App API handles configurations and raw data management, whereas the Delivery API is strictly for optimized frontend storefront requests.
Extending Capabilities with Model Context Protocol (MCP)
We currently utilize a Model Context Protocol (MCP) for our internal operations, but you have the flexibility to build your own skills and autonomous agents.
By leveraging the App API endpoints, our OpenAPI specification files, and our technical documentation detailing model relations, you can create custom agents that natively interact with your Tweakwise instance. This allows you to automate complex configurations—such as dynamically generating recommendation models or managing catalog states—through your own AI-driven tooling.
FAQ
Will my current Instance Key work on the new App API?
Yes. Authentication is identical across both APIs. Simply pass your existing instanceKey as a query parameter.
Do I need to immediately rewrite my existing backend integration to use the App API?
No. Your existing calls to the Legacy Backend API will continue to function without interruption. However, to access new features, you must use the App API.
Where do I find documentation for configuring new features on the App API?
All endpoints are documented in our main reference. Check out specific modules like Recommendations to see how the App API allows you to configure advanced functionalities.
How do I start building custom skills and agents via MCP?
Use our provided OpenAPI spec files in combination with the App API and our model relations documentation. Your agents can parse these specs to understand endpoint capabilities and data structures to securely interact with your Tweakwise instance.