> ## 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.

# Rules and Rewrites API

The Rules and Rewrites API for Commerce Studio enables you to create and manage merchandising [rules](/docs/lw-platform/lw-cs/cstudio-rules) and [query rewrites](/docs/lw-platform/lw-cs/cstudio-query-rewrite) 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](/api-reference/rule-management/list-rules).

## 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.

<Note>
  For visual rule creation and management, use the Commerce Studio UI.
  The API is designed for programmatic workflows where automation and integration are required.
</Note>

## 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.

<Tip>
  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.
</Tip>

<Warning>
  External IDs must be unique within a Commerce Studio instance.
  The API prevents duplicate external IDs to maintain rule integrity.
</Warning>

### Authentication scopes

The API uses two separate authentication scopes:

* `commercestudio.rules`: Required for [rule](/docs/lw-platform/lw-cs/cstudio-rules) operations (create, read, update, delete rules)
* `commercestudio.rewrites`: Required for [query rewrite](/docs/lw-platform/lw-cs/cstudio-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](/api-reference/rule-management/list-rules).

<AccordionGroup>
  <Accordion title="Create a service account">
    If you don't already have a Lucidworks service account whose type is "API", follow the steps below to create one:

    <Steps>
      <Step>
        In Lucidworks Platform, go to **Settings** > **Service Accounts**.
      </Step>

      <Step>
        Click **Create New Service Account**.
      </Step>

      <Step>
        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.
      </Step>

      <Step>
        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.
      </Step>
    </Steps>
  </Accordion>

  <Accordion title="Gather your credentials">
    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

    <Steps>
      <Step title="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`.
      </Step>

      <Step title="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**.
      </Step>
    </Steps>
  </Accordion>

  <Accordion title="Access the API">
    <Steps>
      <Step title="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:

        ```bash theme={"dark"}
        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:

        ```bash theme={"dark"}
        echo -n "CLIENT_ID:CLIENT_SECRET" | base64
        ```

        <Note>
          Some HTTP clients perform the base64 encoding automatically when you provide the client ID as the username and client secret as the password.
        </Note>

        A successful response returns:

        ```json theme={"dark"}
        {
          "token_type": "Bearer",
          "expires_in": 3600,
          "access_token": "YOUR_ACCESS_TOKEN",
          "scope": "commercestudio.rules"
        }
        ```
      </Step>

      <Step title="Make API requests">
        Use the access token in the `Authorization` header of your API requests:

        ```bash theme={"dark"}
        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.
      </Step>

      <Step title="Refresh your token">
        Access tokens expire after 60 minutes.

        <Warning>
          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.
        </Warning>
      </Step>
    </Steps>
  </Accordion>
</AccordionGroup>