2026年7月13日 (一) 09:50 C2h2

2026-07-13T09:50:15Z

←上一版本		2026年7月13日 (一) 17:50的版本
第2行：		第2行：
	\|-		\|-
	! 适用 / Applies to		! 适用 / Applies to
	\| Photonicat 1/2, pcat-manager-web（2026-07 起所有接口强制鉴权） / Photonicat 1/2, pcat-manager-web (auth enforced on all endpoints since 2026-07)		\| Photonicat 2, pcat-manager-web（2026-07 起所有接口强制鉴权） / Photonicat 2, pcat-manager-web (auth enforced on all endpoints since 2026-07)
	\|}		\|}

C2h2：New topic: developer overview of the REST + WebSocket API — auth, endpoint groups, error shape, quick examples

2026-07-12T16:47:12Z

New topic: developer overview of the REST + WebSocket API — auth, endpoint groups, error shape, quick examples

新页面

{| class="wikitable"
|-
! 适用 / Applies to
| Photonicat 1/2, pcat-manager-web（2026-07 起所有接口强制鉴权） / Photonicat 1/2, pcat-manager-web (auth enforced on all endpoints since 2026-07)
|}

pcat-manager-web 管理界面的所有功能都基于一套 '''REST + WebSocket API'''，可用于脚本自动化和第三方集成（Home Assistant、监控面板、短信转发等）。本页是面向开发者的概览。'''注意'''：这是设备内部 API，版本间可能变动，升级固件后请回归测试你的集成。

Everything in the pcat-manager-web UI is driven by a '''REST + WebSocket API''' you can use for scripting and integrations (Home Assistant, monitoring dashboards, SMS forwarding…). This page is a developer-oriented overview. '''Note''': this is the device's internal API and may change between releases — retest integrations after firmware updates.

== 基础 Basics ==

* '''Base URL'''：设备地址，如 <code>http://172.16.0.1/</code> / your device address, e.g. <code>http://172.16.0.1/</code>
* '''认证 Authentication'''：先 POST <code>/login</code> 建立会话（Cookie）；2026-07 起所有 API 强制登录校验。 / Establish a session via <code>/login</code> first; since 2026-07 every endpoint requires it.
* '''格式 Content type'''：POST 一律 <code>application/json</code>，并携带有效 '''CSRF token'''（登录页面/会话中获取）。所有'''改变状态的操作只接受 POST'''。 / POSTs use <code>application/json</code> with a valid '''CSRF token'''; all state-changing operations are POST-only.
* '''错误格式 Error shape'''（统一 / uniform）：
<pre>
{ "status": "error", "message": "Descriptive error message", "error_code": "SPECIFIC_ERROR_CODE" }
</pre>
: HTTP 状态码：200 成功，400 参数错误，401 未登录，403 无权限/CSRF 失败，404 不存在。 / 200 OK, 400 bad request, 401 login required, 403 forbidden/CSRF, 404 not found.

== 接口分组 Endpoint groups ==

