feat(API): align and improve API coverage across v2 endpoints

[Stefan Bruhns (sbruhns)]

A broad pass over the v2 spec to make documented behavior match the actual API. Every change reflects behavior the API already exhibits; no endpoint behavior is altered.

Response coverage

Every v2 operation now documents 401, 403, and (where applicable) 422 alongside the previously-documented 400/404/429. The 403 description on each operation calls out the required OAuth scope, the permission needed, and any account-feature requirement (e.g. Glossary, Webhooks, Job Templates, Over-the-Air Translations, Attachable Screenshots, Verification System, Advanced Workflows, Workflow, Batch Actions, Branching, Automation Job Creation, GitLab Sync, History).

Status-code corrections

• POST /projects/{project_id}/jobs/{id}/lock and .../unlock now document the 200 JSON response (was incorrectly listed as 204).
• GET /projects/{project_id}/locales/{locale_id}/downloads/{id} documents 410 Gone for expired downloads.

New request-body fields

Documents fields the API has been accepting but the spec did not list:

• Projects (create + update): smart_suggest_enabled, smart_suggest_use_glossary, smart_suggest_use_machine_translation, translation_keys_sort_collation, autocomplete_job_enabled, job_locking_enabled, cldr_version. default_encoding is now also accepted on create (it was previously only documented on update).
• Branches/create: base for chaining branches in the newer branching system.
• Locales (create + update): unverify_on_source_changes, language_ai_profile.
• Translations: minor_change on create + update; reviewed on create (was previously only on update).
• Keys (create + update): excluded_in_locales, format_value_type.
• Uploads/create: skip_automated_job_creation, figma_page_name, upload_meta_data.
• Automations (create + update): job_owner_id, include_only_updated_locales.
• ICU/skeleton: id as an alternative source of content (mutually exclusive with content).
• Search/in_account: project_ids to scope the search.

New query parameters

• Projects/list: q (with the name:<text> substring syntax), enum-tightened sort_by and filters.
• Translations/list: key_id and locale_id as filters equivalent to the nested-route forms.
• Jobs/list: states (multiple at once) and key_id.
• Jobs/show: include_figma_preview_attachment.
• Tags/list: only_system_tags (inverse of exclude_system_tags).
• Comments/list: tightened filters (read/unread) and order (asc/desc) to proper enums.
• Documents/list: q search.
• Notifications/list: last_days.
• Translation orders/list: translation_id filter.
• Account locales/list: page and per_page (pagination is supported by the endpoint).

Schema corrections

Fields the API emits are now declared in the corresponding schema:

• upload_batch: field renamed from state to status (matches the actual JSON payload); adds uploads_count.
• translation_order: field renamed from tag to tag_name.
• invitation: field renamed from project_role to project_roles (plural — the API emits an array).
• distribution: renamed distribution_preview schema to distribution_details; adds release_count, updated_at; marks deleted_at nullable.
• release: adds locale_codes (the form returned by list endpoints) and state (returned by show); clarifies that the full locales array is only returned by the show endpoint.
• automation: adds project_ids, job_owner_id, include_only_updated_locales.
• branch: adds the base field and a proper state enum (creating_branch, merging_branch, syncing_branch, merged, success, branch_error, merge_conflict).
• locale: adds language_ai_profile, and unverify_on_source_changes (returned only when the account feature is enabled).
• glossary: adds spaces. glossary_term: adds the parent glossary association.
• project_details: adds branch, autotranslate_overwrite_unverified_translations, autocomplete_job_enabled.
• job_details: adds locked and figma_preview_attachment; documents annotations as conditional on include_annotations=true.
• key_preview (shared by jobs, translations, versions, search, glossary terms, comments): adds data_type and tags.
• screenshot_marker: presentation is now typed as a JSON object with x, y, w, h (was incorrectly typed as a string).
• repo_sync: adds pr_branch.
• job_template and organization_job_template: add autotranslate_enabled. The organization variant also gets an optional source_locale_id.
• tag: adds system_tag.
• account_details: notes that roles is only returned when the account has the Bot Role beta feature enabled.

Enum tightening

Constraints the API enforces are now declared as enums in the spec:

• authorizations.scopes: read, write, orders.create, team.manage.
• Style guides: target_audience, grammatical_person, and vocabulary_type are constrained to fixed value sets.
• Branches merge/sync: strategy accepts use_main, use_branch, and the deprecated alias use_master.

Operation descriptions

Filled in gaps where the API does work the prior description did not mention:

• Asynchronous cascades on branches create/merge/sync, projects create with source_project_id, projects destroy, releases publish, webhooks test, and locale downloads create.
• Soft-delete semantics on job templates, projects, distributions.
• Default values (e.g. shares_translation_memory defaults to true on non-clone project creates).
• Feature-availability notes on every operation gated by a paid or beta feature.

[jablan]

please add the new parameter using a variable like the others.

[jablan]

are we sure not to add something that's not supposed to be exposed? perhaps corresponding features owners should be made aware and review?

perhaps this PR could be split into several smaller? e.g. low risk one (40x responses), new parameters, description changes...

[jablan]

not sure we should list 404 result

never mind, we already do, so it's not a time to raise this now.