# Kuan Yin — API Reference

> 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.
