---
title: "Create a query rewrite"
method: POST
path: "/query-rewrites"
tags: ["Query Rewrite Management"]
---

# Create a query rewrite

`POST /query-rewrites`

Create a query rewrite in Commerce Studio.

## Query parameters

- `fields` string[]

## Request body

- union
  - HeadTailQueryRewriteRequest — Replace underperforming queries with queries that produce higher click-through rates.
    - `description` string — Query rewrite description.
    - `externalId` string — An optional ID set by external users of the API at creation time. Cannot be changed after creation.
    - `published` boolean — Whether the rewrite is staged or published.
    - `type` 'HEAD_TAIL', required — Query rewrite type. Determines which schema applies.
    - `surfaceForm` string — The underperforming query to replace.
    - `outputs` string[] — Query phrases that produce higher click-through rates to replace the underperforming query.
  - MisspellingQueryRewriteRequest — Replace misspelled query terms with their spelling corrections for better search results.
    - `description` string — Query rewrite description.
    - `externalId` string — An optional ID set by external users of the API at creation time. Cannot be changed after creation.
    - `published` boolean — Whether the rewrite is staged or published.
    - `type` 'MISSPELLING', required — Query rewrite type. Determines which schema applies.
    - `surfaceForm` string — The misspelled query term to correct.
    - `outputs` string[] — Correct spellings of the query term.
  - PhraseQueryRewriteRequest — Known phrases are boosted when they appear in new queries. The `surfaceForm` indicates the phrase to boost.
    - `description` string — Query rewrite description.
    - `externalId` string — An optional ID set by external users of the API at creation time. Cannot be changed after creation.
    - `published` boolean — Whether the rewrite is staged or published.
    - `type` 'PHRASE', required — Query rewrite type. Determines which schema applies.
    - `surfaceForm` string — The phrase to boost when detected in queries.
  - RemoveWordsQueryRewriteRequest — Used to remove particular phrases from searches containing specified phrases.
    - `description` string — Query rewrite description.
    - `externalId` string — An optional ID set by external users of the API at creation time. Cannot be changed after creation.
    - `published` boolean — Whether the rewrite is staged or published.
    - `type` 'REMOVE_WORDS', required — Query rewrite type. Determines which schema applies.
    - `surfaceForm` string — The word or phrase to remove from the query.
    - `triggerPhrases` string[] — The surface form to remove from the query when the query also contains any of these phrases.
  - SynonymQueryRewriteRequest — Synonyms are used to expand queries so that they include all known synonyms of the query terms.
    - `description` string — Query rewrite description.
    - `externalId` string — An optional ID set by external users of the API at creation time. Cannot be changed after creation.
    - `published` boolean — Whether the rewrite is staged or published.
    - `type` 'SYNONYM', required — Query rewrite type. Determines which schema applies.
    - `surfaceForm` string — The query term to expand with synonyms.
    - `outputs` string[] — Synonym terms that should expand the query.
    - `direction` 'ONEWAY' | 'SYMMETRIC' — Oneway means that if the surface form is present in the query, the query will be expanded, replacing the surface form with each output in the expansion. Symmetric means this is also done for any output detected in a given query - the query is expanded and the output is replaced with the surface form in the expansion.

## Response `201`

Created

