> ## Documentation Index
> Fetch the complete documentation index at: https://docs.beyondwords.io/llms.txt
> Use this file to discover all available pages before exploring further.

# Match rule text

> Returns pronunciation rules that match the given text.



## OpenAPI

````yaml post /rules/matches
openapi: 3.0.1
info:
  title: BeyondWords REST API
  description: |-
    This is the documentation for the BeyondWords REST API.
              You can use this API to use BeyondWords programmatically.
              You can get your API Key and Project ID for each project in the Project settings tab in the BeyondWords
              <a href="https://dash.beyondwords.io/dashboard">dashboard</a>.
  version: 1.0.0
servers:
  - url: https://api.beyondwords.io/v1
security: []
paths:
  /rules/matches:
    post:
      tags:
        - Rules
      summary: Match rule text
      description: Returns pronunciation rules that match the given text.
      operationId: rules#matches
      parameters: []
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/requestBodyMatchesRule'
      responses:
        '200':
          description: successful
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ruleMatchesModel'
      security:
        - apiKey: []
components:
  schemas:
    requestBodyMatchesRule:
      type: object
      required:
        - project
        - segments
      properties:
        project:
          type: object
          properties:
            id:
              type: integer
              minimum: 1
              description: Project ID to evaluate rules against
        content:
          type: object
          properties:
            id:
              type: string
              description: Content ID to evaluate rules against
        rules:
          type: array
          description: A list of rule IDs to limit the evaluation to (optional)
          items:
            type: integer
            minimum: 1
        segments:
          type: object
          properties:
            uuid:
              type: string
              description: Unique identifier for the segment being evaluated
            text:
              type: string
              description: Plain text of the segment
            language:
              type: object
              properties:
                code:
                  type: string
                  description: Language code (ISO 639-1 with optional region, e.g., en_GB)
                  pattern: ^[a-z]{2}(_[A-Z]{2})?$
                  maxLength: 10
            voice:
              type: object
              nullable: true
              properties:
                id:
                  type: integer
                  minimum: 1
                  description: Voice ID to use when evaluating matches
    ruleMatchesModel:
      type: array
      items:
        type: object
        properties:
          uuid:
            type: string
          selected:
            type: array
            items:
              type: object
              properties:
                rule:
                  $ref: '#/components/schemas/ruleModel'
                start_index:
                  type: integer
                end_index:
                  type: integer
          discarded:
            type: array
            items:
              type: object
              properties:
                rule:
                  $ref: '#/components/schemas/ruleModel'
                start_index:
                  type: integer
                end_index:
                  type: integer
                discard_reason:
                  type: string
    ruleModel:
      type: object
      properties:
        id:
          type: integer
          description: Unique identifier for the rule
        project:
          type: object
          nullable: true
          properties:
            id:
              type: integer
              description: Project ID this rule belongs to
            name:
              type: string
              nullable: true
        content:
          type: object
          nullable: true
          properties:
            id:
              type: string
              description: Content ID this rule is scoped to (if any)
            title:
              type: string
              nullable: true
        type:
          type: string
          description: >-
            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
          enum:
            - substitute
            - say_as_word
            - say_as_letter_sequence
            - ipa_transcription
            - pinyin_transcription
            - jyutping_transcription
        preview_status:
          type: string
          enum:
            - processing
            - processed
            - error
          description: Status of preview generation for this rule
        language:
          type: object
          nullable: true
          properties:
            code:
              type: string
              description: Language code (ISO 639-1 with optional region, e.g., en_GB)
            name:
              type: string
              description: Human-readable language name
            accent:
              type: string
              nullable: true
              description: Regional accent variant (if available)
        preview_voice:
          type: object
          nullable: true
          properties:
            id:
              type: integer
              description: Voice ID used for preview generation
            name:
              type: string
              description: Voice display name
        preview_audio:
          type: object
          nullable: true
          properties:
            url:
              type: string
              description: URL to the generated preview audio
            content_type:
              type: string
              description: MIME type of the preview audio
            duration:
              type: number
              description: Duration (seconds) of the preview audio
        key:
          type: string
          description: The exact text to match in content when applying this rule
        value:
          type: string
          nullable: true
          description: Replacement text or phonetic transcription (depending on rule type)
        magic_ipa_used:
          type: boolean
          description: >-
            When true, the Magic IPA feature was used to generate the
            transcription
        created:
          type: string
          description: Time at which the object was created (ISO 8601)
        updated:
          type: string
          description: Time at which the object was updated (ISO 8601)
  securitySchemes:
    apiKey:
      type: apiKey
      name: X-Api-Key
      in: header

````