<!--
{
  "availability" : [
    "Apple News API: 1.0.0 -"
  ],
  "documentType" : "symbol",
  "framework" : "AppleNews",
  "identifier" : "/documentation/AppleNewsAPI/POST-channels-_channelId_-articles",
  "metadataVersion" : "0.1.0",
  "role" : "Web Service Endpoint",
  "symbol" : {
    "kind" : "Web Service Endpoint",
    "modules" : [
      "Apple News API"
    ],
    "preciseIdentifier" : "rest:news_api:post:channels-{}-articles"
  },
  "title" : "Create an Article"
}
-->

# Create an Article

Publish an article to your channel.

## 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 <doc://com.apple.applenews/documentation/AppleNews/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`](/documentation/AppleNewsAPI/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`](/documentation/AppleNewsAPI/GET-sections-_sectionId_) 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`](/documentation/AppleNewsFormat/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

**Request:**

```
POST /channels/63a75491-2c4d-3530-af91-819be8c3ace0/articles HTTP/1.1
Host: news-api.apple.com
Accept: application/json
Content-Type: multipart/form-data; boundary=535e329ca936f79a19ac9a251f7d48f7
Content-Length: 94348
Authorization: HHMAC; key="1e3gfc5e-e9f8-4232-a6be-17bf40edad09"; signature="gJYsk8qm+6wpONE8twX/yDlGRt0UzS7Qn32yHNpiwnM="; date="2015-03-05T03:00:27Z"
--535e329ca936f79a19ac9a251f7d48f7
Content-Type: application/json
Content-Disposition: form-data; filename=article.json; name=article.json
{
    "version": "1.7",
    "identifier": "SampleArticle",
    "language": "en",
    "title": "Apple News App",
    "subtitle": "A look at the features of the News iOS app",
    "layout": {
        "columns": 7,
        "width": 1024,
        "margin": 75,
        "gutter": 20
    },
    "components": [
        {
            "role": "title",
            "text": "Apple News App",
            "textStyle": "title"
        },
        {
            "role": "body",
            "text": "The Apple News Format allows publishers to craft beautiful editorial layouts. Galleries, audio, video, and fun interactions like animation make stories spring to life."
        },
        {
            "role": "photo",
            "URL": "bundle://image.jpg"
        }
    ],
    "documentStyle": {
        "backgroundColor": "#F7F7F7"
    },
    "componentTextStyles": {
        "default": {
            "fontName": "Helvetica",
            "fontSize": 13,
            "linkStyle": {
                "textColor": "#428bca"
            }
        },
        "title": {
            "fontName": "Helvetica-Bold",
            "fontSize": 30,
            "hyphenation": false
        },
        "default-body": {
        "fontName": "Helvetica",
        "fontSize": 13
        }
    }
}
--535e329ca936f79a19ac9a251f7d48f7
Content-Type: image/jpeg
Content-Disposition: form-data; filename=mountain-lions.jpg; name=my_image
{binary content of mountain-lions.jpg}
--535e329ca936f79a19ac9a251f7d48f7
Content-Type: application/octet-stream
Content-Disposition: form-data; filename=gradient.png; name=a_gradient
{binary content of gradient.png}
--535e329ca936f79a19ac9a251f7d48f7--
```

**Response:**

