openapi: 3.0.1
info:
  title: Coveo Activity Activities Synonym API
  description: API for Coveo Platform
  termsOfService: https://www.coveo.com/en/support/terms-agreements
  contact:
    name: Coveo
    url: https://connect.coveo.com/s/discussions
  version: 1.0.0
servers:
- url: https://platform.cloud.coveo.com
  description: Coveo public API endpoint
security:
- oauth2:
  - full
tags:
- name: Synonym
paths:
  /rest/organizations/{organizationId}/commerce/v2/search/synonyms/{synonymId}:
    get:
      tags:
      - Synonym
      summary: Get a Synonym Rule.
      description: 'Retrieves a synonym rule.</br></br>**Required privilege:** Merchandising Hub - View<br /><br /><details><summary>Privilege required</summary>

        ```

        {"owner":"COMMERCE","targetDomain":"MERCHANDISING_HUB","type":"VIEW","targetId":"*"}

        ```

        </details>'
      operationId: getSynonym
      parameters:
      - name: organizationId
        in: path
        description: The unique identifier of the target [organization](https://docs.coveo.com/en/185/).<br />**Example:** `acmecorporation8tp8wu3`
        required: true
        schema:
          type: string
      - name: trackingId
        in: query
        description: The unique identifier of the tracking target.
        required: true
        schema:
          type: string
        example: acmecorporation_ca
      - name: synonymId
        in: path
        description: A UUID identifying the synonym rule.
        required: true
        schema:
          type: string
          format: uuid
        example: 58bb4b98-1daa-4767-8c15-90a0ea67645c
      responses:
        '200':
          description: OK
          content:
            '*/*':
              schema:
                $ref: '#/components/schemas/SynonymModel'
      x-pretty-name: getSynonym
      x-required-privilege:
        owner: COMMERCE
        targetDomain: MERCHANDISING_HUB
        type: VIEW
        targetId: '*'
      x-required-privileges:
      - owner: COMMERCE
        targetDomain: MERCHANDISING_HUB
        type: VIEW
        targetId: '*'
      x-ui-operation-id: /rest/organizations/paramId/commerce/v2/search/synonyms/paramId_get
    put:
      tags:
      - Synonym
      summary: Edit Synonym Rule
      description: 'Updates a synonym rule.</br></br>**Required privilege:** Merchandising Hub - Edit<br /><br /><details><summary>Privilege required</summary>

        ```

        {"owner":"COMMERCE","targetDomain":"MERCHANDISING_HUB","type":"EDIT","targetId":"{trackingId}"}

        ```

        </details>'
      operationId: editSynonym
      parameters:
      - name: organizationId
        in: path
        description: The unique identifier of the target [organization](https://docs.coveo.com/en/185/).<br />**Example:** `acmecorporation8tp8wu3`
        required: true
        schema:
          type: string
      - name: trackingId
        in: query
        description: The unique identifier of the tracking target.
        required: true
        schema:
          maxLength: 255
          minLength: 1
          type: string
        example: acmecorporation_ca
      - name: synonymId
        in: path
        description: A UUID identifying the synonym rule.
        required: true
        schema:
          type: string
          format: uuid
        example: 58bb4b98-1daa-4767-8c15-90a0ea67645c
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/SynonymModel'
        required: true
      responses:
        '200':
          description: OK
          content:
            '*/*':
              schema:
                $ref: '#/components/schemas/SynonymModel'
      x-pretty-name: editSynonym
      x-required-privilege:
        owner: COMMERCE
        targetDomain: MERCHANDISING_HUB
        type: EDIT
        targetId: '{trackingId}'
      x-required-privileges:
      - owner: COMMERCE
        targetDomain: MERCHANDISING_HUB
        type: EDIT
        targetId: '{trackingId}'
      x-ui-operation-id: /rest/organizations/paramId/commerce/v2/search/synonyms/paramId_put
    delete:
      tags:
      - Synonym
      summary: Delete Synonym Rule.
      description: 'Deletes a synonym rule.</br></br>**Required privilege:** Merchandising Hub - Edit<br /><br /><details><summary>Privilege required</summary>

        ```

        {"owner":"COMMERCE","targetDomain":"MERCHANDISING_HUB","type":"EDIT","targetId":"{trackingId}"}

        ```

        </details>'
      operationId: deleteSynonym
      parameters:
      - name: organizationId
        in: path
        description: The unique identifier of the target [organization](https://docs.coveo.com/en/185/).<br />**Example:** `acmecorporation8tp8wu3`
        required: true
        schema:
          type: string
      - name: trackingId
        in: query
        description: The unique identifier of the tracking target.
        required: true
        schema:
          type: string
        example: acmecorporation_ca
      - name: synonymId
        in: path
        description: A UUID identifying the synonym rule.
        required: true
        schema:
          type: string
          format: uuid
        example: 58bb4b98-1daa-4767-8c15-90a0ea67645c
      responses:
        '204':
          description: No Content
      x-pretty-name: deleteSynonym
      x-required-privilege:
        owner: COMMERCE
        targetDomain: MERCHANDISING_HUB
        type: EDIT
        targetId: '{trackingId}'
      x-required-privileges:
      - owner: COMMERCE
        targetDomain: MERCHANDISING_HUB
        type: EDIT
        targetId: '{trackingId}'
      x-ui-operation-id: /rest/organizations/paramId/commerce/v2/search/synonyms/paramId_delete
  /rest/organizations/{organizationId}/commerce/v2/search/synonyms:
    get:
      tags:
      - Synonym
      summary: List Synonym Rules
      description: 'List synonym rules.</br></br>**Required privilege:** Merchandising Hub - View<br /><br /><details><summary>Privilege required</summary>

        ```

        {"owner":"COMMERCE","targetDomain":"MERCHANDISING_HUB","type":"VIEW","targetId":"*"}

        ```

        </details>'
      operationId: listSynonyms
      parameters:
      - name: organizationId
        in: path
        description: The unique identifier of the target [organization](https://docs.coveo.com/en/185/).<br />**Example:** `acmecorporation8tp8wu3`
        required: true
        schema:
          type: string
      - name: trackingId
        in: query
        description: The unique identifier of the tracking target.
        required: true
        schema:
          maxLength: 255
          minLength: 1
          type: string
        example: acmecorporation_ca
      - name: language
        in: query
        description: An ISO 639-1 language code.
        required: false
        schema:
          pattern: ^[a-z]{2}$
          type: string
        example: en
      - name: country
        in: query
        description: An ISO 3166-1 alpha-2 country code.
        required: false
        schema:
          pattern: ^[A-Z]{2}$
          type: string
        example: US
      - name: currency
        in: query
        description: An ISO 4217 currency code.
        required: false
        schema:
          pattern: ^[A-Z]{3}$
          type: string
        example: USD
      - name: query
        in: query
        description: Filter on search term (query expression) when requesting rules.
        required: false
        schema:
          type: string
        example: mens shoes
      - name: action
        in: query
        description: 'The synonym rule type. Possible values are: one-way, two-way, and one-way-reverse.'
        required: false
        schema:
          type: string
        example: one-way
      - name: sort
        in: query
        description: property.direction to sort by.
        required: false
        schema:
          type: string
        example: query.asc
      - name: page
        in: query
        description: The 0-based index number of the page of rules to retrieve.</br>**Minimum:** `0`</br>**Default:** `0`
        required: false
        schema:
          minimum: 0
          type: integer
          format: int32
          default: 0
      - name: perPage
        in: query
        description: The number of rules to list per page.</br>**Minimum:** `1`</br>**Maximum:** `1000`</br>**Default:** `10`
        required: false
        schema:
          maximum: 1000
          minimum: 1
          type: integer
          format: int32
          default: 10
      responses:
        '200':
          description: OK
          content:
            '*/*':
              schema:
                $ref: '#/components/schemas/CommercePageModelSynonymModel'
      x-pretty-name: listSynonyms
      x-required-privilege:
        owner: COMMERCE
        targetDomain: MERCHANDISING_HUB
        type: VIEW
        targetId: '*'
      x-required-privileges:
      - owner: COMMERCE
        targetDomain: MERCHANDISING_HUB
        type: VIEW
        targetId: '*'
      x-ui-operation-id: /rest/organizations/paramId/commerce/v2/search/synonyms_get
    post:
      tags:
      - Synonym
      summary: Create a Synonym Rule
      description: 'Persists a synonym rule.</br></br>**Required privilege:** Merchandising Hub - Edit<br /><br /><details><summary>Privilege required</summary>

        ```

        {"owner":"COMMERCE","targetDomain":"MERCHANDISING_HUB","type":"EDIT","targetId":"{trackingId}"}

        ```

        </details>'
      operationId: createSynonym
      parameters:
      - name: organizationId
        in: path
        description: The unique identifier of the target [organization](https://docs.coveo.com/en/185/).<br />**Example:** `acmecorporation8tp8wu3`
        required: true
        schema:
          type: string
      - name: trackingId
        in: query
        description: The unique identifier of the tracking target.
        required: true
        schema:
          maxLength: 255
          minLength: 1
          type: string
        example: acmecorporation_ca
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/SynonymModel'
        required: true
      responses:
        '201':
          description: Created
          content:
            '*/*':
              schema:
                $ref: '#/components/schemas/SynonymModel'
      x-pretty-name: createSynonym
      x-required-privilege:
        owner: COMMERCE
        targetDomain: MERCHANDISING_HUB
        type: EDIT
        targetId: '{trackingId}'
      x-required-privileges:
      - owner: COMMERCE
        targetDomain: MERCHANDISING_HUB
        type: EDIT
        targetId: '{trackingId}'
      x-ui-operation-id: /rest/organizations/paramId/commerce/v2/search/synonyms_post
components:
  schemas:
    RuleLocaleModel:
      type: object
      properties:
        language:
          type: string
          description: An ISO 639-1 language code.
          example: en
        country:
          type: string
          description: An ISO 3166-1 alpha-2 country code.
          example: US
        currency:
          type: string
          description: An ISO 4217 currency code.
          example: USD
      description: The list of locales the synonym applies to. When empty, the synonym applies to all locales.
      example:
      - language: en
        country: US
        currency: USD
    CommercePageModelSynonymModel:
      required:
      - items
      - totalEntries
      - totalPages
      type: object
      properties:
        items:
          type: array
          description: The retrieved page of items.
          items:
            $ref: '#/components/schemas/SynonymModel'
        totalEntries:
          type: integer
          description: The total number of results that match the query.
          format: int64
        totalPages:
          type: integer
          description: The total number of pages of items available.
          format: int32
      description: Page
    SynonymModel:
      required:
      - action
      - from
      type: object
      properties:
        id:
          type: string
          description: A UUID identifying the synonym rule.
          format: uuid
          readOnly: true
          example: 58bb4b98-1daa-4767-8c15-90a0ea67645c
        action:
          type: string
          description: 'The synonym rule type. Possible values are: one-way, two-way, and one-way-reverse.'
          example: one-way
          enum:
          - one-way
          - two-way
          - replace
          - exact-match
        from:
          minItems: 1
          type: array
          description: The search terms contained in the output query if matched against a synonym rule.
          example:
          - sandals
          - sneakers
          items:
            type: string
            description: The search terms contained in the output query if matched against a synonym rule.
            example: '["sandals","sneakers"]'
        to:
          type: array
          description: The search terms contained in the input query.
          example:
          - shoes
          - heels
          items:
            type: string
            description: The search terms contained in the input query.
            example: '["shoes","heels"]'
        locales:
          type: array
          description: The list of locales the synonym applies to. When empty, the synonym applies to all locales.
          example:
          - language: en
            country: US
            currency: USD
          items:
            $ref: '#/components/schemas/RuleLocaleModel'
        updatedAt:
          type: string
          description: The date and time at which the synonym was last updated.
      description: The synonym rule to persist.
  securitySchemes:
    oauth2:
      type: oauth2
      flows:
        authorizationCode:
          authorizationUrl: https://platform.cloud.coveo.com/oauth/authorize
          tokenUrl: https://platform.cloud.coveo.com/oauth/token
          scopes:
            full: required