Transactions

A transaction is a list of operations that execute atomically. This reference describes the JSON structure of commit requests. Use it alongside the operations reference to build correct, replayable payloads.

Overview

All state changes flow through the /v1/write/namespaces/{namespace_id}/commit endpoint as transactions. The write daemon validates, executes, and appends operations to the commit log backend before returning a success response. This means every mutation is auditable and replayable by design.

Structure

Commit Request

{
  "actor_id": "lab-operator-17",
  "policy_id": null,
  "operations": [
    { "op": "OperationName", "args": { ... } },
    { "op": "AnotherOperation", "args": { ... } }
  ],
  "idempotency_key": "optional-unique-key",
  "metadata": {
    "custom_field": "optional user metadata"
  },
  "origin": {
    "client": "assetcore-sdk",
    "source": "batch-import"
  }
}

Operation Envelope

Each operation has the same envelope structure. This uniformity is what makes validation and tooling reliable across all domains.

{
  "op": "OperationName",
  "args": {
    "field1": "value1",
    "field2": 123
  }
}

Fields

Request Fields

Field	Type	Required	Description
operations	array	Yes	List of operations to execute
actor_id	string	No	Actor identifier for audit trails
policy_id	string	No	Policy identifier (future use)
idempotency_key	string	No	Unique key for deduplication
metadata	object	No	User-defined metadata echoed in response
origin	object	No	Optional origin metadata echoed in response

Operation Envelope Fields

Field	Type	Required	Description
op	string	Yes	Operation identifier
args	object	Yes	Operation-specific arguments

Response Fields

Field	Type	Description
namespace	integer	Namespace in which the transaction executed
commit_id	string	Opaque commit identifier used for reverse commits
outcome	string	Committed or RolledBack
world_seq_start	integer	First world sequence number in the commit
world_seq_end	integer	Final world sequence number in the commit
event_count	integer	Number of events emitted
start_time_ms	integer	Transaction start time (milliseconds since epoch)
commit_time_ms	integer	Transaction commit time (milliseconds since epoch)
server_correlation_id	string	Server-assigned correlation ID for tracing
client_correlation_id	string	Client-provided correlation ID when supplied
origin	object	Echo of caller-supplied origin metadata
echo	object	Echo of request metadata including idempotency_key
created_entities	object	Summary of entities created during the commit

Examples

Minimal Transaction

{
  "operations": [
    {
      "op": "CreateContainer",
      "args": {
        "container_id": 1001,
        "kind": { "type": "balance" },
        "owner": null,
        "policies": null
      }
    }
  ]
}

Transaction with Idempotency

{
  "operations": [
    {
      "op": "CreateContainer",
      "args": {
        "container_id": 1002,
        "kind": { "type": "balance" },
        "owner": null,
        "policies": null
      }
    }
  ],
  "idempotency_key": "create-container-2026-01-15-001"
}

Multi-Operation Transaction

{
  "operations": [
    {
      "op": "CreateContainer",
      "args": {
        "container_id": 2001,
        "kind": { "type": "slots", "count": 8 },
        "owner": null,
        "policies": null
      }
    },
    {
      "op": "RegisterClass",
      "args": {
        "request": {
          "class_id": 200,
          "flags": 2,
          "name": "SampleClass"
        }
      }
    },
    {
      "op": "AddInstance",
      "args": {
        "class_id": 200,
        "key": 1,
        "location": {
          "container_id": 2001,
          "kind": "slot",
          "slot_index": 1
        }
      }
    }
  ],
  "metadata": {
    "experiment_id": "exp-001",
    "operator": "system"
  }
}

Response:

{
  "namespace": 5001,
  "commit_id": "00000000000000000000000000000001",
  "outcome": "Committed",
  "world_seq_start": 5,
  "world_seq_end": 5,
  "event_count": 3,
  "start_time_ms": 1769800000000,
  "commit_time_ms": 1769800000123,
  "server_correlation_id": "wr-0000000000000001-0000000000000042",
  "echo": {
    "metadata": {
      "experiment_id": "exp-001",
      "operator": "system"
    }
  },
  "created_entities": {
    "classes": [200],
    "containers": [2001],
    "instances": [9001]
  }
}

Idempotent Retry Response

When the same idempotency key is sent again:

{
  "namespace": 5001,
  "commit_id": "00000000000000000000000000000001",
  "outcome": "Committed",
  "world_seq_start": 5,
  "world_seq_end": 5,
  "event_count": 3,
  "start_time_ms": 1769800000000,
  "commit_time_ms": 1769800000123,
  "server_correlation_id": "wr-0000000000000001-0000000000000042",
  "echo": {
    "idempotency_key": "create-sample-2026-01-15-001",
    "metadata": {
      "experiment_id": "exp-001",
      "operator": "system"
    }
  },
  "created_entities": {
    "classes": [200],
    "containers": [2001],
    "instances": [9001]
  }
}

The x-asset-idempotency: hit header indicates a cached response.

Related references

• Action Reference - Complete operation reference
• Recipes - Common multi-operation patterns
• Error Model - Handling transaction failures