Update an article
Example request
Generated- cURL
- JavaScript
- TypeScript
- Python
- PHP
- Go
- Java
- Ruby
- C#
Responses
Updates the supplied fields and leaves the rest untouched. The path accepts a comma-separated list of article ids to apply the same change to several articles at once.
To make sure you are not overwriting somebody else’s newer save, send back the content_token you read, as expected_content_token (top level for the default language, on a multilingual entry for the others) or in an If-Match header. If anyone has saved that language since, working copies included, the article is left unchanged and the request answers 409. Read the article again and reapply your change. Without either, the update applies as it always has. A guarded update answers with the new content_token of each article it wrote.
A token guards a language’s content, so it must name a language the update writes: top-level fields write the default language, a multilingual entry writes its own. One that guards nothing the update writes, such as a token sent with only article fields (category_id, is_published, is_featured) or a default-language token sent with only a translation’s entry, is refused with 400. If a working copy is pending, the live version’s token is refused with 409: read with working_copy=true and send that token to replace the working copy.
Authentication
-
-
ApiKeyBearerhttpbearerAn API key sent as
Authorization: Bearer <key>. A key holds scopes, the same ones OAuth uses, and an operation needs the scope listed for it under OAuth2. A key may also expire, or be revoked or rotated in Settings > API, after which it is refused with a 401.
-
-
-
OAuth2oauth2An OAuth 2.0 access token for an app acting on behalf of a HelpDocs user, sent as
Authorization: Bearer <token>. The authorization code flow requires PKCE (S256). Each operation names the one scope it needs.
-
Path parameters
-
article_idstring Required
Query parameters
-
working_copybooleanSave to the unpublished working copy instead of publishing the change.
Header parameters
-
If-MatchstringOne or more comma-separated entity-tags of the form “::”, as the ETag header of a single-article read gives them. Each guards that language of that article, so one header can guard every article of a multi-id update. A tag for an article not in the path is refused with 400, as is a header whose only tags for an article name languages the request does not write: top-level fields are the default language’s, a translation’s changes go in a multilingual entry, and an update of article fields alone writes no language.
Request body Required
The fields to change. Anything omitted is left as it is.
application/json
UpdateArticleRequest
-
user_idstring NullableNull is the same as leaving the field out.
-
category_idstring NullableNull is the same as leaving the field out.
-
show_tocboolean NullableNull is the same as leaving the field out.
-
is_privateboolean NullableNull is the same as leaving the field out.
-
is_publishedboolean NullableNull is the same as leaving the field out.
-
is_featuredboolean NullableNull is the same as leaving the field out.
-
related_article_idsarray of string NullableNull is the same as leaving the field out.
-
related_autoboolean NullableNull is the same as leaving the field out.
-
is_archivedboolean NullableNull is the same as leaving the field out.
-
archive_reasonstring NullableNull is the same as leaving the field out.
-
iconstring NullableNull is the same as leaving the field out.
-
permission_groupsarray of string NullableNull is the same as leaving the field out.
-
language_codestring -
titlestring NullableNull is the same as leaving the field out.
-
descriptionstring NullableNull is the same as leaving the field out.
-
short_versionstring NullableNull is the same as leaving the field out.
-
bodystring NullableNull is the same as leaving the field out.
-
slugstring NullableNull is the same as leaving the field out.
-
tagsarray of string NullableNull is the same as leaving the field out.
-
is_liveboolean NullableNull is the same as leaving the field out.
-
editor_typestring NullableNull is the same as leaving the field out.
-
machine_translated_atstring (date-time) NullableNull is the same as leaving the field out.
-
expected_content_tokenstring NullableNull is the same as leaving the field out.
-
Null is the same as leaving the field out.
-
Null is the same as leaving the field out.
{
"user_id": "string",
"category_id": "string",
"show_toc": true,
"is_private": true,
"is_published": true,
"is_featured": true,
"related_article_ids": [
"string"
],
"related_auto": true,
"is_archived": true,
"archive_reason": "string",
"icon": "string",
"permission_groups": [
"string"
],
"language_code": "string",
"title": "string",
"description": "string",
"short_version": "string",
"body": "string",
"slug": "string",
"tags": [
"string"
],
"is_live": true,
"editor_type": "string",
"machine_translated_at": "2024-01-15T09:30:00Z",
"expected_content_token": "string",
"multilingual": [
{
"language_code": "string",
"title": "string",
"description": "string",
"short_version": "string",
"body": "string",
"slug": "string",
"tags": [
"string"
],
"is_live": true,
"editor_type": "string",
"machine_translated_at": "2024-01-15T09:30:00Z",
"expected_content_token": "string"
}
],
"stale_status": {
"is_stale": true,
"source": "string",
"reason": "string",
"expires_at": "2024-01-15T09:30:00Z"
}
}
Generated from the schema
Responses
Every article the update touched.
application/json
ArticleUpdatedResponse
The request was rejected: a required field is missing from the body, or a value in it is not acceptable.
text/plain
The failure, as a human-readable message.
-
string
The failure, as a human-readable message.
Authentication failed or no API key was supplied.
application/json
Error
An error response.
-
codeinteger RequiredThe HTTP status code.
-
errstring RequiredA human-readable description of the failure.
The account’s billing is past due and writes are locked. Reads keep working; editing resumes once billing is settled.
application/json
Error
An error response.
-
codeinteger RequiredThe HTTP status code.
-
errstring RequiredA human-readable description of the failure.
The key lacks write permission, or the account’s plan does not include API access.
application/json
Error
An error response.
-
codeinteger RequiredThe HTTP status code.
-
errstring RequiredA human-readable description of the failure.
No such resource in this account, or article_id does not match the pattern this route accepts.
text/plain
The failure, as a human-readable message.
-
string
The failure, as a human-readable message.
An article in the request has been saved since the content_token you sent, so it was not changed, or the article is archived or needs an approved review. On a multi-id update the other articles may have been written: articles lists them.
text/plain
The failure, as a human-readable message.
-
string
The failure, as a human-readable message.
Rate limited. Wait the number of seconds in Retry-After before trying again. X-RateLimit-Limit, X-RateLimit-Remaining and X-RateLimit-Reset say which allowance was spent and when it refills.
-
Retry-Afterinteger -
X-RateLimit-Limitinteger -
X-RateLimit-Remaininginteger -
X-RateLimit-Resetinteger
application/json
Error
An error response.
-
codeinteger RequiredThe HTTP status code.
-
errstring RequiredA human-readable description of the failure.