```json
HTTP/1.1 201 OK
Date: Thu, 05 Mar 2015 02:53:54 GMT
Content-Type: application/json;charset=UTF-8
Transfer-Encoding: chunked
{
  "data": {
    "createdAt": "2015-03-05T02:57:59Z",
    "modifiedAt": "2015-03-05T02:57:59Z",
    "id": "a91760f1-c169-47d2-9fc4-a7711341264d",
    "type": "article",
    "shareUrl": "https://apple.news/ArRPpLPE9QXu3sehS0rvxvA",
    "links": {
      "channel": "https://news-api.apple.com/channels/63a75491-2c4d-3530-af91-819be8c3ace0",
      "self": "https://news-api.apple.com/articles/a91760f1-c169-47d2-9fc4-a7711341264d",
      "sections": [
        "https://news-api.apple.com/sections/0a468272-356f-3b61-afa3-c4f989954180"
      ]
    },
    "meta": {
      "throttling": {
        "isThrottled": true,
        "quotaAvailable": 0,
        "queueSize": 42,
        "estimatedDelayInSeconds”: 1260  
    }
    },
"document": {
  "version": "1.7",
  "identifier": "SampleArticle",
  "language": "en",
  "title": "Apple News App",
  "subtitle": "A look at the features of the News iOS app",
  "layout": {
    "columns": 7,
    "width": 1024,
    "margin": 75,
    "gutter": 20
  },
  "components": [
    {
      "role": "title",
      "text": "Apple News App",
      "textStyle": "title"
    },
    {
      "role": "body",
      "text": "The Apple News Format allows publishers to craft beautiful editorial layouts. Galleries, audio, video, and fun interactions like animation make stories spring to life."
    },
    {
      "role": "photo",
      "URL": "bundle://image.jpg"
    }
  ],
  "documentStyle": {
    "backgroundColor": "#F7F7F7"
  },
  "componentTextStyles": {
    "default": {
      "fontName": "Helvetica",
      "fontSize": 13,
      "linkStyle": {
        "textColor": "#428bca"
      }
    },
    "title": {
      "fontName": "Helvetica-Bold",
      "fontSize": 30,
      "hyphenation": false
    },
    "default-body": {
      "fontName": "Helvetica",
      "fontSize": 13
    }
  }
},
"revision": "AAAAAAAAAAAAAAAAAAAAew==",
"state": "PROCESSING",
"title": "Flother City Lions",
"maturityRating": null,
"warnings": [],
"isCandidateToBeFeatured": false,
"isSponsored": false,
"isPreview": false
}
}
```

### Example Code for Creating an Article with Metadata

**Request:**

```
POST /channels/63a75491-2c4d-3530-af91-819be8c3ace0/articles HTTP/1.1
Host: news-api.apple.com
Accept: application/json
Content-Type: multipart/form-data; boundary=535e329ca936f79a19ac9a251f7d48f7
Content-Length: 94348
Authorization: HHMAC; key="1e3gfc5e-e9f8-4232-a6be-17bf40edad09"; signature="gJYsk8qm+6wpONE8twX/yDlGRt0UzS7Qn32yHNpiwnM="; date="2015-03-05T03:00:27Z"
--535e329ca936f79a19ac9a251f7d48f7
Content-Type: application/json
Content-Disposition: form-data; name=metadata
{
    "data": {
        "isCandidateToBeFeatured": "false",
        "isSponsored": true,
        "isPreview": true,
        "maturityRating": null,
        "targetTerritoryCountryCodes": ["GB", "US"],
        "links": {
            "sections": [
                "https://news-api.apple.com/sections/0a468272-356f-3b61-afa3-c4f989954180",
                "https://news-api.apple.com/sections/5cec0b36-529e-31bc-bc1e-3eaccbc15b97"
            ]
        }
    }
}
--535e329ca936f79a19ac9a251f7d48f7
Content-Type: application/json
Content-Disposition: form-data; filename=article.json; name=article.json
{
    "version": "1.7",
    "identifier": "SampleArticle",
    "language": "en",
    "title": "Apple News App",
    "subtitle": "A look at the features of the News iOS app",
    "layout": {
        "columns": 7,
        "width": 1024,
        "margin": 75,
        "gutter": 20
    },
    "components": [
        {
            "role": "title",
            "text": "Apple News App",
            "textStyle": "title"
        },
        {
            "role": "body",
            "text": "The Apple News Format allows publishers to craft beautiful editorial layouts. Galleries, audio, video, and fun interactions like animation make stories spring to life."
        },
        {
            "role": "photo",
            "URL": "bundle://image.jpg"
        }
    ],
    "documentStyle": {
        "backgroundColor": "#F7F7F7"
    },
    "componentTextStyles": {
        "default": {
            "fontName": "Helvetica",
            "fontSize": 13,
            "linkStyle": {
                "textColor": "#428bca"
            }
        },
        "title": {
            "fontName": "Helvetica-Bold",
            "fontSize": 30,
            "hyphenation": false
        },
        "default-body": {
        "fontName": "Helvetica",
        "fontSize": 13
        }
    }
}
--535e329ca936f79a19ac9a251f7d48f7
Content-Type: image/jpeg
Content-Disposition: form-data; filename=mountain-lions.jpg; name=my_image
{binary content of mountain-lions.jpg}
--535e329ca936f79a19ac9a251f7d48f7
Content-Type: application/octet-stream
Content-Disposition: form-data; filename=gradient.png; name=a_gradient
{binary content of gradient.png}
-535e329ca936f79a19ac9a251f7d48f7--
```

