Document style profiles and style_profile_id on /v2/translate and /v2/document

[lawl-dev]

Adds API reference documentation for the /v3/style_profiles endpoints and for style_profile_id on POST /v2/translate and POST /v2/document, plus a Using Style Profiles guide under Customize.

A style profile bundles your other customizations, glossaries, style rule lists and translation memories, behind a single style_profile_id, so one ID stands for a whole translation configuration instead of a list of individual parameters.

Endpoints documented

Method	Path	Scope
GET	/v3/style_profiles	style_profiles:read
GET	/v3/style_profiles/{style_profile_id}	style_profiles:read
POST	/v3/style_profiles	style_profiles:write
PATCH	/v3/style_profiles/{style_profile_id}	style_profiles:write
DELETE	/v3/style_profiles/{style_profile_id}	style_profiles:write

Behavior called out in the descriptions

• The list includes style profiles shared with the account, not only those it owns
• Creation is atomic. If a referenced component ID cannot be used, no profile is created, and the 400 message names the list the bad ID was passed in
• PATCH is open to the owner and to accounts the profile was shared with for editing. It leaves absent fields unchanged. An empty string clears description and industry, an empty name is a 400, and each component list that is sent replaces that linked set in full
• DELETE returns 204 No Content and only unlinks the bundled glossaries, style rule lists and translation memories. They are not deleted. Deleting a component removes it from every profile that links it
• Only the owner can delete a style profile. One that was shared with the account, and that the account can list and retrieve, returns 404 on delete, the same status as an unknown ID
• glossary_priority_order_enabled makes the order of glossary_ids decide which glossary wins when two define the same source term. Without it the order has no effect
• 456 when the account has reached its style profile limit, and 403 when the plan does not include creating style profiles
• At most one style rule list per target language, and at most one translation memory per source language. Sending two for the same language is a 400

style_profile_id on POST /v2/translate

• Accepted in JSON and form-encoded bodies
• The profile is applied per text once the source language is known. Components that do not fit a text's language pair are left out without an error
• Cannot be combined with glossary_id, glossary_ids, style_id, translation_memory_id, translation_memory_threshold or custom_instructions (400)
• An unknown or inaccessible profile returns 404

style_profile_id on POST /v2/document

• The profile is applied once the document's source language is known. Components that do not fit the language pair are left out without an error
• Cannot be combined with glossary_id, glossary_ids, style_id, translation_memory_id or translation_memory_threshold (400)
• An unknown or inaccessible profile is accepted at upload; the document status then reports Style profile not found.

Changes

• api-reference/openapi.yaml: the two paths, the ManageStyleProfiles tag, the StyleProfile and StyleProfileId schemas, style_profile_id on both POST /v2/translate request bodies, and style_profile_id on POST /v2/document
• api-reference/openapi.json: regenerated with yq -o=json '.' api-reference/openapi.yaml > api-reference/openapi.json
• api-reference/style-profiles/: five endpoint pages
• docs.json: a Style Profiles group under Customize, next to the other customization resources
• docs/customize/using-style-profiles.mdx: how-to guide (create, translate, glossary priority, update, limits), linked from the Customize nav
• docs/customize/overview.mdx: a style profiles row in the customization table

A question for the reviewer

Field character limits are stated in prose in the field descriptions rather than encoded as maxLength or maximum in the schema, following the OpenAPI conventions in CLAUDE.md.

Worth a second opinion, though: the neighboring customization endpoints do encode their limits in the schema, so the spec now reads two ways depending on which resource you look at. Would you rather these fields match the neighbors, or keep them as they are and treat this as the pattern to move toward? Happy to change it either way, just say which.

Verification

• yq parses the YAML and every new $ref resolves. The regenerated JSON is identical to the previous one apart from the additions
• mint broken-links passes; the guide's links resolve
• mint broken-links --check-anchors reports the same six pre-existing anchors as main and nothing new

Opened as a draft because the endpoints are not released yet. Includes the changes from #439 and #440.

Replaces #424, which was opened from a fork. The Convert YAML specs to JSON workflow checks the branch out of this repository, so it can never resolve a fork's head ref and failed on every commit there. Pushed to a branch here instead.

[mintlify]

Preview deployment for your docs. Learn more about Mintlify Previews.

Project	Status	Preview	Updated
deepl-c950b784	🟢 Ready	View Preview	Oct 13, 2026, 2:39 PM

💡 Tip: Enable Automations to automatically generate PRs for you.