How To Write the Minimum ANS for a Viable Story Document
Minimum Viable Story ANS
The ANS schema has a lot of specific keys and details that can vary widely between ANS content types. When planning to write ANS for migrating data into the system using Arc XP’s Draft API, which fields are the most necessary ones? Let’s narrow the focus, and pay attention to only the minimum selection of all the possible ANS fields necessary to create just story content.
In this article we will discuss what is the minimum ANS that will result in a viable Arc XP story. There will still be many other useful ANS fields that are not included in this discussion. Yet, after reviewing this article, you will be equipped with a solid story ANS starting point.
Stories are the only kind of content in Arc XP that need to be created in multiple JSON posts. One JSON object contains the ANS fields to describe the story content and characteristics to create the story. The second JSON object contains ANS fields that attach the websites and sections to the story, a process we call circulation. When both posts have been sent to Draft API, a third Draft post sets the status of the story to publish. The story URLs are not usable until the publish event happens.
Uncirculated stories are those without at least one website and section designation. Uncirculated stories are temporarily affiliated with your organization’s default website. For more information, see Defining your organization's websites
Create Story
This is the smallest ANS you can send to Draft API to create a story. Even though the ANS contains canonical_website, this ANS does not affect circulation.
{ "_id": ANS ID, "version": Most recent stable ANS version, "type": "story", "canonical_website": Site Service Website ID, "owner": { "id": Arc XP Organization ID }, "headlines": { "basic": "a headline" }, "content_elements": [ { "content": "some kind of content", "type": "text" }, # there are many different kinds of content elements, this is a very basic text item { "_id": ANS ID of image or video "type": "reference", "referent": { "type": "image" # or, "video" "id": ANS ID of image or video } # there are many different kinds of content elements, this is a reference to another Arc XP oject like an image or video } ]}Circulation
This is the smallest ANS you can send to the Draft API circulation endpoint. You can circulate a story without specifying the story’s URL in advance. When you don’t provide the website_url in the circulation ANS, URL format rules will activate and create the story’s URL when the story is published. But, in many migrations you already have an exisitng url you want to use. In that case you can choose to enter a specific website_url in this circulation ANS.
Example without explicit URL:
{ "document_id": same ANS ID as story _id, "website_id": same Site Service Website Id as story canonical_website, "website_primary_section": { "type": "reference", "referent": { "id": Site Service Section Id, "type": "section", "website": same Site Service Website Id } }, "website_sections": [ { "type": "reference", "referent": { "id": same Site Service Section Id, "type": "section", "website": same Site Service Website Id } } ]}For more information about circulation and URL format rules, see How to circulate with Draft API and auto-generate the circulation url and How Draft API uses format rules to generate content URLs.
Example with explicit URL:
{ "document_id": same ANS ID as story _id, "website_id": same Site Service Website Id as story canonical_website, "website_primary_section": {...}, "website_sections": {...} "website_url": Relative URL of the story from the original CMS that will be migrated as the canonical_url value in Arc XP}For more information about circulating a story with website_url see
How to circulate with Draft API using specific URLs.
Update Status to Publish
You can now publish the story using:
Draft API: Getting started with the Draft API
Migration Center: Sending multiple ANS objects to Arc XP services using Migration Center
Additional Useful ANS Fields
The example minimum story ANS includes a content block of just one text element. There are many different kinds of content elements, like headers, custom embeds, social embeds, and links. This article won’t detail all of these different content elements ANS format specifics. However, content elements can contain items that are other Arc XP objects, like images, videos or galleries, and adding an object as a child to an ANS fields requires adding it with ANS reference syntax.
When writing a reference, use the target content’s Arc ID as both the value of the content_elements._id field and also its referent.id field. Normally Arc XP will generate content_elements._id uniquely once you submit the ANS. But when using a nested Arc XP object as a content element, you can write the content_elements._id using the Arc ID of the child object. This allows you to be able to search Content API and find stories where an image was used in the body of an article. This search works because content_elements._id is a searchable Content API field.
{ "content_elements": [ { "_id": ANS ID of image or video "type": "reference", "referent": { "type": "image" # or, "video" "id": ANS ID of image or video } } ]}In addition to the story headline, you can include a sub headline or a description.
{ "subheadlines": { "basic": "a sub headline" }, "description": { "basic": "a description" },}You can add a publish date and display date to the story ANS. The dates must be in UTC timezone and use the format YYYY-MM-DDThh:mm:ssZ. If you decide not to include these, the current day and time will be automatically added to the ANS when the story is published.
{ "display_date": "2025-10-15T18:00:00.000Z", "publish_date": "2025-10-15T18:00:00.000Z",}For more information about the date fields in Arc XP see Draft API Interactions with ANS.
Featured media is the promotional art that you use to promote your story throughout the Arc XP platform, such as your homepage and section fronts, or at the top of your article pages. You use reference syntax in the promo_items.basic or other promo_items.* fields in which you provide the content type and its arc id. When the story is retrieved from Content API, the child ANS the reference points to is also retrieved and returned in its denormalized entirety.
{ "promo_items": { "basic": { "_id": Ans ID matching the image or video in the reference, "type": "reference", "referent": { "type": "image", # or "video" "id": ANS ID of the image or video } } }}To include author information in the Story ANS add an array element in credits.by. The array element can contain either a reference to an Arc XP Author object, or a set of fields that describe an author that is attached only to this story as guest author.
Author object
{ "credits": { "by": [ { "referent": { "id": Author ID from Author Service, "type": "author" }, "type": "reference" } ] }}Guest Author
{ "credits": { "by": [ { "name": "Name of Author That is not in Author Service", "org": "Associated Press", "type": "author" } ] }}Assign a distributor object to restrict the website where a story can be used. Distributor objects are first created in the Arc XP Global Settings application, and a website restriction can be assigned to its definition. Once saved, the distributor will receive an id. Use this ID in the distributor.reference_id field in the story ANS.
Or, you can add a custom distributor to the story instead. Custom distributors do not add extra capabilities to the story, other than metadata that may inform editorial decisions. For example your organization may have standard operating procedures around what it means for a piece of content to be labeled “staff” or “wire” and how editorial staff should interact with content having these labels.
Distributor object
{ "distributor": { "mode": "reference", "reference_id": Distributor ID from Global Settings }}Custom distributor
{ "distributor": { "mode": "custom", "category": "staff", # staff, other, handout, wire, freelance, stock, or any custom value "name": "the distributor name", }}For more information about distributor objects, see Managing Distributors
The source.* fields add searchable metadata to the story. source.source_id should hold the original CMS’s primary key or identifier of the content before it was migrated into Arc XP. source.system should hold the name of your previous CMS.
{ "source": { "source_id": original CMS identity data, "system": original CMS name }}Story ANS Examples
Example 1: Only minimum fields to create the story
{ "_id": "2UMZRNOQU5GB5F5EUVWNX5R6FI", "version": "0.10.11", "type": "story", "canonical_website": "arc_test", "content_elements": [ { "content": "Burmese devonshire rex sphynx turkish angora. Leopard british shorthair mouser havana brown, but cornish rex siberian. Scottish fold persian american shorthair so devonshire rex. Panther lion, or siberian. Bengal ragdoll and mouser.", "type": "text" } ], "headlines": { "basic": "Burmese devonshire rex" }, "owner": { "id": "sandbox.arctesting" }}Example 2: Story including the subset of additional fields discussed in this article
{ "_id": "2UMZRNOQU5GB5F5EUVWNX5R6FI", "version": "0.10.11", "type": "story", "canonical_website": "arc_test", "owner": { "id": "sandbox.arctesting" }, "source": { "source_id": "12345abc44569x", "system": "wordpress" }, "display_date": "2025-10-15T18:00:00.000Z", "publish_date": "2025-10-15T18:00:00.000Z", "content_elements": [ { "content": "Burmese devonshire rex sphynx turkish angora. Leopard british shorthair mouser havana brown, but cornish rex siberian. Scottish fold persian american shorthair so devonshire rex. Panther lion, or siberian. Bengal ragdoll and mouser.", "type": "text" }, { "_id": "5GB5F5EUVWNX2UMZRNOQU5R6FI", "type": "reference", "referent": { "type": "video" "id": "5GB5F5EUVWNX2UMZRNOQU5R6FI" } } ], "headlines": { "basic": "Burmese devonsire rex" }, "subheadlines": { "basic": "Lorum ipsum" }, "description": { "basic": "You'll never guess what the Burmese cats are getting up to now" }, "distributor": { "mode": "reference", "reference_id": "123-456-789-0108" }, "credits": { "by": [ { "referent": { "id": "KilgoreTrout", "type": "author" }, "type": "reference" }, { "name": "Kilgore B. Trout", "org": "Associated Press", "type": "author" } ] } "promo_items": { "basic": { "_id": "F5EUVWNX5R6FI2UMZRNOQU5GB5", "type": "reference", "referent": { "type": "image", "id": "F5EUVWNX5R6FI2UMZRNOQU5GB5" } } }}Example 3: Circulation ANS, including URL
{ "document_id": "2UMZRNOQU5GB5F5EUVWNX5R6FI", "website_id": "arc_test", "website_url": "/lifestyle/original/published/path/burmese-cats-lorum-ipsum/", "website_primary_section": { "type": "reference", "referent": { "id": "/archives", "type": "section", "website": "arc_test" } }, "website_sections": [ { "type": "reference", "referent": { "id": "/archives", "type": "section", "website": "arc_test" } } ]}