Eve library

Kuan Yin — API Reference

Guide

Revision 1

On this page

Technical doc 32.16.1.2. Surface defined in @kuanyin/sdk-api (rest-api-endpoints.ts, graphql-api.ts).

All endpoints are versioned under /v1. Requests and responses are JSON. Authentication is described in 09-configuration.md and the SDK auth section of 03-sdk-usage.md. Every decision-returning endpoint also emits a domain event (see 05-event-system.md) and an audit record (AuditLog).

REST endpoints#

Analysis#

Method Path Purpose
POST /v1/analyze-intent Classify primary/secondary intent + confidence for a draft
POST /v1/analyze-emotion Arousal/valence + discrete emotion + crisis flag
POST /v1/assess-harm Harm score, top harm categories, urgency, recommended action

POST /v1/assess-harm body mirrors HarmPotentialInput:

jsonc
{
  "text": "…",
  "userHistoryViolations": 0,
  "userTrustScore": 80, // 0–100
  "isReply": false,
  "targetIsPerformer": false,
}

Response (HarmPotentialResult): harmScore (0–1), topCategories[], urgencyLevel (none|low|medium|high|critical), recommendedAction, keywordsDetected[].

Intervention#

Method Path Purpose
POST /v1/intervention/trigger Begin a friction intervention for content
POST /v1/intervention/complete Record completion + user response + outcome

Reputation#

Method Path Purpose
GET /v1/user/{id}/trust-score Composite trust (0–100) + reliability label
GET /v1/user/{id}/merit Merit total, tier, recent ledger
POST /v1/merit/award Award merit for a recognised positive action

Rehabilitation & circles#

Method Path Purpose
POST /v1/rehabilitation/enroll Enrol a user in a shadow-work journey
GET /v1/rehabilitation/{id}/progress Stage, percent, blockers, days remaining
POST /v1/circle/request Request a restorative circle
GET /v1/circle/{id}/status Circle schedule + participant roles

Community, performer, analytics, appeals#

Method Path Purpose
GET /v1/community/{id}/health Six-dimension health score + trend
GET /v1/performer/{id}/protection Current shield level + active features
POST /v1/performer/shield/configure Set boundary rules + protection level
GET /v1/analytics/dharma Dharma analytics rollup
GET /v1/reports/transparency Public moderation transparency report
POST /v1/appeal/submit Submit an appeal against an action
GET /v1/appeal/{id}/status Appeal decision + rationale
WS /v1/realtime Live shield/temperature/alert stream

GraphQL#

graphql-api.ts exposes a schema with User extensions and Intervention, Rehabilitation, Merit, Community, and Analytics types. Resolvers cover Query, Mutation, and Subscription, with DataLoader batching, authorization directives, query-complexity limits, and per-field rate limiting. Prefer GraphQL for dashboards that need to fan out across reputation + health + analytics in one round trip; prefer REST for single-purpose moderation calls on the hot path.

Error model#

All errors derive from KuanYinError (@kuanyin/foundation) and serialize to { code, message, retryable, safeguards? }. Validation failures return the Zod issue list. Rate-limit responses include retryAfterMs. Irreversible-action requests that lack human review return 403 with an ApprovalRequired safeguard rather than applying the action.