Create an Article

Publish an article to your channel.

URL

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

Path Parameters

Name	Type	Description
`channelId` Required	string	The UUID of the channel to publish the article to.

Response Codes

Status	Reason	Type	Description
201	Created Content-Type: application/json	`ArticleResponse`	You successfully created the article. The server returns a warning for articles with a publication date before 2015.
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 server provides the original article ID in the response. `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 the `article.json` file 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_ID`. The section URL has a section ID that isn’t a valid UUID. Key path: `data.links.sections.#`. `INVALID_RESOURCE_TYPE`. The path in the section URL doesn’t start with `/sections/`. 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 isn’t 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 include the Article UUID or the Share URL ID 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.
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 channel you want to add an article to doesn’t exist. Key path: `channelId`.
429	Too Many Requests Content-Type: application/json	`Error`	You exceeded the number of articles that can be published within the allowed time window. The response header `<Retry-After: delay-seconds>` indicates the time in seconds you need to wait before sending a new request to publish articles.

Mentioned in

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 an 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” below.
The server requires additional parts 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 you must specify the filename parameter of Content-Disposition.
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 in the URL 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:

You can include an optional metadata part 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.
You must wrap all metadata fields 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 don’t 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:

For articles with a source URL or thumbnail, avoid posting more than one article on the same channel using the same title, source URL, or thumbnail, within a 24-hour period. An article is considered a duplicate if these conditions are met.
For articles without a source URL and thumbnail, avoid posting more than one article on same channel, using the same title, within a 24-hour period. An article is considered a duplicate if these conditions are met.
When you create an article, be sure to retain the article ID or the self URL that’s returned in the response. You need the article ID to read, update, and delete an article.
To publish older articles, use the metadata properties in Apple News Format. If you set an older publication date, the article appears 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.
Don’t change the canonical URL of the article after it has been set.

Example Code for Creating an Article Without Metadata

Example Code for Creating an Article with Metadata

HTTP Body

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