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:
{
"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.