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

# Update an Article

Update an existing article in your channel.

## 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`](/documentation/AppleNewsAPI/POST-channels-_channelId_-articles) request, all parts of an Update an Article request are optional except for the metadata section. The Update an Article 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 an Article request is identical to the Create an Article request. Although you can omit MIME parts that you previously posted, you can’t partially update the Apple News Format document in the `article.json.` You can only replace it, not patch it.

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

Updating an article doesn’t change the timestamp of the article or its placement in your  feeds, such as the Today feed, channel feeds, and topic feeds.

Here are the guidelines for updating an existing article:

- For each update, provide the article ID and the `revision` token that matches the current revision of the article. This ensures that two users can’t update an article at the same time and lose data. If this happens, the client informs the second user (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 an 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`](/documentation/AppleNewsAPI/GET-articles-_articleId_), or use a revision ID from an earlier Create an Article or Update an Article call.
- You must wrap all metadata fields in a data key. See “Example Code for Updating an Article with Metadata” below. The server returns the `INVALID_JSON` error if there is no data key in the request call.
- Include `isPreview` in the metadata to allow an update call to change the article’s preview/published state. Additionally, on update, you can make a preview article public (change `true` to `false`), but you can’t 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

**Request:**

```
POST /articles/ArRPpLPE9QXu3sehS0rvxvA 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": {
    "revision": "AAAAAAAAAAAAAAAAAAAAev=="
  }
}
--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--
```

**Response:**

```json
HTTP/1.1 200 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”: 126
      }
    },
"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_UPDATE",
"title": "Flother City Bears",
"maturityRating": null,
"warnings": [],
"isCandidateToBeFeatured": false,
"isSponsored": true,
"isPreview": true
}
}       
```

### Example Code for Updating an Article with Metadata

**Request:**

```
POST /articles/a91760f1-c169-47d2-9fc4-a7711341264d 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": {
    "targetTerritoryCountryCodes": ["GB", "US"],
    "links": {
      "sections": [
        "https://news-api.apple.com/sections/5cec0b36-529e-31bc-bc1e-3eaccbc15b97"
      ]
    },
    "revision": "AAAAAAAAAAAAAAAAAAAAeZ=="
  }
}
--535e329ca936f79a19ac9a251f7d48f7--
```

**Response:**

```json
HTTP/1.1 200 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/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": "AAAAAAAAAAAAAAAAAAAAfA==",
"state": "PROCESSING_UPDATE",
"title": "Flother City Lions",
"maturityRating": null,
"warnings": [],
"isCandidateToBeFeatured": false,
"isSponsored": true,
"isPreview": false,
"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)