Guides and Sample Code

Developer

Apple News API Reference

On This Page

Create Article

A Create Article request publishes a new article to a channel. This endpoint accepts a MIME multipart request, in multipart/form-data format, instead of JSON (application/json).

Publishing a New Article

To publish a new article:

Method

URL

POST

/channels/{channel_id}/articles

where channel_id is the UUID of the channel to publish this article to.

MIME Parts

Part

Required

Description

article.json

Yes

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

Content-type: application/json

{filename}

Sometimes

An additional part is required for each unique bundle bundle://URL in the Apple news format document.

Content-type: determined by the resource

Apple News Format Document and Resources

A Create Article request must consist of at least one MIME part that contains the article’s Apple News Format document. Additional parts are required for each resource referenced in the Apple News Format document with a bundle:// URL.

Each part must have a Content-Disposition header. The disposition must be form-data, and the filename parameter of Content-Disposition must be specified.

The part that contains the Apple News Format document must have filename set to article.json.

In resource parts, the filename parameter must match the path of the bundle:// URL in the Apple News Format document that references this file. For example, if the document references a URL of bundle://logo.png, there must be a MIME part with filename set to logo.png. For resource parts, the valid values for Content-Type are as follows:

  • image/jpeg

  • image/png

  • image/gif

  • application/octet-stream

Metadata

An optional metadata part can also be included, to provide additional non–Apple News Format data about the article.

The metadata part also specifies any sections for the article, by URL. See Sections.

Sections

Sections work as follows:

  • If links.sections is omitted, the article will be published to the channel’s default section.

  • To post an article to a section, see List Sections. To get information about a specific section, see Read Section to get the relevant section_id(s). See Example Request: Post Article with Metadata below.

  • To publish a standalone article outside of sections, set sections to [ ] (an empty array). Standalone articles will not appear in your channel, but they’ll still appear in topics and search results, and may appear in For You.

Metadata Fields

Field

Required

Description

links.sections

No

The URLs of the sections to which this article should be added. See Metadata for more information about how sections work.) By default, articles are added to the channel’s default section. If the article is reposted to a secondary section as opposed to updating the existing links.sections array in the original article, the new article will be given a separate article ID and will be considered a duplicate against the original article, never appearing in News.

isSponsored

No

Indicates whether this article consists of sponsored content for promotional purposes. Sponsored content must be marked as such; channels that do not follow this policy may be suspended.

When using isSponsored, if you do not want the sponsored article to appear in your channel’s feed, set sections to [] (an empty array).

Default value: false

isPreview

No

Indicates whether this article should be public (live) or should be a preview that is only visible to members of your channel. Set isPreview to false to publish the article right away and make it visible to all News users.

  • If your channel has not yet been approved to publish articles in Apple News Format, setting isPreview to false will result in an ONLY_PREVIEW_ALLOWED error.

  • Default value: true if your channel has not yet been approved to publish articles in Apple News Format; false if your channel has been approved.

accessoryText

No

Text to include below the article excerpt in the channel view, such as a byline or category label.

Maximum length: 100 characters.

Default value: metadata.authors from the Apple News Format article.

maturityRating

No

Indicates the viewing audience for the content. The types of audiences or ratings are KIDS, MATURE, and GENERAL. Note that a Mature rating indicates explicit content that is appropriate for a specific audience only.

Default value: null

isCandidateToBeFeatured

No

Indicates whether or not this article should be considered for featuring in News. See News Publisher Resources and Support for more information.

Default value: false

Fields Returned

Create Article requests return the same fields as those in Read Article responses, plus the following in a meta section.

Field

Type

Description

throttling.isThrottled

Boolean

A boolean value that indicates whether requests to this channel are currently being throttled. If true, this request is added to the queue to be processed later rather than immediately.

throttling.quotaAvailable

Integer

Number of additional article publish or update requests which could be submitted now before the system will begin throttling.

throttling.queueSize

Integer

Number of requests currently queued for later processing.

throttling.estimatedDelayInSeconds

Integer

Estimate of the number of seconds until this request begins processing.

When you create an article, be sure to retain the article id or self URL that’s returned in the response. You’ll need the article ID if you later decide to delete the article.

Links Returned

Create Article requests return the same links as those in Read Article responses.

Example Request

