Commits

Commits are the only write path for repository data. A single commit can contain multiple operations — adding things, revising data, creating assertions, and managing collections — all applied atomically.

---

POST /api/repos/:orgName/:repoName/commit

Create a commit with one or more operations.

Auth: Required, repo:write scope.

Path Parameters

Parameter	Type	Description
orgName	string	Organization name
repoName	string	Repository name

Request Body

Field	Type	Required	Description
author	string	Yes	Author name for the commit
message	string	No	Commit message
operations	array	Yes	Array of operation objects (see below)

Operation Schema

Each operation in the operations array has a different shape depending on its operation and kind. See Commit Operations for detailed semantics.

Add a thing

{
  "operation": "add",
  "kind": "thing",
  "name": "temp-1",
  "data": { "location": "Building A", "type": "temperature" }
}

Add an assertion

{
  "operation": "add",
  "kind": "assertion",
  "name": "temp-1-reading-v1",
  "about": "Sensor/temp-1",
  "data": { "value": 72.5, "unit": "fahrenheit" }
}

Add a shape

{
  "operation": "add",
  "kind": "shape",
  "name": "Sensor",
  "data": { "fields": { "location": "string", "type": "string" } }
}

Shape data supports a top-level description, typed field objects with per-field descriptions, and field constraints (string enum/length, number range, typed wref shape, array bounds):

{
  "operation": "add",
  "kind": "shape",
  "name": "Sensor",
  "data": {
    "description": "A physical sensor device",
    "fields": {
      "location": { "type": "string", "description": "Installation site" },
      "reading": { "type": "number", "minimum": 0 },
      "owner": { "type": "wref", "shape": "Device" },
      "type": "string"
    }
  }
}

Add a collection

{
  "operation": "add",
  "kind": "collection",
  "type": "set",
  "members": ["Sensor/temp-1", "Sensor/temp-2"]
}

Revise a thing

{
  "operation": "revise",
  "kind": "thing",
  "name": "temp-1",
  "data": { "location": "Building B", "type": "temperature" }
}

Deactivate a thing

{
  "operation": "revise",
  "kind": "thing",
  "name": "temp-1",
  "data": {},
  "active": false
}

Operation Fields

Field	Type	Required	Description
operation	string	Yes	"add" or "revise"
kind	string	Yes	"shape", "thing", "assertion", or "collection"
name	string	Yes	Entity name (optional for add collection)
data	object	Varies	Data payload. Required for shapes, things, and assertions. Not accepted for collections.
about	string	No	Target wref such as Sensor/temp-1 (required for assertions)
active	boolean	No	Set to false to deactivate (revise only)
type	string	Varies	Collection type: "pair", "triple", "set", "list". Required for add collection.
members	string[]	Varies	Member wrefs. Required for add collection.

Response 201

{
  "number": 43,
  "author": "sensor-agent",
  "message": "Update sensor location",
  "operationCount": 1,
  "operations": [
    {
      "name": "temp-1",
      "operation": "revise",
      "version": 4,
      "dataHash": "a1b2c3d4"
    }
  ]
}

Field	Type	Description
number	number	Commit sequence number
author	string	Commit author
message	string	Commit message
operationCount	number	Number of operations in the commit
operations	array	Result of each operation with name, operation type, version, and data hash

Errors

Code	Status	Description
VALIDATION_ERROR	400	Invalid operation schema, missing required fields, or malformed data
SHAPE_MISMATCH	400	Operation kind doesn’t match the target shape, or a typed wref field references a thing belonging to the wrong shape
CROSS_REPO_MUTATION	400	Operation references an entity in a different repository
RESERVED_NAME	400	The name is reserved by the system
ILLEGAL_OP_SEQUENCE	400	Invalid operation sequence (e.g., revising a thing that doesn’t exist)
WREF_UNRESOLVABLE	404	A wref in the operation data could not be resolved — the referenced thing does not exist or the reference format is invalid
NOT_FOUND	404	Repository not found
FORBIDDEN	403	Insufficient permissions
RATE_LIMITED	429	Too many write requests. Honor Retry-After before retrying.

Example

curl -X POST https://api.warmhub.ai/api/repos/myorg/myrepo/commit \
  -H "Authorization: Bearer <token>" \
  -H "Content-Type: application/json" \
  -d '{
    "author": "sensor-agent",
    "message": "Add temperature sensor and initial reading",
    "operations": [
      {
        "operation": "add",
        "kind": "thing",
        "name": "temp-1",
        "data": { "location": "Building A", "type": "temperature" }
      },
      {
        "operation": "add",
        "kind": "assertion",
        "name": "temp-1-reading-v1",
        "about": "Sensor/temp-1",
        "data": { "value": 72.5, "unit": "fahrenheit" }
      }
    ]
  }'