Chainabit Docs

English

Selector
Türkçe

English

Selector
Türkçe

Appearance

Türkçe

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 ​

MethodPathDescriptionAuth
GET/agents/twins/exportExport the signed-in person's Twin dataJWT
PATCH/agents/twins/me/preferencesUpdate the signed-in person's Twin preferencesJWT
GET/workspaces/{workspaceId}/ai/twinsList twins in a workspaceJWT
GET/workspaces/{workspaceId}/ai/twins/skill-coverageSkill coverage summaryJWT
GET/workspaces/{workspaceId}/ai/twins/behavioral-baselineBehavioral baseline summaryJWT
GET/workspaces/{workspaceId}/ai/twins/{twinId}/brainRead the latest twin profileJWT
GET/workspaces/{workspaceId}/ai/twins/{twinId}/confidencePer-field confidence valuesJWT
GET/workspaces/{workspaceId}/ai/twins/{twinId}/evidenceProvenance for the twin's claimsJWT
GET/workspaces/{workspaceId}/ai/twins/{twinId}/timelineHistory of twin profile versionsJWT
PATCH/workspaces/{workspaceId}/ai/twins/{twinId}/preferencesUpdate behavioural preferencesJWT
POST/workspaces/{workspaceId}/ai/twins/{twinId}/testRun a sample prompt against the twinJWT
DELETE/workspaces/{workspaceId}/ai/twins/{entityTwinId}/contributions/{userId}Admin: revoke a member's contributions to an entity twinJWT, admin role
POST/workspaces/{workspaceId}/ai/twins/{entityTwinId}/contributions/{userId}/regrantAdmin: make a member eligible to contribute againJWT, admin role
GET/agents/twins/me/beliefsWhat your Twin currently believes about how you decide, with its basisJWT
POST/agents/twins/me/beliefs/rulingsConfirm or reject one beliefJWT
DELETE/agents/twins/me/beliefsErase every belief your Twin holds about youJWT
GET/agents/twins/{twinId}/memoriesList memoriesJWT
POST/agents/twins/{twinId}/memories/{id}/deletions/previewReview a memory before forgetting itJWT
POST/agents/twins/{twinId}/memories/{id}/deletions/cancelCancel a pending memory deletionJWT
DELETE/agents/twins/{twinId}/memories/{id}Forget a memoryJWT
POST/agents/twins/{twinId}/memories/{id}/flagFlag a memory as wrongJWT

GET /agents/twins/export ​

Returns the signed-in person's Twin record and its memories, behavioral evidence, and workspace policies in a JSON response. The response has a data object with twin, memories, evidence, and policies fields. Returns 404 if that person has no Twin to export. Access requires a JWT and the applicable Twin entitlement and policy checks.

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
    json
    {
  "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 ​

bash
curl -H "Authorization: Bearer $TOKEN" \
  https://api.chainabit.com/api/v1/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
    json
    { "data": { "preference.terse_replies": 0.82, "style.code_oriented": 0.61 } }

Code Example ​

bash
curl -H "Authorization: Bearer $TOKEN" \
  https://api.chainabit.com/api/v1/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 ​

bash
curl -H "Authorization: Bearer $TOKEN" \
  "https://api.chainabit.com/api/v1/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 ​

bash
curl -H "Authorization: Bearer $TOKEN" \
  "https://api.chainabit.com/api/v1/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:

FieldTypeNotes
pausedbooleanPause background twin updates.
observationEnabledbooleanAllow the system to observe signals for this twin.
aggregationCronstringCron expression (subject to policy bounds).
memoryRetentionDaysinteger (1–3650)How long memories are retained.
sensitivityLevel"low" | "med" | "high"Privacy / sharing sensitivity.
publicBrainShowcasebooleanOpt-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:
    json
    { "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 ​

bash
curl -X PATCH \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{ "paused": false, "memoryRetentionDays": 180, "sensitivityLevel": "med" }' \
  https://api.chainabit.com/api/v1/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 ​

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

POST /workspaces/{workspaceId}/ai/twins/{entityTwinId}/contributions/{userId}/regrant ​

Account admins can remove a prior contribution exclusion for an active member. This does not change the member's observation consent; it only makes the member eligible to contribute again if consent and policy allow it.

The 201 Created response reports participation: "eligible_if_consented", whether the exclusion changed, and confirms that observation consent was not changed.

Beliefs ​

Beyond individual memories, your Twin keeps a small set of evidence-backed beliefs about how you tend to decide and communicate — for example that you prefer fixes that address root causes, in engineering work. A belief is only ever one choice from a fixed list of dimensions and stances, scoped to a context, so it never contains free text.

A belief earns its standing from repeated evidence on different days. A single inferred observation does not guide personalization; a preference you explicitly state or confirm can qualify sooner. Beliefs can guide Agents that use your Twin, rather than being included automatically in every conversation. Your current request always takes priority. Observation requires your consent and stops while paused; beliefs remain personal to you.

GET /agents/twins/me/beliefs ​

Returns the beliefs your Twin holds in the data array. Each item includes a readable statement and eligibleForPersonalization, a boolean indicating whether current consent and evidence allow it to guide personalization. Eligibility does not mean the belief is included in every conversation.

Items also have dimension, stance, context (general, engineering, business, personal, learning or creative), status (hypothesis, emerging, established, contested or stale), basis (observed, stated or mixed), confidence (tentative, moderate or high), supportDays, firstObservedAt and lastSupportedAt. Dimensions: detail_level, answer_format, solution_scope, solution_origin, delivery_style, risk_attitude, speed_quality, cost_attitude, delegation, evidence_standard, privacy_stance, learning_style.

POST /agents/twins/me/beliefs/rulings ​

Rule on one belief. Body: { "dimension": "solution_scope", "context": "engineering", "stance": "systemic", "ruling": "confirmed" }. ruling is confirmed or rejected. A confirmation can establish a valid preference even if it has not previously been observed. A rejection retires existing support for that stance; only later evidence can rebuild it. Rejection is a correction, not physical deletion of individual evidence. Allowed even after you withdraw consent. Responds 201 Created with { "data": { "ruled": true } }, or 422 for an unsupported dimension, context or stance combination.

DELETE /agents/twins/me/beliefs ​

Erases every belief and its evidence. Responds 200 OK with { "data": { "erased": 12 } }; erased counts removed pieces of supporting evidence. Saved memories and individual Agents' experience are separate and are not erased by this operation.

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

Description ​

Review the exact memory first. Delete only after the user explicitly confirms the returned semantic fact. The confirmation expires after ten minutes and is bound to the requesting user, workspace, Twin, memory and revision. A changed memory requires a new preview. A direct DELETE without a confirmation receipt is rejected.

Request ​

  • Path parameters: twinId, id from the memory list.
  • JSON body: { "previewToken": "<receipt returned by preview>" }.
  • Use the same workspace context for preview, cancellation and confirmation.
  • To cancel, POST the same body to /agents/twins/{twinId}/memories/{id}/deletions/cancel; the memory remains unchanged.

Response ​

  • Preview: data.success, data.previewToken, data.expiresAt, data.totalFound, and data.willForget (semantic content and type). A missing or inaccessible memory produces no confirmation receipt.
  • Confirmed deletion: 200 OK with { "data": { "success": true, "preview": false, "deletedCount": 1 } }. Repeating the confirmed operation returns the same count with replayed: true.
  • Missing, expired, cancelled, changed or incorrectly scoped confirmation: 400 Bad Request. The service does not disclose another user’s memory.

Code example ​

bash
# Read-only preview; show willForget to the user.
curl -X POST \
  -H "Authorization: Bearer $TOKEN" \
  -H "X-Workspace-Id: $WORKSPACE_ID" \
  -H "Content-Type: application/json" \
  -d '{}' \
  https://api.chainabit.com/api/v1/agents/twins/$TWIN/memories/$MEMORY_ID/deletions/preview

# Run only after explicit user confirmation. PREVIEW_TOKEN comes from the preview.
curl -X DELETE \
  -H "Authorization: Bearer $TOKEN" \
  -H "X-Workspace-Id: $WORKSPACE_ID" \
  -H "Content-Type: application/json" \
  -d "{\"previewToken\":\"$PREVIEW_TOKEN\"}" \
  https://api.chainabit.com/api/v1/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 ​

bash
curl -X POST \
  -H "Authorization: Bearer $TOKEN" \
  https://api.chainabit.com/api/v1/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 ​

bash
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.com/api/v1/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.

Built with purpose.

Copyright 2026-present Chainabit