Edit an article translation
Edit an article translation, and get the whole row back.
/v1/help-centre/articles/{translation_id}Editor- Operation id
- patch_article
- Access
- A viewer is refused.
/v1/help-centre/articles/{translation_id}Edit an article translation, and get the whole row back.
Exactly six fields are editable: title, slug, visibility,
editorial_state, category_id and body. Any other key is refused
rather than ignored, so a write you thought you made cannot go missing.
Send only what changes. An omitted field is left alone. category_id is
the one field where an explicit null means something: it files the article
under nothing.
editorial_state is what publishes an article, and visibility is what
decides whether a visitor may read it. Both have to be right before it
appears on the public site.
Editing marks the article as locally edited. A later update from the original source will then be held as a conflict instead of overwriting your text.
The response is the same shape the read path serves, so a caller never has
to reconcile a partial write response against what it had. The slug it gets
back is the normalised one that was stored, and body_html is the freshly
derived render, or null if that derivation failed, which the read shape
already allows for and the render pass will fix without another request.
Tenancy: the request is scoped to one workspace, and the credential presented is what selects it. A caller with no membership in that workspace is refused with 404, which is indistinguishable from a workspace that does not exist.
Authorisation: editor, admin or owner. A viewer receives 403 insufficient_role.
Access: Authorization: Bearer carrying either a realm access token or an API key. A key must hold the help-centre-staff:write scope, and the workspace role of the person who owns it must meet the floor above.
A realm-issued access token, presented as Authorization: Bearer <token>. It acts as the person who signed in, and every operation resolves their workspace role live from the membership record.
In: header
Path Parameters
uuidQuery Parameters
Request Body
application/json
TypeScript Definitions
Use the request body type in TypeScript.
The six editable fields, and structurally nothing else (FR-100, AC-36a).
extra="forbid" is the enforcement: a general patch that happened to carry
vote_count or content_hash is refused by the model rather than filtered
by a handler, so the field set cannot be widened by forgetting to filter.
Every field is optional and "absent" is not "null". A caller changing only
the title must not clear the category. Absence is read from
model_fields_set, so category_id: null genuinely means file this
article under nothing, and it is the only field for which null is a value.
The enums are Literal rather than free strings so an unknown value is a
422 naming the field, instead of a database CHECK violation surfacing as a
500 several layers away.
Response Body
application/json
application/json
curl -X PATCH "https://example.com/v1/help-centre/articles/497f6eca-6276-4993-bfeb-53cbbbba6f08" \ -H "Content-Type: application/json" \ -d '{}'{ "article_id": "string", "translation_id": "string", "locale": "string", "title": "string", "slug": "string", "excerpt": "string", "container_path": "string", "url": "string", "position": 0, "promoted": true, "breadcrumbs": [ { "name": "string", "path": "string", "url": "string" } ], "updated_at": "2019-08-24T14:15:22Z", "published_at": "2019-08-24T14:15:22Z", "vote_count": 0, "vote_sum": 0, "visibility": "string", "editorial_state": "string", "source_visibility_raw": {}, "permission_group_id": "string", "user_segment_ids": [ "string" ], "outdated": true, "outdated_locales": [ "string" ], "missing_at_source_at": "2019-08-24T14:15:22Z", "locally_edited_at": "2019-08-24T14:15:22Z", "has_conflict": true, "conflict_seen_at": "2019-08-24T14:15:22Z", "body_html": "string", "body_markdown": "string", "body_format": "string", "sanitizer_version": "string", "sanitize_report": {}, "link_report": {}, "asset_report": {}, "source_status_raw": "string", "canonical_url": "string", "alternates": [ { "locale": "string", "url": "string" } ], "author_label": "string", "labels": [ "string" ], "source_url": "string", "source_created_at": "2019-08-24T14:15:22Z", "source_updated_at": "2019-08-24T14:15:22Z", "noindex": true}