# Entity Command API

This API provides a collection of JSON data endpoints to perform specific actions (commands) against Mindful Entity Kinds.

## Connecting to the API

This API requires user, machine, or company token [authentication](/mindful-apis/authentication.md).

In addition to the authentication header, make sure to send the namespace header to designate the intended [tenant](/mindful-apis/getting-started.md#tenancy) for your request! This API also supports the `view` parameter to designate the tenant view. For most use cases, this should be `main`.

```http
POST https://api.mindfulcms.com/commands/<entity-kind>/<command-key> HTTP/1.1
Authentication: Bearer <api-token>
Content-Type: application/json
Host: api.mindfulcms.com
X-Namespace: <org-key>/<workspace-key>

{
  "command": {
    "input": [...]
  },
  "view": "<view-key>"
}
```

The shape of the `input` param varies based on the command being used, but it will always be an array of input payloads.

### Metadata

The current metadata for available commands, entities, and fragments can be retrieved by sending a GET request to the /commands endpoint:

```http
GET https://api.mindfulcms.com/commands HTTP/1.1
Authentication: Bearer <api-token>
Content-Type: application/json
Host: api.mindfulcms.com
X-Namespace: <org-key>/<workspace-key>
```

<details>

<summary>Command Metadata</summary>

The `commands` key in the metadata response indicates the name, resource, and URL to access to send a command.

```json
{
  "_id": String,      // The command name
  "resource": String, // The kebab-case command name
  "endpoint": String, // The relative URL of the command route
}
```

</details>

<details>

<summary>Entity Kind Metadata</summary>

The `entities` key in the metadata response indicates the name and resource of each Entity Kind. It includes metadata about available props (fields), edges (single related item), connections (multiple related items), embedManies (multiple embedded Entity Fragments), and embedOnes (single embedded Entity Fragment).

If the Entity Kind supports Variant Forms, the same information is available under the `forms` key for each Variant Form.

#### Entity Metadata

```json
{
  "_id": String, // The Entity Kind type key
  "resource": String, // The kebab-case Entity Kind type key
  "forms": EntityForm[], // An array of supported variant forms
  "connections": Reference[],
  "edges": Reference[],
  "embedManies": Embed[],
  "embedOnes": Embed[],
  "props": Attribute[],
}
```

</details>

<details>

<summary>Entity Form Metadata</summary>

```javascript
{
  "_id": String, // The Entity Variant Form type key
  "resource": String, // The kebab-case Entity Variant Form type key
  "connections": Reference[],
  "edges": Reference[],
  "embedManies": Embed[],
  "embedOnes": Embed[],
  "props": Attribute[],
}  
```

</details>

<details>

<summary>Entity Fragment Metadata</summary>

```javascript
{
  "_id": String, // The Entity Fragment type key
  "resource": String, // The kebab-case Entity Kind type key
  "forms": EntityForm[], // An array of supported variant forms
  "connections": Reference[],
  "edges": Reference[],
  "embedManies": Embed[],
  "embedOnes": Embed[],
  "props": Attribute[],
}
```

</details>

<details>

<summary>Attribute Metadata</summary>

```javascript
{
  "_id": String,       // The field key/name
  "required": Boolean, // If the field is required
}
```

</details>

<details>

<summary>Reference Metadata</summary>

```javascript
{
  "_id": String,
  "required": Boolean,
  "ref": {
    "kind": String, // The referenced Entity Kind key
    "disallow": String[], // Disallowed values
  },
}
```

</details>

<details>

<summary>Embed Metadata</summary>

```javascript
{
  "_id": String,
  "required": Boolean,
  "ref": {
    "kind": String, // The referenced Entity Fragment key
    "disallow": String[], // Disallowed values
  },
}
```

</details>

## Available Entity Kinds

* Advertising Company
* Advertising Creative
* Advertising Email Channel
* Advertising Image
* Advertising Line Item
* Advertising Order
* Advertising Post
* Advertising Unit
* Advertising Website Channel
* Email Automation Job
* Email Channel
* Email Channel Block
* Email Channel Deployment
* File
* Image
* Label
* Label Option
* Magazine Channel
* Magazine Channel Issue
* Magazine Channel Section
* Place or Thing
* Post
* Post Interaction
* Vocab
* Vocab Term
* Website Channel
* Website Channel Topic

{% hint style="info" %}
This list is abbreviated — the current list of Entity Kinds can be found in the [command metadata](#metadata).
{% endhint %}

## Available Commands

* Clone
* Create
* Delete
* Delete Connection Edges
* Delete Edge
* Delete Embed Manies
* Delete Embed One
* Merge
* Modify Connection Edge Prop Value
* Modify Edge Prop Value
* Modify Embed Many Prop Value
* Modify Embed Many Prop Values
* Modify Embed One Prop Value
* Modify Embed One Prop Values
* Modify Multiple Connection Edge Prop Values
* Modify Multiple Embed Many Prop Values
* Modify Prop Value
* Modify Prop Values
* Replace Existing Edge
* Set New Connection Edges
* Set New Edge
* Set New Embed Manies
* Set New Embed One
* Set or Delete Connection Edges

{% hint style="info" %}
This list is abbreviated — the current list of available commands can be found in the [command metadata](#metadata).
{% endhint %}

## Examples

### Create a Company Post

This example creates a new Post, using the  "Company" Variant Form, specifying the name field.

{% tabs %}
{% tab title="JavaScript" %}

```javascript

const input = [
  {
    form: "COMPANY",
    props: {
      name: "ACME Co., Inc.",
    },
  },
];

const url = 'https://api.mindfulcms.com/commands/post/create';
await fetch(url, {
  method: 'POST',
  headers: {
    'authorization': 'Bearer <MY-AUTH-TOKEN>',
    'content-type': 'application/json',
    'x-namespace': '<account-key>/<workspace-key>',
  },
  body: JSON.stringify({
    command: { input },
    view: "main",
  }),
});

```

{% endtab %}

{% tab title="curl" %}

```sh

curl -X POST https://api.mindfulcms.com/commands/post/create \
  -H 'Authorization: Bearer <MY-AUTH-TOKEN>' \
  -H 'Content-Type: application/json' \
  -H 'X-Namespace: <account-key>/<workspace-key>' \
  -d '{"command":{"input":[{"form":"COMPANY","props":{"name":"ACME Co., Inc."}}]},"view":"main"}'

```

{% endtab %}
{% endtabs %}

### Create an Article Post

This example creates a new Post, using the  "Post" Variant Form, specifying the title and the display type of `Article`.

{% hint style="info" %}
Multiple display types are available for Post entities, including Article, News, Blog, and more.

For a complete list, review the Entity Form metadata from the Entity Metadata endpoint.
{% endhint %}

{% tabs %}
{% tab title="JavaScript" %}

```javascript

const input = [
  {
    form: "POST",
    props: {
      title: "Test Article",
      type: "ARTICLE"
    }
  }
];

const url = 'https://api.mindfulcms.com/commands/post/create';
await fetch(url, {
  method: 'POST',
  headers: {
    'authorization': 'Bearer <MY-AUTH-TOKEN>',
    'content-type': 'application/json',
    'x-namespace': '<account-key>/<workspace-key>',
  },
  body: JSON.stringify({
    command: { input },
    view: "main",
  }),
});

```

{% endtab %}

{% tab title="curl" %}

```sh

curl -X POST https://api.mindfulcms.com/commands/post/create \
  -H 'Authorization: Bearer <MY-AUTH-TOKEN>' \
  -H 'Content-Type: application/json' \
  -H 'X-Namespace: <account-key>/<workspace-key>' \
  -d '{"command":{"input":[{"form":"POST","props":{"title":"Test Article","type":"ARTICLE"}}]},"view":"main"}'

```

{% endtab %}
{% endtabs %}

### Modify Product Post: Add Company

This example modifies an existing Product Post to set the company edge.

{% tabs %}
{% tab title="JavaScript" %}

```javascript

const input = [
  {
    node: {
      _id: "<product-id>",
      form: "PRODUCT",
    },
    edge: {
      name: "company",
      value: {
        node: {
          _id: "<company-id>",
          form: "COMPANY",
        },
      },
    },
  },
];

const url = 'https://api.mindfulcms.com/commands/post/set-new-edge';
await fetch(url, {
  method: 'POST',
  headers: {
    'authorization': 'Bearer <MY-AUTH-TOKEN>',
    'content-type': 'application/json',
    'x-namespace': '<account-key>/<workspace-key>',
  },
  body: JSON.stringify({
    command: { input },
    view: "main",
  }),
});

```

{% endtab %}

{% tab title="curl" %}

```sh

curl -X POST https://api.mindfulcms.com/commands/post/set-new-edge \
  -H 'Authorization: Bearer <MY-AUTH-TOKEN>' \
  -H 'Content-Type: application/json' \
  -H 'X-Namespace: <account-key>/<workspace-key>' \
  -d '{"command":{"input":[{"node":{"_id":"<product-id>","form":"PRODUCT"},"edge":{"name":"company","value":{"node":{"_id":"<company-id>","form":"COMPANY"}}}}]},"view":"main"}'

```

{% endtab %}
{% endtabs %}

### Modify Product Post: Replace Company

This example modifies an existing Product Post to replace the company edge's related node.

{% tabs %}
{% tab title="JavaScript" %}

```javascript

const input = [
  {
    node: {
      _id: "<product-id>",
      form: "PRODUCT",
    },
    edge: {
      _id: "<existing-company-edge-id>",
      name: "company",
      value: {
        node: {
          _id: "<company-id>",
          form: "COMPANY",
        },
      },
    },
  },
];

const url = 'https://api.mindfulcms.com/commands/post/replace-existing-edge';
await fetch(url, {
  method: 'POST',
  headers: {
    'authorization': 'Bearer <MY-AUTH-TOKEN>',
    'content-type': 'application/json',
    'x-namespace': '<account-key>/<workspace-key>',
  },
  body: JSON.stringify({
    command: { input },
    view: "main",
  }),
});

```

{% endtab %}

{% tab title="curl" %}

```sh

curl -X POST https://api.mindfulcms.com/commands/post/set-new-edge \
  -H 'Authorization: Bearer <MY-AUTH-TOKEN>' \
  -H 'Content-Type: application/json' \
  -H 'X-Namespace: <account-key>/<workspace-key>' \
  -d '{"command":{"input":[{"node":{"_id":"<product-id>","form":"PRODUCT"},"edge":{"_id":"<existing-company-edge-id>","name":"company","value":{"node":{"_id":"<company-id>","form":"COMPANY"}}}}]},"view":"main"}'
  
```

{% endtab %}
{% endtabs %}

### Create a Website Channel

This example creates a new Website Channel, specifying the asset and root domain URLs.

{% tabs %}
{% tab title="JavaScript" %}

```javascript

const input = [
  {
    "embedOnes": {
      "date": {},
      "hostname": {
        "props": {
          "root": "www.test.com",
          "asset": "cdn.test.com"
        }
      },
      "language": {}
    },
    "props": {
      "abbreviation": "TST",
      "name": "Test.com",
      "description": "Exclusive testing website."
    }
  }
];

const url = 'https://api.mindfulcms.com/commands/website-channel/create';
await fetch(url, {
  method: 'POST',
  headers: {
    'authorization': 'Bearer <MY-AUTH-TOKEN>',
    'content-type': 'application/json',
    'x-namespace': '<account-key>/<workspace-key>',
  },
  body: JSON.stringify({
    command: { input },
    view: "main",
  }),
});

```

{% endtab %}

{% tab title="curl" %}

```sh

curl -X POST https://api.mindfulcms.com/commands/website-channel/create \
  -H 'Authorization: Bearer <MY-AUTH-TOKEN>' \
  -H 'Content-Type: application/json' \
  -H 'X-Namespace: <account-key>/<workspace-key>' \
  -d ''{"command":{"input":{"embedOnes":{"date":{},"hostname":{"props":{"root":"www.evrepairmag.com","asset":"img.evrepairmag.com"}},"language":{}},"props":{"abbreviation":"EVRM","name":"EV Repair","description":"The only publication in Canada that focuses exclusively on electric vehicle collision repair."}}},"view":"main"}''
  
```

{% endtab %}
{% endtabs %}

### Create an Email Channel Deployment

This example creates a new Email Channel Deployment, using the "Omeda" Variant Form, specifying the day, name, and subject line fields, and adding the Email Channel as a related edge.

{% tabs %}
{% tab title="JavaScript" %}

```javascript

const input = [
  {
    "form": "OMEDA",
    "edges": {
      "emailChannel": {
        "node": {
          "_id": "67ab672f8576d21b018b456b",
          "form": "PRIMARY",
        },
      },
    },
    "props": {
      "day": "2025-04-08",
      "name": "New Campaign - Tuesday, April 8, 2025",
      "subjectLine": "Urgent news update: Widget sale!",
    },
  },
];

const url = 'https://api.mindfulcms.com/commands/email-channel-deployment/create';
await fetch(url, {
  method: 'POST',
  headers: {
    'authorization': 'Bearer <MY-AUTH-TOKEN>',
    'content-type': 'application/json',
    'x-namespace': '<account-key>/<workspace-key>',
  },
  body: JSON.stringify({
    command: { input },
    view: "main",
  }),
});

```

{% endtab %}

{% tab title="curl" %}

```sh

curl -X POST https://api.mindfulcms.com/commands/email-channel-deployment/create \
  -H 'Authorization: Bearer <MY-AUTH-TOKEN>' \
  -H 'Content-Type: application/json' \
  -H 'X-Namespace: <account-key>/<workspace-key>' \
  -d '{"command":{"input":[{"form":"OMEDA","edges":{"emailChannel":{"node":{"_id":"67ab672f8576d21b018b456b","form":"PRIMARY"}}},"props":{"day":"2025-04-08","name":"New Campaign - Tuesday, April 8, 2025","subjectLine":"Urgent news update: Widget sale!"}}]},"view":"main"}'
  
```

{% endtab %}
{% endtabs %}

### Pause an Email Advertising Channel Automation Job

This example modifies the embedded Automation Config of an Advertising Email Channel to pause execution of recurring Email Automation Jobs.

{% tabs %}
{% tab title="JavaScript" %}

```javascript

const input = [
  {
    "node": {
      "_id": "<advertising-email-channel-id>"
    },
    "embed": {
      "name": "automationConfig",
      "value": {
        _id: "<embedded-automation-config-id>",
        prop: {
          name: "paused",
          value: true,
        },
      },
    },
  },
];

const url = 'https://api.mindfulcms.com/commands/advertising-email-channel/modify-embed-one-prop-value';
await fetch(url, {
  method: 'POST',
  headers: {
    'authorization': 'Bearer <MY-AUTH-TOKEN>',
    'content-type': 'application/json',
    'x-namespace': '<account-key>/<workspace-key>',
  },
  body: JSON.stringify({
    command: { input },
    view: "main",
  }),
});

```

{% endtab %}

{% tab title="curl" %}

```sh

curl -X POST https://api.mindfulcms.com/commands/advertising-email-channel/modify-embed-one-prop-value \
  -H 'Authorization: Bearer <MY-AUTH-TOKEN>' \
  -H 'Content-Type: application/json' \
  -H 'X-Namespace: <account-key>/<workspace-key>' \
  -d '{"command":{"input":[{"node":{"_id":"<advertising-email-channel-id>"},"embed":{"name":"automationConfig","value":{"_id":"<embedded-automation-config-id>","prop":{"name":"paused","value":true}}}}]},"view":"main"}'
  
```

{% endtab %}
{% endtabs %}

### Create a Root Website Channel Topic

This example creates a new Website Channel Topic, using the Root Variant Form, specifying the name and slug fields, and setting the website channel edge.

{% tabs %}
{% tab title="JavaScript" %}

```javascript

const input = [
  {
    "form": "ROOT",
    "edges": {
      "websiteChannel": {
        "node": {
          "_id": "<website-channel-id>"
        },
      },
    },
    "props": {
      "name": "My New Root Topic",
      "slug": "my-new-root-topic",
    },
  },
];

const url = 'https://api.mindfulcms.com/commands/website-channel-topic/create';
await fetch(url, {
  method: 'POST',
  headers: {
    'authorization': 'Bearer <MY-AUTH-TOKEN>',
    'content-type': 'application/json',
    'x-namespace': '<account-key>/<workspace-key>',
  },
  body: JSON.stringify({
    command: { input },
    view: "main",
  }),
});

```

{% endtab %}

{% tab title="curl" %}

```sh

curl -X POST https://api.mindfulcms.com/commands/website-channel-topic/create \
  -H 'Authorization: Bearer <MY-AUTH-TOKEN>' \
  -H 'Content-Type: application/json' \
  -H 'X-Namespace: <account-key>/<workspace-key>' \
  -d '{"command":{"input":[{"form":"ROOT","edges":{"websiteChannel":{"node":{"_id":"<website-channel-id>"}}},"props":{"name":"My New Root Topic","slug":"my-new-root-topic"}}]},"view":"main"}'
  
```

{% endtab %}
{% endtabs %}

### Create a Child Website Channel Topic

This example creates a new Website Channel Topic, using the Child Variant Form, specifying the name and slug fields, and setting the parent edge.

{% tabs %}
{% tab title="JavaScript" %}

```javascript

const input = [
  {
    "form": "CHILD",
    "edges": {
      "parentTopic": {
        "node": {
          "_id": "<root-website-channel-topic-id>",
          "form": "ROOT",
        },
      },
    },
    "props": {
      "name": "My New Child Topic",
      "slug": "my-new-child-topic",
    },
  },
];

const url = 'https://api.mindfulcms.com/commands/website-channel-topic/create';
await fetch(url, {
  method: 'POST',
  headers: {
    'authorization': 'Bearer <MY-AUTH-TOKEN>',
    'content-type': 'application/json',
    'x-namespace': '<account-key>/<workspace-key>',
  },
  body: JSON.stringify({
    command: { input },
    view: "main",
  }),
});

```

{% endtab %}

{% tab title="curl" %}

```sh

curl -X POST https://api.mindfulcms.com/commands/advertising-email-channel/modify-embed-one-prop-value \
  -H 'Authorization: Bearer <MY-AUTH-TOKEN>' \
  -H 'Content-Type: application/json' \
  -H 'X-Namespace: <account-key>/<workspace-key>' \
  -d '{"command":{"input":[{"form":"CHILD","edges":{"parentTopic":{"node":{"_id":"<root-website-channel-topic-id>","form":"ROOT"}}},"props":{"name":"My New Child Topic","slug":"my-new-child-topic"}}]},"view":"main"}'
  
```

{% endtab %}
{% endtabs %}

{% hint style="success" %}
That's all for now! If you have any specific questions about using the Entity Command API or have suggestions on how this guide can be improved, please let us know via <support@parameter1.com>.

Please feel free to leave feedback on this page and let us know what you think.
{% endhint %}


---

# Agent Instructions: Querying This Documentation

If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter:

```
GET https://docs.parameter1.com/mindful-apis/entity-command-api.md?ask=<question>
```

The question should be specific, self-contained, and written in natural language.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.