# MetaSoul EPU4 SDK

> Public REST API definitions, Socket.IO MDAD monitoring, bilingual developer documentation, and channel decoding resources for MetaSoul Emotion Processing Unit 4.

## Documentation
- [Account EPUID List](https://emohuman.com/docs/EPU4/agent-guide.md): Proposed account-secret read-only `POST /epuid_list` operation, available only after backend deployment and explicit enablement. Returns normalized available, in-use and unknown-status device lists; no device login or reservation.
- [Interactive EPU4 Swagger (English / 中文)](https://emohuman.com/docs/EPU4/): Browser-based authenticated API testing, realtime MDAD graph, and channel documentation.
- [AI agent guide (English)](https://emohuman.com/docs/EPU4/agent-guide.md): Login, text-only /derive, Socket.IO subscribe, GET /mdad, and decoder notes.
- [AI 智能体指南（中文）](https://emohuman.com/docs/EPU4/agent-guide-zh.md): 简体中文开发说明。

## Machine-readable files
- [OpenAPI 3.0 JSON](https://emohuman.com/docs/EPU4/openapi.json): Main machine-readable REST API specification; includes x-metasoul-mdad and x-metasoul-socket-io vendor extensions.
- [OpenAPI YAML](https://emohuman.com/docs/EPU4/openapi.yaml): Same REST API specification in YAML.
- [MDAD channel mapping JSON](https://emohuman.com/docs/EPU4/mdad-channels.json): 12 emotion APEX channel indexes, Optimistic channel 9, historical additional channels 120-123.

## Runnable source examples
- [JavaScript account EPUID List helper](https://emohuman.com/docs/EPU4/epuid-list.mjs): A secret-based read-only client for the separately enabled `POST /epuid_list` route. Account IDs are sensitive; never log raw account responses.
- [JavaScript Socket.IO example](https://emohuman.com/docs/EPU4/javascript-example.mjs): Node.js authentication, realtime subscription, text-only /derive, and MDAD decoding.
- [Python REST example](https://emohuman.com/docs/EPU4/python-example.py): Python authentication, text-only /derive, optional GET /mdad, and MDAD decoding.

## Session management

- [Session lifetime and optional keepalive](https://emohuman.com/docs/EPU4/agent-guide.md#session-lifetime-and-optional-keepalive): Current gateway default 60-minute REST inactivity timeout, separate 24-hour token lifetime, and optional GET /mdad keepalive after 55 minutes without REST activity. Incoming Socket.IO MDAD frames do not renew REST authentication. Keepalive is opt-in to avoid reserving abandoned EPUIDs.

## Source distinction
The EPU SDK integration guide (2026-10-19) specifies 120-value MDAD responses, but a live REST response on 2026-10-31 contained 123 values. Validate array length; the older EPU-III Brochure describes emotion APEX indexes and a 124-channel legacy layout. Indices 120-123 are NOT guaranteed to exist in 120-value EPU4 responses. No EPUIDs, credentials, or tokens are published in these files.