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

Create an Article Post

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

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.

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

curl

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

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

Create a Website Channel

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

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

curl

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

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

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

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

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 [email protected].

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