- union
  - HeadTailQueryRewriteSummary — Replace underperforming queries with queries that produce higher click-through rates.
    - `id` string, uuid — Entity ID.
    - `createdBy` string — User who created the entity.
    - `creationDate` string, date-time — Date when the entity was created.
    - `lastModifiedBy` string — User who last updated the entity.
    - `lastModified` string, date-time — Date when the entity was last updated.
    - `published` boolean — Whether the rewrite is staged or published.
    - `version` string, date-time — The version of this rewrite for synchronization purposes. Not the same as `lastModified`, and not used for `If-Match` in the API.
    - `stagingFusionSyncStatus` FusionSyncStatusV2Summary — Status of this content's synchronization.
      - `lastSyncedVersion` string, date-time — Version of this content that was last successfully synced.
      - `fusionVersion` string — Version received when the last successful sync was performed. This value comes from the underlying search engine's optimistic concurrency mechanism.
    - `liveFusionSyncStatus` FusionSyncStatusV2Summary — Status of this content's synchronization.
      - `lastSyncedVersion` string, date-time — Version of this content that was last successfully synced.
      - `fusionVersion` string — Version received when the last successful sync was performed. This value comes from the underlying search engine's optimistic concurrency mechanism.
    - `markedForDeletion` boolean — `True` if this rewrite is marked for deletion but has not yet been fully removed from the system. This should only show up as `true` in rare cases. The system is supposed to resolve this situation eventually. Rewrites in this state (`true`) should not show up in the listing endpoints (other than `GET` by ID) unless explicitly requested to be included. Intended for troubleshooting purposes.
    - `description` string — Rewrite description.
    - `externalId` string — An optional ID set by external users of the API at creation time. Cannot be changed after creation.
    - `migratedId` string — If this was originally migrated from another system, this field shows the ID of the original rewrite.
    - `type` 'HEAD_TAIL', required — Query rewrite type. Determines which schema applies.
    - `surfaceForm` string — The underperforming query to replace.
    - `outputs` string[] — Query phrases that produce higher click-through rates to replace the underperforming query.
  - MisspellingQueryRewriteSummary — Replace misspelled query terms with their spelling corrections for better search results.
    - `id` string, uuid — Entity ID.
    - `createdBy` string — User who created the entity.
    - `creationDate` string, date-time — Date when the entity was created.
    - `lastModifiedBy` string — User who last updated the entity.
    - `lastModified` string, date-time — Date when the entity was last updated.
    - `published` boolean — Whether the rewrite is staged or published.
    - `version` string, date-time — The version of this rewrite for synchronization purposes. Not the same as `lastModified`, and not used for `If-Match` in the API.
    - `stagingFusionSyncStatus` FusionSyncStatusV2Summary — Status of this content's synchronization.
      - `lastSyncedVersion` string, date-time — Version of this content that was last successfully synced.
      - `fusionVersion` string — Version received when the last successful sync was performed. This value comes from the underlying search engine's optimistic concurrency mechanism.
    - `liveFusionSyncStatus` FusionSyncStatusV2Summary — Status of this content's synchronization.
      - `lastSyncedVersion` string, date-time — Version of this content that was last successfully synced.
      - `fusionVersion` string — Version received when the last successful sync was performed. This value comes from the underlying search engine's optimistic concurrency mechanism.
    - `markedForDeletion` boolean — `True` if this rewrite is marked for deletion but has not yet been fully removed from the system. This should only show up as `true` in rare cases. The system is supposed to resolve this situation eventually. Rewrites in this state (`true`) should not show up in the listing endpoints (other than `GET` by ID) unless explicitly requested to be included. Intended for troubleshooting purposes.
    - `description` string — Rewrite description.
    - `externalId` string — An optional ID set by external users of the API at creation time. Cannot be changed after creation.
    - `migratedId` string — If this was originally migrated from another system, this field shows the ID of the original rewrite.
    - `type` 'MISSPELLING', required — Query rewrite type. Determines which schema applies.
    - `surfaceForm` string — The misspelled query term to correct.
    - `outputs` string[] — Correct spellings of the query term.
  - PhraseQueryRewriteSummary — Known phrases are boosted when they appear in new queries. The `surfaceForm` indicates the phrase to boost.
    - `id` string, uuid — Entity ID.
    - `createdBy` string — User who created the entity.
    - `creationDate` string, date-time — Date when the entity was created.
    - `lastModifiedBy` string — User who last updated the entity.
    - `lastModified` string, date-time — Date when the entity was last updated.
    - `published` boolean — Whether the rewrite is staged or published.
    - `version` string, date-time — The version of this rewrite for synchronization purposes. Not the same as `lastModified`, and not used for `If-Match` in the API.
    - `stagingFusionSyncStatus` FusionSyncStatusV2Summary — Status of this content's synchronization.
      - `lastSyncedVersion` string, date-time — Version of this content that was last successfully synced.
      - `fusionVersion` string — Version received when the last successful sync was performed. This value comes from the underlying search engine's optimistic concurrency mechanism.
    - `liveFusionSyncStatus` FusionSyncStatusV2Summary — Status of this content's synchronization.
      - `lastSyncedVersion` string, date-time — Version of this content that was last successfully synced.
      - `fusionVersion` string — Version received when the last successful sync was performed. This value comes from the underlying search engine's optimistic concurrency mechanism.
    - `markedForDeletion` boolean — `True` if this rewrite is marked for deletion but has not yet been fully removed from the system. This should only show up as `true` in rare cases. The system is supposed to resolve this situation eventually. Rewrites in this state (`true`) should not show up in the listing endpoints (other than `GET` by ID) unless explicitly requested to be included. Intended for troubleshooting purposes.
    - `description` string — Rewrite description.
    - `externalId` string — An optional ID set by external users of the API at creation time. Cannot be changed after creation.
    - `migratedId` string — If this was originally migrated from another system, this field shows the ID of the original rewrite.
    - `type` 'PHRASE', required — Query rewrite type. Determines which schema applies.
    - `surfaceForm` string — The phrase to boost when detected in queries.
    - `wordCount` integer — Number of words in the phrase. This is only a very basic whitespace-delimited token count.
  - RemoveWordsQueryRewriteSummary — Used to remove particular phrases from searches containing specified phrases.
    - `id` string, uuid — Entity ID.
    - `createdBy` string — User who created the entity.
    - `creationDate` string, date-time — Date when the entity was created.
    - `lastModifiedBy` string — User who last updated the entity.
    - `lastModified` string, date-time — Date when the entity was last updated.
    - `published` boolean — Whether the rewrite is staged or published.
    - `version` string, date-time — The version of this rewrite for synchronization purposes. Not the same as `lastModified`, and not used for `If-Match` in the API.
    - `stagingFusionSyncStatus` FusionSyncStatusV2Summary — Status of this content's synchronization.
      - `lastSyncedVersion` string, date-time — Version of this content that was last successfully synced.
      - `fusionVersion` string — Version received when the last successful sync was performed. This value comes from the underlying search engine's optimistic concurrency mechanism.
    - `liveFusionSyncStatus` FusionSyncStatusV2Summary — Status of this content's synchronization.
      - `lastSyncedVersion` string, date-time — Version of this content that was last successfully synced.
      - `fusionVersion` string — Version received when the last successful sync was performed. This value comes from the underlying search engine's optimistic concurrency mechanism.
    - `markedForDeletion` boolean — `True` if this rewrite is marked for deletion but has not yet been fully removed from the system. This should only show up as `true` in rare cases. The system is supposed to resolve this situation eventually. Rewrites in this state (`true`) should not show up in the listing endpoints (other than `GET` by ID) unless explicitly requested to be included. Intended for troubleshooting purposes.
    - `description` string — Rewrite description.
    - `externalId` string — An optional ID set by external users of the API at creation time. Cannot be changed after creation.
    - `migratedId` string — If this was originally migrated from another system, this field shows the ID of the original rewrite.
    - `type` 'REMOVE_WORDS', required — Query rewrite type. Determines which schema applies.
    - `surfaceForm` string — The word or phrase to remove from the query.
    - `triggerPhrases` string[] — The surface form to remove will be removed from the query when the query also contains any of these phrases.
  - SynonymQueryRewriteSummary — Synonyms are used to expand queries so that they include all known synonyms of the query terms.
    - `id` string, uuid — Entity ID.
    - `createdBy` string — User who created the entity.
    - `creationDate` string, date-time — Date when the entity was created.
    - `lastModifiedBy` string — User who last updated the entity.
    - `lastModified` string, date-time — Date when the entity was last updated.
    - `published` boolean — Whether the rewrite is staged or published.
    - `version` string, date-time — The version of this rewrite for synchronization purposes. Not the same as `lastModified`, and not used for `If-Match` in the API.
    - `stagingFusionSyncStatus` FusionSyncStatusV2Summary — Status of this content's synchronization.
      - `lastSyncedVersion` string, date-time — Version of this content that was last successfully synced.
      - `fusionVersion` string — Version received when the last successful sync was performed. This value comes from the underlying search engine's optimistic concurrency mechanism.
    - `liveFusionSyncStatus` FusionSyncStatusV2Summary — Status of this content's synchronization.
      - `lastSyncedVersion` string, date-time — Version of this content that was last successfully synced.
      - `fusionVersion` string — Version received when the last successful sync was performed. This value comes from the underlying search engine's optimistic concurrency mechanism.
    - `markedForDeletion` boolean — `True` if this rewrite is marked for deletion but has not yet been fully removed from the system. This should only show up as `true` in rare cases. The system is supposed to resolve this situation eventually. Rewrites in this state (`true`) should not show up in the listing endpoints (other than `GET` by ID) unless explicitly requested to be included. Intended for troubleshooting purposes.
    - `description` string — Rewrite description.
    - `externalId` string — An optional ID set by external users of the API at creation time. Cannot be changed after creation.
    - `migratedId` string — If this was originally migrated from another system, this field shows the ID of the original rewrite.
    - `type` 'SYNONYM', required — Query rewrite type. Determines which schema applies.
    - `surfaceForm` string — The query term to expand with synonyms.
    - `outputs` string[] — Synonym terms that should expand the query.
    - `direction` 'ONEWAY' | 'SYMMETRIC' — `ONEWAY` means that if the surface form is present in the query, the query will be expanded, replacing the surface form with each output in the expansion. `SYMMETRIC` means this is also done for any output detected in a given query; the query is expanded and the output is replaced with the surface form in the expansion.

---

[API](https://skmtc.dev/lucidworks/apis/rules-rewrites-api.md) · [All operations](https://skmtc.dev/lucidworks/apis/rules-rewrites-api/llms.txt) · [OpenAPI document](https://skmtc-service-production.skmtc.workers.dev/v1/apis/lucidworks/rules-rewrites-api/revisions/f2d3747848e8/schema)