Entity Command API

A guide to using the Mindful Entity Command API to modify data.

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.

In addition to the authentication header, make sure to send the namespace header to designate the intended tenant for your request! This API also supports the view parameter to designate the tenant view. For most use cases, this should be main.

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:

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>

Command Metadata

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

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

Entity Kind Metadata

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

{
  "_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[],
}

Entity Form Metadata

{
  "_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[],
}  

Entity Fragment Metadata

{
  "_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[],
}

Attribute Metadata

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

Reference Metadata

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

Embed Metadata

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

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

This list is abbreviated — the current list of Entity Kinds can be found in the command metadata.

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

This list is abbreviated — the current list of available commands can be found in the command metadata.

Examples

Create a Company Post

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

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",
  }),
});

curl

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"}'

Modify Product Post: Add Company

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

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",
  }),
});

curl

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"}'

Modify Product Post: Replace Company

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

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",
  }),
});

curl

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"}'
  

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.

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",
  }),
});

curl

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"}'
  

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.

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",
  }),
});

curl

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"}'
  

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.

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",
  }),
});

curl

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"}'
  

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.

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",
  }),
});

curl

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"}'
  

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 [e-mail].

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