Engine Endpoints¶

The engine endpoints process observations and produce execution contracts. These are the core of Identity OS.

Process Observation¶

POST /instances/{id}/process

Process a single behavioral observation and get the execution contract.

Path Parameters¶

Parameter	Type	Notes
`id`	string	Instance ID (e.g., `inst_xxx`)

Request¶

{
  "mode_target": "EXPLORATION",
  "signal_strength": 0.8,
  "confidence": 0.9,
  "context": {
    "task": "research",
    "tool_failed": false
  }
}

Fields¶

Field	Type	Required	Default	Notes
`mode_target`	string	Yes	—	Target mode (see modes)
`signal_strength`	float	Yes	—	0.0–1.0, intensity
`confidence`	float	No	1.0	0.0–1.0, certainty
`context`	object	No	{}	Metadata (arbitrary)

Modes¶

Valid values for mode_target:

"PERCEPTION"
"EXPLORATION"
"ORDER"
"ASSERTION"
"CONNECTION"
"IDENTITY"
"STRESS_RESPONSE"

Response¶

{
  "data": {
    "snapshot": {
      "instance_id": "inst_xxx",
      "cycle": 42,
      "mode_strengths": {
        "perception": 0.50,
        "exploration": 0.50,
        "order": 0.50,
        "assertion": 0.50,
        "connection": 0.50,
        "identity": 0.50,
        "stress_response": 0.50
      },
      "energy_level": 0.50,
      "stress_state": "LOW",
      "stability_index": 0.50
    },
    "contract": {
      "dominant_modes": ["Order", "Identity"],
      "suppressed_modes": ["Exploration"],
      "allowed_actions": ["execute", "clarify", "suggest"],
      "forbidden_actions": ["pivot", "explore"],
      "decision_style": {
        "tempo": "decisive",
        "risk": "bounded",
        "expressiveness": "medium",
        "commitment_threshold": "medium"
      },
      "energy_level": 0.50,
      "stress_state": "LOW",
      "recovery_profile": {
        "preferred_path": "gradual",
        "support_required": false,
        "cooldown_required": false
      }
    },
    "drift": {
      "level": "D0",
      "deviation": "..."
    }
  }
}

Examples¶

PythoncURL

result = client.engine.process(
    instance_id="inst_xxx",
    mode_target=Mode.EXPLORATION,
    signal_strength=0.8,
    confidence=0.9
)

contract = result.contract
print(f"Allowed: {contract.allowed_actions}")
print(f"Stress: {contract.stress_state}")

curl -X POST https://api.identity-os.dev/v1/instances/inst_xxx/process \
  -H "Authorization: Bearer idos_sk_xxx" \
  -H "Content-Type: application/json" \
  -d '{
    "mode_target": "EXPLORATION",
    "signal_strength": 0.8,
    "confidence": 0.9
  }'

Batch Process¶

POST /instances/{id}/process/batch

Process multiple observations in sequence and get the final contract.

Path Parameters¶

Parameter	Type	Notes
`id`	string	Instance ID

Request¶

{
  "observations": [
    {
      "mode_target": "EXPLORATION",
      "signal_strength": 0.8,
      "confidence": 0.9
    },
    {
      "mode_target": "ORDER",
      "signal_strength": 0.7,
      "confidence": 0.85
    },
    {
      "mode_target": "ASSERTION",
      "signal_strength": 0.6,
      "confidence": 0.8
    }
  ],
  "include_intermediate": false
}

Fields¶

Field	Type	Required	Default	Notes
`observations`	array	Yes	—	List of observations
`include_intermediate`	bool	No	false	Return all intermediate states

Response (include_intermediate=false)¶

{
  "data": {
    "snapshot": { /* final state after all 3 observations */ },
    "contract": { /* final contract */ },
    "drift": { /* final drift classification */ },
    "processed_count": 3
  }
}

Response (include_intermediate=true)¶

