Skip to main content

Documentation Index

Fetch the complete documentation index at: https://doc.lucidworks.com/llms.txt

Use this file to discover all available pages before exploring further.

The Rules and Rewrites API for Commerce Studio enables you to create and manage merchandising rules and query rewrites programmatically. This API supports enterprise automation workflows, cross-environment synchronization, and integration with internal tools. This topic explains how to use this API. For complete details about all of its endpoints, methods, and parameters, see the Rules and Rewrites API reference.

​
When to use this API

The Rules and Rewrites API enables the following use cases:
  • Automate rule deployment: Create and update rules and rewrites through CI/CD (continuous integration/continuous deployment) pipelines or automated workflows.
  • Synchronize across environments: Maintain consistent rules and rewrites across development, QA (quality assurance), and production environments.
  • Manage rules at scale: Efficiently handle large rule sets that are impractical to manage through the UI (user interface) alone.
  • Fallback with version control: Fetch rules and rewrites, then commit them to your source control repository at intervals so you can easily revert to earlier versions if needed.
  • Integrate with AI agents: Use AI to automate creation and updates of rules and rewrites.
For visual rule creation and management, use the Commerce Studio UI. The API is designed for programmatic workflows where automation and integration are required.

​
Key concepts

​
Rule and rewrite identifiers

Every rule and rewrite has two ID fields that you can use interchangeably in API operations:
  • id: Automatically generated UUID (Universally Unique Identifier) assigned by the platform when you create a rule or rewrite. This identifier is unique within the Commerce Studio instance.
  • externalId: Optional user-defined identifier that you can assign when creating a rule or rewrite. This field enables you to maintain your own naming conventions and synchronize rules across multiple environments.
Use external IDs to maintain stable references across environments. For example, assign an external ID like promo-summer-2026 to ensure the same rule can be identified and updated consistently in development, QA, and production.
External IDs must be unique within a Commerce Studio instance. The API prevents duplicate external IDs to maintain rule integrity.

​
Authentication scopes

The API uses two separate authentication scopes:
  • commercestudio.rules: Required for rule operations (create, read, update, delete rules)
  • commercestudio.rewrites: Required for query rewrite operations (create, read, update, delete rewrites)
Request separate access tokens for each scope based on the operations you need to perform.

​
Rate limiting

Platform rate limits apply to all API requests to protect system stability. If you encounter rate limit errors, implement exponential backoff in your integration.

​
Use the Rules and Rewrites API

To use the API, you need a Lucidworks service account. Then you can gather your credentials and begin making API calls. For complete details about API endpoints, methods, and parameters, see the Commerce Studio Rules and Rewrites API reference.
If you don’t already have a Lucidworks service account whose type is “API”, follow the steps below to create one:
1
In Lucidworks Platform, go to Settings > Service Accounts.
2
Click Create New Service Account.
3
In the New Service Account window, be sure to select API as the service account type. Enter a name and optionally a description to help you remember what this account is for.
4
Click Create New Service Account. The new account appears in the list. You can click on the account you created to get the Client ID and Client Secret that you’ll need for accessing the API.
You’ll need the following information to access the API:
  • Commerce Studio ID: Your Commerce Studio instance identifier
  • Client ID: From your service account
  • Client Secret: From your service account
1

Find your Commerce Studio ID

Your Commerce Studio ID is part of your Commerce Studio URL. For example, if your Commerce Studio URL is https://COMMERCE_STUDIO_ID.experiencemanager.lucidworks.com, your Commerce Studio ID is COMMERCE_STUDIO_ID.
2

Get your service account credentials

In Lucidworks Platform, go to Settings > Service Accounts and click the service account you created. Copy the Client ID and Client Secret.
1

Fetch an access token

Before making API requests, you need to authenticate and obtain an access token.Send a POST request to the authentication endpoint:
curl --request POST \
  --url 'https://identity.lucidworks.com/oauth2/ausao8uveaPmyhv0v357/v1/token?scope=API_SCOPE&grant_type=client_credentials' \
  --header 'Accept: application/json' \
  --header 'Authorization: Basic [CLIENT_ID:CLIENT_SECRET_BASE64]' \
  --header 'Cache-Control: no-cache' \
  --header 'Content-Type: application/x-www-form-urlencoded'
Replace API_SCOPE with one or both of these (as a space-separated list):
  • commercestudio.rules for rule operations
  • commercestudio.rewrites for query rewrite operations
The Authorization header uses basic authentication with your base64-encoded client ID and client secret. You can encode your credentials using:
echo -n "CLIENT_ID:CLIENT_SECRET" | base64
Some HTTP clients perform the base64 encoding automatically when you provide the client ID as the username and client secret as the password.
A successful response returns:
{
  "token_type": "Bearer",
  "expires_in": 3600,
  "access_token": "YOUR_ACCESS_TOKEN",
  "scope": "commercestudio.rules"
}
2

Make API requests

Use the access token in the Authorization header of your API requests:
curl --request GET \
  --url 'https://{COMMERCE_STUDIO_ID}.experiencemanager.lucidworks.com/em-rules' \
  --header 'Authorization: Bearer YOUR_ACCESS_TOKEN'
Replace {COMMERCE_STUDIO_ID} with your Commerce Studio instance ID.
3

Refresh your token

Access tokens expire after 60 minutes.
Once you request a new token, the previous one is deleted even if it has not yet expired. All subsequent API calls must use the new token.