---
title: "Match rule text"
method: POST
path: "/rules/matches"
tags: ["Rules"]
---

# Match rule text

`POST /rules/matches`

## Request

- Base URL: `https://api.beyondwords.io/v1`
- URL: `https://api.beyondwords.io/v1/rules/matches`
- Auth: API key in header `X-Api-Key`

Returns pronunciation rules that match the given text.

## Request body

- RequestBodyMatchesRule
  - `project` object, required
    - `id` integer: Project ID to evaluate rules against
  - `content` object
    - `id` string: Content ID to evaluate rules against
  - `rules` integer[]: A list of rule IDs to limit the evaluation to (optional)
  - `segments` object, required
    - `uuid` string: Unique identifier for the segment being evaluated
    - `text` string: Plain text of the segment
    - `language` object
      - `code` string: Language code (ISO 639-1 with optional region, e.g., en_GB)
    - `voice` object, nullable
      - `id` integer: Voice ID to use when evaluating matches

## Response `200`

successful

- object[]
  - `uuid` string
  - `selected` object[]
    - `rule` RuleModel
      - `id` integer: Unique identifier for the rule
      - `project` object, nullable
        - `id` integer: Project ID this rule belongs to
        - `name` string, nullable
      - `content` object, nullable
        - `id` string: Content ID this rule is scoped to (if any)
        - `title` string, nullable
      - `type` 'substitute' | 'say_as_word' | 'say_as_letter_sequence' | 'ipa_transcription' | 'pinyin_transcription' | 'jyutping_transcription': The rule type. Possible values are `substitute`, `say_as_word`, `say_as_letter_sequence`, `ipa_transcription`, `pinyin_transcription`, `jyutping_transcription`. Please note that not all voices support all rules
      - `preview_status` 'processing' | 'processed' | 'error': Status of preview generation for this rule
      - `language` object, nullable
        - `code` string: Language code (ISO 639-1 with optional region, e.g., en_GB)
        - `name` string: Human-readable language name
        - `accent` string, nullable: Regional accent variant (if available)
      - `preview_voice` object, nullable
        - `id` integer: Voice ID used for preview generation
        - `name` string: Voice display name
      - `preview_audio` object, nullable
        - `url` string: URL to the generated preview audio
        - `content_type` string: MIME type of the preview audio
        - `duration` number: Duration (seconds) of the preview audio
      - `key` string: The exact text to match in content when applying this rule
      - `value` string, nullable: Replacement text or phonetic transcription (depending on rule type)
      - `magic_ipa_used` boolean: When true, the Magic IPA feature was used to generate the transcription
      - `created` string: Time at which the object was created (ISO 8601)
      - `updated` string: Time at which the object was updated (ISO 8601)
    - `start_index` integer
    - `end_index` integer
  - `discarded` object[]
    - `rule` RuleModel
      - `id` integer: Unique identifier for the rule
      - `project` object, nullable
        - `id` integer: Project ID this rule belongs to
        - `name` string, nullable
      - `content` object, nullable
        - `id` string: Content ID this rule is scoped to (if any)
        - `title` string, nullable
      - `type` 'substitute' | 'say_as_word' | 'say_as_letter_sequence' | 'ipa_transcription' | 'pinyin_transcription' | 'jyutping_transcription': The rule type. Possible values are `substitute`, `say_as_word`, `say_as_letter_sequence`, `ipa_transcription`, `pinyin_transcription`, `jyutping_transcription`. Please note that not all voices support all rules
      - `preview_status` 'processing' | 'processed' | 'error': Status of preview generation for this rule
      - `language` object, nullable
        - `code` string: Language code (ISO 639-1 with optional region, e.g., en_GB)
        - `name` string: Human-readable language name
        - `accent` string, nullable: Regional accent variant (if available)
      - `preview_voice` object, nullable
        - `id` integer: Voice ID used for preview generation
        - `name` string: Voice display name
      - `preview_audio` object, nullable
        - `url` string: URL to the generated preview audio
        - `content_type` string: MIME type of the preview audio
        - `duration` number: Duration (seconds) of the preview audio
      - `key` string: The exact text to match in content when applying this rule
      - `value` string, nullable: Replacement text or phonetic transcription (depending on rule type)
      - `magic_ipa_used` boolean: When true, the Magic IPA feature was used to generate the transcription
      - `created` string: Time at which the object was created (ISO 8601)
      - `updated` string: Time at which the object was updated (ISO 8601)
    - `start_index` integer
    - `end_index` integer
    - `discard_reason` string

## Changes

- **2026-11-03** `994b9853e685`: 1 info
  - endpoint added

[Operation history](https://skmtc.dev/beyondwords/apis/beyondwords-rest-api/changes/rules/matches/post.md)

---

[API](https://skmtc.dev/beyondwords/apis/beyondwords-rest-api.md) - [All operations](https://skmtc.dev/beyondwords/apis/beyondwords-rest-api/llms.txt) - [OpenAPI document](https://skmtc.dev/beyondwords/apis/beyondwords-rest-api/revisions/994b9853e685?raw)