This is an example request to create an article.

  1. POST /channels/63a75491-2c4d-3530-af91-819be8c3ace0/articles HTTP/1.1
  2. Host: news-api.apple.com
  3. Accept: application/json
  4. Content-Type: multipart/form-data; boundary=535e329ca936f79a19ac9a251f7d48f7
  5. Content-Length: 94348
  6. Authorization: HHMAC; key="1e3gfc5e-e9f8-4232-a6be-17bf40edad09"; signature="gJYsk8qm+6wpONE8twX/yDlGRt0UzS7Qn32yHNpiwnM="; date="2015-03-05T03:00:27Z"
  7. --535e329ca936f79a19ac9a251f7d48f7
  8. Content-Type: application/json
  9. Content-Disposition: form-data; filename=article.json; name=article.json
  10. {
  11. ...,
  12. "components": [
  13. {
  14. "role": "photo",
  15. "URL": "bundle://mountain-lions.jpg",
  16. "caption": "Thanks to the record drought, mountain lions have begun to descend, sometimes into urban settings."
  17. "backgroundColor": "#FFFFFF",
  18. "opacity": 1,
  19. "fill": {
  20. "type": "image",
  21. "URL": "bundle://gradient.png"
  22. }
  23. }
  24. ],
  25. ...
  26. }
  27. --535e329ca936f79a19ac9a251f7d48f7
  28. Content-Type: image/jpeg
  29. Content-Disposition: form-data; filename=mountain-lions.jpg; name=my_image
  30. {binary content of mountain-lions.jpg}
  31. --535e329ca936f79a19ac9a251f7d48f7
  32. Content-Type: application/octet-stream
  33. Content-Disposition: form-data; filename=gradient.png; name=a_gradient
  34. {binary content of gradient.png}
  35. --535e329ca936f79a19ac9a251f7d48f7--

Example Response

This is an example response to a request to create an article.

  1. HTTP/1.1 201 OK
  2. Date: Thu, 05 Mar 2015 02:53:54 GMT
  3. Content-Type: application/json;charset=UTF-8
  4. Transfer-Encoding: chunked
  5. {
  6. "data": {
  7. "createdAt": "2015-03-05T02:57:59Z",
  8. "modifiedAt": "2015-03-05T02:57:59Z",
  9. "id": "a91760f1-c169-47d2-9fc4-a7711341264d",
  10. "type": "article",
  11. "shareUrl": "https://apple.news/ArRPpLPE9QXu3sehS0rvxvA",
  12. "links": {
  13. "channel": "https://news-api.apple.com/channels/63a75491-2c4d-3530-af91-819be8c3ace0",
  14. "self": "https://news-api.apple.com/articles/a91760f1-c169-47d2-9fc4-a7711341264d",
  15. "sections": [
  16. "https://news-api.apple.com/sections/0a468272-356f-3b61-afa3-c4f989954180"
  17. ]
  18. },
  19. "meta": {
  20. "throttling": {
  21. "isThrottled": true,
  22. "quotaAvailable": 0,
  23. "queueSize": 42,
  24. "estimatedDelayInSeconds”: 1260
  25. }
  26. },
  27. "document": {
  28. ...
  29. },
  30. "revision": "AAAAAAAAAAAAAAAAAAAAew==",
  31. "state": "PROCESSING",
  32. "accessoryText": null,
  33. "title": "Flother City Lions",
  34. "maturityRating": null,
  35. "warnings": [ ],
  36. "isCandidateToBeFeatured": false,
  37. "isSponsored": false,
  38. "isPreview": false
  39. }
  40. }

Example Request: Post Article with Metadata

This is an example request to create an article with metadata.

  1. POST /channels/63a75491-2c4d-3530-af91-819be8c3ace0/articles HTTP/1.1
  2. Host: news-api.apple.com
  3. Accept: application/json
  4. Content-Type: multipart/form-data; boundary=535e329ca936f79a19ac9a251f7d48f7
  5. Content-Length: 94348
  6. Authorization: HHMAC; key="1e3gfc5e-e9f8-4232-a6be-17bf40edad09"; signature="gJYsk8qm+6wpONE8twX/yDlGRt0UzS7Qn32yHNpiwnM="; date="2015-03-05T03:00:27Z"
  7. --535e329ca936f79a19ac9a251f7d48f7
  8. Content-Type: application/json
  9. Content-Disposition: form-data; name=metadata
  10. {
  11. "data": {
  12. "isCandidateToBeFeatured": "false",
  13. "isSponsored": true,
  14. "isPreview": true,
  15. "maturityRating": null,
  16. "accessoryText": "by Luther J. Pellegrini",
  17. "links": {
  18. "sections": [
  19. "https://news-api.apple.com/sections/0a468272-356f-3b61-afa3-c4f989954180",
  20. "https://news-api.apple.com/sections/5cec0b36-529e-31bc-bc1e-3eaccbc15b97"
  21. ]
  22. }
  23. }
  24. }
  25. --535e329ca936f79a19ac9a251f7d48f7
  26. Content-Type: application/json
  27. Content-Disposition: form-data; filename=article.json; name=article.json
  28. {
  29. ...,
  30. "components": [
  31. {
  32. "role": "photo",
  33. "URL": "bundle://mountain-lions.jpg",
  34. "caption": "Thanks to the record drought, mountain lions have begun to descend, sometimes into urban settings."
  35. "backgroundColor": "#FFFFFF",
  36. "opacity": 1,
  37. "fill": {
  38. "type": "image",
  39. "URL": "bundle://gradient.png"
  40. }
  41. }
  42. ],
  43. ...
  44. }
  45. --535e329ca936f79a19ac9a251f7d48f7
  46. Content-Type: image/jpeg
  47. Content-Disposition: form-data; filename=mountain-lions.jpg; name=my_image
  48. {binary content of mountain-lions.jpg}
  49. --535e329ca936f79a19ac9a251f7d48f7
  50. Content-Type: application/octet-stream
  51. Content-Disposition: form-data; filename=gradient.png; name=a_gradient
  52. {binary content of gradient.png}
  53. -535e329ca936f79a19ac9a251f7d48f7--