{
  "data": {
    "states": [
      {
        "snapshot": { /* after observation 1 */ },
        "contract": { /* contract 1 */ },
        "drift": { /* drift 1 */ }
      },
      {
        "snapshot": { /* after observation 2 */ },
        "contract": { /* contract 2 */ },
        "drift": { /* drift 2 */ }
      },
      {
        "snapshot": { /* after observation 3 */ },
        "contract": { /* contract 3 */ },
        "drift": { /* drift 3 */ }
      }
    ],
    "processed_count": 3
  }
}

Examples¶

PythoncURL

from identity_os_sdk import Mode

result = client.engine.process_batch(
    instance_id="inst_xxx",
    observations=[
        {"mode_target": Mode.EXPLORATION, "signal_strength": 0.8},
        {"mode_target": Mode.ORDER, "signal_strength": 0.7},
        {"mode_target": Mode.ASSERTION, "signal_strength": 0.6}
    ],
    include_intermediate=False
)

print(f"Processed {result.processed_count} observations")
print(f"Final stress: {result.contract.stress_state}")

curl -X POST https://api.identity-os.dev/v1/instances/inst_xxx/process/batch \
  -H "Authorization: Bearer idos_sk_xxx" \
  -H "Content-Type: application/json" \
  -d '{
    "observations": [
      {"mode_target": "EXPLORATION", "signal_strength": 0.8},
      {"mode_target": "ORDER", "signal_strength": 0.7}
    ]
  }'

Get Snapshot¶

GET /instances/{id}/snapshot

Get the current identity state without processing a new observation.

Path Parameters¶

Parameter	Type	Notes
`id`	string	Instance ID

Response¶

{
  "data": {
    "instance_id": "inst_xxx",
    "cycle": 42,
    "mode_strengths": {
      "perception": 0.50,
      "exploration": 0.50,
      "order": 0.50,
      "assertion": 0.50,
      "connection": 0.50,
      "identity": 0.50,
      "stress_response": 0.50
    },
    "energy_level": 0.50,
    "stress_state": "LOW",
    "stability_index": 0.50,
    "cycle_count": 42,
    "created_at": "2026-03-24T10:15:30Z",
    "updated_at": "2026-03-24T10:45:00Z"
  }
}

Examples¶

PythoncURL

snapshot = client.engine.get_snapshot("inst_xxx")
print(f"Energy: {snapshot.energy_level}")
print(f"Stress: {snapshot.stress_state}")

curl -X GET https://api.identity-os.dev/v1/instances/inst_xxx/snapshot \
  -H "Authorization: Bearer idos_sk_xxx"

Get Contract¶

GET /instances/{id}/contract

Get the current execution contract without processing a new observation.

Path Parameters¶

Parameter	Type	Notes
`id`	string	Instance ID

Response¶

{
  "data": {
    "dominant_modes": ["Order", "Identity"],
    "suppressed_modes": ["Exploration"],
    "allowed_actions": ["execute", "clarify", "suggest"],
    "forbidden_actions": ["pivot", "explore"],
    "decision_style": {
      "tempo": "decisive",
      "risk": "bounded",
      "expressiveness": "medium",
      "commitment_threshold": "medium"
    },
    "energy_level": 0.50,
    "stress_state": "LOW",
    "recovery_profile": {
      "preferred_path": "gradual",
      "support_required": false,
      "cooldown_required": false
    }
  }
}

Examples¶

PythoncURL

contract = client.engine.get_contract("inst_xxx")
if "execute" in contract.allowed_actions:
    print("Agent can execute")

curl -X GET https://api.identity-os.dev/v1/instances/inst_xxx/contract \
  -H "Authorization: Bearer idos_sk_xxx"

Get History¶

GET /instances/{id}/history

Get observation history for an instance.

Path Parameters¶

Parameter	Type	Notes
`id`	string	Instance ID

Query Parameters¶

Parameter	Type	Default	Notes
`limit`	int	100	Max 1000
`offset`	int	0	For pagination

Response¶

{
  "data": [
    {
      "cycle": 42,
      "mode_target": "EXPLORATION",
      "signal_strength": 0.8,
      "confidence": 0.9,
      "context": {},
      "timestamp": "2026-03-24T10:45:00Z"
    },
    {
      "cycle": 41,
      "mode_target": "ORDER",
      "signal_strength": 0.7,
      "confidence": 0.85,
      "context": {},
      "timestamp": "2026-03-24T10:44:30Z"
    }
  ],
  "pagination": {
    "limit": 100,
    "offset": 0,
    "total": 42,
    "has_more": false
  }
}

Examples¶

PythoncURL

history = client.engine.get_history("inst_xxx", limit=50)
for obs in history.data:
    print(f"Cycle {obs.cycle}: {obs.mode_target}")

curl -X GET 'https://api.identity-os.dev/v1/instances/inst_xxx/history?limit=50' \
  -H "Authorization: Bearer idos_sk_xxx"

Get Drift Events¶

GET /instances/{id}/drift

Get drift events and classifications for an instance.

Path Parameters¶

Parameter	Type	Notes
`id`	string	Instance ID

Response¶

{
  "data": [
    {
      "cycle": 47,
      "drift_level": "D3",
      "deviation": "...",
      "affected_modes": ["identity", "connection"],
      "rolled_back": true,
      "timestamp": "2026-03-24T10:50:00Z"
    },
    {
      "cycle": 23,
      "drift_level": "D1",
      "deviation": "...",
      "affected_modes": ["assertion"],
      "rolled_back": false,
      "timestamp": "2026-03-24T09:45:12Z"
    }
  ],
  "pagination": {
    "total": 2
  }
}

Examples¶

Python

drift = client.engine.get_drift("inst_xxx")
for event in drift.data:
    if event.drift_level == "D3":
        print(f"CRITICAL: Rollback at cycle {event.cycle}")

Reset Instance¶

POST /instances/{id}/reset

Reset instance to a previous state.

Path Parameters¶

Parameter	Type	Notes
`id`	string	Instance ID

Request¶

{
  "mode": "initial"
}

Fields¶

Field	Type	Required	Options	Notes
`mode`	string	Yes	`"initial"`, `"default"`	Which state to restore

Response¶

{
  "data": {
    "id": "inst_xxx",
    "reset_to": "initial",
    "cycle": 0,
    "energy_level": 0.8,
    "stress_state": "LOW"
  }
}

Examples¶

PythoncURL

# Reset to creation state
client.engine.reset("inst_xxx", mode="initial")

# Or reset to a clean default state
client.engine.reset("inst_xxx", mode="default")

curl -X POST https://api.identity-os.dev/v1/instances/inst_xxx/reset \
  -H "Authorization: Bearer idos_sk_xxx" \
  -H "Content-Type: application/json" \
  -d '{"mode": "initial"}'

Throttling¶

The engine enforces a minimum cycle interval to prevent rapid-fire observations:

Minimum interval: 1.0 second between observations
Violation: Returns 200 OK with the previous snapshot unchanged (no new cycle is billed)

Solution: Batch multiple observations with /process/batch or wait 1+ second between calls.

Create instance — Create before processing
Get instance — Instance metadata
Personas — Reference persona definitions

Engine Endpoints¶

Process Observation¶

Path Parameters¶

Request¶

Fields¶

Modes¶

Response¶

Examples¶

Batch Process¶

Path Parameters¶

Request¶

Fields¶

Response (include_intermediate=false)¶

Response (include_intermediate=true)¶

Examples¶

Get Snapshot¶

Path Parameters¶

Response¶

Examples¶

Get Contract¶

Path Parameters¶

Response¶

Examples¶

Get History¶

Path Parameters¶

Query Parameters¶

Response¶

Examples¶

Get Drift Events¶

Path Parameters¶

Response¶

Examples¶

Reset Instance¶

Path Parameters¶

Request¶

Fields¶

Response¶

Examples¶

Throttling¶

Related Endpoints¶