> For the complete documentation index, see [llms.txt](https://docs.parameter1.com/basecms-graphql/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.parameter1.com/basecms-graphql/modifying-data/modifying-content.md).

# Modifying content

A guide to using content mutations to modify content data via the BaseCMS GraphQL API.

## Requirements

{% hint style="info" %}
You'll need the following information to schedule content via the API:

* An API URL
* A BASE instance URL
* A Tenant Key
* An active BASE user with permission to read and write data
* A content ID

If you're missing any of this information, please reach out to <support@parameter1.com> and we'd be happy to provide it!
{% endhint %}

### Connecting to the API

Connect to the API using a the GraphQL client, programming library, or request utility of your choice. Make sure to send your tenant key along with your request in the `x-tenant-key` HTTP header. For a detailed example, review the [Connecting to the API](/basecms-graphql/connecting-to-the-api.md) guide.

#### Authentication

To modify content, you must first authenticate to the BaseCMS GraphQL API using valid user credentials with access to read and write data. Once complete, send your authentication token along with your request in the `authorization` header (using the `Bearer` prefix). For a detailed example, review the [Authenticating to the API](/basecms-graphql/connecting-to-the-api.md#authenticating-to-the-api) segment of the [Connecting to the API](/basecms-graphql/connecting-to-the-api.md) guide.

#### BASE instance access

In order to route to the correct environment, make sure you send your BASE instance URL along with your request in the `x-base4-api-uri` HTTP header. For a detailed example, review the [Specifying your BASE instance](/basecms-graphql/connecting-to-the-api.md#specifying-your-base-instance) segment of the [Connecting to the API](/basecms-graphql/connecting-to-the-api.md) guide.

## Chaining Requests

One handy feature of GraphQL is that you can send multiple operations in a single HTTP request, lowering the overall request overhead of communicating with the API (which is great for staying under rate limits, too!). You can send multiple operations by including them as siblings in the request body.

![Sending multiple mutation operations in a single request.](https://3551656615-files.gitbook.io/~/files/v0/b/gitbook-legacy-files/o/assets%2F-MJmAeLxWsdoZNmpFobC%2F-MfErmi2DdQ5GBwY-TFP%2F-MfEsz8sy6u6a9KY5_2I%2Fimage.png?alt=media\&token=bd6001ba-ca85-41ff-a8e7-7b0d0f8d03f8)

## Name, Teaser, and Body fields

The Name, Teaser, and Body fields all support multiple values based on the content mutation (also referred to as a revision), to allow different values to be displayed based on the viewing medium. Commonly, this functionality is used to show a different name when used in an email newsletter, or to customize the display of the content name for viewing on the website.

For all three fields, the mutated value can be removed by sending an empty string `""` to the relevant mutation's `value` field. The default/non-mutated value for the Teaser and Body fields can be removed in the same manner, but the Name field (which is required) cannot.

When the default/non-mutated field is requested via the GraphQL API, the field will return the Website mutation value if present, and the default value if none is present. This field supports `input` parameters (you can see the full set by introspecting the GraphQL schema from your client!) to override this behavior.

### Name

To set the name, use the `contentName` mutation, specifying the new value and mutation (revision) if necessary.

![Setting the content name (default/non-mutated) value.](https://3551656615-files.gitbook.io/~/files/v0/b/gitbook-legacy-files/o/assets%2F-MJmAeLxWsdoZNmpFobC%2F-MfEAPM4bYpuCt_TGug5%2F-MfEJTjn6eztSyBonJGX%2Fimage.png?alt=media\&token=4f95ee44-52a6-4e26-a888-0fa9c5778124)

![Setting the content name Email mutation value.](https://3551656615-files.gitbook.io/~/files/v0/b/gitbook-legacy-files/o/assets%2F-MJmAeLxWsdoZNmpFobC%2F-MfEAPM4bYpuCt_TGug5%2F-MfEJnCJSvLLVHRK6UAJ%2Fimage.png?alt=media\&token=d7308963-d848-4afa-9d76-2b9cc28bf4e2)

![Removing the content name Email mutation value.](https://3551656615-files.gitbook.io/~/files/v0/b/gitbook-legacy-files/o/assets%2F-MJmAeLxWsdoZNmpFobC%2F-MfEAPM4bYpuCt_TGug5%2F-MfEJxeMq2NTThUaFjpu%2Fimage.png?alt=media\&token=ef05ea66-ef87-4955-919b-40484e987960)

### Teaser

To modify the `teaser` field, use the `contentTeaser` mutation, specifying the new value and mutation (revision) if necessary. To remove the teaser, send an empty string for the `value` input.

{% hint style="info" %}
When querying for the teaser, be sure to send the `minLength` input to ensure the teaser is not truncated. Teasers are automatically truncated if they are under the minimum length or over the maximum length (which default to 75 and 125 characters, respectively.)
{% endhint %}

![Setting the content teaser field and using the \`minLength\` input arguments.](https://3551656615-files.gitbook.io/~/files/v0/b/gitbook-legacy-files/o/assets%2F-MJmAeLxWsdoZNmpFobC%2F-MfEKvY37kb34EYJfIIj%2F-MfEbweoV9NAGQXy_tx5%2Fimage.png?alt=media\&token=e4119bd6-257d-4414-a516-cfcabafe5e9e)

### Body

To modify the `body` field, use the `contentBody` mutation, specifying the new value and mutation (revision) if necessary. To remove the body, send an empty string for the `value` input.

![Setting the content body field.](https://3551656615-files.gitbook.io/~/files/v0/b/gitbook-legacy-files/o/assets%2F-MJmAeLxWsdoZNmpFobC%2F-MfEKvY37kb34EYJfIIj%2F-MfEcFgtF1fnarWzdKGO%2Fimage.png?alt=media\&token=66332b4b-b51b-4066-91a4-633933f4c107)

## Publishing

You can use the `contentPublishing` mutation to affect the contents `status` (one of draft, active, or deleted), the `published` date (when the content is available for viewing), and the `unpublished` date (when the content is no longer available).

Content is visible on your website when the content is in `active` status, the `published` date is in the past, and the `unpublished` date is in the future, or not set. The `textStatus` `Content` field contains a user-friendly version of the content state, with the notable addition of the `Scheduled` state to indicate the content is published, but not yet visible.

Content is also visible (but not indexable) on your website when accessed via Preview mode from BASE.

To immediately publish a content item, send the `active` value to the `status` input of the `contentPublishing` mutation.

![Immediately publishing a content item via the \`contentPublishing\` mutation.](https://3551656615-files.gitbook.io/~/files/v0/b/gitbook-legacy-files/o/assets%2F-MJmAeLxWsdoZNmpFobC%2F-MfEq2ym2CG2WK2Tf6yd%2F-MfEqfoBZZxC9N4_pBZO%2Fimage.png?alt=media\&token=05b339f4-decd-4fd2-bfb0-6d031deb9dce)

![Scheduling content to publish later via the \`contentPublishing\` mutation.](https://3551656615-files.gitbook.io/~/files/v0/b/gitbook-legacy-files/o/assets%2F-MJmAeLxWsdoZNmpFobC%2F-MfEq2ym2CG2WK2Tf6yd%2F-MfErCFY91vNvgf1Yge0%2Fimage.png?alt=media\&token=17e0fa2b-4012-417e-a0c0-bec32fd4059a)

{% hint style="warning" %}
If a `published` date has previously been set it will be retained **unless it is in the future**.
{% endhint %}

If there is a future `published` date already set, it will be updated to *now* to ensure the content is immediately accessible. To override this behavior, you must explicitly send a date in the `published` input.

{% hint style="warning" %}
If an `unpublished` date has previously been set it will be retained **unless it is in the past**.
{% endhint %}

If there is a past `unpublished` date already set, it will be removed to ensure the content is immediately accessible. To override this behavior, you must explicitly send a date in the `unpublished` input.

To immediately unpublish a content item, send the `draft` or `deleted` value to the `status` input of the `contentPublishing` mutation.

![Immediately unpublishing content by putting it in \`draft\` state via the \`contentPublishing\` mutation.](https://3551656615-files.gitbook.io/~/files/v0/b/gitbook-legacy-files/o/assets%2F-MJmAeLxWsdoZNmpFobC%2F-MfEq2ym2CG2WK2Tf6yd%2F-MfErfUg8STbx9G88VU6%2Fimage.png?alt=media\&token=787f2d76-61e7-4c29-8524-ffbc8e8cd88b)

## Custom Attributes

BASE supports setting custom text attributes on content items to store additional information, such as legacy/external IDs, or anything else you'd like! You can view and store any\* text value via the GraphQL API by using the `customAttribute` query field and the `contentCustomAttributes` mutation.

{% hint style="warning" %}
Only pre-defined custom attributes will show up in the BASE UI. If there's an attribute you'd like to see in the BASE UI, please reach out to us and we'd be happy to add it for you!
{% endhint %}

### Retrieving a custom attribute

To retrieve a custom attribute, send the `path` input to the `customAttribute` field to specify the custom attribute you'd like to retrieve. The following example returns the `externalId` field, and shows an example of aliasing to return it as a top-level field.

![Retrieving a custom attribute via the \`content\` query and the \`customAttribute\` field.](https://3551656615-files.gitbook.io/~/files/v0/b/gitbook-legacy-files/o/assets%2F-MJmAeLxWsdoZNmpFobC%2F-MfEt7DT23nYtbX8UcYb%2F-MfEx23ZhZ2sm_tfU6gp%2Fimage.png?alt=media\&token=051d9f3c-51f8-4749-b01a-b7691fa0f35d)

### Modifying a custom attribute

To set a custom attribute, include the `path` and `value` inputs to the `contentCustomAttribute` mutation. To remove a custom attribute, send an empty string `""` as the value.

![Setting a custom attribute via the \`contentCustomAttribute\` mutation.](https://3551656615-files.gitbook.io/~/files/v0/b/gitbook-legacy-files/o/assets%2F-MJmAeLxWsdoZNmpFobC%2F-MfEt7DT23nYtbX8UcYb%2F-MfEwLOmKBUMtBnBZnrT%2Fimage.png?alt=media\&token=89bc3848-6b25-4b37-8de3-a853c588e817)

![Removing a custom attribute via the \`contentCustomAttribute\` mutation.](https://3551656615-files.gitbook.io/~/files/v0/b/gitbook-legacy-files/o/assets%2F-MJmAeLxWsdoZNmpFobC%2F-MfEt7DT23nYtbX8UcYb%2F-MfEweuoxJ35Gt4N9nFb%2Fimage.png?alt=media\&token=7d046e86-aefe-428d-bce1-7abf9d011399)

## Modifying Event dates

The `startDate` and `endDate` fields are unique to the `ContentEvent` type and can be manipulated using the `contentEventDates` mutation. This mutation also supports the `allDay` Boolean parameter, which indicates that the times should be ignored from these dates.

{% hint style="warning" %}
As with all `Date` inputs available via the GraphQL API, make sure to send the value as a UNIX timestamp with millisecond precision!
{% endhint %}

![Setting the \`startDate\` and \`allDay\` fields via the \`contentEventDates\` mutation.](https://3551656615-files.gitbook.io/~/files/v0/b/gitbook-legacy-files/o/assets%2F-MJmAeLxWsdoZNmpFobC%2F-MfEx9-uel3sxIFgVqpP%2F-MfEz7HJf8HZD44JLsB2%2Fimage.png?alt=media\&token=9c8c654a-00b5-41ae-9c23-289ac3a2ae55)

## Modifying Contactable fields

All of the fields of the `Contactable` interface can be modified with the `contentContactFields` mutation. To remove a value, you must explicitly send a `null` value to the relevant input field.

![Setting Contactable fields via the \`contentContactFields\` mutation.](https://3551656615-files.gitbook.io/~/files/v0/b/gitbook-legacy-files/o/assets%2F-MJmAeLxWsdoZNmpFobC%2F-MfEx9-uel3sxIFgVqpP%2F-MfF-WJAo2tWvV3sLWQd%2Fimage.png?alt=media\&token=b9117717-3ca9-4cb7-b7a7-05453a6d6624)

{% hint style="warning" %}
Make sure you are modifying a content item that implements the `Contactable` interface when using this mutation. If you attempt to modify a content item that does not support these fields, the request will fail!
{% endhint %}

## Modifying Addressable fields

All of the fields of the `Addressable` interface can be modified with the `contentAddressFields` mutation. To remove a value, you must explicitly send a `null` value to the relevant input field.

![Setting \`Addressable\` fields via the \`contentAddressFields\` mutation.](https://3551656615-files.gitbook.io/~/files/v0/b/gitbook-legacy-files/o/assets%2F-MJmAeLxWsdoZNmpFobC%2F-MfF08KZjx3Q2Zg0AMl0%2F-MfF1093uCMaM3YKt4Sw%2Fimage.png?alt=media\&token=711de0a3-32fc-4e89-80ae-39d93c88e561)

{% hint style="warning" %}
Make sure you are modifying a content item that implements the `Addressable` interface when using this mutation. If you attempt to modify a content item that does not support these fields, the request will fail!
{% endhint %}