---
title: "Create rule"
method: POST
path: "/rules"
tags: ["Rules"]
---

# Create rule

`POST /rules`

Creates a pronunciation rule in your organization.

## Request body

- RequestBodyRule
  - `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
  - `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
  - `project` object, nullable
    - `id` integer — Project ID to scope the rule to
  - `content` object, nullable
    - `id` string — Content ID to scope the rule to
  - `language` object, nullable
    - `code` string — Language code (ISO 639-1 with optional region, e.g., en_GB)

## Response `201`

successful

- 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)

---

[API](https://skmtc.net/beyondwords/apis/beyondwords-rest-api.md) · [All operations](https://skmtc.net/beyondwords/apis/beyondwords-rest-api/llms.txt) · [OpenAPI document](https://skmtc-service-staging.skmtc.workers.dev/v1/apis/beyondwords/beyondwords-rest-api/revisions/8c4bfe3e2ebd/schema)