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

# Core Concepts

This page explains the data model behind the Style Guide API and how Style Guides, Rules, and Content Groups relate
to each other and to TMS projects.

<Note>
  **New integrations should use the v2 endpoints** (`POST /api/v2/styleguides`, `PUT /api/v2/styleguides/{id}`). They
  accept a `contentGroupId` parameter that links the Style Guide to a Content Group and unlocks automatic rule
  application in TMS projects.
</Note>

## Style Guides

A Style Guide is a Markdown document that captures writing guidelines for a specific language — tone, grammar rules,
terminology, and formatting conventions. An organization can have one Style Guide per Content Group and language.

Key properties:

* **Language** — BCP-47 locale code (e.g., `en-GB`, `sv-SE`). Each Style Guide is scoped to exactly one language.
* **Name and description** — human-readable metadata updated on every revision.
* **Content Group** — link to a Content Group (see below). Required when using v2 endpoints.

## Versions

Every time a new Markdown file is uploaded to a Style Guide, a new version is created. Versions are immutable
snapshots — you cannot edit a version's file after creation, only supersede it with a new upload.

Each version records:

| Field                                   | Description                                                                       |
| --------------------------------------- | --------------------------------------------------------------------------------- |
| `versionNumber`                         | Monotonically increasing integer                                                  |
| `name` / `description`                  | Metadata at the time of upload                                                    |
| `changeNotes`                           | Optional free-text summary of what changed (`versionChangeReason` on the request) |
| `fileName`, `fileSizeBytes`, `fileType` | File metadata                                                                     |

The Style Guide's top-level `name`, `description`, and `lastModifiedAt` always reflect the latest version.

## Rules

A Rule is a single writing instruction — for example, "Avoid passive voice in all user-facing content.". Rules are
used by AI Translation Agent and MT Optimize evaluate to improve translation quality.

### Origins

Rules come from two sources:

| Origin        | How it works                                                                                                                                                       |
| ------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| **Extracted** | Automatically generated when a Style Guide is created or updated. Each distinct guideline in the Markdown file becomes a separate Rule, linked to the Style Guide. |
| **Manual**    | Created directly via `POST /api/v1/rules`. Useful for rules that don't belong to any Style Guide, or for adding guidelines incrementally.                          |

### Scope

Each Rule carries two independent scope dimensions:

**Content Group scope** — which Content Groups this rule applies to:

* `allContentGroups: true` — rule applies across every Content Group in the organization.
* `allContentGroups: false` + non-empty `contentGroupIds` — rule applies only to the listed Content Groups.

**Language scope** — which languages this rule applies to:

* `allLanguages: true` — rule applies to translations in every language.
* `allLanguages: false` + non-empty `languages` — rule applies only to the listed locale codes.

### Lifecycle

Extracted Rules start out linked to their source Style Guide (`styleGuide` field is populated). A Rule becomes
**unlinked** (standalone) when a `PATCH /api/v1/rules/{id}` request does either of the following:

* Edits the rule text.
* **Changes** the content group or language scope in any way — including narrowing it, broadening it, or switching
  to `allContentGroups: true` / `allLanguages: true`. Resubmitting the exact same scope the rule already has is
  not a change and does not unlink it.

Because unlinking is permanent, `PATCH /api/v1/rules/{id}` requires you to confirm it explicitly: if the update
would unlink the rule and the request does not set `forceUnlink: true`, the API returns `409 Conflict`
(`RULE_UNLINK_REQUIRES_CONFIRMATION`) and applies none of the requested changes. Retry the same request with
`forceUnlink: true` to proceed. See [Working with Rules](/en/api/style-guides/rules) for an example.

Unlinking turns the rule into a manual rule. The original Style Guide is unchanged.

**When a new Style Guide version is uploaded**, every rule still linked to that Style Guide is deleted and replaced
by the freshly extracted set. Only rules that were already **unlinked** beforehand (via a prior `forceUnlink: true`
edit) survive a new version upload as standalone rules. If the updated Style Guide file still contains an
equivalent guideline, the newly extracted rule can duplicate one of these surviving standalone rules. Review
standalone rules that originated from a Style Guide after uploading a new version, and remove any that now
duplicate a freshly extracted rule.

### Active and AI check flags

Each Rule has two toggles:

* `active` — disabled rules are excluded from all checks and are not used by AI Translation Agent or MT Optimize.
* `aiCheckEnabled` — when `false`, the rule is excluded from AI-powered Quality Assurance checks but is still used
  by AI Translation Agent and MT Optimize.

## Content Groups

A Content Group is an identifier managed by the **Content Group API** (a separate service). It is a broader Platform
concept that is used to organize Assets and Projects across logical groups. In case of Style Guides, a content
group acts as a shared reference point that connects Style Guides and their Rules to TMS projects.

Content Groups are created and managed outside this API. The Style Guide API accepts a Content Group ID as an opaque
string — use the Content Group API to create and list groups.

## How Everything Connects

```
Style Guide (language: en-GB)
  ├── linked to → Content Group "marketing"
  └── source of → Rules (each scoped to Content Group "marketing", language en-GB)

TMS Project
  └── linked to → Content Group "marketing"
        └── at translation time, applies all active Rules where:
              contentGroupIds contains "marketing" (or allContentGroups = true)
              AND languages contains job language (or allLanguages = true)
```

### TMS project integration

In previous versions of the API, a TMS project had to be linked to a Style Guide per target language. With Content
Groups, the workflow changes:

1. Create a Style Guide with a `contentGroupId` (v2 endpoint).
2. Link the TMS project to the same Content Group (via TMS project settings).
3. When a translation job runs, the AI Translation Agent and MT Optimize automatically pick up all active Rules
   whose content group and language scope match the job's Content Group and target language.

This means a single Content Group can aggregate Rules from multiple Style Guides across languages, and one Style
Guide can serve multiple projects through a shared Content Group.

<Tip>
  Rule changes — whether made directly via the Rules API or triggered by uploading a new Style Guide version — take
  effect immediately for any running jobs in that Content Group. To avoid unintended effects on in-flight
  translations, make rule changes when no jobs for that Content Group are active. You can update and review rules
  before starting new jobs to verify they produce the expected results.
</Tip>

## Summary

| Resource      | Scope                                                | Created by                              |
| ------------- | ---------------------------------------------------- | --------------------------------------- |
| Style Guide   | One per Content Group & language per organization    | API upload (v1 or v2)                   |
| Version       | One per file upload                                  | Automatic on Style Guide create/update  |
| Rule          | Many per Style Guide; standalone rules also possible | Automatic extraction or manual creation |
| Content Group | Organization-wide                                    | Content Group API                       |

For step-by-step API usage, see [Working with Rules](/en/api/style-guides/rules) and the **API Documentation** section in the left navigation.