Skip to content

Instance Endpoints

Instances represent stateful personality models for individual agents. Create an instance once, then send observations to it over many turns.

Create Instance

POST /instances

Create a new identity instance.

Request

{
  "name": "Aria",
  "description": "Helpful research assistant",
  "initial_config": {
    "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
  }
}

Fields

Field Type Required Default Notes
name string Yes — Agent name (max 100 chars)
description string No "" Optional metadata
initial_config object No All neutral Initial personality state
initial_config.mode_strengths object No {all: 0.0} Starting mode values
initial_config.energy_level float No 0.8 Starting energy (0.0–1.0)

Response

{
  "data": {
    "id": "inst_9f190826e20c49ea",
    "name": "Aria",
    "description": "Helpful research assistant",
    "created_at": "2026-03-24T10:15:30Z",
    "updated_at": "2026-03-24T10:15:30Z"
  }
}

Examples

instance = client.instances.create(
    name="Aria",
    description="Research assistant"
)
print(instance.id)

curl -X POST https://api.identity-os.dev/v1/instances \
  -H "Authorization: Bearer idos_sk_xxx" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Aria",
    "description": "Research assistant"
  }'

List Instances

GET /instances

List all instances for your account.

Query Parameters

Parameter Type Default Notes
limit int 20 Max 100
offset int 0 For pagination
sort string "created_at" created_at or name
order string "desc" asc or desc

Response

{
  "data": [
    {
      "id": "inst_9f190826e20c49ea",
      "name": "Aria",
      "description": "Research assistant",
      "created_at": "2026-03-24T10:15:30Z",
      "cycle_count": 42,
      "energy_level": 0.50
    },
    {
      "id": "inst_a1b2c3d4e5f67890",
      "name": "Bot-2",
      "description": "",
      "created_at": "2026-03-24T09:30:00Z",
      "cycle_count": 128,
      "energy_level": 0.50
    }
  ],
  "pagination": {
    "limit": 20,
    "offset": 0,
    "total": 2,
    "has_more": false
  }
}

Examples

instances = client.instances.list(limit=50)
for inst in instances.data:
    print(f"{inst.name}: {inst.cycle_count} cycles")

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

Get Instance

GET /instances/{id}

Get details for a specific instance.

Path Parameters

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

Response

{
  "data": {
    "id": "inst_9f190826e20c49ea",
    "name": "Aria",
    "description": "Research assistant",
    "created_at": "2026-03-24T10:15:30Z",
    "updated_at": "2026-03-24T10:15:30Z",
    "cycle_count": 42,
    "energy_level": 0.50,
    "stress_state": "LOW",
    "stability_index": 0.50
  }
}

Examples

instance = client.instances.get("inst_9f190826e20c49ea")
print(f"Cycles: {instance.cycle_count}")

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

Update Instance

PATCH /instances/{id}

Update instance metadata (name, description only). Engine state cannot be modified through this endpoint.

Path Parameters

Parameter Type Notes
id string Instance ID

Request

{
  "name": "Aria v2",
  "description": "Senior research assistant"
}

Response

{
  "data": {
    "id": "inst_9f190826e20c49ea",
    "name": "Aria v2",
    "description": "Senior research assistant",
    "updated_at": "2026-03-24T11:00:00Z"
  }
}

Examples

instance = client.instances.update(
    "inst_9f190826e20c49ea",
    name="Aria v2"
)

curl -X PATCH https://api.identity-os.dev/v1/instances/inst_9f190826e20c49ea \
  -H "Authorization: Bearer idos_sk_xxx" \
  -H "Content-Type: application/json" \
  -d '{"name": "Aria v2"}'

Delete Instance

DELETE /instances/{id}

Delete an instance and all associated data. This action cannot be undone.

Path Parameters

Parameter Type Notes
id string Instance ID

Response

{
  "data": {
    "id": "inst_9f190826e20c49ea",
    "deleted": true
  }
}

Examples

client.instances.delete("inst_9f190826e20c49ea")

curl -X DELETE https://api.identity-os.dev/v1/instances/inst_9f190826e20c49ea \
  -H "Authorization: Bearer idos_sk_xxx"