Skip to main content

How To Circulate with Draft API using Specific URL

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

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.

In this section: