AI Twins

Your AI Twin is a personalised view of how Chainabit understands you. The system maintains it automatically — you observe it via these endpoints, tune the limited behavioural preferences, and forget or flag items you don't want.

Identity is system-managed. There is no endpoint to author a twin's profile or memories by hand.

Endpoints

Method	Path	Description	Auth
GET	/workspaces/{workspaceId}/ai/twins	List twins in a workspace	JWT
GET	/workspaces/{workspaceId}/ai/twins/skill-coverage	Skill coverage summary	JWT
GET	/workspaces/{workspaceId}/ai/twins/behavioral-baseline	Behavioral baseline summary	JWT
GET	/workspaces/{workspaceId}/ai/twins/{twinId}/brain	Read the latest twin profile	JWT
GET	/workspaces/{workspaceId}/ai/twins/{twinId}/confidence	Per-field confidence values	JWT
GET	/workspaces/{workspaceId}/ai/twins/{twinId}/evidence	Provenance for the twin's claims	JWT
GET	/workspaces/{workspaceId}/ai/twins/{twinId}/timeline	History of twin profile versions	JWT
PATCH	/workspaces/{workspaceId}/ai/twins/{twinId}/preferences	Update behavioural preferences	JWT
POST	/workspaces/{workspaceId}/ai/twins/{twinId}/test	Run a sample prompt against the twin	JWT
DELETE	/workspaces/{workspaceId}/ai/twins/{entityTwinId}/contributions/{userId}	Admin: revoke a member's contributions to an entity twin	JWT, admin role
GET	/agents/twins/{twinId}/memories	List memories	JWT
DELETE	/agents/twins/{twinId}/memories/{id}	Forget a memory	JWT
POST	/agents/twins/{twinId}/memories/{id}/flag	Flag a memory as wrong	JWT

---

GET /workspaces/{workspaceId}/ai/twins/{twinId}/brain

Description

Returns the current profile of the twin: its personality dimensions and the most-supported claims it has formed about you. If the twin is still gathering its first signals, the response indicates status: "seeded".

Request

• Headers: Authorization: Bearer <token>
• Path params:
  • workspaceId
  • twinId

Response

• 200 OK

  {
    "data": {
      "version": 12,
      "personality": {
        "threatSensitivity": 0.2,
        "rewardSensitivity": 0.6,
        "impulseControl": 0.7,
        "socialTrust": 0.5,
        "uncertaintyTolerance": 0.4,
        "emotionalRegulation": 0.65,
        "goalPersistence": 0.8
      },
      "topClaims": [
        { "fieldPath": "preference.terse_replies", "claim": "terse_replies", "confidence": 0.82, "evidenceCount": 14 }
      ]
    }
  }

Code Example

curl -H "Authorization: Bearer $TOKEN" \
  https://api.chainabit.io/workspaces/$WORKSPACE/ai/twins/$TWIN/brain

---

GET /workspaces/{workspaceId}/ai/twins/{twinId}/confidence

Description

Returns a flat map of fieldPath → confidence (0..1) for every claim the twin currently holds. Use it to decide which claims to display prominently and which to surface as tentative.

Request

• Path params: workspaceId, twinId

Response

• 200 OK

  { "data": { "preference.terse_replies": 0.82, "style.code_oriented": 0.61 } }

Code Example

curl -H "Authorization: Bearer $TOKEN" \
  https://api.chainabit.io/workspaces/$WORKSPACE/ai/twins/$TWIN/confidence

---

GET /workspaces/{workspaceId}/ai/twins/{twinId}/evidence

Description

Returns the recent provenance rows that back the twin's claims. Optionally filter by fieldPath (e.g. preference.terse_replies) to see what supports a specific claim.

Request

• Path params: workspaceId, twinId
• Query: fieldPath (optional), limit (optional, default 50)

Response

• 200 OK — array of evidence entries with claim, polarity, confidence, extractor, channel, createdAt.

Code Example

curl -H "Authorization: Bearer $TOKEN" \
  "https://api.chainabit.io/workspaces/$WORKSPACE/ai/twins/$TWIN/evidence?fieldPath=preference.terse_replies"

---

GET /workspaces/{workspaceId}/ai/twins/{twinId}/timeline

Description

Returns the recent versions of the twin profile, newest first. Use it to see how the twin has evolved over time.

Request

• Path params: workspaceId, twinId
• Query: limit (optional, default 20)

Response