以下为主要分组及代表接口（完整字段见设备仓库 docs/api.md）。 / Major groups with representative endpoints (full schemas in the repo's docs/api.md).

{| class="wikitable" style="width:100%"
! style="width:22%" | 分组 Group !! 代表接口 Representative endpoints !! 说明 Notes
|-
| '''系统 System''' || <code>GET /api/v1/system/board.json</code>（设备信息 device info）、系统信息 system info、重启/关机 reboot & poweroff || 型号、序列号、固件版本、运行时间 / model, serial, firmware, uptime
|-
| '''网络 Network''' || 无线配置 wireless config、接口状态 interfaces、<code>GET</code> 已连接设备 connected devices || WiFi SSID/密码、DHCP 客户端列表 / WiFi credentials, DHCP client list
|-
| '''蜂窝 Mobile''' || APN 设置、调制解调器信息/配置 modem info & config || 运营商、信号、IMEI、网络模式 / carrier, signal, IMEI, network mode
|-
| '''短信 SMS''' || 列表 list、发送 send（v1/v2）、标记已读 mark-read、删除 delete、清空 clear || 收发短信自动化的主要入口 / the main hook for SMS automation
|-
| '''语音通话 Voice call''' || 拨打 make、接听 answer、挂断 hangup、状态 status、通话记录 history、音频通道 audio path || 蜂窝版专属 / cellular models only
|-
| '''设备控制 Device control''' || 电源 LED、蜂鸣器 beeper、设备设置 device settings || 灯光/提示音策略 / LED & beeper policies
|-
| '''定时 Timer''' || 时间信息、定时任务管理、车载模式 car boot mode || 对应 /timer 页面的三种电源模式 / powers the /timer page modes
|-
| '''统计 Statistics''' || 仪表盘数据 dashboard、状态 status、流量统计 data statistics || 监控集成最常用 / most used for monitoring integrations
|-
| '''屏幕 Screen''' || <code>GET/POST /api/v1/screen/user_config.json</code>、<code>GET /api/v1/screen/data.json</code>、<code>GET /api/v1/screen/frame.png</code>、custom_metrics 状态/执行 || 布局、数据、'''实时截屏''' / layout, data, '''live frame capture'''
|-
| '''系统配置 System config''' || CPU 调度 CPU scheduling、风扇转速 fan speed、屏幕短信条数限制 SMS screen limit || 性能与散热调优 / performance & thermals
|-
| '''维护 Maintenance''' || 固件管理 firmware management、软件包管理 package management、SMS Hook 管理 || 升级与短信钩子（转发脚本）/ upgrades & SMS hooks (forwarding scripts)
|}

== WebSocket（SocketIO）==

实时事件走 SocketIO（连接根路径）。 / Real-time events use SocketIO at the root URL.

* '''客户端 → 服务器 Client → server'''：<code>request_install</code>（本地 IPK 安装 / local IPK install）、<code>request_install_package</code>（仓库安装 / repo install）、<code>request_firmware_upgrade</code>、<code>get_firmware_upgrade_status_socket</code>、<code>cancel_firmware_upgrade</code>（仅下载阶段可取消 / cancellable during download only）
* '''服务器 → 客户端 Server → client'''：<code>log_response</code>（实时日志 / live logs）、<code>firmware_upgrade_status</code>（含进度百分比 / with progress percentage）：
<pre>
{ "status": "downloading", "progress": 45, "message": "Downloading firmware (45%)" }
</pre>
* 2026-07 起 WebSocket 连接同样需要已登录会话。 / Since 2026-07 the socket also requires an authenticated session.

== 快速上手示例 Quick example ==

<pre>
# 登录拿会话 / log in for a session cookie
curl -c jar.txt -X POST http://172.16.0.1/login -d 'password=YOUR_PASSWORD'

# 读取设备信息 / read device info
curl -b jar.txt http://172.16.0.1/api/v1/system/board.json

# 抓一帧屏幕画面 / grab a live screen frame
curl -b jar.txt -o frame.png http://172.16.0.1/api/v1/screen/frame.png
</pre>

; 提示 Tips
* 写操作需附带 CSRF token；具体字段名以当前固件版本为准。 / State-changing calls need the CSRF token; field names follow your firmware version.
* 不要在公网直接暴露管理端口；如需远程访问请走 VPN。 / Never expose the manager port to the internet; use a VPN for remote access.

[[Photonicat 2 管理界面新功能 (2026)]] ｜ [[Photonicat 2 小屏幕自定义]]

Photonicat 2 开发者 API - 版本历史

2026年7月13日 (一) 09:50 C2h2

C2h2：​New topic: developer overview of the REST + WebSocket API — auth, endpoint groups, error shape, quick examples

C2h2：New topic: developer overview of the REST + WebSocket API — auth, endpoint groups, error shape, quick examples