Web Service Endpoint

Update an Article

Update an existing article in your channel.

URL

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

Path Parameters

articleId
string
(Required)

UUID of the article you want to update.

HTTP Body

form-data

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

Parts

Additional, non–Apple News Format data about the article. The metadata part can also specify any sections for the article by URL.

Any Key
binary

Assets, such as images.

article.json
string
(Required)

The Apple News Format document that contains this article’s content.

Response Codes

OK

The request was successful.

400 Bad Request
Bad Request
  • MIME_PART_TOO_SLOW. The MIME part took too long to load from the request body. Key path: {mime_part_name}.

  • INVALID_MIME_MULTIPART. The request body cannot be parsed as valid MIME-multipart. Key path: None.

  • MISSING. The specified MIME part is required and was missing. Key path: {mime_part_name}.

  • MIME_PART_MISSING_FILENAME. The specified MIME part does not have the filename parameter in its Content-Disposition header. Key path: {mime_part_name}.

  • INVALID_DOCUMENT. The JSON in the Apple News Format document (article.json) is invalid. Test article.json with News Preview first. Key path: None.

  • DOES_NOT_EXIST. The section you specified does not exist. Key path: data.links.sections.#.

  • MISSING. The Article UUID field was not supplied in the request. Key path: *

  • INVALID_TYPE. The value specified for the article is not of the correct type for that field. Key path: channelId.

  • WRONG_REVISION. The revision specified does not match the current revision, most likely because the article has been updated by another call. Key path: data.revision

  • NOT_ALLOWED. The section you specified does not belong to the given channel. Key path: data.links.sections.#

  • INVALID_ARTICLE_LANGUAGE.The language of the article does not match the language of the channel. Key path: None.

  • INVALID_URL The section URL you specified is not a valid URL. Key path: data.links.sections.#.

  • INVALID_SCHEME. The section URL must have the https scheme. Key path: data.links.sections.#.

  • INCORRECT_ENCODING. The body of the request is not 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_RESOURCE_TYPE. The path in the section URL does not 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_ARTICLE_TERRITORY. A country code is not valid. Key path: None.

  • ARTICLE_TERRITORY_NOT_ALLOWED. A country code is not supported by the channel. Key path: None.

  • MISSING_RESOURCE_ID. The section URL is missing the section_id UUID. Key path: data.links.sections.#.

  • ONLY_PREVIEW_ALLOWED. This channel is currently only allowed to publish preview articles, but isPreview is false. Key path: None.

  • PUBLISHING_NOT_ALLOWED. This channel is currently not allowed to publish articles. Key path: None.

  • TOO_LONG. The accessoryText field is longer than 100 characters. Key path: metadata.accessoryText.

  • UNSUPPORTED_ENCODING. The encoding specified in Content-Type or Content-Transfer-Encoding is not supported. Key path: None.

  • DUPLICATE_ARTICLE_FOUND. An article with the same title was published to the same channel within the last 24 hours.

401 Unauthorized
Unauthorized

The Authorization header was not supplied. Key path: None.

403 Forbidden
Forbidden

You tried to access a channel your API key does not have permission to access. Key path: None.

404 Not Found
Not Found
  • The endpoint you tried to access does not exist. Key path: None.

  • The article you tried to access does not exist. Key path: articleId.

409 Conflict
Conflict

The revision specified does not match the current revision, most likely because the article has been updated by another call. Key path: data.revision.

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 article request are optional except for the metadata section. The update 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 article request is identical to the create an article request. Although MIME parts that were previously posted can be omitted, the Apple News Format document in the article.json part cannot be partially updated. It can only be replaced, not patched.

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).

Here are the guidelines for updating an existing article:

  • Supply the revision metadata field that matches the current revision of the article on each update. This ensures that two users can’t update an article at the same time and lose data. If this happens, the second user is informed (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 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.

  • All metadata fields must be wrapped in a data key. See "Example Code for Updating an Article With Metadata," below. The INVALID_JSON error is returned if there is no data key in the request call.

  • Include isPreview in the metadata for the article’s preview/published state to be affected by an update call. Additionally, on update, you can make a preview article public (change true to false), but you cannot 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

POST /articles/a91760f1-c169-47d2-9fc4-a7711341264d HTTP/1.1Host: news-api.apple.comAccept: application/jsonContent-Type: multipart/form-data; boundary=535e329ca936f79a19ac9a251f7d48f7Content-Length: 94348Authorization: HHMAC; key="1e3gfc5e-e9f8-4232-a6be-17bf40edad09"; signature="gJYsk8qm+6wpONE8twX/yDlGRt0UzS7Qn32yHNpiwnM="; date="2015-03-05T03:00:27Z"--535e329ca936f79a19ac9a251f7d48f7Content-Type: application/jsonContent-Disposition: form-data; name=metadata{ "data": { "targetTerritoryCountryCodes": ["GB", "US"], "links": { "sections": [ "https://news-api.apple.com/sections/5cec0b36-529e-31bc-bc1e-3eaccbc15b97" ] }, "accessoryText": "by Luther J. Pellegrini", "revision": "AAAAAAAAAAAAAAAAAAAAeZ==" }}--535e329ca936f79a19ac9a251f7d48f7--

See Also

Articles

Create an Article

Publish an article to your channel.

Read Article Information

Retrieve information about an article, such as the revision number and maturity rating.

Search Articles in a Channel

See a list of all articles in a channel that match the specified search criteria.

Search Articles in a Section

See a list of all articles in a section that match the specified search criteria.

Delete an Article

Delete the specified article from your channel.

object Create Article Metadata Fields

See the optional metadata fields for the create article request.

object ArticleLinksRequest

See the required field for the create article request.

object Update Article Metadata Fields

See the metadata fields for the update article request.

object Article

See the fields returned by the article endpoints.

object ArticleResponse

See which objects make up the create article, read article, and update article responses.

object ArticleLinksResponse

See the links returned by the article endpoints.

object SearchResponse

See the fields returned by the search article endpoints.

object Meta

See the object that wraps the throttling information that's returned for the create article and read article endpoints.

object Throttling

See the object that wraps the throttling information that's returned for the create article and update article endpoints.