• 200 OK — array of profile snapshots ordered by version desc.

Code Example

curl -H "Authorization: Bearer $TOKEN" \
  "https://api.chainabit.io/workspaces/$WORKSPACE/ai/twins/$TWIN/timeline?limit=20"

---

PATCH /workspaces/{workspaceId}/ai/twins/{twinId}/preferences

Description

Update the twin's behavioural preferences. This is the only writable surface on a twin's identity. Identity itself is system-managed.

Allowed fields:

Field	Type	Notes
paused	boolean	Pause background twin updates.
observationEnabled	boolean	Allow the system to observe signals for this twin.
aggregationCron	string	Cron expression (subject to policy bounds).
memoryRetentionDays	integer (1–3650)	How long memories are retained.
sensitivityLevel	"low" | "med" | "high"	Privacy / sharing sensitivity.
publicBrainShowcase	boolean	Opt-in to the public brain showcase on your profile. Off by default.

Workspace and enterprise admin policies may override or restrict these fields.

Request

• Headers: Authorization: Bearer <token>, Content-Type: application/json
• Body:

  { "paused": false, "memoryRetentionDays": 180, "sensitivityLevel": "med" }

Response

• 200 OK — { "data": { "preferences": { ... } } }
• 400 Bad Request — invalid field values
• 403 Forbidden — caller not in twin's scope

Code Example

curl -X PATCH \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{ "paused": false, "memoryRetentionDays": 180, "sensitivityLevel": "med" }' \
  https://api.chainabit.io/workspaces/$WORKSPACE/ai/twins/$TWIN/preferences

---

DELETE /workspaces/{workspaceId}/ai/twins/{entityTwinId}/contributions/

Description

Admin-only. Revokes a single member's contributions to a team / workspace / enterprise twin. The member's own user twin is unaffected.

Use ?cascade=teams on an enterprise twin to also revoke from every team within the enterprise.

Request

• Path params: workspaceId, entityTwinId, userId
• Query: cascade=teams (optional)

Response

• 200 OK — { "data": { "evidenceRowsDeleted": 42, "teamsCascaded": 3 } }
• 403 Forbidden — caller is not an admin in scope.

Code Example

curl -X DELETE \
  -H "Authorization: Bearer $TOKEN" \
  "https://api.chainabit.io/workspaces/$WORKSPACE/ai/twins/$ENTITY_TWIN/contributions/$USER_ID?cascade=teams"

---

DELETE /agents/twins/{twinId}/memories/

Description

Forget a memory. The deletion is permanent — the system will not re-derive a tombstoned item.

Request

• Path params: twinId, id (the memory ID, from List memories's GET /agents/twins/{twinId}/memories response)

Response

• 200 OK — { "data": { "deleted": 1 } }

Code Example

curl -X DELETE \
  -H "Authorization: Bearer $TOKEN" \
  https://api.chainabit.io/agents/twins/$TWIN/memories/$MEMORY_ID

---

POST /agents/twins/{twinId}/memories/{id}/flag

Description

Flag a memory as wrong. The system demotes the memory's influence going forward and may tombstone it if it accumulates further flags within a short window.

Request

• Path params: twinId, id (the memory ID, from List memories's GET /agents/twins/{twinId}/memories response)

Response

• 200 OK — { "data": { "flaggedCount": 1 } }

Code Example

curl -X POST \
  -H "Authorization: Bearer $TOKEN" \
  https://api.chainabit.io/agents/twins/$TWIN/memories/$MEMORY_ID/flag

---

POST /workspaces/{workspaceId}/ai/twins/{twinId}/test

Description

Run a sample prompt against the twin and return what the twin would have produced. Useful for QA and product-tuning. Does not affect the twin's stored state.

Request

• Headers: Authorization: Bearer <token>, Content-Type: application/json
• Body: { "prompt": "string", "context": { ... } }

Response

• 200 OK — the sample response and any tool calls the twin would have made.

Code Example

curl -X POST \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{ "prompt": "How would you phrase a reminder for this user?" }' \
  https://api.chainabit.io/workspaces/$WORKSPACE/ai/twins/$TWIN/test

---

Notes

• Rate limits and pagination apply per the standard platform headers.
• Auth is JWT with workspace-scoped entitlements; admin endpoints additionally require an admin role in the enterprise.
• For agent execution records (run history, approvals, automation rules), see the agent actions reference.
• For the Brain Simulator (brain graph, memory graph, live activity, narration), see Twin Brain.