How To Circulate with Draft API using Specific URL

Last updatedFeb 3, 2025View as Markdown

The purpose of this guide is to demonstrate how to circulate a document to a provided URL in lieu of automatic generation.

Manually setting a circulation URL
Requirements
Existing document
Circulating to a provided URL

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 to the Draft API documentation and Getting Started with the Draft API.

Existing document

Given two circulated documents, URWCJIIJPNGEZKZR3EZ54TO22Y and 67B2A6C51AEE442B95F8C921FF, start by listing the active circulations for each.

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"
          }
        }
      ]
    }
  ]
}
curl --request GET \
  --header 'Authorization: Bearer <TOKEN>' \
  --url https://api.{{org}}.arcpublishing.com/draft/v1/story/67B2A6C51AEE442B95F8C921FF/circulation

# RESPONSE
{
  "circulations": [
    {
      "document_id": "67B2A6C51AEE442B95F8C921FF",
      "website_id": "river-city-post",
      "website_url": "/news/2019/09/04/man-bites-dog/",
      "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"
          }
        }
      ]
    }
  ]
}

These calls provide the following information:

The document URWCJIIJ... is circulated on websites cyclist-daily and river-city-post at URLs /wheels-news/2019/09/04/parade/ and /news/2019/09/04/parade/ respectively.
The document 67B2A6C5... is circulated on website river-city-post at URL /news/2019/09/04/man-bites-dog/.

Circulating to a provided URL

To circulate a document at a specific URL and skip automatic URL generation, provide a website_url value with the circulate call. website_url must be an unused URL or occupied by a redirect targeting the same document.

For instance, attempting to circulate 67B2A6C5... to website cyclist-daily under the circulation URL for URWCJIIJ... fails.

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

# ERROR RESPONSE
{
    "error_code": "ErrUrlAlreadyExists",
    "error_message": "url /wheels-news/2019/09/04/parade/ already exists for website cyclist-daily"
}

Instead, circulating 67B2A6C5... to the unused URL /wheels-news/man-bites-dog on cyclist-daily succeeds.

curl --request PUT \
  --header 'Authorization: Bearer <TOKEN>' \
  --header 'content-type: application/json' \
  --url https://api.{{org}}.arcpublishing.com/draft/v1/story/67B2A6C51AEE442B95F8C921FF/circulation/cyclist-daily \
  --data '{
    "website_url": "/wheels-news/man-bites-dog/"
  }'

# SUCCESS RESPONSE
{
    "document_id": "67B2A6C51AEE442B95F8C921FF",
    "website_id": "cyclist-daily",
    "website_url": "/wheels-news/man-bites-dog/"
}

Listing the documents’ circulations again shows the updated websites and URLs.

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"
          }
        }
      ]
    }
  ]
}
curl --request GET \
  --header 'Authorization: Bearer <TOKEN>' \
  --url https://api.{{org}}.arcpublishing.com/draft/v1/story/67B2A6C51AEE442B95F8C921FF/circulation

# RESPONSE
{
  "circulations": [
    {
      "document_id": "67B2A6C51AEE442B95F8C921FF",
      "website_id": "cyclist-daily",
      "website_url": "/wheels-news/man-bites-dog/"
    },
    {
      "document_id": "67B2A6C51AEE442B95F8C921FF",
      "website_id": "river-city-post",
      "website_url": "/news/2019/09/04/man-bites-dog/"
    }
  ]
}

Note: Don’t forget the trailing slash on all urls.