How to Use Draft API to Unpublish a Document

If you haven’t already done so, read Getting Started with the Draft API.

This guide assumes that:

Before we get into the “how” of unpublishing a document, let’s go over the difference between unpublishing and reverting a document in Draft API.

As we go over in our Introductory Guide, each time you publish your Document in Draft API, a new Publish Revision is created. For a Document that has been published and updated multiple times, there are many Publish Revisions in its history.

There may come a moment where the latest published revision was either published accidentally or published with an error. In these cases, you still want the document to appear on your site to viewers, but you want to revert what viewers are seeing back to a prevision published revision. (More details on performing this Revert here).

In contrast, you may also find yourself in a situation where the document was published before it was ready to be viewed on your site at all. In another case, your document may have reached the end of its life, and is ready to be taken down from your site entirely. In these cases, unpublishing is the right choice.

To sum it up:

Let’s assume we already have a document created with at least one published revision:

  --request GET \
  --header 'Authorization: Bearer <TOKEN>' \
  --url https://api.{{org}}.arcpublishing.com/draft/v1/story/PCK6763FZNDO7HPCNMRAJRNVRE

#RESPONSE
{
    "id": "PCK6763FZNDO7HPCNMRAJRNVRE",
    "type": "STORY",
    "created_at": "2020-06-04T13:12:46.402Z",
    "first_published_at": "2020-06-04T13:17:13.269Z",
    "last_published_at": "2020-06-04T13:18:01.078Z",
    "draft_revision_id": "7PT2PXU5IZA6RNXUCTLM2NMJ4E",
    "published_revision_id": "T2VAF75XVZG63FQ67WZGKTSTX4"
}

Now we’ve decided we no longer want the document to be published at all. To do this, we can use the unpublish endpoint:

curl --request DELETE \
  --header 'Authorization: Bearer <TOKEN>' \
  --header 'Content-Type: application/json' \
  --url https://api.{{org}}.arcpublishing.com/draft/v1/story/PCK6763FZNDO7HPCNMRAJRNVRE/revision/published \


# RESPONSE
{
    "id": "T2VAF75XVZG63FQ67WZGKTSTX4",
    "document_id": "PCK6763FZNDO7HPCNMRAJRNVRE",
    "ans": {
        "additional_properties": {
            "has_published_copy": true
        },
        "canonical_website": "the-herald",
        "created_date": "2020-06-04T13:18:00.975Z",
        "display_date": "2020-06-04T13:17:13.269Z",
        "first_publish_date": "2020-06-04T13:17:13.269Z",
        "headlines": {
            "basic": "That Thing Happened at that Place."
        },
        "last_updated_date": "2020-06-04T13:18:00.975Z",
        "publish_date": "2020-06-04T13:18:01.078Z",
        "subheadlines": {
            "basic": "And it was amazing!"
        },
        "type": "story",
        "version": "0.10.5"
    },
    "created_at": "2020-06-04T13:18:00.975Z",
    "unpublished_at": "2020-06-04T13:21:20.344Z", 
    "type": "PUBLISHED"
}

In this response, we get back the published revision that has been unpublished, and we can see the unpublished_at timestamp to denote that that specific published revision was unpublished.

Along with this, the document itself gets two new timestamps:

curl --request GET \
  --header 'Authorization: Bearer <TOKEN>' \
  --url https://api.{{org}}.arcpublishing.com/draft/v1/story/PCK6763FZNDO7HPCNMRAJRNVRE
  
# RESPONSE
{
    "id": "PCK6763FZNDO7HPCNMRAJRNVRE",
    "type": "STORY",
    "created_at": "2020-06-04T13:12:46.402Z",
    "first_published_at": "2020-06-04T13:17:13.269Z",
    "last_published_at": "2020-06-04T13:18:01.078Z",
     "first_unpublished_at": "2020-06-04T13:21:20.344Z",
    "last_unpublished_at": "2020-06-04T13:21:20.344Z", 
    "draft_revision_id": "7PT2PXU5IZA6RNXUCTLM2NMJ4E"
}

In this response, the document no longer has a publish_revision_id associated with it, because there is currently no published revision of this document.

If sometime later, we want to lookup which revisions of this document were ever unpublished, we can use the /revision endpoint to find that out:

curl --request GET \
  --header 'Authorization: Bearer <TOKEN>' \
  --url https://api.{{org}}.arcpublishing.com/draft/v1/story/PCK6763FZNDO7HPCNMRAJRNVRE/revision

# RESPONSE
{
    "revisions": [
        ...
        {
            "id": "T2VAF75XVZG63FQ67WZGKTSTX4",
            "document_id": "PCK6763FZNDO7HPCNMRAJRNVRE",
            "ans": {
                "created_date": "2020-06-04T13:18:00.975Z",
                "display_date": "2020-06-04T13:18:01.078Z",
                "first_publish_date": "2020-06-04T13:17:13.269Z",
                "headlines": {
                    "basic": "That Thing Happened at that Place."
                },
                "last_updated_date": "2020-06-04T13:18:00.975Z",
                "publish_date": "2020-06-04T13:18:01.078Z",
                "type": "story"
            },
            "created_at": "2020-06-04T13:18:00.975Z",
             "unpublished_at": "2020-06-04T13:21:20.344Z", 
            "type": "PUBLISHED"
        },
        ...
    ]
}
Each revision that has been unpublished now includes this timestamp.