# How to Decirculate a Document in Draft API

Source: https://docs.arcxp.com/en/products/publishing-platform/how-to-decirculate-a-document-in-draft-api.html

The purpose of this guide is to demonstrate how to use the Draft API to decirculate a document from a website and recirculate it back to the same website.

## Requirements

- You are familiar with the basic usage of the API (HTTP, Authentication, etc).
- If you have not used the API before, or need a refresher, refer back to [The Introductory Guide](https://dev.arcxp.com/publishing-platform/developer-docs/draft-api/getting-started-with-the-draft-api/).

## Existing document

Given a circulated document, `URWCJIIJPNGEZKZR3EZ54TO22Y`, start by listing the active circulations.

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

# RESPONSE
{
  "circulations": [
    {
      "document_id": "URWCJIIJPNGEZKZR3EZ54TO22Y",
      "website_id": "cyclist-daily",
      "website_url": "/wheels-news/2019/09/04/parade",
      "website_primary_section": {
        "type": "reference",
        "referent": {
          "type": "section",
          "id": "/wheels-news",
          "website": "cyclist-daily"
        }
      },
      "website_sections": [
        {
          "type": "reference",
          "referent": {
            "type": "section",
            "id": "/wheels-news",
            "website": "cyclist-daily"
          }
        }
      ]
    },
    {
      "document_id": "URWCJIIJPNGEZKZR3EZ54TO22Y",
      "website_id": "river-city-post",
      "website_url": "/news/2019/09/04/parade",
      "website_primary_section": {
        "type": "reference",
        "referent": {
          "type": "section",
          "id": "/news",
          "website": "river-city-post"
        }
      },
      "website_sections": [
        {
          "type": "reference",
          "referent": {
            "type": "section",
            "id": "/news",
            "website": "river-city-post"
          }
        },
        {
          "type": "reference",
          "referent": {
            "type": "section",
            "id": "/the-city",
            "website": "river-city-post"
          }
        }
      ]
    }
  ]
}
```

Additionally, list redirects for both circulated websites.

```
curl --request GET \
  --header 'Authorization: Bearer <TOKEN>' \
  --url https://api.{{org}}.arcpublishing.com/draft/v1/story/URWCJIIJPNGEZKZR3EZ54TO22Y/redirect/cyclist-daily

# RESPONSE
{
  "redirects": [
    {
      "website_id": "cyclist-daily",
      "website_url": "/wheels-news/2019/09/03/parade",
      "document_id": "URWCJIIJPNGEZKZR3EZ54TO22Y",
      "created_at": "2019-09-04T12:13:34.91Z",
      "updated_at": "2019-09-04T12:21:06.22Z"
    }
  ]
}

curl --request GET \
  --header 'Authorization: Bearer <TOKEN>' \
  --url https://api.{{org}}.arcpublishing.com/draft/v1/story/URWCJIIJPNGEZKZR3EZ54TO22Y/redirect/river-city-post

# RESPONSE
{
  "redirects": []
}
```

These calls provide the following information:

- The document is circulated on website `river-city-post` at URL `/news/2019/09/04/parade`.
- The document is circulated on website `cyclist-daily` at URL `/wheels-news/2019/09/04/parade`.
- URL `/wheels-news/2019/09/03/parade` on `cyclist-daily` redirects to the document’s circulation URL, `/wheels-news/2019/09/04/parade`.

## Decirculating a document from a website

To remove document `URWCJIIJ...` from website `cyclist-daily`, call the de-circulate endpoint.

```
curl --request DELETE \
  --header 'Authorization: Bearer <TOKEN>' \
  --url https://api.{{org}}.arcpublishing.com/draft/v1/story/URWCJIIJPNGEZKZR3EZ54TO22Y/circulation/cyclist-daily

# RESPONSE
{
  "document_id": "URWCJIIJPNGEZKZR3EZ54TO22Y",
  "website_id": "cyclist-daily",
  "website_url": "/news/2019/09/04/parade",
  "website_primary_section": {
    "type": "reference",
    "referent": {
      "type": "section",
      "id": "/news",
      "website": "cyclist-daily"
    }
  },
  "website_sections": [
    {
      "type": "reference",
      "referent": {
        "type": "section",
        "id": "/ews",
        "website": "cyclist-daily"
      }
    }
  ]
}
```

Listing circulation again now shows only one circulated website on which `URWCJIIJ...` will appear.

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

# RESPONSE
{
  "circulations": [
    {
      "document_id": "URWCJIIJPNGEZKZR3EZ54TO22Y",
      "website_id": "river-city-post",
      "website_url": "/news/2019/09/04/parade",
      "website_primary_section": {
        "type": "reference",
        "referent": {
          "type": "section",
          "id": "/news",
          "website": "cyclist-daily"
        }
      },
      "website_sections": [
        {
          "type": "reference",
          "referent": {
            "type": "section",
            "id": "/news",
            "website": "cyclist-daily"
          }
        }
      ]
    }
  ]
}
```

> **Note:**
>
> Redirects to the document on the decirculated `cyclist-daily` website **WILL NOT** be removed, continuing to redirect to the now missing `/news/2019/09/04/parade` circulation URL. This preservation enables re-use in the event of recirculation to `cyclist-daily`. The preserved redirect can be verified by a direct fetch after decirculation.

```
curl --request GET \
  --header 'Authorization: Bearer <TOKEN>' \
  --url https://api.{{org}}.arcpublishing.com/draft/v1/redirect/cyclist-daily/wheels-news/2019/09/03/parade"

# RESPONSE
{
  "document_id": "URWCJIIJPNGEZKZR3EZ54TO22Y",
  "website_id": "cyclist-daily",
  "website_url": "/wheels-news/2019/09/03/parade",
  "created_at": "2019-09-04T12:13:34.91Z",
  "updated_at": "2019-09-04T12:21:06.22Z"
}
```

## Recirculating a document to a website

Adding a document back to a website is identical to a first-time circulate. If `website_url` is omitted, the URL will be automatically generated. In this case, `URWCJIIJ...` is recirculated to website `cyclist-daily` with the prior URL explicitly specified.

```
curl --request PUT \
  --header 'Authorization: Bearer <TOKEN>' \
  --header 'content-type: application/json' \
  --url https://api.{{org}}.arcpublishing.com/draft/v1/story/URWCJIIJPNGEZKZR3EZ54TO22Y/circulation/cyclist-daily \
  --data '{
    "website_url": "/wheels-news/2019/09/04/parade"
  }'

# RESPONSE
{
  "document_id": "URWCJIIJPNGEZKZR3EZ54TO22Y",
  "website_id": "cyclist-daily",
  "website_url": "/wheels-news/2019/09/04/parade"
}
```

Listing the document’s circulation a final time shows `cyclist-daily` back as one of the document’s active websites. Redirects preserved across decirculation will now point to the present document.

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

# RESPONSE
{
  "circulations": [
    {
      "document_id": "URWCJIIJPNGEZKZR3EZ54TO22Y",
      "website_id": "cyclist-daily",
      "website_url": "/wheels-news/2019/09/04/parade"
    },
    {
      "document_id": "URWCJIIJPNGEZKZR3EZ54TO22Y",
      "website_id": "river-city-post",
      "website_url": "/news/2019/09/04/parade"
    }
  ]
}
```