Example Response: Article Posted with Metadata

This is an example response to a request to create an article with metadata.

  1. HTTP/1.1 201 OK
  2. Date: Thu, 05 Mar 2015 02:53:54 GMT
  3. Content-Type: application/json;charset=UTF-8
  4. Transfer-Encoding: chunked
  5. {
  6. "data": {
  7. "createdAt": "2015-03-05T02:57:59Z",
  8. "modifiedAt": "2015-03-05T02:57:59Z",
  9. "id": "a91760f1-c169-47d2-9fc4-a7711341264d",
  10. "type": "article",
  11. "shareUrl": "https://apple.news/ArRPpLPE9QXu3sehS0rvxvA",
  12. "links": {
  13. "channel": "https://news-api.apple.com/channels/63a75491-2c4d-3530-af91-819be8c3ace0",
  14. "self": "https://news-api.apple.com/articles/a91760f1-c169-47d2-9fc4-a7711341264d",
  15. "sections": [
  16. "https://news-api.apple.com/sections/0a468272-356f-3b61-afa3-c4f989954180",
  17. "https://news-api.apple.com/sections/5cec0b36-529e-31bc-bc1e-3eaccbc15b97"
  18. ]
  19. },
  20. "meta": {
  21. "throttling": {
  22. "isThrottled": true,
  23. "quotaAvailable": 0,
  24. "queueSize": 42,
  25. "estimatedDelayInSeconds”: 1260
  26. }
  27. },
  28. "document": {
  29. ...
  30. },
  31. "revision": "AAAAAAAAAAAAAAAAAAAAew==",
  32. "state": "PROCESSING",
  33. "accessoryText": "by Luther J. Pellegrini",
  34. "title": "Flother City Lions",
  35. "maturityRating": null,
  36. "warnings": [ ],
  37. "isCandidateToBeFeatured": false,
  38. "isSponsored": true,
  39. "isPreview": true
  40. }
  41. }

Errors

Create Article requests return the errors shown in Common Errors, as well as these additional errors.

Code

Status

Description

INVALID_MIME_MULTIPART

400

The request body cannot be parsed as valid MIME-multipart.

Key path: N/A

MISSING

400

The specified MIME part is required and was missing.

Key path: {mime_part_name}

MIME_PART_TOO_LARGE

400

The specified MIME part is larger than 20 MB in size.

Key path: {mime_part_name}

MIME_PART_MISSING_FILENAME

400

The specified MIME part does not have the filename parameter in its Content-Disposition header.

Key path: {mime_part_name}

MIME_PART_TOO_SLOW

400

The specified MIME part took more than 60 seconds to transmit the request.

Key path: {mime_part_name}

INVALID_DOCUMENT

400

The JSON in the Apple News Format document (article.json) is invalid. Please test with News Preview first.

Key path: N/A

DOES_NOT_EXIST

400

The section you specified does not exist.

Key path: data.links.sections.#

NOT_ALLOWED

400

The section you specified does not belong to the given channel.

Key path: data.links.sections.#

INVALID_URL

400

The section URL you specified is not a valid URL.

Key path: data.links.sections.#

INVALID_SCHEME

400

The section URL must have the https scheme.

Key path: data.links.sections.#

INCORRECT_ENCODING

400

The body of the request is not encoded with the encoding specified in Content-Encoding.

Key path: N/A

INCORRECT_HOST

400

The section URL has the wrong hostname or port.

Key path: data.links.sections.#

INVALID_RESOURCE_TYPE

400

The path in the section URL does not start with /sections/.

Key path: data.links.sections.#

INVALID_RESOURCE_ID

400

The section URL has a section_id that is not a valid UUID.

Key path: data.links.sections.#

MISSING_RESOURCE_ID

400

The section URL is missing the section_id UUID.

Key path: data.links.sections.#

ONLY_PREVIEW_ALLOWED

400

This channel is currently only allowed to publish preview articles, but isPreview is false.

Key path: N/A

PUBLISHING_NOT_ALLOWED

400

This channel is currently not allowed to publish articles.

Key path: N/A

TOO_LONG

400

The accessoryText field is longer than 100 characters.

Key path: metadata.accessoryText

UNSUPPORTED_ENCODING

400

The encoding specified in Content-Type or Content-Transfer-Encoding is not supported.

Key path: N/A