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

# Create pronunciation rule

> Creates a rule in a organization



## OpenAPI

````yaml post /rules
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:
    post:
      tags:
        - Rules
      summary: Create
      description: Creates a rule in a organization
      operationId: rules#create
      parameters: []
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/requestBodyRule'
            examples:
              example:
                $ref: '#/components/examples/requestRuleExample'
      responses:
        '201':
          description: successful
          content:
            application/json:
              examples:
                example:
                  $ref: '#/components/examples/ruleExample'
              schema:
                $ref: '#/components/schemas/ruleModel'
      security:
        - apiKey: []
components:
  schemas:
    requestBodyRule:
      type: object
      properties:
        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
        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
        project:
          type: object
          nullable: true
          properties:
            id:
              type: integer
              minimum: 1
              description: Project ID to scope the rule to
        content:
          type: object
          nullable: true
          properties:
            id:
              type: string
              description: Content ID to scope the rule to
        language:
          type: object
          nullable: true
          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
    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)
  examples:
    requestRuleExample:
      summary: Sample creation of a rule in a content item
      value:
        key: CO2
        value: carbon dioxide
        type: substitute
        project:
          id: 1
        content:
          id: d8414aee-4171-419e-be42-bd57e9e2ccd2
    ruleExample:
      summary: A sample rule response
      value:
        id: 1
        key: CO2
        value: Carbon dioxide
        type: substitute
        project:
          id: 1
          name: Test project
        content:
          id: d8414aee-4171-419e-be42-bd57e9e2ccd2
          title: >-
            Unveiling the Catastrophic Consequences of Excess Carbon Dioxide
            Emissions
        created: 2023-01-01 00:00:00 UTC
        updated: 2023-01-01 00:00:05 UTC
  securitySchemes:
    apiKey:
      type: apiKey
      name: X-Api-Key
      in: header

````