Invariant
STABLE SDK REFERENCE

Invariant SDK

Integrate formal constraint checking into your deployment pipelines. The Invariant SDK allows you to define, verify, and enforce system invariants in real-time.

▶ Try it live

Run these commands in your terminal to interact with the Invariant API directly. No SDK required, just curl.

Health check 
# Verify the engine is running
curl https://invariant.me/health
Create entity + assert a claim 
# 1. Create an entity (represents the thing you're tracking)
curl -X POST https://invariant.me/entities \
  -H "X-API-Key: YOUR_KEY" \
  -H "Content-Type: application/json" \
  -d '{"name":"deal_492","type":"GENERIC"}'
# → {"id":"cmmz7...","name":"deal_492","type":"GENERIC"}

# 2. Assert a claim about it (use the entity id from step 1)
curl -X POST https://invariant.me/claims \
  -H "X-API-Key: YOUR_KEY" \
  -H "Content-Type: application/json" \
  -d '{"entityId":"ENTITY_ID","predicate":"status","value":"open","sourceName":"crm-read-tool"}'

Required claim fields: entityId, predicate, value, sourceName. Optional: confidence (0–1).

Validate an action before executing 
# Validate before executing — pass the entity IDs the action will affect
curl -X POST https://invariant.me/actions/validate \
  -H "X-API-Key: YOUR_KEY" \
  -H "Content-Type: application/json" \
  -d '{"operation":"update_crm_status","impactedEntityIds":["ENTITY_ID"]}'
# → {"proposal":{...},"validation":{"admissibility":"VALID","psiScore":0.02,"reasons":[...]}}

Response: validation.admissibility (VALID / RISKY / BLOCKED), validation.psiScore, and validation.reasons[].

Get world coherence score 
# Fetch the global Φ(G) coherence score
curl https://invariant.me/world/coherence \
  -H "X-API-Key: YOUR_KEY"
# → {"phi":0.99,"claimsCount":12,"contradictionsCount":0,...}

Returns phi (0–1 coherence score), claim and contradiction counts.

01 Getting Started

Install the Invariant Node.js client to begin asserting claims and validating actions. The SDK wraps the full REST API and is optimized for high-concurrency agent environments.

npm install invariant-sdk

Core API Endpoints

POST
/observations

Ingest raw observations from agents, tools, or sensors into the world state graph.

POST
/claims

Assert a typed predicate about an entity. Claims are validated against active constraints before commit.

POST
/actions/validate

Validate a proposed agent action. Returns admissibility (VALID / RISKY / BLOCKED), ΔΦ, Ψ score, and constraint trace.

GET
/world/coherence

Returns the current global coherence score Φ(G) and per-dimension breakdown (consistency, knowledge, drift, utility, boundary).

02 Posting Claims

Claims represent atomic facts about entities in your world state. Before posting a claim you need an entity to attach it to. Create one first with POST /entities, then assert claims against its ID.

POST /entities — required fields

  • name string — human-readable label
  • type GENERIC | PERSON | PROJECT | FILE | TASK | AGENT | COMPONENT | ENVIRONMENT_STATE | …

POST /claims — required fields

  • entityId string — ID from POST /entities
  • predicate string — the property being asserted, e.g. "status", "temperature"
  • value any — the value of that property
  • sourceName string — name of the agent or tool asserting this claim
  • confidence number (0–1), optional — defaults to 1.0

JS SDK Quickstart

Install the Node.js SDK and run the full assert → validate flow in under 10 lines.

Full flow — create entity, assert claim, validate action 
import { InvariantClient } from 'invariant-sdk';

const inv = new InvariantClient({ baseUrl: 'https://invariant.me', apiKey: 'YOUR_KEY' });

// 1. Create the entity you want to track
const entity = await inv.entities.create({ name: 'deal_492', type: 'GENERIC' });

// 2. Assert a claim about its current state
await inv.claims.create({
  entityId: entity.id,
  predicate: 'status',
  value: 'open',
  sourceName: 'crm-read-tool'
});

// 3. Validate an action before executing it
const result = await inv.actions.validate({
  operation: 'update_crm_status',
  impactedEntityIds: [entity.id]
});

if (result.validation.admissibility !== 'BLOCKED') {
  // safe to proceed
}

03 Defining Constraints

Constraints define rules that must hold across entities. When a constraint is violated, actions against affected entities are flagged or blocked.

POST /constraints — required fields

  • name string
  • description string — human-readable explanation
  • type NUMERIC_RANGE | STATUS_DEPENDENCY | VERIFICATION_REQUIRED | MUTUAL_EXCLUSION | COMPLETENESS | CUSTOM
  • expression object — constraint parameters (shape depends on type)
  • entityIds string[] — optional, entity IDs this constraint applies to
  • weight number (0–10), optional — constraint weight in scoring
Example
curl -X POST https://invariant.me/constraints \
  -H "X-API-Key: YOUR_KEY" \
  -H "Content-Type: application/json" \
  -d '{"name":"no-close-after-refund","description":"Cannot close after refund initiated","type":"STATUS_DEPENDENCY","expression":{"condition":"refund_active","blocked_status":"closed"},"entityIds":["ENTITY_ID"]}'