Update an Article

Update an existing article in your channel.

URL

POST https://news-api.apple.com/articles/{articleId}

Path Parameters

Name	Type	Description
`articleId` Required	string	The UUID or the Share URL ID of the article you want to update.

Response Codes

Status	Reason	Type	Description
200	OK Content-Type: application/json	`ArticleResponse`	The request was successful. The server returns a warning for articles with a publication date before 2015.
202	Accepted Content-Type: application/json	`ArticleResponse`	The Apple News team optimized the article, so your updates weren’t applied. Contact your Apple News technical representative if you need to make updates.
400	Bad Request Content-Type: application/json	`Error`	`ARTICLE_TERRITORY_NOT_ALLOWED`. The channel doesn’t support the country code you provided, or the country code you provided is valid but isn’t an Apple News territory (US, UK, AU or CA). Key path: None. `DOES_NOT_EXIST.` The section you specified doesn’t exist. Key path: `data.links.sections.#`. `DUPLICATE_ARTICLE_FOUND`. An article with a source URL or a thumbnail is considered a duplicate if you post the article on the same channel, using the same title, source URL, or thumbnail, within a 24-hour period. An article without a source URL and thumbnail is considered a duplicate if you post the article on the same channel, using the same title, within a 24-hour period. The original article ID is provided in the `value` field. `INCORRECT_ENCODING`. The body of the request isn’t encoded with the encoding specified in `Content-Encoding`. Key path: None. `INCORRECT_HOST`. The section URL has the wrong hostname or port. Key path: `data.links.sections`.`#`. `INVALID_ARTICLE_LANGUAGE`. The language of the article doesn’t match the language of the channel. Key path: None. `INVALID_ARTICLE_TERRITORY`. A country code isn’t valid. Key path: None. `INVALID_DOCUMENT`. The JSON in the Apple News Format document (`article.json`) is invalid. Test `article.json` with News Preview first. Key path: None. `INVALID_MIME_MULTIPART`. The server can’t parse the request body as valid MIME-multipart. Key path: None. `INVALID_PUBLISHING_DATE`. The publication date of the article can’t be before 1970. Key path: `metadata.datePublished`. `INVALID_RESOURCE_TYPE`. The path in the section URL doesn’t start with /sections/. Key path: `data.links.sections.#`. `INVALID_RESOURCE_ID`. The section URL has a section ID that is not a valid UUID. Key path: data.links.sections.#. `INVALID_SCHEME`. The section `URL` must have the https scheme. Key path: `data`.`links.sections`.`#`. `INVALID_TYPE`. The value you specified for the article is not of the correct type for that field. Key path: `channelId`. `INVALID_URL` The section `URL` you specified is not a valid URL. Key path: `data.links.sections.#`. `MIME_PART_MISSING_FILENAME.` The specified MIME part doesn’t have the filename parameter in its `Content-Disposition` header. Key path: {`mime_part_name`}. `MIME_PART_TOO_SLOW`. The MIME part took too long to load from the request body. Key path: {`mime_part_name`}. `MIME_PART_TOO_LARGE`. The MIME part is larger than the allowable size limit. Images exceeding 20 MB, fonts exceeding 5 MB, and attachments exceeding 50 MB generate this error. Key path: {`file name}`. `MISSING`. The specified MIME part is required and was missing. Key path: {`mime_part_name}`. `MISSING`. You didn’t supply the article `UUID` field in the request. Key path: * `MISSING_RESOURCE_ID`. The section URL is missing the `section_id UUID`. Key path: `data`.`links`.`sections.#`. `NOT_ALLOWED`. The section you specified doesn’t belong to the given channel. Key path: `data`.`links.sections`.`#`. `ONLY_PREVIEW_ALLOWED`. This channel is currently allowed to publish preview articles only, but `isPreview` is `false`. Key path: None. `PUBLISHING_NOT_ALLOWED`. This channel is currently not allowed to publish articles. Key path: None. `REQUEST_BODY_TOO_LARGE`. The article bundle size is larger than the allowable size limit. An article bundle exceeding 450 MB generates this error. Key path: None. `UNSUPPORTED_ENCODING`. The encoding specified in `Content-Type` or `Content-Transfer-Encoding` isn’t supported. Key path: None. `WRONG_REVISION.` The revision specified doesn’t match the current revision, most likely because another call updated the article. Key path: `data.revision`.
401	Unauthorized Content-Type: application/json	`Error`	You didn’t include the `Authorization` header. Key path: None.
403	Forbidden Content-Type: application/json	`Error`	You tried to access a channel your API key doesn’t have permission to access. Key path: None.
404	Not Found Content-Type: application/json	`Error`	The endpoint you tried to access doesn’t exist. Key path: None. The article you tried to access doesn’t exist. Key path: `articleId`.
409	Conflict Content-Type: application/json	`Error`	The revision specified doesn’t match the current revision, most likely because another call updated the article. Key path: `data.revision`.
429	Too Many Requests Content-Type: application/json	`Error`	You exceeded the number of articles that you can update within the specific time window. The response header `<Retry-After: delay-seconds>` indicates the time in seconds you need to wait before sending a new update request.

Mentioned in

Apple News API Release Notes

Discussion

The Update an Article endpoint accepts a MIME multipart request, in multipart/form-data format, instead of JSON (application/json). In contrast to the Create an Article request, all parts of an Update an Article request are optional except for the metadata section. The Update an Article request may also include the article’s Apple News Format document or any of the resources referenced in the document with a bundle:// URL, each with its own MIME part.

For example, you can update a single image, the document text or layout, the metadata, or all of them at once. Other than the option to omit parts, the format of the Update an Article request is identical to the Create an Article request. Although you can omit MIME parts that you previously posted, you can’t partially update the Apple News Format document in the article.json. You can only replace it, not patch it.

If you remove a resource part in one update call and later decide you want to reference it in the article, you must upload the resource again (not just restore the reference).

Updating an article doesn’t change the timestamp of the article or its placement in your feeds, such as the Today feed, channel feeds, and topic feeds.

Here are the guidelines for updating an existing article:

For each update, provide the article ID and the revision token that matches the current revision of the article. This ensures that two users can’t update an article at the same time and lose data. If this happens, the client informs the second user (via the WRONG_REVISION error) that the specified revision was incorrect because the article was updated in the meantime. The second user must retrieve the new version before proceeding. The client can then attempt to merge the two versions and call Update an Article again, or can choose to overwrite the older version with the new version. To get the current revision, use the method call shown in Read Article Information, or use a revision ID from an earlier Create an Article or Update an Article call.
You must wrap all metadata fields in a data key. See “Example Code for Updating an Article with Metadata” below. The server returns the INVALID_JSON error if there is no data key in the request call.
Include isPreview in the metadata to allow an update call to change the article’s preview/published state. Additionally, on update, you can make a preview article public (change true to false), but you can’t set a currently public article back to a preview state (change false to true).
Use the isHidden property in the metadata to hide and unhide an article in the Update an Article request.

Example Code for Updating an Article Without Metadata

Example Code for Updating an Article with Metadata

HTTP Body

The article’s Apple News Format JSON document and other assets, like PDFs, images, and fonts.