Skip to content

API mutations

Mutations provide write access to schema-defined data through the API.

All mutations are executed transactionally per request and are subject to the same validation and rule enforcement as interactive operations in the system.

If a mutation fails validation, no partial changes are committed.

Characteristics

Mutation execution has the following characteristics:

  • Write rules are enforced
  • Classifications referenced by write rules are evaluated
  • Fully transactional per request

Mutations operate on rows identified by either the internal id or the external _id identifier.

Mutation types

The API exposes three primary mutation operations for every table in the schema.

Create row (add_<entity>)

Creates a new row in the target table.

Example – create a new person:

mutation {
  add_person(input: {
    first_name: "Anna"
    last_name: "Larsson"
  }) {
    id
    _id
  }
}

Update row (edit_<entity>)

Updates an existing row identified by either id or _id.

Example – update by id:

mutation {
  edit_person(id: 123, input: {
    last_name: "Svensson"
  }) {
    id
    last_name
  }
}

Example – update by _id:

mutation {
  edit_person(_id: "external-42", input: {
    first_name: "Anna"
  }) {
    id
    first_name
  }
}

Delete row (delete_<entity>)

Deletes an existing row identified by either id or _id.

Example – delete by id:

mutation {
  delete_person(id: 123)
}

Example – delete by _id:

mutation {
  delete_person(_id: "external-42")
}

Relation mutations

Relations can be modified through nested mutation inputs using the _action field.

Supported actions include:

  • ADD – create a relation and optionally create a new related row
  • EDIT – modify an existing related row
  • REMOVE – remove the relation only
  • DELETE – remove both the relation and the related row

Relation mutation behavior is documented separately in API – relations.

Related concepts