Set Commit Messages on Document Operations

Set an author and message on any document write so that the commit log records who made the change and why.

The parameters

Every write endpoint on the Document API (POST, PUT, DELETE) accepts two query parameters that are recorded in the commit:

These parameters apply to:

• POST /api/document/{path} (insert)
• PUT /api/document/{path} (replace)
• DELETE /api/document/{path} (delete)

curl example (insert)

Loading…

The author and message values are URL-encoded query parameters. Use + for spaces or %20.

TypeScript example (JS client)

import TerminusClient from "@terminusdb/terminusdb-client";

const client = new TerminusClient.WOQLClient("http://localhost:6363", {
  user: "admin",
  key: "root",
});
client.db("MyDatabase");

await client.addDocument(
  { "@id": "terminusdb:///data/product-2001", "name": "Widget Pro", "price": 29.99 },
  { raw_json: true },
  undefined,
  "Add new product SKU-2001"  // commit message
);

The fourth parameter to addDocument is the commit message. The author is taken from the client's authenticated user.

Verify your commit message

After writing, confirm the message was recorded:

Loading…

Expected:

[
  {
    "@id": "ValidCommit/<commit-sha>",
    "@type": "ValidCommit",
    "author": "jane@example.com",
    "identifier": "<commit-sha>",
    "instance": "layer_data:Layer_<hash>",
    "message": "Add new product SKU-2001",
    "parent": "ValidCommit/<previous-sha>",
    "schema": "layer_data:Layer_<hash>",
    "timestamp": 1714400000.0
  }
]

Python example

from terminusdb_client import Client

client = Client("http://localhost:6363")
client.connect(user="admin", key="root", db="MyDatabase")

client.insert_document(
    {"@type": "Product", "name": "Widget Pro", "price": 29.99},
    commit_msg="Add new product SKU-2001",
    last_data_version=None
)

The Python client takes commit_msg as a named parameter. The author is derived from the authenticated user.

WOQL commit messages

When writing via WOQL queries, the commit message is passed as the second argument to client.query():

await client.query(
  WOQL.insert_document({ "@type": "Product", "name": "Widget Pro", "price": 29.99 }, "v:Id"),
  "Add new product SKU-2001",  // commit message
  undefined,                    // all_witnesses
  undefined,                    // last_data_version
  "jane@example.com"           // author
);

Best practices

• Use the operator's real identity as author — not a generic "admin"
• Describe intent, not mechanics — "Increase credit limit after Q1 review" beats "Updated document"
• Include a reference if applicable — "Fix price per JIRA-1234"
• Keep messages under 100 characters — they appear in log listings and diffs
• Use present tense — "Add product" not "Added product" (matches git conventions)

See also

• Audit Data Changes — full tutorial on using the commit log for auditing
• Recover Data from Version History — using commit messages to identify recovery points
• Document API Reference — full parameter reference