**Response:**

```json
HTTP/1.1 201 OK
Date: Thu, 05 Mar 2015 02:53:54 GMT
Content-Type: application/json;charset=UTF-8
Transfer-Encoding: chunked
{
  "data": {
    "createdAt": "2015-03-05T02:57:59Z",
    "modifiedAt": "2015-03-05T02:57:59Z",
    "id": "a91760f1-c169-47d2-9fc4-a7711341264d",
    "type": "article",
    "shareUrl": "https://apple.news/ArRPpLPE9QXu3sehS0rvxvA",
    "links": {
      "channel": "https://news-api.apple.com/channels/63a75491-2c4d-3530-af91-819be8c3ace0",
      "self": "https://news-api.apple.com/articles/a91760f1-c169-47d2-9fc4-a7711341264d",
      "sections": [
        "https://news-api.apple.com/sections/0a468272-356f-3b61-afa3-c4f989954180",
        "https://news-api.apple.com/sections/5cec0b36-529e-31bc-bc1e-3eaccbc15b97"
      ]
    },
    "meta": {
      "throttling": {
        "isThrottled": true,
        "quotaAvailable": 0,
        "queueSize": 42,
        "estimatedDelayInSeconds”: 1260  
      }
    },
"document": {
  "version": "1.7",
  "identifier": "SampleArticle",
  "language": "en",
  "title": "Apple News App",
  "subtitle": "A look at the features of the News iOS app",
  "layout": {
    "columns": 7,
    "width": 1024,
    "margin": 75,
    "gutter": 20
  },
  "components": [
    {
      "role": "title",
      "text": "Apple News App",
      "textStyle": "title"
    },
    {
      "role": "body",
      "text": "The Apple News Format allows publishers to craft beautiful editorial layouts. Galleries, audio, video, and fun interactions like animation make stories spring to life."
    },
    {
      "role": "photo",
      "URL": "bundle://image.jpg"
    }
  ],
  "documentStyle": {
    "backgroundColor": "#F7F7F7"
  },
  "componentTextStyles": {
    "default": {
      "fontName": "Helvetica",
      "fontSize": 13,
      "linkStyle": {
        "textColor": "#428bca"
      }
    },
    "title": {
      "fontName": "Helvetica-Bold",
      "fontSize": 30,
      "hyphenation": false
    },
    "default-body": {
      "fontName": "Helvetica",
      "fontSize": 13
    }
  }
},
"revision": "AAAAAAAAAAAAAAAAAAAAew==",
"state": "PROCESSING",
"title": "Flother City Lions",
"maturityRating": null,
"warnings": [
  
],
"isCandidateToBeFeatured": false,
"isSponsored": true,
"isPreview": true,
"targetTerritoryCountryCodes": ["GB", "US"]
}
}
```

---

Copyright &copy; 2026 Apple Inc. All rights reserved. | [Terms of Use](https://www.apple.com/legal/internet-services/terms/site.html) | [Privacy Policy](https://www.apple.com/privacy/privacy-policy)