# Draft API Interactions with ANS

Source: https://dev.arcxp.com/publishing-platform/developer-docs/draft-api/draft-api-interactions-with-ans/

## Overview

The Draft API `document` endpoints listed below contain some special handling for the Arc XP Native Specification (ANS) blob that is passed in through the request body and/or returned in responses. When creating and editing Revisions, there are some fields that are promoted to “first-class” fields in order to make searching and JSON manipulation easier, while others are handled in separated endpoints entirely.

This document outlines the various ways that ANS fields are handled and what users can expect when making requests.

For this documentation, we will be referring to the following endpoints:

`POST /draft/v1/story`: Create a Document

`GET /draft/v1/story/:id/revision`: List All Revisions

`GET /draft/v1/story/:id/revision/:revision_id`: Get Revision by ID

`PUT /draft/v1/story/:id/revision/draft`: Update Draft Revision

`POST /draft/v1/story/:id/revision/published`: Publish Document

`DELETE /draft/v1/story/:id/revision/published`: Unpublish Document

`PUT /draft/v1/story/:id/revision/revert`: Revert Document

Each of the fields discussed below is nested under the `ans` field, which is a property of a `revision`.

## Dates

### System Generated Fields

- `created_date`
- `last_updated_date`
- `first_publish_date`

These fields are generated by the system, and will be ignored if they are passed into Write endpoints through the request body.

### Overridable Fields

- `publish_date`
- `display_date`

These fields are generated by the system, but can be overridden by values in the request body when using the following two endpoints:

- `POST /draft/v1/story`: Create a Document
- `PUT /draft/v1/story/:id/revision/draft`: Update Draft Revision

See our [Guide for Manually Setting the Publish\_date or Display\_date of a Document](https://docs.arcxp.com/alc?sys%5Fkb%5Fid=c9d5430147665910d0cba8b5536d435c&id=kb%5Farticle%5Fview)

### Revert Document Endpoint

The fields `first_publish_date` and `publish_date` are omitted from the response of this endpoint.

## IDs

The following fields are omitted from responses. They will be ignored if they are included in the request body.

- `_id`
- `revision.revision_id`
- `revision.parent_id`

## URLs and Circulations

In Draft API, the concept of a Document’s Revisions is independent of its Circulations. For this reason, we no longer return Circulation information in the Revision endpoints. To access these fields, you can see the Circulation endpoints, which are documented [here](https://docs.arcxp.com/alc?sys%5Fkb%5Fid=9ca36fa94772d550d0cba8b5536d43ee&id=kb%5Farticle%5Fview#operations-tag-Circulation%5FOperations).

The following fields are omitted from responses. Draft API endpoints will reject requests if any of these fields are present in the request body.

- `websites`
- `canonical_url`
- `taxonomy.sections`
- `taxonomy.sites`
- `taxonomy.primary_section`
- `taxonomy.primary_site`

## Revisions

The following fields are omitted from responses. They will be ignored if they are included in the request body.

- `revision.index`
- `revision.branch`
- `revision.editions`

### List all Revisions Endpoint

The following fields are omitted from the response from this endpoint in order to remain compatible with Story API. In later versions of Draft API after the full Deprecation of Story API, we will begin to send these additional fields.

- `canonical_website`
- `owner.id`
- `version`
- `slug`