Web Service Endpoint

Create an Article

Publish an article to your channel.

URL

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

Path Parameters

channelId
string
(Required)

UUID of the channel to publish the article to.

HTTP Body

form-data

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

Parts

You can include an optional metadata to provide 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 and fonts. Images can have image/png, image/gif, image/jpeg, or application/octet-stream as the content type. Fonts should have application/octet-stream as the content type.

article.json
string

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

Response Codes

201 Created
Created

The article was created successfully.

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 the article.json file 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_ARTICLE_LANGUAGE.The language of the article does not match the language of the channel. Key path: None

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

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

  • 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 allowed to publish only 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 channel you want to add an article to does not exist. Key path: channelId.

Discussion

Use the Create an Article endpoint to publish an article to your channel.

Here are the guidelines for Apple News Format documents and resources:

  • A Create Article request must consist of at least one MIME part that contains the article’s Apple News Format document. This part must have filename set to article.json. See Example Code for Creating an Article Without Metadata.

  • Additional parts are required for each resource referenced in the Apple News Format document that uses a URL in this format: 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.

  • 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 image/jpeg, image/png, image/gif, and application/octet-stream.

  • When using a remote image, the URL must be in http:// or https:// format. No additional parts are required for remote images.

See Apple News API Tutorial to learn how to publish an article using the Apple News API.

Here are the guidelines for Apple News Format metadata:

  • An optional metadata part can be included to provide additional non–Apple News Format data about the article, such as isSponsored and maturityRating. See Create Article Metadata Fields. The metadata part can also specify any sections for the article, by URL.

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

Here are the guidelines for Apple News Format sections:

  • To publish the article to the channel's default section, omit links.sections.

  • To get information about a specific section, such as the section ID, use the Read Section Information endpoint.

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

Here are general guidelines for Apple News Format:

  • Avoid posting more than one article on the same channel, using the same title and canonical URL, within a 24-hour period. Otherwise, only the first article posted is available to readers. The values in the title and metadata.canonicalURL properties of an Apple News Format article are used to determine if an article is a duplicate.

  • 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 to read, update, and delete an article.

  • To publish older articles, use the metadata properties in Apple News Format. Set an older publication date and the article will appear earlier in the feed. See Metadata in Apple News Format documentation. Articles are sorted by publication date.

  • A canonical URL is required to do data collection and reporting for comScore analytics.

  • Do not change the canonical URL of the article after it has been set.

Example Code for Creating an Article Without Metadata

Example Code for an Creating Article With Metadata

See Also

Articles

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.

Update an Article

Update an existing article in your channel.

Delete an Article

Delete the specified article from your channel.

object Article

See the fields returned by the article endpoints.

object ArticleLinks

See the links returned by the article endpoints.

object ArticleResponse

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

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.

object Create Article Metadata Fields

See the optional metadata fields for the create article request.

object Update Article Metadata Fields

See the metadata fields for the update article request.

object SearchResponse

See the fields returned by the search article endpoints.