Change one entity

What it is

Three mutations start an action on one entity without a plan from rules:

• executeActionAddition creates the subject.
• executeActionUpdate changes the predicates the document carries and leaves the rest alone.
• executeActionDeletion removes the subject.

Each one stages a plan and runs it like any other, so the change is validated and recorded.

An action needs an action shape: the shape a handler is registered for, which decides what the action may write and how it reaches the outside system. supportedActionShapes lists them for a type.

The properties of an addition or an update is a JSON-LD document that describes the subject. Build the whole input with entityActionInput, which writes each literal with the datatype your generated schema declares.

Import

import {
  ExecuteAgentActionAdditionDocument,
  ExecuteAgentActionDeletionDocument,
  ExecuteAgentActionUpdateDocument,
  SupportedActionShapesDocument,
  mantaGraphQLClient,
} from "@manta-eu/client";
import { entityActionInput } from "@manta-eu/client/shared/action-document";
import { mintInstanceIri } from "@manta-eu/client/shared/rdf-namespaces";

Example

import { EventSchema } from "./.ldkit/your-namespace";

const client = mantaGraphQLClient(new URL("https://app.hiremanta.com"), undefined, {
  Authorization: `Bearer ${accessToken}`,
  "x-manta-datastore": "your-datastore",
});

const { supportedActionShapes } = await client.request(SupportedActionShapesDocument, {
  rdfType: EventSchema["@type"],
});
const shape = supportedActionShapes.supportedActionShapes.find((each) => each.supportsUpdate);

if (!shape) throw new Error("No action shape updates an Event");

const { actionShape } = shape;
const input = entityActionInput(EventSchema, actionShape, {
  $id: eventIri,
  capacity: 120,
  startsAt: new Date("2026-11-30T18:00:00Z"),
});

const { executeActionUpdate } = await client.request(ExecuteAgentActionUpdateDocument, { input });

Send only the fields that change: an update writes every predicate in the document. To clear a property, name its key in the last argument:

const input = entityActionInput(EventSchema, actionShape, { $id: eventIri }, ["startsAt"]);

An addition needs an IRI nothing describes yet:

const $id = mintInstanceIri(EventSchema["@type"], crypto.randomUUID());
const input = entityActionInput(EventSchema, actionShape, { $id, name: "Launch", capacity: 120 });

await client.request(ExecuteAgentActionAdditionDocument, { input });

A deletion carries no document:

await client.request(ExecuteAgentActionDeletionDocument, {
  input: { subjectIri: eventIri, rdfType: EventSchema["@type"], actionShape },
});

Request

supportedActionShapes(rdfType) returns each shape’s actionShape, rdfTypes, operations, and supportsCreate, supportsUpdate and supportsDelete.

entityActionInput(schema, actionShape, entity, cleared?) takes an LDKit schema with an @type, the action shape, an entity with $id and any of the schema’s keys, and the keys to clear. It returns the mutation input: subjectIri is the entity’s $id, rdfType the schema’s @type, and properties the document:

{
  "@id": "https://example.org/vocab#Event_1",
  "@type": "https://example.org/vocab#Event",
  "https://example.org/vocab#capacity": {
    "@value": "120",
    "@type": "http://www.w3.org/2001/XMLSchema#integer"
  },
  "https://example.org/vocab#startsAt": {
    "@value": "2026-11-30T18:00:00.000Z",
    "@type": "http://www.w3.org/2001/XMLSchema#dateTime"
  }
}

Strings and enum values stay plain, an IRI property becomes { "@id": ... }, and a nested schema becomes a blank node. A list with one element comes out as that element.

A cleared key is sent as { "@id": "http://www.w3.org/2002/07/owl#Nothing" }. To build only the document, call entityActionDocument(schema, entity).

• The document must give the subject the rdfType you send.
• An update describes only the subject and its blank nodes.
• An addition may describe further new entities, each with its own action shape.

Response

Each mutation returns success, code, error, namedGraphIri and workflowId. namedGraphIri is the plan it staged; read the run from it as in Run history. A rejected document returns success: false with code: BAD_REQUEST and the reason in error, and a second action on a subject that already has one running returns code: CONFLICT. A value with the wrong datatype is not rejected here: the run fails, and the run history carries the message.