{"components":{"parameters":{"FromTime":{"description":"起始时间 ISO 8601 UTC;支持相对 `-7d` / `-1h`","in":"query","name":"from","schema":{"format":"date-time","type":"string"}},"Page":{"in":"query","name":"page","schema":{"default":1,"minimum":1,"type":"integer"}},"PageSize":{"in":"query","name":"page_size","schema":{"default":20,"maximum":200,"minimum":1,"type":"integer"}},"ResourceId":{"description":"资源 ID(带语义前缀,如 `m_xyz`, `v_xyz`, `mcpt_xyz`)","in":"path","name":"id","required":true,"schema":{"type":"string"}},"ToTime":{"description":"结束时间 ISO 8601 UTC","in":"query","name":"to","schema":{"format":"date-time","type":"string"}}},"responses":{"BadRequest":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}},"description":"400 请求参数错误 / 校验失败"},"Conflict":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}},"description":"409 资源冲突 / 已存在"},"Forbidden":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}},"description":"403 权限不足 / scope 不足 / 档位限制"},"InternalError":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}},"description":"5xx 服务端错误"},"MessageOK":{"content":{"application/json":{"schema":{"properties":{"data":{"properties":{"message":{"type":"string"}},"type":"object"},"request_id":{"type":"string"}},"type":"object"}}},"description":"成功(data.message 为人类可读文案)"},"NotFound":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}},"description":"404 资源不存在"},"OkTrue":{"content":{"application/json":{"schema":{"properties":{"data":{"properties":{"ok":{"example":true,"type":"boolean"}},"type":"object"},"request_id":{"type":"string"}},"type":"object"}}},"description":"成功(data.ok = true)"},"PayloadTooLarge":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}},"description":"413 请求 body 超出限制(32KB)"},"RateLimited":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}},"description":"429 限速 / 配额超出","headers":{"Retry-After":{"description":"建议等待秒数","schema":{"type":"integer"}},"X-RateLimit-Limit":{"schema":{"type":"integer"}},"X-RateLimit-Remaining":{"schema":{"type":"integer"}},"X-RateLimit-Reset":{"schema":{"format":"date-time","type":"string"}}}},"ServiceUnavailable":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}},"description":"503 服务不可用(维护 / 过载 / 节点不可用)"},"Unauthorized":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}},"description":"401 未鉴权 / API Key 无效 / 已撤销 / 已过期"},"Unprocessable":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}},"description":"422 业务校验失败(目标命中黑名单 / 节点不足 / 数据缺失 等)"}},"schemas":{"AgentObsChecksListResponse":{"allOf":[{"$ref":"#/components/schemas/Envelope"},{"properties":{"data":{"properties":{"items":{"items":{"properties":{"checked_at":{"format":"date-time","type":"string"},"error_code":{"nullable":true,"type":"string"},"id":{"type":"string"},"latency_ms":{"nullable":true,"type":"number"},"monitor_id":{"type":"string"},"obs_type":{"type":"string"},"response_preview":{"nullable":true,"type":"string"},"status":{"type":"string"},"tokens_used":{"nullable":true,"type":"integer"}},"type":"object"},"type":"array"},"limit":{"type":"integer"},"next_cursor":{"description":"Keyset 模式下用于翻下一页的不透明游标;无下一页或 offset 模式时省略。 回传到本接口的 cursor 查询参数即可获取下一页。","type":"string"},"offset":{"type":"integer"},"total":{"type":"integer"}},"type":"object"}},"type":"object"}]},"AgentObsConfigRequest":{"description":"agent-obs(LLM/工具/RAG 可观测)配置请求","properties":{"check_interval_s":{"type":"integer"},"endpoint_url":{"type":"string"},"expected_tokens_max":{"type":"integer"},"latency_sla_ms":{"type":"integer"},"model_name":{"type":"string"},"obs_type":{"enum":["llm_endpoint","tool_api","rag"],"type":"string"},"payload_template":{"additionalProperties":true,"type":"object"}},"type":"object"},"AgentObsConfigResponse":{"properties":{"data":{"properties":{"check_interval_s":{"type":"integer"},"created_at":{"format":"date-time","type":"string"},"endpoint_url":{"type":"string"},"expected_tokens_max":{"nullable":true,"type":"integer"},"latency_sla_ms":{"nullable":true,"type":"integer"},"model_name":{"nullable":true,"type":"string"},"monitor_id":{"type":"string"},"obs_type":{"type":"string"},"updated_at":{"format":"date-time","type":"string"}},"type":"object"},"request_id":{"type":"string"}},"type":"object"},"AgentObsEvent":{"properties":{"cost_usd":{"description":"M21 实际花费","nullable":true,"type":"number"},"failure_class":{"enum":["timeout","4xx","5xx","malformed","semantic","budget"],"nullable":true,"type":"string"},"failure_detail":{"additionalProperties":true,"nullable":true,"type":"object"},"id":{"example":"aoe_xyz","type":"string"},"latency_ms":{"nullable":true,"type":"integer"},"monitor_id":{"type":"string"},"occurred_at":{"format":"date-time","type":"string"},"owner_id":{"type":"string"},"region":{"description":"哪个节点验证","type":"string"},"success":{"type":"boolean"},"trace_id":{"description":"可选 Agent 端 trace 关联","nullable":true,"type":"string"}},"type":"object"},"AgentObsEventStreamFrame":{"description":"SSE 流单帧;实际响应是 `text/event-stream`,格式:\n```\nevent: agent_obs.event\nid: \u003cevent_id\u003e\ndata: \u003cjson AgentObsEvent\u003e\n```\n客户端断线后用 `Last-Event-ID` header 续传。\n","properties":{"data":{"$ref":"#/components/schemas/AgentObsEvent"},"event":{"example":"agent_obs.event","type":"string"},"id":{"type":"string"}},"type":"object"},"AgentObsMonitor":{"allOf":[{"$ref":"#/components/schemas/CreateAgentObsMonitorRequest"},{"properties":{"created_at":{"format":"date-time","type":"string"},"id":{"example":"aom_xyz","type":"string"},"owner_id":{"type":"string"},"paused_at":{"format":"date-time","nullable":true,"type":"string"},"status":{"description":"状态机:\n- `active` 正常运行\n- `paused` 用户手动暂停\n- `exceeded_budget` D7 budget 触发自动暂停(发邮件通知);需用户手动调整 budget 后 resume\n","enum":["active","paused","exceeded_budget"],"type":"string"},"total_cost_this_month_usd":{"description":"D7 原子 UPDATE 累加;同 transaction 内做 budget 检查","type":"number"}},"type":"object"}]},"AgentObsMonitorListResponse":{"allOf":[{"$ref":"#/components/schemas/Envelope"},{"properties":{"data":{"items":{"$ref":"#/components/schemas/AgentObsMonitor"},"type":"array"}},"type":"object"}]},"AlertChannel":{"description":"告警通知渠道","properties":{"config":{"additionalProperties":true,"type":"object"},"created_at":{"format":"date-time","type":"string"},"id":{"type":"string"},"name":{"type":"string"},"type":{"enum":["email","webhook","wecom","dingtalk","feishu","telegram","slack","wechat"],"type":"string"},"user_id":{"type":"string"},"verified":{"type":"boolean"}},"type":"object"},"AlertEvent":{"properties":{"acknowledged_at":{"format":"date-time","nullable":true,"type":"string"},"acknowledged_by":{"nullable":true,"type":"string"},"id":{"example":"ae_xyz","type":"string"},"metadata":{"additionalProperties":true,"nullable":true,"type":"object"},"monitor_id":{"type":"string"},"policy_id":{"type":"string"},"resolved_at":{"format":"date-time","nullable":true,"type":"string"},"started_at":{"format":"date-time","type":"string"},"status":{"enum":["firing","acknowledged","resolved"],"type":"string"}},"type":"object"},"AlertEventListResponse":{"allOf":[{"$ref":"#/components/schemas/Envelope"},{"properties":{"data":{"properties":{"has_more":{"type":"boolean"},"items":{"items":{"$ref":"#/components/schemas/AlertEvent"},"type":"array"},"page":{"type":"integer"},"page_size":{"type":"integer"},"total":{"type":"integer"}},"type":"object"}},"type":"object"}]},"AlertGroup":{"description":"告警聚合分组规则","properties":{"created_at":{"format":"date-time","type":"string"},"group_by":{"enum":["monitor_prefix","tag","type"],"type":"string"},"group_value":{"type":"string"},"id":{"type":"string"},"name":{"type":"string"},"user_id":{"type":"string"},"wait_seconds":{"type":"integer"}},"type":"object"},"AlertPolicy":{"properties":{"escalation":{"additionalProperties":true,"type":"object"},"id":{"example":"ap_xyz","type":"string"},"name":{"type":"string"},"on_recovery":{"additionalProperties":true,"type":"object"},"rules":{"items":{"properties":{"channels":{"items":{"properties":{"channel_id":{"type":"string"},"to":{"items":{"type":"string"},"type":"array"},"type":{"enum":["email","sms","webhook","slack","dingtalk","feishu","lark","wechatwork","telegram","voice"],"type":"string"}},"type":"object"},"type":"array"},"delay_sec":{"default":0,"type":"integer"},"match":{"properties":{"severity":{"items":{"enum":["critical","warning","info"],"type":"string"},"type":"array"},"tags_any":{"items":{"type":"string"},"type":"array"},"time_window":{"properties":{"days":{"items":{"enum":["mon","tue","wed","thu","fri","sat","sun"],"type":"string"},"type":"array"},"end":{"pattern":"^\\d{2}:\\d{2}$","type":"string"},"start":{"pattern":"^\\d{2}:\\d{2}$","type":"string"},"timezone":{"example":"Asia/Shanghai","type":"string"}},"type":"object"}},"type":"object"},"repeat":{"properties":{"enabled":{"type":"boolean"},"interval_sec":{"type":"integer"},"max_count":{"type":"integer"}},"type":"object"}},"type":"object"},"type":"array"},"suppression":{"additionalProperties":true,"type":"object"}},"type":"object"},"AlertPolicyListResponse":{"allOf":[{"$ref":"#/components/schemas/Envelope"},{"properties":{"data":{"items":{"$ref":"#/components/schemas/AlertPolicy"},"type":"array"}},"type":"object"}]},"AlertSilence":{"description":"告警静默窗口","properties":{"created_at":{"format":"date-time","type":"string"},"ends_at":{"format":"date-time","type":"string"},"id":{"type":"string"},"monitor_id":{"nullable":true,"type":"string"},"reason":{"type":"string"},"starts_at":{"format":"date-time","type":"string"},"status":{"enum":["upcoming","active","expired"],"type":"string"},"user_id":{"type":"string"}},"type":"object"},"ApiKey":{"properties":{"created_at":{"format":"date-time","type":"string"},"expires_at":{"format":"date-time","nullable":true,"type":"string"},"id":{"example":"key_xyz","type":"string"},"key_prefix":{"description":"展示用前缀(masked),格式 `sk_live_xxx...` 或 `sk_test_xxx...`","example":"sk_live_abcd1234...","type":"string"},"last_used_at":{"format":"date-time","nullable":true,"type":"string"},"name":{"type":"string"},"scopes":{"items":{"type":"string"},"type":"array"},"status":{"enum":["active","revoked"],"type":"string"},"type":{"enum":["production","test"],"type":"string"}},"type":"object"},"ApiKeyListResponse":{"properties":{"data":{"properties":{"api_keys":{"items":{"$ref":"#/components/schemas/ApiKey"},"type":"array"}},"type":"object"},"request_id":{"example":"req_xyz","type":"string"}},"type":"object"},"Assertion":{"properties":{"op":{"enum":["eq","ne","gt","gte","lt","lte","in","not_in","contains","regex"],"type":"string"},"type":{"enum":["status_code","response_time","body_contains","body_regex","json_path","header_value","ssl_days_remaining"],"type":"string"},"value":{}},"type":"object"},"AttestKeyResponse":{"properties":{"algorithm":{"example":"ECDSA_P256_SHA256","type":"string"},"ceremony_log_id":{"description":"关联的 key_ceremony_log 记录","type":"string"},"created_at":{"format":"date-time","type":"string"},"key_id":{"type":"string"},"key_version":{"type":"integer"},"public_key_fingerprint":{"type":"string"},"public_key_pem":{"type":"string"},"revoked_at":{"format":"date-time","nullable":true,"type":"string"},"rotated_at":{"format":"date-time","nullable":true,"type":"string"},"status":{"description":"revoked / rotated key 仍可查询 public key(只读)","enum":["active","rotated","revoked"],"type":"string"}},"type":"object"},"AttestVerifyResponse":{"description":"D-Concern1 锁定响应字段;不走 Envelope(此接口公开 + 不限频 + 缓存友好)。","properties":{"content_hash":{"description":"SHA-256 of PDF bytes","example":"sha256:...","type":"string"},"invalid_reason":{"description":"valid=false 时填充","enum":[null,"signature_mismatch","tsa_invalid","content_modified","key_unknown","malformed_pdf"],"nullable":true,"type":"string"},"legal_disclaimer":{"description":"法律边界声明(中英双语,UI 必须展示)","example":"本报告为 idcd.com 提供的一手观测数据,不构成司法鉴定结论。This report is observation data from idcd.com and does not constitute a forensic conclusion.","type":"string"},"public_key_fingerprint":{"description":"公钥 SHA-256 指纹","example":"sha256:abcdef...","type":"string"},"report_type":{"default":"observation_only","description":"D-Concern1 必含字段。默认 `observation_only`,明确告知第三方:\n\"本报告是一手观测数据,不是司法鉴定结论\"。\n","enum":["observation_only"],"type":"string"},"signature_chain":{"description":"签名证书链 PEM","type":"string"},"signature_key_id":{"description":"签名所用 key id","type":"string"},"signature_key_version":{"description":"签名所用 key version(可能已撤销/过期;public key 仍可拉取用于历史验签,详 18 §7.1)","type":"integer"},"signed_at":{"description":"签名时间(由签名内嵌字段提取)","example":"2026-05-13T01:00:00Z","format":"date-time","type":"string"},"tsa_provider":{"description":"§P 字段保留但不填充(无 RFC3161 TSA)","enum":["digicert","globalsign","ntsc"],"type":"string"},"tsa_time":{"description":"§P:服务器时间(非 RFC3161)","format":"date-time","type":"string"},"valid":{"description":"验签结果","example":true,"type":"boolean"}},"required":["valid","report_type","legal_disclaimer"],"type":"object"},"AttestationRecord":{"description":"D4 WAL 行;每 step 完成写一条。","properties":{"action":{"description":"§P 实际只产生 `signed`(localfile RSA)+ `s3_archived`(普通 OSS)+ `revoked`;\n`tsa_stamped` / `anchored` / `self_verified` 枚举保留但不再写入。\n","enum":["signed","tsa_stamped","anchored","s3_archived","self_verified","revoked"],"type":"string"},"completed_at":{"format":"date-time","nullable":true,"type":"string"},"created_at":{"format":"date-time","type":"string"},"error_detail":{"nullable":true,"type":"string"},"external_id":{"description":"§P:localfile sign id / S3 ETag(原 TSA serial / chain tx / KMS req id 不再产生)","type":"string"},"id":{"example":"att_xyz","type":"string"},"idempotency_key":{"description":"§P:localfile sign idempotency(确定性签名);原 KMS/TSA idempotency token 不再使用","type":"string"},"report_id":{"type":"string"},"result":{"enum":["success","failure"],"type":"string"},"retry_count":{"description":"D4 step 重试次数(0-3)","type":"integer"},"status":{"enum":["pending","success","failure"],"type":"string"}},"type":"object"},"AuthResponse":{"properties":{"access_token":{"type":"string"},"expires_in":{"example":3600,"type":"integer"},"refresh_token":{"type":"string"},"user":{"$ref":"#/components/schemas/User"}},"type":"object"},"AuthTokenResponse":{"description":"登录/换取令牌的统一响应(2FA / OAuth / passkey / 微信扫码)","properties":{"data":{"properties":{"access_token":{"type":"string"},"expires_in":{"description":"秒","type":"integer"},"user_id":{"type":"string"}},"type":"object"},"request_id":{"type":"string"}},"type":"object"},"CertManualChallenge":{"properties":{"fqdn":{"description":"TXT record name, e.g. _acme-challenge.example.com.","type":"string"},"message":{"description":"Sentinel hint when the challenge is not ready yet","type":"string"},"value":{"description":"TXT record value (case-sensitive)","type":"string"}},"type":"object"},"CertOrderResponse":{"properties":{"account_id":{"type":"string"},"ca":{"type":"string"},"cert_id":{"format":"int64","nullable":true,"type":"integer"},"challenge_type":{"type":"string"},"common_name":{"nullable":true,"type":"string"},"created_at":{"format":"date-time","type":"string"},"dns_credential_id":{"format":"int64","nullable":true,"type":"integer"},"events":{"items":{"properties":{"action":{"type":"string"},"action_seq":{"type":"integer"},"occurred_at":{"format":"date-time","type":"string"}},"type":"object"},"type":"array"},"finalized_at":{"format":"date-time","nullable":true,"type":"string"},"id":{"format":"int64","type":"integer"},"last_error":{"nullable":true,"type":"string"},"manual_challenge":{"allOf":[{"$ref":"#/components/schemas/CertManualChallenge"}],"description":"Legacy single-record field (first live record, or a \"not ready\" message while the worker is still preparing). New clients read manual_challenges.","nullable":true},"manual_challenges":{"description":"All live dns-01 TXT records the user must install — one per SAN authorization (#405). Present for manual-DNS orders awaiting confirmation; a retry regenerates these with fresh values.","items":{"$ref":"#/components/schemas/CertManualChallenge"},"type":"array"},"retry_count":{"type":"integer"},"sans":{"items":{"type":"string"},"type":"array"},"sans_unicode":{"items":{"type":"string"},"type":"array"},"status":{"enum":["draft","validating","awaiting_org_validation","issuing","issued","failed","revoking","revoked"],"type":"string"},"tier":{"description":"e.g. free-dv","type":"string"}},"type":"object"},"CertResponse":{"properties":{"account_id":{"type":"string"},"created_at":{"format":"date-time","type":"string"},"fingerprint_sha256":{"type":"string"},"id":{"format":"int64","type":"integer"},"issuer":{"type":"string"},"not_after":{"format":"date-time","type":"string"},"not_before":{"format":"date-time","type":"string"},"order_id":{"format":"int64","type":"integer"},"revoke_reason":{"nullable":true,"type":"string"},"revoked_at":{"format":"date-time","nullable":true,"type":"string"},"sans":{"items":{"type":"string"},"type":"array"},"serial_hex":{"type":"string"},"status":{"enum":["issued","revoking","revoked","expired"],"type":"string"}},"type":"object"},"ComplianceReport":{"description":"Compliance 年订自动生成的周/月度报告","properties":{"created_at":{"format":"date-time","type":"string"},"id":{"example":"cr_xyz","type":"string"},"monitors_included":{"type":"integer"},"pdf_url":{"format":"uri","type":"string"},"period_month":{"nullable":true,"type":"integer"},"period_week":{"nullable":true,"type":"integer"},"period_year":{"type":"integer"},"report_type":{"default":"observation_only","enum":["observation_only"],"type":"string"},"signature":{"type":"string"},"subscription_id":{"type":"string"},"tsa_provider":{"enum":["digicert","globalsign","ntsc"],"type":"string"},"tsa_time":{"format":"date-time","type":"string"}},"type":"object"},"ComplianceReportListResponse":{"allOf":[{"$ref":"#/components/schemas/Envelope"},{"properties":{"data":{"items":{"$ref":"#/components/schemas/ComplianceReport"},"type":"array"}},"type":"object"}]},"ComplianceSubscription":{"properties":{"canceled_at":{"format":"date-time","nullable":true,"type":"string"},"created_at":{"format":"date-time","type":"string"},"ext_subscription_id":{"type":"string"},"free_verdict_count":{"type":"integer"},"free_verdict_used":{"type":"integer"},"history_retention_months":{"type":"integer"},"id":{"example":"cs_xyz","type":"string"},"monitors_quota":{"type":"integer"},"owner_id":{"type":"string"},"period_end":{"format":"date-time","type":"string"},"period_start":{"format":"date-time","type":"string"},"price_cny":{"type":"number"},"reports_frequency":{"enum":["monthly","weekly","custom"],"type":"string"},"status":{"enum":["active","past_due","canceled","expired"],"type":"string"},"tier":{"enum":["starter","pro","enterprise"],"type":"string"}},"type":"object"},"ComplianceSubscriptionResponse":{"allOf":[{"$ref":"#/components/schemas/Envelope"},{"properties":{"data":{"properties":{"checkout_url":{"description":"跳聚合支付 checkout 完成支付","format":"uri","type":"string"},"subscription":{"$ref":"#/components/schemas/ComplianceSubscription"}},"type":"object"}},"type":"object"}]},"CreateAgentObsMonitorRequest":{"properties":{"agent_name":{"description":"用户给 Agent 起的名(如 `customer_support_v3`)","type":"string"},"budget_per_check_usd":{"description":"M21 必填(防爆账单);单次 check 预估 USD 成本。\n原子 UPDATE budget(D7);超额 → status=`exceeded_budget`。\n","type":"number"},"endpoint_config":{"additionalProperties":true,"description":"不同 type 不同字段(详 04 §3.15-3.17);如 LLM 类型含 prompt / model","type":"object"},"endpoint_url":{"format":"uri","type":"string"},"failure_threshold":{"additionalProperties":true,"description":"失败阈值定义(latency / status_codes / payload_assertions)","type":"object"},"frequency_seconds":{"example":300,"minimum":10,"type":"integer"},"notification_channels":{"description":"关联 channel ID 列表","items":{"type":"string"},"type":"array"},"step_name":{"description":"Agent 工作流 step 名(可选,如 `retrieval`)","type":"string"},"type":{"description":"- `llm` = M21 LLM Endpoint Health(OpenAI/Anthropic/Bedrock/自家)— **强制 `budget_per_check_usd`**\n- `tool` = M22 Tool/API Endpoint\n- `rag` = M23 RAG/Vector Store\n- `other` = 其他类型\n","enum":["llm","tool","rag","other"],"type":"string"}},"required":["agent_name","type","endpoint_url","frequency_seconds","failure_threshold"],"type":"object"},"CreateApiKeyRequest":{"properties":{"allowed_origins":{"items":{"type":"string"},"type":"array"},"expires_at":{"format":"date-time","nullable":true,"type":"string"},"name":{"type":"string"},"scopes":{"items":{"enum":["probe","probe:read","monitor:read","monitor:write","alert:read","alert:write","status:read","status:write","billing:read","billing:write"],"type":"string"},"type":"array"}},"required":["name","scopes"],"type":"object"},"CreateApiKeyResponse":{"description":"创建 API Key 响应。`data` 平铺 ApiKey 字段并额外携带一次性的 `key` 原文。\n","properties":{"data":{"allOf":[{"$ref":"#/components/schemas/ApiKey"},{"properties":{"key":{"description":"API Key 完整原文;**仅返回一次**;务必保存。","example":"sk_live_aBcDeF...","type":"string"}},"type":"object"}]},"request_id":{"example":"req_xyz","type":"string"}},"type":"object"},"CreateComplianceSubscriptionRequest":{"properties":{"billing_address":{"additionalProperties":true,"type":"object"},"contact_company":{"description":"企业用户合规对接所需","type":"string"},"contact_email":{"format":"email","type":"string"},"tier":{"description":"K5b 锁定档位:\n- `starter` ¥3k/年 — 50 监控 + 月度报告 + 12 月历史\n- `pro` ¥12k/年 — 200 监控 + 周度报告 + 24 月历史 + 5 份免费 Verdict\n- `enterprise` ¥30k/年(议价)— 1000 监控 + 任意频率 + 6 年历史 + 不限 Verdict\n","enum":["starter","pro","enterprise"],"type":"string"}},"required":["tier"],"type":"object"},"CreateEnrollmentTokenRequest":{"properties":{"country_code":{"description":"声明国家代码 ISO 3166-1 alpha-2（服务端转大写）；可选","pattern":"^[A-Za-z]{2}$","type":"string"},"declared_province":{"description":"声明省/州（来自固定字典的 ISO 3166-2 代码，如 CN-GD，服务端 whitelist 校验）；可选","pattern":"^[A-Za-z]{2}-[A-Za-z0-9]{1,3}$","type":"string"},"label":{"description":"可选标签，便于识别节点","maxLength":40,"type":"string"},"sponsor_user_id":{"description":"预留字段，当前仅支持填写自己的 user_id","type":"string"}},"type":"object"},"CreateLeaderboardOptoutRequest":{"properties":{"applicant_email":{"format":"email","type":"string"},"applicant_organization":{"type":"string"},"contact_phone":{"type":"string"},"identity_proof_url":{"description":"主体认证材料(营业执照 / 公章 文件)","format":"uri","type":"string"},"reason":{"description":"退出原因","maxLength":5000,"type":"string"},"vendor_name":{"example":"ExampleCDN Inc","type":"string"}},"required":["vendor_name","applicant_email","identity_proof_url"],"type":"object"},"CreateMaintenanceWindowRequest":{"properties":{"advance_notice_minutes":{"default":0,"description":"提前预告的分钟数(0..10080,§8 ②b);省略默认 0(不预告)。","maximum":10080,"minimum":0,"type":"integer"},"ends_at":{"format":"date-time","type":"string"},"recurrence":{"default":"none","description":"省略默认 none。recurrence_until 在 none 时被忽略(置 null)。","enum":["none","daily","weekly","monthly"],"type":"string"},"recurrence_until":{"description":"周期重复的 occurrence START 上界(含);省略/null=无截止。须 \u003e= starts_at。","format":"date-time","nullable":true,"type":"string"},"scope_ids":{"description":"非 all scope 必须非空;all scope 忽略(规范化为 [])。","items":{"type":"string"},"type":"array"},"scope_type":{"enum":["monitor","group","tag","all"],"type":"string"},"starts_at":{"format":"date-time","type":"string"},"title":{"maxLength":200,"nullable":true,"type":"string"}},"required":["scope_type","starts_at","ends_at"],"type":"object"},"CreateMcpTokenRequest":{"properties":{"auto_renew":{"default":true,"description":"D2:workspace / service 默认 true(过期前 24h auto_renewal,基于 last_used_at;\n超 30 天未用不续 → 等于自动撤销);personal 走 OAuth-like refresh,此字段忽略。\n","type":"boolean"},"expires_at":{"description":"**必填,最长 90 天**(D2):\n- personal 默认 24h(也是最长)\n- workspace 最长 90d\n- service 最长 90d\n超过最长值返回 422。\n","format":"date-time","type":"string"},"ip_whitelist":{"description":"CIDR 列表(如 `[\"1.2.3.4/32\", \"5.6.7.0/24\"]`)。\n**service 必填**;personal / workspace 可选。\n无白名单的 service 创建请求返回 422 `validation_error`。\n","example":["1.2.3.4/32"],"items":{"format":"cidr","type":"string"},"type":"array"},"name":{"example":"Cursor on MacBook","type":"string"},"scope":{"description":"限定 tools / regions(默认全开)","properties":{"regions":{"example":["CN","US","EU"],"items":{"type":"string"},"type":"array"},"tools":{"example":["ping","http","diagnose"],"items":{"type":"string"},"type":"array"}},"type":"object"},"type":{"description":"D21 锁定三种形态。区别详 03 §5a.1。\n","enum":["personal","workspace","service"],"type":"string"}},"required":["type","name"],"type":"object"},"CreateMcpTokenResponse":{"allOf":[{"$ref":"#/components/schemas/Envelope"},{"properties":{"data":{"properties":{"secret":{"description":"完整 token 明文(`idcd_mcp_xxx...`)**仅此一次返回**;\n存到 Cursor / Claude Code / Codex 配置文件,后续不可再查。\n","example":"idcd_mcp_aBcDeFg...","type":"string"},"token":{"$ref":"#/components/schemas/McpToken"}},"type":"object"}},"type":"object"}]},"CreateMonitorGroupRequest":{"properties":{"name":{"maxLength":200,"type":"string"},"sort_order":{"default":0,"type":"integer"}},"required":["name"],"type":"object"},"CreateMonitorRequest":{"properties":{"alert_policy_id":{"nullable":true,"type":"string"},"assertions":{"items":{"$ref":"#/components/schemas/Assertion"},"type":"array"},"group_id":{"nullable":true,"type":"string"},"interval_sec":{"enum":[10,30,60,300,900],"type":"integer"},"name":{"maxLength":200,"type":"string"},"node_selection":{"$ref":"#/components/schemas/NodeSelection"},"params":{"additionalProperties":true,"type":"object"},"tags":{"items":{"type":"string"},"type":"array"},"target":{"type":"string"},"trigger_rule":{"properties":{"consecutive_fail":{"default":2,"type":"integer"},"fail_node_quorum":{"default":"2/3","type":"string"}},"type":"object"},"type":{"enum":["http","ping","tcping","dns","ssl","domain","icp","keyword","json","heartbeat","browser"],"type":"string"}},"required":["name","type","target","interval_sec"],"type":"object"},"CreateVerdictOrderRequest":{"properties":{"idempotency_key":{"description":"客户端去重 key(也可通过 Idempotency-Key header 传)","type":"string"},"notes":{"type":"string"},"notify_email":{"description":"报告生成完成通知邮箱(默认账户邮箱)","format":"email","type":"string"},"target":{"type":"string"},"template":{"$ref":"#/components/schemas/VerdictTemplate"},"time_window_end":{"format":"date-time","type":"string"},"time_window_start":{"format":"date-time","type":"string"},"webhook_url":{"description":"报告生成完成时回调(可选;与邮件并行)","format":"uri","type":"string"}},"required":["template","target","time_window_start","time_window_end"],"type":"object"},"CreateVerdictOrderResponse":{"allOf":[{"$ref":"#/components/schemas/Envelope"},{"properties":{"data":{"properties":{"order_id":{"description":"新建 verdict_order 的 id(v_*)。","example":"v_abc123","type":"string"},"pay_url":{"description":"跳转聚合支付 checkout 完成支付;支付成功 聚合支付 webhook 触发 generation。\nURL 有效期 24 小时;过期需重新创建订单。**payment_method=report_credit\n时为空字符串**(已用按次报告额度结清,无需支付)。\n","example":"https://pay.example.com/checkout/xyz","type":"string"},"payment_method":{"description":"订单结算方式:`charge`=已下发 pay_url 待用户支付;\n`report_credit`=用户持有 report_pack 余额,已扣 1 次额度直接结清\n(订单立即 paid 并入队生成,无 pay_url)。\n","enum":["charge","report_credit"],"example":"charge","type":"string"},"price_cny":{"description":"订单价格(元,含促销/优惠后实际应付)。","example":299,"type":"number"}},"type":"object"}},"type":"object"}]},"CreateWebhookEndpointRequest":{"properties":{"description":{"type":"string"},"events":{"items":{"example":"monitor.down","type":"string"},"type":"array"},"url":{"format":"uri","type":"string"}},"required":["url","events"],"type":"object"},"CreateWebhookEndpointResponse":{"allOf":[{"$ref":"#/components/schemas/Envelope"},{"properties":{"data":{"properties":{"endpoint":{"$ref":"#/components/schemas/WebhookEndpoint"},"secret":{"description":"签名 secret;**仅返回一次**;用户端用此 secret 校验出站 webhook 签名。","type":"string"}},"type":"object"}},"type":"object"}]},"DNSCredentialResponse":{"properties":{"account_id":{"type":"string"},"created_at":{"format":"date-time","type":"string"},"display_name":{"type":"string"},"health_checked_at":{"format":"date-time","nullable":true,"type":"string"},"health_status":{"enum":["valid","invalid","unknown"],"type":"string"},"id":{"format":"int64","type":"integer"},"provider":{"type":"string"},"revoked_at":{"format":"date-time","nullable":true,"type":"string"}},"type":"object"},"DiagnoseRequest":{"properties":{"node_ids":{"description":"固定节点 ID 列表;多节点对比拨测,后端为每个节点创建一个 task(详","items":{"type":"string"},"type":"array"},"nodes":{"$ref":"#/components/schemas/NodeSelection"},"scope":{"items":{"enum":["http","ping","dns","traceroute","ssl","security_headers"],"type":"string"},"type":"array"},"target":{"type":"string"}},"required":["target"],"type":"object"},"DiagnoseResponse":{"allOf":[{"$ref":"#/components/schemas/Envelope"},{"properties":{"data":{"properties":{"id":{"type":"string"},"overall_score":{"maximum":100,"minimum":0,"type":"integer"},"sections":{"additionalProperties":true,"type":"object"},"status":{"enum":["running","completed","failed"],"type":"string"},"target":{"type":"string"}},"type":"object"}},"type":"object"}]},"DnsProbeRequest":{"properties":{"node_id":{"description":"单节点简写(node_ids 的单值形式)","type":"string"},"node_ids":{"description":"固定节点 ID 列表;多节点对比拨测,后端为每个节点创建一个 task(详","items":{"type":"string"},"type":"array"},"nodes":{"$ref":"#/components/schemas/NodeSelection"},"params":{"description":"DNS 探测参数","properties":{"record_type":{"default":"A","enum":["A","AAAA","CNAME","MX","TXT","NS","SOA","CAA","ANY"],"type":"string"},"server":{"description":"自定义 DNS server","type":"string"}},"type":"object"},"target":{"description":"目标域名","example":"example.com","type":"string"}},"required":["target"],"type":"object"},"DnsProbeResponse":{"allOf":[{"$ref":"#/components/schemas/Envelope"},{"properties":{"data":{"properties":{"domain":{"type":"string"},"pollution_detected":{"description":"多节点解析不一致(可能 DNS 污染)","type":"boolean"},"records_by_node":{"items":{"properties":{"node_id":{"type":"string"},"records":{"items":{"additionalProperties":true,"type":"object"},"type":"array"}},"type":"object"},"type":"array"},"type":{"type":"string"}},"type":"object"}},"type":"object"}]},"DomainComboPreview":{"description":"/domain-combo/preview 的便宜计数结果。","properties":{"capped":{"description":"总数超过有效 cap → stream 截断。","type":"boolean"},"effective":{"cap)。":null,"description":"stream 实际会发出的数量 == min(total","type":"integer"},"sample":{"description":"按生成顺序的前几个域名。","items":{"type":"string"},"type":"array"},"total":{"description":"封顶前的原始组合总数(展示用","type":"integer","可能饱和)。":null}},"type":"object"},"DomainComboSpec":{"description":"域名组合生成规则。SLD 由有序 slots 笛卡尔展开,与每个 TLD 组合。","properties":{"cap":{"description":"单次封顶(\u003c=0 → 默认 1000,clamp 到 5000)。","type":"integer"},"exclude":{"description":"要排除的字符;包含任一字符的 token 被丢弃。","type":"string"},"slots":{"description":"有序槽位;每个槽位按 kind+variant 展开成一组候选 token。","items":{"properties":{"kind":{"enum":["number","letter","word","literal"],"type":"string"},"literal":{"description":"KindLiteral 的固定片段。","type":"string"},"variant":{"description":"kind 下的子集(如 number/single、letter/pinyin);literal 忽略。","type":"string"}},"required":["kind"],"type":"object"},"type":"array"},"tlds":{"description":"要组合的 TLD 列表(不含点)。","items":{"example":"com","type":"string"},"type":"array"}},"required":["slots","tlds"],"type":"object"},"EnrollmentTokenCreated":{"allOf":[{"$ref":"#/components/schemas/Envelope"},{"properties":{"data":{"properties":{"expires_at":{"format":"date-time","type":"string"},"token":{"description":"完整 enrollment token，仅在创建时返回，以 ent_ 开头","example":"ent_a1b2c3d4...","type":"string"}},"required":["token","expires_at"],"type":"object"}},"type":"object"}]},"EnrollmentTokenItem":{"properties":{"consumed_node_id":{"nullable":true,"type":"string"},"created_at":{"format":"date-time","type":"string"},"expires_at":{"format":"date-time","type":"string"},"id":{"example":"et_01J8XXXXX","type":"string"},"label":{"type":"string"},"preview":{"example":"ent_***1a2b","type":"string"},"status":{"enum":["active","used","expired"],"type":"string"}},"required":["id","label","status","created_at","expires_at","preview"],"type":"object"},"EnrollmentTokenList":{"allOf":[{"$ref":"#/components/schemas/Envelope"},{"properties":{"data":{"properties":{"tokens":{"items":{"$ref":"#/components/schemas/EnrollmentTokenItem"},"type":"array"}},"required":["tokens"],"type":"object"}},"type":"object"}]},"Entitlement":{"description":"一条 user_entitlements 行的公开投影。","properties":{"attrs":{"additionalProperties":true,"type":"object"},"balance":{"format":"int64","type":"integer"},"expires_at":{"format":"date-time","nullable":true,"type":"string"},"granted_at":{"format":"date-time","type":"string"},"id":{"type":"string"},"kind":{"enum":["quota_override","api_pack","report_pack"],"type":"string"},"order_ref":{"nullable":true,"type":"string"},"source":{"type":"string"},"status":{"enum":["active","revoked","expired"],"type":"string"},"user_id":{"type":"string"}},"type":"object"},"Envelope":{"description":"所有响应的标准 envelope(data + meta)","properties":{"data":{},"meta":{"$ref":"#/components/schemas/Meta"}},"type":"object"},"Error":{"description":"错误响应 envelope。handler 实际形态:`{error: {code, message, request_id}, request_id}`。\n`meta` 字段保留作为可选扩展位(部分新接口会把 trace 信息挂在这里),\n但通用 handler(`response.Error`)目前只渲染 error.* + 顶层 request_id。\n","properties":{"error":{"properties":{"code":{"description":"稳定的机器可读错误码,**UPPER_SNAKE_CASE**,直接出现在 JSON 响应的\n`error.code` 字段。SSOT = `backend/lib/shared/errcode/codes.go`(本 enum\n与其一一对应);人类可读文案按 `Accept-Language` 由 i18n catalog 渲染进\n`message`,故 `code` 用于客户端分支、`message` 仅用于展示。按模块分组:\n- **Auth/session**:`AUTH_REQUIRED` `AUTH_INVALID_TOKEN` `AUTH_EXPIRED` `AUTH_CREDENTIALS_INVALID` `AUTH_EMAIL_NOT_VERIFIED` `AUTH_ACCOUNT_DISABLED` `AUTH_2FA_REQUIRED` `AUTH_2FA_INVALID` `AUTH_OAUTH_LINKED_OTHER_USER` `AUTH_OAUTH_STATE_INVALID` `AUTH_WEBAUTHN_CHALLENGE_INVALID` `AUTH_SESSION_INVALID` `AUTH_OTP_INVALID` `AUTH_OTP_EXPIRED` `AUTH_OTP_ATTEMPTS_EXCEEDED` `AUTH_PASSWORD_WEAK` `AUTH_PASSWORD_REUSED`\n- **Account**:`ACCOUNT_NOT_FOUND` `ACCOUNT_EMAIL_TAKEN` `ACCOUNT_USERNAME_TAKEN` `ACCOUNT_LOCALE_UNSUPPORTED` `ACCOUNT_TIMEZONE_INVALID` `ACCOUNT_DELETED` `ACCOUNT_EMAIL_UNVERIFIED`\n- **通用边界**:`VALIDATION_FAILED` `RATE_LIMIT_EXCEEDED` `NOT_FOUND` `FORBIDDEN` `CONFLICT` `DUPLICATE` `REQUEST_TIMEOUT` `REQUEST_BODY_INVALID`\n- **服务端**:`INTERNAL_ERROR` `UNAVAILABLE` `UNKNOWN`\n- **Monitors**:`MONITOR_NOT_FOUND` `MONITOR_NAME_TAKEN` `MONITOR_LIMIT_EXCEEDED` `MONITOR_INVALID_TARGET` `MONITOR_INVALID_INTERVAL` `MONITOR_PAUSED`\n- **Alerts**:`ALERT_RULE_CONFLICT` `ALERT_RULE_NOT_FOUND` `ALERT_CHANNEL_NOT_FOUND` `ALERT_CHANNEL_INVALID` `ALERT_NOISE_RULE_NOT_FOUND`\n- **Billing**:`BILLING_INSUFFICIENT_CREDITS` `BILLING_PLAN_NOT_FOUND` `BILLING_INVOICE_NOT_FOUND` `BILLING_PAYMENT_FAILED` `BILLING_REFUND_FAILED` `BILLING_QUOTA_EXCEEDED`\n- **Quota/plan**:`QUOTA_EXCEEDED` `FEATURE_LOCKED`\n- **Status pages**:`STATUS_PAGE_NOT_FOUND` `STATUS_PAGE_SLUG_TAKEN` `STATUS_PAGE_DOMAIN_INVALID` `STATUS_PAGE_DOMAIN_TAKEN`\n- **Nodes**:`NODE_NOT_FOUND` `NODE_ENROLLMENT_TOKEN_INVALID` `NODE_OFFLINE` `NODE_UPGRADE_FAILED` `NODE_STATE_CONFLICT` `NODE_ALREADY_BANNED` `NODE_NOT_BANNED`\n- **Teams**:`TEAM_NOT_FOUND` `TEAM_MEMBER_EXISTS` `TEAM_INVITE_INVALID`\n- **API keys / PAT**:`API_KEY_NOT_FOUND` `API_KEY_REVOKED` `PAT_NOT_FOUND` `TOKEN_EXPIRED` `TOKEN_LIMIT_EXCEEDED`\n- **Incidents**:`POSTMORTEM_NOT_FOUND` `INCIDENT_NOT_FOUND`\n- **Probe**:`PROBE_JOB_NOT_FOUND` `PROBE_TARGET_INVALID` `DIAGNOSE_REPORT_TOO_LONG`\n- **Oncall**:`ONCALL_SCHEDULE_NOT_FOUND` `ONCALL_PARTICIPANT_NOT_FOUND` `ONCALL_SCHEDULE_NAME_TAKEN` `ONCALL_TEAM_MEMBER_REQUIRED`\n","enum":["AUTH_REQUIRED","AUTH_INVALID_TOKEN","AUTH_EXPIRED","AUTH_CREDENTIALS_INVALID","AUTH_EMAIL_NOT_VERIFIED","AUTH_ACCOUNT_DISABLED","AUTH_2FA_REQUIRED","AUTH_2FA_INVALID","AUTH_OAUTH_LINKED_OTHER_USER","AUTH_OAUTH_STATE_INVALID","AUTH_WEBAUTHN_CHALLENGE_INVALID","AUTH_SESSION_INVALID","AUTH_OTP_INVALID","AUTH_OTP_EXPIRED","AUTH_OTP_ATTEMPTS_EXCEEDED","AUTH_PASSWORD_WEAK","AUTH_PASSWORD_REUSED","ACCOUNT_NOT_FOUND","ACCOUNT_EMAIL_TAKEN","ACCOUNT_USERNAME_TAKEN","ACCOUNT_LOCALE_UNSUPPORTED","ACCOUNT_TIMEZONE_INVALID","ACCOUNT_DELETED","ACCOUNT_EMAIL_UNVERIFIED","VALIDATION_FAILED","RATE_LIMIT_EXCEEDED","NOT_FOUND","FORBIDDEN","CONFLICT","DUPLICATE","REQUEST_TIMEOUT","REQUEST_BODY_INVALID","INTERNAL_ERROR","UNAVAILABLE","UNKNOWN","MONITOR_NOT_FOUND","MONITOR_NAME_TAKEN","MONITOR_LIMIT_EXCEEDED","MONITOR_INVALID_TARGET","MONITOR_INVALID_INTERVAL","MONITOR_PAUSED","ALERT_RULE_CONFLICT","ALERT_RULE_NOT_FOUND","ALERT_CHANNEL_NOT_FOUND","ALERT_CHANNEL_INVALID","ALERT_NOISE_RULE_NOT_FOUND","BILLING_INSUFFICIENT_CREDITS","BILLING_PLAN_NOT_FOUND","BILLING_INVOICE_NOT_FOUND","BILLING_PAYMENT_FAILED","BILLING_REFUND_FAILED","BILLING_QUOTA_EXCEEDED","QUOTA_EXCEEDED","FEATURE_LOCKED","STATUS_PAGE_NOT_FOUND","STATUS_PAGE_SLUG_TAKEN","STATUS_PAGE_DOMAIN_INVALID","STATUS_PAGE_DOMAIN_TAKEN","NODE_NOT_FOUND","NODE_ENROLLMENT_TOKEN_INVALID","NODE_OFFLINE","NODE_UPGRADE_FAILED","NODE_STATE_CONFLICT","NODE_ALREADY_BANNED","NODE_NOT_BANNED","TEAM_NOT_FOUND","TEAM_MEMBER_EXISTS","TEAM_INVITE_INVALID","API_KEY_NOT_FOUND","API_KEY_REVOKED","PAT_NOT_FOUND","TOKEN_EXPIRED","TOKEN_LIMIT_EXCEEDED","POSTMORTEM_NOT_FOUND","INCIDENT_NOT_FOUND","PROBE_JOB_NOT_FOUND","PROBE_TARGET_INVALID","DIAGNOSE_REPORT_TOO_LONG","ONCALL_SCHEDULE_NOT_FOUND","ONCALL_PARTICIPANT_NOT_FOUND","ONCALL_SCHEDULE_NAME_TAKEN","ONCALL_TEAM_MEMBER_REQUIRED"],"example":"VALIDATION_FAILED","type":"string"},"details":{"additionalProperties":true,"description":"字段级错误等","type":"object"},"doc_url":{"example":"https://docs.idcd.com/errors/VALIDATION_FAILED","format":"uri","type":"string"},"message":{"description":"人类可读错误信息(按 Accept-Language 本地化);仅用于展示,客户端分支请用 `code`。","example":"请求参数校验失败","type":"string"},"request_id":{"description":"与顶层 request_id 重复,便于客户端只读 error.* 时也能拿到 trace id","example":"req_xyz","type":"string"}},"required":["code","message"],"type":"object"},"meta":{"description":"可选扩展位,通用 handler 不写","properties":{"request_id":{"example":"req_xyz","type":"string"}},"type":"object"},"request_id":{"description":"与 error.request_id 同步,顶层冗余便于 client 拦截器统一取","example":"req_xyz","type":"string"}},"required":["error"],"type":"object"},"ExportMonitor":{"description":"监控的可移植、与实例无关投影(导出/导入共用)。运行时字段 (id/status/uptime/时间戳)刻意省略;group 按名称携带。","properties":{"config":{"description":"监控配置(assertions 等);空对象时省略","type":"object"},"group":{"description":"分组名(空=未分组)","type":"string"},"interval_s":{"type":"integer"},"name":{"type":"string"},"node_count":{"type":"integer"},"tags":{"items":{"type":"string"},"type":"array"},"target":{"type":"string"},"type":{"type":"string"}},"type":"object"},"GenericProbeRequest":{"description":"通用拨测请求(tcp / mtr / smtp / ntp / speedtest 共用)。target + 节点选择。","properties":{"node_id":{"description":"指定单节点","type":"string"},"node_ids":{"description":"指定多节点","items":{"type":"string"},"type":"array"},"nodes":{"$ref":"#/components/schemas/NodeSelection"},"params":{"additionalProperties":true,"description":"协议特定参数","type":"object"},"target":{"description":"拨测目标(host / host:port / url)","type":"string"}},"required":["target"],"type":"object"},"HeartbeatRotateResponse":{"properties":{"data":{"properties":{"token":{"description":"新打卡 token(旧 token 立即失效)","type":"string"},"url":{"description":"新完整打卡 URL","type":"string"}},"required":["token","url"],"type":"object"},"request_id":{"example":"req_xyz","type":"string"}},"type":"object"},"HttpHeadersResponse":{"allOf":[{"$ref":"#/components/schemas/Envelope"},{"properties":{"data":{"properties":{"analysis":{"properties":{"insecure":{"description":"命中任一强信号即 true","type":"boolean"},"reasons":{"items":{"enum":["no_https_redirect","no_hsts","no_compression","no_cdn"],"type":"string"},"type":"array"}},"type":"object"},"final_url":{"description":"跟完重定向链后的最终 URL","type":"string"},"headers":{"additionalProperties":{"type":"string"},"description":"最终响应头(多值用 \", \" join,key 规范化大小写)","type":"object"},"hops":{"description":"重定向链逐跳(含最终一跳)","items":{"properties":{"location":{"description":"3xx 时的 Location 头","type":"string"},"status_code":{"type":"integer"},"url":{"type":"string"}},"type":"object"},"type":"array"},"security":{"description":"抽取的安全/优化相关头(空值省略)","properties":{"cdn":{"description":"综合指纹判定的 CDN 标识","type":"string"},"content_encoding":{"type":"string"},"csp":{"type":"string"},"hsts":{"type":"string"},"referrer_policy":{"type":"string"},"server":{"type":"string"},"x_content_type_options":{"type":"string"},"x_frame_options":{"type":"string"}},"type":"object"},"url":{"description":"用户原始请求(可能补了 http:// 前缀)","type":"string"}},"type":"object"}},"type":"object"}]},"HttpProbeRequest":{"properties":{"node_id":{"description":"单节点简写(node_ids 的单值形式)","type":"string"},"node_ids":{"description":"固定节点 ID 列表;多节点对比拨测,后端为每个节点创建一个 task(详","items":{"type":"string"},"type":"array"},"nodes":{"$ref":"#/components/schemas/NodeSelection"},"params":{"description":"HTTP 探测参数","properties":{"body":{"maxLength":32768,"type":"string"},"follow_redirects":{"default":true,"type":"boolean"},"headers":{"additionalProperties":{"type":"string"},"type":"object"},"ip_version":{"default":"auto","enum":["v4","v6","auto"],"type":"string"},"method":{"default":"GET","enum":["GET","HEAD","POST","PUT","DELETE","OPTIONS","PATCH"],"type":"string"},"timeout_ms":{"default":10000,"maximum":30000,"minimum":1000,"type":"integer"}},"type":"object"},"target":{"description":"目标 URL","example":"https://example.com","type":"string"}},"required":["target"],"type":"object"},"HttpProbeResponse":{"allOf":[{"$ref":"#/components/schemas/Envelope"},{"properties":{"data":{"properties":{"node_results":{"items":{"properties":{"error":{"nullable":true,"type":"string"},"final_url":{"type":"string"},"headers":{"additionalProperties":{"type":"string"},"type":"object"},"node":{"properties":{"asn":{"type":"integer"},"city":{"type":"string"},"country":{"type":"string"},"isp":{"type":"string"}},"type":"object"},"node_id":{"type":"string"},"response_ms":{"type":"integer"},"response_size":{"type":"integer"},"status_code":{"type":"integer"},"success":{"type":"boolean"},"timing":{"properties":{"dns_ms":{"type":"integer"},"download_ms":{"type":"integer"},"tcp_ms":{"type":"integer"},"tls_ms":{"type":"integer"},"ttfb_ms":{"type":"integer"}},"type":"object"},"tls":{"properties":{"cipher":{"type":"string"},"version":{"type":"string"}},"type":"object"}},"type":"object"},"type":"array"},"status":{"enum":["running","completed","failed"],"type":"string"},"summary":{"properties":{"avg_response_ms":{"type":"number"},"fail_count":{"type":"integer"},"p95_response_ms":{"type":"number"},"success_count":{"type":"integer"}},"type":"object"},"target":{"type":"string"},"task_id":{"example":"pt_xyz","type":"string"}},"type":"object"}},"type":"object"}]},"IcpResponse":{"allOf":[{"$ref":"#/components/schemas/Envelope"},{"properties":{"data":{"properties":{"company":{"type":"string"},"domain":{"type":"string"},"filed_at":{"description":"备案 / 审核通过日期","type":"string"},"icp_number":{"example":"京ICP备XXXXX号","type":"string"},"inquiry_url":{"description":"工信部公示页跳转链接(主域名预填)","type":"string"},"note":{"description":"未命中时的提示文案","type":"string"},"source":{"type":"string"},"type":{"description":"主体性质(企业 / 个人 等)","type":"string"}},"type":"object"}},"type":"object"}]},"IpInfoResponse":{"allOf":[{"$ref":"#/components/schemas/Envelope"},{"properties":{"data":{"properties":{"asn":{"type":"integer"},"city":{"type":"string"},"country":{"type":"string"},"ip":{"type":"string"},"isp":{"type":"string"},"org":{"type":"string"},"region":{"type":"string"}},"type":"object"}},"type":"object"}]},"IpReputationResponse":{"allOf":[{"$ref":"#/components/schemas/Envelope"},{"properties":{"data":{"properties":{"asn":{"type":"string"},"city":{"type":"string"},"country":{"type":"string"},"evidence":{"description":"命中信号及其权重(可解释)。signal 取值:tor_exit / vpn / proxy / abuse_asn / hosting。其中 abuse_asn 来自已知 abuse / bulletproof-hosting ASN 名单,description 含命中原因(#508)。","items":{"properties":{"description":{"type":"string"},"signal":{"example":"tor_exit","type":"string"},"weight":{"type":"integer"}},"type":"object"},"type":"array"},"ip":{"type":"string"},"isp":{"type":"string"},"risk_level":{"enum":["low","medium","high"],"type":"string"},"score":{"description":"0–100 风险评分(越高越可疑)","type":"integer"},"types":{"description":"类型标签:tor / vpn / proxy / hosting / residential。命中独立 VPN 段数据源时报告 `vpn`(比上游 proxy 更精确);仅上游 proxy 标记而无 VPN 段命中时报告 `proxy`——两者互斥不同时出现(#508)。","items":{"enum":["tor","vpn","proxy","hosting","residential"],"type":"string"},"type":"array"}},"type":"object"}},"type":"object"}]},"KeyCeremonyListResponse":{"properties":{"data":{"items":{"$ref":"#/components/schemas/KeyCeremonyLog"},"type":"array"},"meta":{"$ref":"#/components/schemas/Meta"}},"type":"object"},"KeyCeremonyLog":{"description":"§P:仅免费证书模块(§O,KMS 信任根)产生;Verdict 改 localfile 自签后不产生密钥仪式。","properties":{"action":{"enum":["root_gen","root_split","sign_key_rotate","emergency_revoke"],"type":"string"},"actors":{"description":"参与方(双人/多人审批 + 公证)","items":{"properties":{"identity":{"example":"founder@idcd.com","type":"string"},"role":{"example":"kms_admin","type":"string"}},"type":"object"},"type":"array"},"created_at":{"format":"date-time","type":"string"},"evidence_url":{"description":"录像 / 公证 PDF 链接(transparency 公开)","format":"uri","type":"string"},"id":{"example":"kc_xyz","type":"string"},"key_id":{"nullable":true,"type":"string"},"key_version":{"nullable":true,"type":"integer"},"notes":{"type":"string"}},"type":"object"},"LeaderboardOptoutRequest":{"allOf":[{"$ref":"#/components/schemas/CreateLeaderboardOptoutRequest"},{"properties":{"created_at":{"format":"date-time","type":"string"},"decided_at":{"format":"date-time","nullable":true,"type":"string"},"decision_reason":{"nullable":true,"type":"string"},"id":{"type":"string"},"status":{"enum":["pending","approved","rejected"],"type":"string"}},"type":"object"}]},"LeaderboardReport":{"description":"CDN/云厂商月度排行榜报告(K6 边界控制)。\n勘误公告通过 `errata_pdf_url`(D-Concern3);不直接删除原报告。\n","properties":{"created_at":{"format":"date-time","type":"string"},"errata_pdf_url":{"description":"D-Concern3 勘误公告 PDF(已发布后修订用此 URL,不删除原报告)","format":"uri","nullable":true,"type":"string"},"errata_reason":{"description":"勘误原因(厂商申诉 / 内部修订 等)","nullable":true,"type":"string"},"excluded_vendors":{"description":"已申请退出的厂商","items":{"type":"string"},"type":"array"},"id":{"example":"lb_2026_05","type":"string"},"methodology_version":{"type":"string"},"pdf_url":{"format":"uri","type":"string"},"period_month":{"type":"integer"},"period_year":{"type":"integer"},"published_at":{"format":"date-time","nullable":true,"type":"string"},"status":{"enum":["draft","reviewing","published","archived"],"type":"string"},"verdict_report_id":{"description":"配套 Verdict 报告(自我背书)","nullable":true,"type":"string"}},"type":"object"},"ListVerdictOrdersResponse":{"description":"GET /v1/verdict/orders 的分页信封(「我的存证」列表)。owner 过滤在 SQL 层,\n`total` 为该用户订单总数的独立 COUNT。\n","properties":{"limit":{"description":"本页返回上限(clamp 至 1-100","type":"integer","默认 20)":null},"offset":{"description":"本页起始偏移(clamp 至 ≥0)","type":"integer"},"orders":{"items":{"$ref":"#/components/schemas/VerdictOrder"},"type":"array"},"total":{"description":"当前用户订单总数(与 offset 无关)","type":"integer"}},"required":["orders","total","limit","offset"],"type":"object"},"LoginRequest":{"properties":{"email":{"format":"email","type":"string"},"otp":{"description":"2FA TOTP(若启用)","type":"string"},"password":{"type":"string"}},"required":["email","password"],"type":"object"},"MaintenanceWindow":{"description":"维护窗口(后续期 B,§7.3 / A8)。与 handler `MaintenanceWindowResponse` 对齐。scope_type 决定 scope_ids 含义:monitor=监控 id 数组,group=分组 id 数组,tag=标签数组,all=全部监控(scope_ids 为 [])。","properties":{"advance_notice_minutes":{"description":"每次 occurrence 开始前多少分钟向窗口 owner 账户邮箱发预告邮件(§8 ②b);0=不预告。","maximum":10080,"minimum":0,"type":"integer"},"created_at":{"format":"date-time","type":"string"},"ends_at":{"format":"date-time","type":"string"},"id":{"example":"mmw_xyz","type":"string"},"recurrence":{"description":"周期(§8 ②a)。none=一次性;daily/weekly/monthly 按首个窗口的时刻重复。","enum":["none","daily","weekly","monthly"],"type":"string"},"recurrence_until":{"description":"最后一次 occurrence 的 START 上界(含);null=无截止(永久重复)。none 时为 null。","format":"date-time","nullable":true,"type":"string"},"scope_ids":{"items":{"type":"string"},"type":"array"},"scope_type":{"enum":["monitor","group","tag","all"],"type":"string"},"starts_at":{"format":"date-time","type":"string"},"title":{"nullable":true,"type":"string"},"user_id":{"type":"string"}},"type":"object"},"MaintenanceWindowListResponse":{"properties":{"data":{"properties":{"items":{"items":{"$ref":"#/components/schemas/MaintenanceWindow"},"type":"array"}},"type":"object"},"request_id":{"example":"req_xyz","type":"string"}},"type":"object"},"MaintenanceWindowResponse":{"properties":{"data":{"$ref":"#/components/schemas/MaintenanceWindow"},"request_id":{"example":"req_xyz","type":"string"}},"type":"object"},"McpSession":{"description":"MCP 会话(MCP client 连接 mcp.idcd.com 时建立)。SSE 连接 stateful(D13),\nLB sticky session 必要。\n","properties":{"client_id":{"enum":["Cursor","ClaudeCode","Codex","sdk-py","sdk-ts","other"],"type":"string"},"client_ip":{"format":"ipv4","type":"string"},"client_version":{"type":"string"},"ended_at":{"format":"date-time","nullable":true,"type":"string"},"id":{"example":"mcps_xyz","type":"string"},"last_activity_at":{"format":"date-time","type":"string"},"owner_id":{"type":"string"},"started_at":{"format":"date-time","type":"string"},"token_id":{"type":"string"},"total_tool_calls":{"type":"integer"},"total_units":{"type":"integer"}},"type":"object"},"McpToken":{"properties":{"auto_renew":{"type":"boolean"},"created_at":{"format":"date-time","type":"string"},"expires_at":{"format":"date-time","type":"string"},"id":{"example":"mcpt_xyz","type":"string"},"ip_whitelist":{"items":{"type":"string"},"type":"array"},"last_renewed_at":{"format":"date-time","nullable":true,"type":"string"},"last_used_at":{"format":"date-time","nullable":true,"type":"string"},"name":{"type":"string"},"owner_id":{"type":"string"},"revoke_reason":{"nullable":true,"type":"string"},"revoked":{"type":"boolean"},"scope":{"properties":{"regions":{"items":{"type":"string"},"type":"array"},"tools":{"items":{"type":"string"},"type":"array"}},"type":"object"},"token_display":{"description":"前缀 + 后 4 位掩码(明文格式 `idcd_mcp_*`);完整 token 仅创建时返回一次","example":"idcd_mcp_***1234","type":"string"},"type":{"enum":["personal","workspace","service"],"type":"string"}},"type":"object"},"McpTokenListResponse":{"allOf":[{"$ref":"#/components/schemas/Envelope"},{"properties":{"data":{"items":{"$ref":"#/components/schemas/McpToken"},"type":"array"}},"type":"object"}]},"McpToolCall":{"description":"单次 MCP tool 调用(高频写入;TimescaleDB Hypertable)。\n默认 payload 哈希存储(隐私);D7 用户可在 /app/mcp/settings 开启\n\"失败 case 临时存 7 天原 payload\",仅 status=failure 写入 `*_raw` jsonb,\n过期 cron 自动清理。\n","properties":{"created_at":{"format":"date-time","type":"string"},"error_class":{"nullable":true,"type":"string"},"error_detail":{"nullable":true,"type":"string"},"id":{"example":"mctc_xyz","type":"string"},"latency_ms":{"type":"integer"},"owner_id":{"type":"string"},"payload_retain_until":{"format":"date-time","nullable":true,"type":"string"},"request_payload_hash":{"type":"string"},"request_payload_raw":{"additionalProperties":true,"description":"D7 失败 case + 用户授权下临时存(7 天自动清理)","nullable":true,"type":"object"},"response_payload_hash":{"type":"string"},"response_payload_raw":{"additionalProperties":true,"nullable":true,"type":"object"},"session_id":{"type":"string"},"status":{"enum":["success","failure","timeout","rate_limited"],"type":"string"},"tool_name":{"description":"MCP registry 实注册的 8 个工具(裸名,无 idcd_ 前缀)。","enum":["ping","http","dns","traceroute","ssl","diagnose","ip","whois"],"type":"string"},"units_charged":{"type":"integer"}},"type":"object"},"McpUsageResponse":{"allOf":[{"$ref":"#/components/schemas/Envelope"},{"properties":{"data":{"properties":{"by_client":{"description":"按 client 拆分","items":{"properties":{"calls":{"type":"integer"},"client_id":{"type":"string"},"units":{"type":"integer"}},"type":"object"},"type":"array"},"by_tool":{"description":"按 tool 拆分","items":{"properties":{"avg_latency_ms":{"type":"number"},"calls":{"type":"integer"},"cost_cny":{"type":"number"},"tool_name":{"type":"string"},"units":{"type":"integer"}},"type":"object"},"type":"array"},"period":{"example":"2026-05","type":"string"},"time_series":{"description":"按时间序列(daily / hourly,取决于 group_by)","items":{"properties":{"bucket":{"format":"date-time","type":"string"},"calls":{"type":"integer"},"units":{"type":"integer"}},"type":"object"},"type":"array"},"total_cost_cny":{"example":8.5,"type":"number"},"total_units_quota":{"example":5000,"type":"integer"},"total_units_used":{"example":4250,"type":"integer"}},"type":"object"}},"type":"object"}]},"Meta":{"properties":{"cache":{"properties":{"age_sec":{"type":"integer"},"hit":{"type":"boolean"}},"type":"object"},"pagination":{"properties":{"has_more":{"type":"boolean"},"next_cursor":{"type":"string"},"page":{"type":"integer"},"page_size":{"type":"integer"},"total":{"type":"integer"}},"type":"object"},"rate_limit":{"properties":{"limit":{"example":5000,"type":"integer"},"remaining":{"example":4982,"type":"integer"},"reset":{"format":"date-time","type":"string"}},"type":"object"},"request_id":{"example":"req_xyz","type":"string"},"took_ms":{"example":42,"type":"integer"}},"type":"object"},"Monitor":{"description":"Monitor 资源对象 — 与 handler `MonitorResponse` Go struct 严格对齐\n(`apps/api/internal/handler/monitor/monitor.go`)。注意 `interval_s`\n(秒)和 `config`(类型特定原始 JSON)与 PRD 公开契约 schema\n`CreateMonitorRequest` 用的 `interval_sec` / `params` 暂未对齐 —\nv2 公开 GA 时统一,届时再回写本 schema。\n","properties":{"config":{"additionalProperties":true,"description":"类型特定参数(method/headers/body/expected_status 等),原始 JSON。 heartbeat 类型(M10)为排期配置,双模式(服务端物化默认值后存储): interval 模式 {\"mode\":\"interval\",\"interval_s\":86400,\"grace_s\":17280}; cron 模式 {\"mode\":\"cron\",\"cron_expr\":\"0 3 * * *\",\"timezone\":\"Asia/Shanghai\",\"grace_s\":1800}。 v1.1 可选项(§3.2):assert_body_contains(打卡 body 必含子串,否则按 fail;≤256 字符)、 max_duration_s(配合 /start 的「跑太久」阈值秒数,0=关闭)。"},"created_at":{"format":"date-time","type":"string"},"current_status":{"description":"运行态健康(状态机维护,与配置态 status 区分)。config status 受 CHECK 约束永不为 down/degraded,故健康必须来自此字段。omitempty:零值(测试夹具)省略, 生产恒存在(NOT NULL DEFAULT 'unknown')。","enum":["up","down","degraded","unknown"],"type":"string"},"group_id":{"description":"所属分组(后续期 C);null = 未分组","nullable":true,"type":"string"},"heartbeat":{"description":"仅 type=heartbeat 携带(M10,PRD 26 §6.2)。创建响应(POST /v1/monitors 201) 为 {\"token\",\"url\",\"state\"}(唯一一次随创建全量下发 token+完整打卡 URL); 详情(GET /v1/monitors/{id})为 {\"url\",\"state\",\"last_ping_at\",\"last_ping_ip\", \"last_ping_via\",\"ping_count\"}。非 heartbeat 类型与列表行不携带本字段。","oneOf":[{"$ref":"#/components/schemas/MonitorHeartbeatCreateInfo"},{"$ref":"#/components/schemas/MonitorHeartbeatDetail"}]},"id":{"example":"m_xyz","type":"string"},"in_maintenance":{"description":"是否处于活跃维护窗口内(后续期 B,List/Get 由 monitormaint 实时解析)","type":"boolean"},"interval_s":{"description":"拨测间隔(秒);MVP 阈值 60/300/1800,v2 GA 将扩展为 10/30/60/300/900。 heartbeat 类型此字段为服务端派生的期望打卡最小间隔(限速基准), 不可直接 PATCH(改 config 由服务端重算)。","type":"integer"},"last_check_at":{"format":"date-time","nullable":true,"type":"string"},"name":{"type":"string"},"next_check_at":{"description":"下次拨测时间;heartbeat 类型语义复用为「判 down 截止时刻」(PRD 26 §4.3)","format":"date-time","nullable":true,"type":"string"},"node_count":{"type":"integer"},"status":{"enum":["active","paused","archived"],"type":"string"},"tags":{"description":"标签(lowercase 规范化、去重排序);筛选用 tags @\u003e '[\"x\"]'","items":{"type":"string"},"type":"array"},"target":{"description":"探测目标;heartbeat 类型存打卡 token 前 11 位展示前缀(\"hb_\"+8","type":"string","非凭据)":null},"type":{"enum":["http","https","ping","tcp","dns","ssl_expiry","domain_expiry","keyword","rbl","llm_endpoint","tool_api","rag","heartbeat"],"type":"string"},"updated_at":{"format":"date-time","type":"string"},"uptime_percent":{"example":99.95,"type":"number"},"user_id":{"type":"string"}},"type":"object"},"MonitorCheck":{"properties":{"error":{"nullable":true,"type":"string"},"id":{"example":"mc_xyz","type":"string"},"monitor_id":{"type":"string"},"node_id":{"type":"string"},"response_ms":{"type":"integer"},"started_at":{"format":"date-time","type":"string"},"status_code":{"nullable":true,"type":"integer"},"success":{"type":"boolean"}},"type":"object"},"MonitorChecksResponse":{"allOf":[{"$ref":"#/components/schemas/Envelope"},{"properties":{"data":{"items":{"$ref":"#/components/schemas/MonitorCheck"},"type":"array"}},"type":"object"}]},"MonitorEvent":{"description":"monitor_event 行 —— 状态机产生的故障事件,独立于告警策略(plan §4.2)","properties":{"ack_at":{"format":"date-time","nullable":true,"type":"string"},"acknowledged_by":{"nullable":true,"type":"string"},"affected_nodes":{"description":"触发本轮 down 的节点 id","items":{"type":"string"},"type":"array"},"created_at":{"format":"date-time","type":"string"},"duration_sec":{"description":"关闭时 = ended_at-started_at(秒)","nullable":true,"type":"integer"},"ended_at":{"description":"null=进行中","format":"date-time","nullable":true,"type":"string"},"id":{"example":"mev_xxx","type":"string"},"is_false_positive":{"type":"boolean"},"monitor_id":{"example":"mon_xxx","type":"string"},"notes":{"nullable":true,"type":"string"},"reason":{"description":"evaluator 失败断言摘要","nullable":true,"type":"string"},"resolved_by":{"nullable":true,"type":"string"},"started_at":{"format":"date-time","type":"string"},"type":{"enum":["down","degraded"],"type":"string"}},"type":"object"},"MonitorEventListResponse":{"allOf":[{"$ref":"#/components/schemas/Envelope"},{"properties":{"data":{"properties":{"items":{"items":{"$ref":"#/components/schemas/MonitorEvent"},"type":"array"},"limit":{"type":"integer"},"monitor_id":{"type":"string"},"page":{"type":"integer"},"total":{"type":"integer"}},"type":"object"}},"type":"object"}]},"MonitorEventResponse":{"properties":{"data":{"$ref":"#/components/schemas/MonitorEvent"},"request_id":{"example":"req_xyz","type":"string"}},"type":"object"},"MonitorExportEnvelope":{"description":"JSON 导出的顶层信封。","properties":{"count":{"type":"integer"},"exported_at":{"format":"date-time","type":"string"},"kind":{"example":"idcd.monitors.export","type":"string"},"monitors":{"items":{"$ref":"#/components/schemas/ExportMonitor"},"type":"array"},"version":{"example":1,"type":"integer"}},"type":"object"},"MonitorGroup":{"description":"监控分组(后续期 C,§7.1)。与 handler `MonitorGroupResponse` 对齐。","properties":{"created_at":{"format":"date-time","type":"string"},"id":{"example":"mgr_xyz","type":"string"},"name":{"type":"string"},"sort_order":{"type":"integer"},"user_id":{"type":"string"}},"type":"object"},"MonitorGroupListResponse":{"properties":{"data":{"properties":{"items":{"items":{"$ref":"#/components/schemas/MonitorGroup"},"type":"array"}},"type":"object"},"request_id":{"example":"req_xyz","type":"string"}},"type":"object"},"MonitorGroupResponse":{"properties":{"data":{"$ref":"#/components/schemas/MonitorGroup"},"request_id":{"example":"req_xyz","type":"string"}},"type":"object"},"MonitorHeartbeatCreateInfo":{"description":"heartbeat 创建响应附带块 — 打卡 token 与完整打卡 URL。","properties":{"badge_url":{"description":"v1.1 §3.2 只读状态徽章 URL(基于稳定 public_id,轮换 token 不变)","example":"https://api-prod.idcd.com/badge/hb/hbp_V1StGXR8_Z5jdHi6BmyT9.svg","type":"string"},"state":{"description":"新建恒为 new(未收到首个 ping","enum":["new"],"type":"string","不告警)":null},"token":{"example":"hb_V1StGXR8_Z5jdHi6BmyT9","type":"string"},"url":{"example":"https://api-prod.idcd.com/heartbeat/hb_V1StGXR8_Z5jdHi6BmyT9","type":"string"}},"required":["token","url","state","badge_url"],"type":"object"},"MonitorHeartbeatDetail":{"description":"heartbeat 详情响应附带块 — 打卡 URL + 运行态 + 最近打卡元数据。","properties":{"badge_url":{"description":"v1.1 §3.2 只读状态徽章 URL(基于稳定 public_id,轮换 token 不变)","type":"string"},"last_ping_at":{"format":"date-time","nullable":true,"type":"string"},"last_ping_ip":{"description":"最近打卡来源 IP(帮助发现 token 泄露的异常来源)","nullable":true,"type":"string"},"last_ping_via":{"enum":["get","post","head","fail",null],"nullable":true,"type":"string"},"ping_count":{"format":"int64","type":"integer"},"state":{"description":"心跳状态机(PRD 26 §4.2);与 current_status 映射 new→unknown/up→up/grace→degraded/down→down","enum":["new","up","grace","down"],"type":"string"},"url":{"type":"string"}},"required":["url","badge_url","state","last_ping_at","last_ping_ip","last_ping_via","ping_count"],"type":"object"},"MonitorImportRequest":{"properties":{"content":{"description":"文件原文(JSON 信封/裸数组 或 CSV)","type":"string"},"dry_run":{"description":"true=仅预览不写入;false=确认后实际创建","type":"boolean"},"format":{"default":"json","enum":["json","csv"],"type":"string"}},"required":["content"],"type":"object"},"MonitorImportResponse":{"properties":{"data":{"properties":{"created_ids":{"description":"仅 commit(dry_run=false)时填充","items":{"type":"string"},"type":"array"},"dry_run":{"type":"boolean"},"rows":{"items":{"$ref":"#/components/schemas/MonitorImportRowResult"},"type":"array"},"summary":{"properties":{"create":{"type":"integer"},"error":{"type":"integer"},"new_groups":{"description":"尚不存在、commit 时将创建的分组名","items":{"type":"string"},"type":"array"},"skip":{"type":"integer"},"total":{"type":"integer"}},"type":"object"}},"type":"object"},"request_id":{"example":"req_xyz","type":"string"}},"type":"object"},"MonitorImportRowResult":{"properties":{"action":{"enum":["create","skip","error"],"type":"string"},"index":{"description":"文件内 0-based 行号","type":"integer"},"name":{"type":"string"},"reason":{"description":"skip/error 的机器码(already_exists / quota_exceeded / interval_not_allowed / node_count_not_allowed / invalid_type / invalid_target / invalid_interval / invalid_config / invalid_tags / invalid_group / name_required / name_too_long / invalid_node_count)。","type":"string"}},"type":"object"},"MonitorListResponse":{"properties":{"data":{"properties":{"items":{"items":{"$ref":"#/components/schemas/Monitor"},"type":"array"},"limit":{"type":"integer"},"page":{"type":"integer"},"status_counts":{"description":"按 effective-status(paused 配置态优先;否则 current_status 运行态)的全量计数, 跨所有页、跟随当前筛选(与 total 同 WHERE)。total == up+down+paused+degraded。 驱动列表页统计卡,使其不随翻页跳变。","properties":{"degraded":{"description":"运行态 degraded","type":"integer"},"down":{"description":"运行态 down","type":"integer"},"paused":{"description":"配置态 paused","type":"integer"},"up":{"description":"active 且运行 up(含未检测过)","type":"integer"}},"type":"object"},"total":{"type":"integer"}},"type":"object"},"request_id":{"example":"req_xyz","type":"string"}},"type":"object"},"MonitorResponse":{"properties":{"data":{"$ref":"#/components/schemas/Monitor"},"request_id":{"example":"req_xyz","type":"string"}},"type":"object"},"MonitorSparklinesResponse":{"allOf":[{"$ref":"#/components/schemas/Envelope"},{"properties":{"data":{"properties":{"sparklines":{"additionalProperties":{"items":{"$ref":"#/components/schemas/SparkPoint"},"type":"array"},"description":"监控项 id → 24h 分桶序列(按时间升序)","type":"object"}},"type":"object"}},"type":"object"}]},"MonitorTagListResponse":{"properties":{"data":{"properties":{"items":{"items":{"$ref":"#/components/schemas/TagCount"},"type":"array"}},"type":"object"},"request_id":{"example":"req_xyz","type":"string"}},"type":"object"},"MonitorTestResultResponse":{"allOf":[{"$ref":"#/components/schemas/Envelope"},{"properties":{"data":{"properties":{"per_node":{"items":{"properties":{"error":{"type":"string"},"failed_assertions":{"items":{"additionalProperties":true,"type":"object"},"type":"array"},"latency_ms":{"nullable":true,"type":"integer"},"node_id":{"type":"string"},"raw_signals":{"additionalProperties":true,"type":"object"},"status":{"enum":["pending","up","degraded","down"],"type":"string"}},"type":"object"},"type":"array"},"status":{"enum":["pending","done"],"type":"string"},"test_id":{"type":"string"},"verdict":{"enum":["up","degraded","down","pending"],"type":"string"}},"type":"object"}},"type":"object"}]},"MonitorTestRunResponse":{"allOf":[{"$ref":"#/components/schemas/Envelope"},{"properties":{"data":{"properties":{"status":{"enum":["pending"],"example":"pending","type":"string"},"test_id":{"example":"mt_xyz","type":"string"}},"type":"object"}},"type":"object"}]},"Node":{"properties":{"asn":{"type":"integer"},"city":{"description":"Frozen city name snapshot captured at enrollment (not a live join to geo_cities).","type":"string"},"city_id":{"description":"geo_cities.id (CSC stable id); null for legacy free-text rows.","nullable":true,"type":"integer"},"confidence_label":{"description":"Anchor 节点偏差检测后的可信度分类(详 10 §6.5,D10);\n`low` 节点不参与 Verdict 报告生成(详 18 §3.2 step 2)。\n","enum":["high","medium","low"],"type":"string"},"country_code":{"description":"ISO 3166-1 alpha-2 (uppercased server-side).","example":"JP","pattern":"^[A-Z]{2}$","type":"string"},"id":{"example":"nd_jp_tk_01_vultr","type":"string"},"isp":{"type":"string"},"name":{"description":"Operator-supplied display name fixed at enrollment-token issuance\n(e.g. `staging-sg-1`). Falls back to agent hostname → node id when\nthe operator did not provide one. LLM/UI consumers should render\nthis instead of `id`.\n","type":"string"},"provider":{"type":"string"},"region":{"deprecated":true,"description":"Legacy field mirroring metadata.region (now an ISO 3166-2 subdivision\ncode). Superseded by subdivision/province; retained for backward\ncompatibility, no new writes.\n","type":"string"},"status":{"enum":["healthy","degraded","unhealthy","offline"],"type":"string"},"tags":{"items":{"type":"string"},"type":"array"}},"type":"object"},"NodeListResponse":{"allOf":[{"$ref":"#/components/schemas/Envelope"},{"properties":{"data":{"items":{"$ref":"#/components/schemas/Node"},"type":"array"}},"type":"object"}]},"NodeSelection":{"description":"节点选择(详 04 §3 / 08 §5)","properties":{"ids":{"description":"节点 ID 列表(mode=fixed 必填)","items":{"type":"string"},"type":"array"},"isps":{"example":["chinatelecom","chinaunicom"],"items":{"type":"string"},"type":"array"},"mode":{"default":"pool","description":"pool=自动从池中挑选 N 个;fixed=指定节点 ID","enum":["pool","fixed"],"type":"string"},"regions":{"example":["CN","US","EU"],"items":{"type":"string"},"type":"array"},"size":{"default":3,"maximum":50,"minimum":1,"type":"integer"},"tags":{"items":{"type":"string"},"type":"array"}},"type":"object"},"OncallSchedule":{"description":"值班排班","properties":{"created_at":{"format":"date-time","type":"string"},"handoff_hour":{"nullable":true,"type":"integer"},"id":{"type":"string"},"name":{"type":"string"},"rotation_type":{"enum":["daily","weekly"],"type":"string"},"team_id":{"type":"string"}},"type":"object"},"PingProbeRequest":{"properties":{"node_id":{"description":"单节点简写(node_ids 的单值形式)","type":"string"},"node_ids":{"description":"固定节点 ID 列表;多节点对比拨测,后端为每个节点创建一个 task(详","items":{"type":"string"},"type":"array"},"nodes":{"$ref":"#/components/schemas/NodeSelection"},"params":{"description":"Ping 探测参数","properties":{"count":{"default":4,"maximum":50,"minimum":1,"type":"integer"},"ip_version":{"default":"auto","enum":["v4","v6","auto"],"type":"string"},"timeout_ms":{"default":5000,"type":"integer"}},"type":"object"},"target":{"example":"1.1.1.1","type":"string"}},"required":["target"],"type":"object"},"PingProbeResponse":{"allOf":[{"$ref":"#/components/schemas/Envelope"},{"properties":{"data":{"properties":{"node_results":{"items":{"additionalProperties":true,"type":"object"},"type":"array"},"summary":{"properties":{"avg_ms":{"type":"number"},"max_ms":{"type":"number"},"min_ms":{"type":"number"},"packet_loss":{"type":"number"}},"type":"object"},"target":{"type":"string"},"task_id":{"type":"string"}},"type":"object"}},"type":"object"}]},"Plan":{"properties":{"code":{"example":"pro","type":"string"},"features":{"items":{"type":"string"},"type":"array"},"limits":{"additionalProperties":{"type":"integer"},"description":"配额 KV(resource_key → limit_value)。limit_value 三态约定:\n-1 = 无限 / 0 = 禁用 / \u003e0 = 上限。配合 resource_meta 渲染。\n","type":"object"},"name":{"example":"Pro","type":"string"},"price_cny_monthly":{"nullable":true,"type":"number"},"price_cny_yearly":{"nullable":true,"type":"number"},"tier_group":{"enum":["core","compliance"],"type":"string"}},"type":"object"},"PlanLimitCell":{"description":"套餐矩阵的一个 (plan, resource) cell。","properties":{"default_value":{"description":"Go seed 值(用于 drift 高亮)","format":"int64","type":"integer"},"drifted":{"description":"db_override 且 limit_value 偏离 default_value","type":"boolean"},"limit_value":{"description":"-1 无限 / 0 禁用 / \u003e0 上限","format":"int64","type":"integer"},"period":{"enum":["concurrent","day"],"type":"string"},"plan":{"type":"string"},"resource_key":{"type":"string"},"source":{"enum":["db_override","go_default"],"type":"string"},"updated_at":{"format":"date-time","nullable":true,"type":"string"},"updated_by":{"nullable":true,"type":"string"}},"type":"object"},"PlanListResponse":{"allOf":[{"$ref":"#/components/schemas/Envelope"},{"properties":{"data":{"properties":{"plans":{"items":{"$ref":"#/components/schemas/Plan"},"type":"array"},"resource_meta":{"additionalProperties":{"$ref":"#/components/schemas/PlanResourceMeta"},"type":"object"}},"type":"object"}},"type":"object"}]},"PlanResourceMeta":{"description":"单个配额项的渲染元数据(enforce 算子 + 哨兵值)。","properties":{"disabled_value":{"example":0,"type":"integer"},"enforce":{"enum":["count","max","min"],"type":"string"},"unlimited_value":{"example":-1,"type":"integer"}},"type":"object"},"Postmortem":{"description":"故障复盘报告(完整包裹响应)","properties":{"data":{"properties":{"created_at":{"format":"date-time","type":"string"},"event_id":{"type":"string"},"id":{"type":"string"},"impact":{"type":"string"},"resolution":{"type":"string"},"root_cause":{"type":"string"},"severity":{"type":"string"},"status":{"type":"string"},"title":{"type":"string"},"updated_at":{"format":"date-time","type":"string"}},"type":"object"},"request_id":{"type":"string"}},"type":"object"},"ProbeTaskAccepted":{"properties":{"callback_url":{"type":"string"},"status":{"enum":["running"],"type":"string"},"task_id":{"example":"pt_xyz","type":"string"},"task_ids":{"description":"多节点拨测时每个节点对应的 task_id(task_id 为首个,向后兼容)。","items":{"type":"string"},"type":"array"}},"type":"object"},"ReferralCodeResponse":{"properties":{"data":{"properties":{"code":{"type":"string"},"url":{"type":"string"},"uses_count":{"type":"integer"}},"type":"object"},"request_id":{"type":"string"}},"type":"object"},"RegisterRequest":{"properties":{"email":{"format":"email","type":"string"},"invite_code":{"type":"string"},"password":{"minLength":12,"type":"string"}},"required":["email","password"],"type":"object"},"RenameTagRequest":{"properties":{"from":{"description":"现有标签(大小写不敏感)。","maxLength":50,"type":"string"},"to":{"description":"新标签;规范化后不得与 from 相同。","maxLength":50,"type":"string"}},"required":["from","to"],"type":"object"},"SlaReport":{"allOf":[{"$ref":"#/components/schemas/Envelope"},{"properties":{"data":{"properties":{"period":{"example":"2026-04","type":"string"},"total_downtime_minutes":{"type":"integer"},"total_incidents":{"type":"integer"},"uptime_pct":{"type":"number"}},"type":"object"}},"type":"object"}]},"SparkPoint":{"description":"24h sparkline 的一个时间桶(字段名压缩以控批量载荷)。latency_ms 决定柱高; up/total 决定柱色(全 up→绿 / 部分→琥珀 / 全 down→红)。","properties":{"latency_ms":{"description":"该桶 datacenter 节点平均延迟(四舍五入)","type":"integer"},"t":{"Unix 秒(UTC)":null,"description":"桶起始","format":"int64","type":"integer"},"total":{"description":"桶内总检测数","type":"integer"},"up":{"description":"桶内 up 检测数","type":"integer"}},"type":"object"},"SslResponse":{"allOf":[{"$ref":"#/components/schemas/Envelope"},{"properties":{"data":{"properties":{"days_remaining":{"type":"integer"},"host":{"type":"string"},"issuer":{"type":"string"},"port":{"type":"integer"},"score":{"enum":["A+","A","B","C","D","F"],"type":"string"},"subject":{"type":"string"},"valid_from":{"format":"date-time","type":"string"},"valid_until":{"format":"date-time","type":"string"}},"type":"object"}},"type":"object"}]},"StatusPage":{"properties":{"custom_domain":{"nullable":true,"type":"string"},"id":{"example":"sp_xyz","type":"string"},"name":{"type":"string"},"public_url":{"format":"uri","type":"string"},"slug":{"example":"my-status","type":"string"}},"type":"object"},"StatusPageIncident":{"description":"状态页事件(含更新时间线)","properties":{"affected_monitor_ids":{"items":{"type":"string"},"type":"array"},"created_at":{"format":"date-time","type":"string"},"id":{"type":"string"},"impact":{"enum":["minor","major","critical"],"type":"string"},"resolved_at":{"format":"date-time","nullable":true,"type":"string"},"started_at":{"format":"date-time","type":"string"},"status":{"enum":["investigating","identified","monitoring","resolved"],"type":"string"},"title":{"type":"string"},"updated_at":{"format":"date-time","type":"string"},"updates":{"items":{"properties":{"body":{"type":"string"},"created_at":{"format":"date-time","type":"string"},"id":{"type":"string"},"status":{"type":"string"}},"type":"object"},"type":"array"}},"type":"object"},"StatusPageItem":{"description":"状态页(管理视图)","properties":{"created_at":{"format":"date-time","type":"string"},"custom_domain":{"type":"string"},"custom_domain_verified":{"type":"boolean"},"description":{"type":"string"},"id":{"type":"string"},"is_public":{"type":"boolean"},"name":{"type":"string"},"overall_status":{"description":"真实运行态聚合(operational/degraded/outage)；空串=无法计算，前端隐藏徽章","type":"string"},"slug":{"type":"string"}},"type":"object"},"StatusPageListResponse":{"allOf":[{"$ref":"#/components/schemas/Envelope"},{"properties":{"data":{"properties":{"status_pages":{"items":{"$ref":"#/components/schemas/StatusPageItem"},"type":"array"}},"type":"object"}},"type":"object"}]},"StatusPageSummary":{"allOf":[{"$ref":"#/components/schemas/Envelope"},{"properties":{"data":{"properties":{"active_incidents":{"items":{"additionalProperties":true,"type":"object"},"type":"array"},"components":{"items":{"additionalProperties":true,"type":"object"},"type":"array"},"name":{"type":"string"},"slug":{"type":"string"},"status":{"enum":["operational","degraded","partial_outage","major_outage"],"type":"string"}},"type":"object"}},"type":"object"}]},"SubscriptionBreakdown":{"description":"各档活跃订阅数。键对齐 subscriptions.plan CHECK(free/pro/team/business)。","properties":{"business":{"type":"integer"},"free":{"type":"integer"},"pro":{"type":"integer"},"team":{"type":"integer"}},"type":"object"},"SubscriptionResponse":{"allOf":[{"$ref":"#/components/schemas/Envelope"},{"properties":{"data":{"properties":{"cancel_at_period_end":{"type":"boolean"},"period_end":{"format":"date-time","type":"string"},"status":{"enum":["active","past_due","canceled","expired"],"type":"string"},"tier":{"enum":["free","pro","team","business"],"type":"string"}},"type":"object"}},"type":"object"}]},"TagCount":{"description":"一个标签及携带它的活跃监控数量(后续期 §8 ③)。","properties":{"count":{"example":12,"type":"integer"},"tag":{"example":"prod","type":"string"}},"type":"object"},"TagMutationResponse":{"properties":{"data":{"properties":{"updated":{"description":"受影响(被更新)的监控数量。","type":"integer"}},"type":"object"},"request_id":{"example":"req_xyz","type":"string"}},"type":"object"},"TcpingProbeRequest":{"properties":{"node_id":{"description":"单节点简写(node_ids 的单值形式)","type":"string"},"node_ids":{"description":"固定节点 ID 列表;多节点对比拨测,后端为每个节点创建一个 task(详","items":{"type":"string"},"type":"array"},"nodes":{"$ref":"#/components/schemas/NodeSelection"},"params":{"description":"TCP 探测参数","properties":{"count":{"default":4,"maximum":50,"minimum":1,"type":"integer"},"port":{"maximum":65535,"minimum":1,"type":"integer"},"timeout_ms":{"default":5000,"type":"integer"}},"type":"object"},"target":{"description":"host:port,或 host(端口走 params.port)","example":"example.com:443","type":"string"}},"required":["target"],"type":"object"},"Team":{"description":"团队","properties":{"created_at":{"format":"date-time","type":"string"},"id":{"type":"string"},"name":{"type":"string"},"role":{"description":"当前用户在团队中的角色","enum":["owner","admin","member"],"type":"string"},"slug":{"type":"string"}},"type":"object"},"TracerouteRequest":{"properties":{"node_id":{"description":"单节点简写(node_ids 的单值形式)","type":"string"},"node_ids":{"description":"固定节点 ID 列表;多节点对比拨测,后端为每个节点创建一个 task(详","items":{"type":"string"},"type":"array"},"nodes":{"$ref":"#/components/schemas/NodeSelection"},"params":{"description":"Traceroute 探测参数","properties":{"max_hops":{"default":30,"type":"integer"}},"type":"object"},"target":{"type":"string"}},"required":["target"],"type":"object"},"TracerouteResponse":{"allOf":[{"$ref":"#/components/schemas/Envelope"},{"properties":{"data":{"properties":{"hops_by_node":{"items":{"properties":{"hops":{"items":{"properties":{"ip":{"type":"string"},"rtt_ms":{"type":"number"},"ttl":{"type":"integer"}},"type":"object"},"type":"array"},"node_id":{"type":"string"}},"type":"object"},"type":"array"},"target":{"type":"string"}},"type":"object"}},"type":"object"}]},"TsaResponse":{"description":"单次 TSA 调用记录。§P 废弃:Verdict 改服务器时间,无 RFC3161 TSA;schema/表保留备用,不再产生新行。","properties":{"created_at":{"format":"date-time","type":"string"},"id":{"example":"tsa_xyz","type":"string"},"issued_at":{"format":"date-time","type":"string"},"latency_ms":{"type":"integer"},"provider":{"enum":["digicert","globalsign","ntsc"],"type":"string"},"request_hash":{"type":"string"},"serial_number":{"type":"string"},"status":{"enum":["success","failure","timeout"],"type":"string"},"used_by_report_id":{"nullable":true,"type":"string"},"valid_until":{"format":"date-time","type":"string"}},"type":"object"},"UpdateMaintenanceWindowRequest":{"description":"局部更新;省略的字段保持不变。scope_type / scope_ids / recurrence 三者按最终组合校验。 recurrence_until 三态:省略=不变,null=清除(永久),时间=设置。","properties":{"advance_notice_minutes":{"description":"提前预告分钟数(0..10080,§8 ②b);省略=不变。","maximum":10080,"minimum":0,"type":"integer"},"ends_at":{"format":"date-time","type":"string"},"recurrence":{"enum":["none","daily","weekly","monthly"],"type":"string"},"recurrence_until":{"description":"三态 — 省略=不变,null=清除(永久重复),时间=设置。","format":"date-time","nullable":true,"type":"string"},"scope_ids":{"items":{"type":"string"},"type":"array"},"scope_type":{"enum":["monitor","group","tag","all"],"type":"string"},"starts_at":{"format":"date-time","type":"string"},"title":{"maxLength":200,"nullable":true,"type":"string"}},"type":"object"},"UpdateMonitorGroupRequest":{"description":"局部更新;省略的字段保持不变。","properties":{"name":{"maxLength":200,"type":"string"},"sort_order":{"type":"integer"}},"type":"object"},"UpdateMonitorRequest":{"allOf":[{"$ref":"#/components/schemas/CreateMonitorRequest"}]},"UploadCommitResponse":{"properties":{"content_type":{"type":"string"},"etag":{"type":"string"},"object_id":{"type":"string"},"size_bytes":{"description":"HeadObject 实测字节数。","format":"int64","type":"integer"},"status":{"enum":["committed"],"type":"string"}},"required":["object_id","status","size_bytes","content_type"],"type":"object"},"UploadInitRequest":{"properties":{"content_type":{"description":"媒体类型,须在该 purpose 的白名单内(如 image/png、application/pdf)。","example":"image/png","type":"string"},"filename":{"description":"建议性文件名(日志/未来 content-disposition);不影响服务端选 key。","type":"string"},"purpose":{"description":"上传用途。PR1 仅 user_upload(系统用途 verdict_report/agent_release 不经此端点)。","enum":["user_upload"],"type":"string"},"size":{"description":"客户端声明字节数,仅用于 init 早拒;commit 以 HeadObject 实测为准。","example":1024,"format":"int64","type":"integer"}},"required":["content_type","size","purpose"],"type":"object"},"UploadInitResponse":{"properties":{"expires_at":{"format":"date-time","type":"string"},"headers":{"additionalProperties":{"type":"string"},"description":"浏览器 fetch(PUT) 须发送的 header。x-oss-forbid-overwrite: true 已签名(缺失→SignatureDoesNotMatch, 二次 PUT 同 key→409 FileAlreadyExists 写一次;阿里云 OSS 原生,S3 If-None-Match 在 OSS 上 NotImplemented); Content-Type 未签名但应回传以便 OSS 存正确类型。\n","type":"object"},"method":{"example":"PUT","type":"string"},"object_id":{"description":"storage_object id;commit 时回传。","type":"string"},"upload_strategy":{"enum":["presigned_put"],"type":"string"},"url":{"description":"短时 presigned PUT URL。","type":"string"}},"required":["object_id","upload_strategy","method","url","headers","expires_at"],"type":"object"},"UsageResponse":{"allOf":[{"$ref":"#/components/schemas/Envelope"},{"properties":{"data":{"description":"`api_calls` 与 `mcp_units` 是统一套餐配额下的两个独立计量分项\n(各自有 quota/used/remaining),同属一套套餐权益,非独立计费池。\n","properties":{"api_calls":{"properties":{"quota":{"type":"integer"},"remaining":{"type":"integer"},"used":{"type":"integer"}},"type":"object"},"mcp_units":{"properties":{"quota":{"type":"integer"},"remaining":{"type":"integer"},"used":{"type":"integer"}},"type":"object"},"monitor_checks_count":{"type":"integer"},"monitors_count":{"type":"integer"},"period":{"example":"2026-05","type":"string"}},"type":"object"}},"type":"object"}]},"User":{"properties":{"created_at":{"format":"date-time","type":"string"},"email":{"format":"email","type":"string"},"id":{"example":"u_aBcDeFg","type":"string"},"plan":{"enum":["free","pro","team","business","compliance_starter","compliance_pro","compliance_enterprise"],"type":"string"},"username":{"type":"string"}},"type":"object"},"UserResponse":{"allOf":[{"$ref":"#/components/schemas/Envelope"},{"properties":{"data":{"$ref":"#/components/schemas/User"}},"type":"object"}]},"VerdictOrder":{"properties":{"created_at":{"format":"date-time","type":"string"},"delivered_at":{"format":"date-time","nullable":true,"type":"string"},"ext_order_id":{"type":"string"},"failed_at":{"format":"date-time","nullable":true,"type":"string"},"id":{"description":"订单 ID(v_ 前缀)","example":"v_abc123","type":"string"},"owner_id":{"type":"string"},"paid_at":{"format":"date-time","nullable":true,"type":"string"},"price_cny":{"example":299,"type":"number"},"price_paid_cny":{"description":"实收(支付通道扣费后)","type":"number"},"refund_apology_sent_at":{"description":"D5 道歉邮箱发送时间(无论 refund 是否成功,30min 内必发)","format":"date-time","nullable":true,"type":"string"},"refund_attempt_count":{"description":"D5 refund retry queue 累计次数(0-3+)","type":"integer"},"refund_reason":{"nullable":true,"type":"string"},"refunded_at":{"format":"date-time","nullable":true,"type":"string"},"report_id":{"description":"已生成报告 ID(vr_ 前缀);status=delivered 时透出,其余状态为 null。\n前端凭此从订单详情跳转 / 拉取报告(GET /v1/verdict/reports/{id})。\n","example":"vr_xyz","nullable":true,"type":"string"},"status":{"description":"订单状态机(D4 + D5)。§P 轻量化:Verdict 现免费(定价 0,走免费路径),\n收费 / 退款相关状态(paid/refunded/refund_failed)与代码保留不删,future 可调价重启:\n- `pending` 待支付(免费路径下直接进 generating)\n- `paid` 已支付(收费重启后由聚合支付 webhook 确认;免费下不经过)\n- `generating` 报告生成中(WAL 走 attestation_record)\n- `delivered` 报告已交付(所有 step 成功:localfile 签名 + OSS 归档;§P 无 self_verify 门)\n- `failed` 生成失败(任一 step DLQ;§P best-effort 自动重试 + 站内/邮件告知,无 P0)\n- `refunded` 已退款(收费重启后 D5 自动 retry 或人工;§P 免费下不触发)\n- **`refund_failed`** — D5 兜底失败状态(收费重启后才可能进入);§P 免费下不触发。\n","enum":["pending","paid","generating","delivered","failed","refunded","refund_failed"],"type":"string"},"target":{"type":"string"},"template":{"$ref":"#/components/schemas/VerdictTemplate"},"time_window_end":{"format":"date-time","type":"string"},"time_window_start":{"format":"date-time","type":"string"}},"type":"object"},"VerdictQuoteRequest":{"properties":{"regions":{"description":"限定参与节点的地理范围(可选)","items":{"type":"string"},"type":"array"},"target":{"description":"domain / url / ip","example":"example.com","type":"string"},"template":{"$ref":"#/components/schemas/VerdictTemplate"},"time_window_end":{"format":"date-time","type":"string"},"time_window_start":{"format":"date-time","type":"string"}},"required":["template","target","time_window_start","time_window_end"],"type":"object"},"VerdictQuoteResponse":{"allOf":[{"$ref":"#/components/schemas/Envelope"},{"properties":{"data":{"properties":{"available_nodes_count":{"description":"时间窗内有数据的节点数;\u003c 3 时 eligible=false","type":"integer"},"data_coverage_pct":{"description":"时间窗内数据覆盖率(0-100);\u003c 50% 时 eligible=false","type":"number"},"eligible":{"description":"是否可生成(若 false,见 reason)","type":"boolean"},"legal_disclaimer":{"description":"法律边界声明文案(产品 UI 必须展示)","example":"本报告为 idcd.com 提供的一手观测数据,不构成司法鉴定结论。","type":"string"},"price_cny":{"example":299,"type":"number"},"reason":{"description":"不可生成原因(eligible=true 时为 ok)","enum":["ok","data_insufficient","target_in_denylist","nodes_lt_3","target_high_risk","target_unresolvable"],"type":"string"},"template":{"$ref":"#/components/schemas/VerdictTemplate"}},"required":["eligible","price_cny"],"type":"object"}},"type":"object"}]},"VerdictReport":{"allOf":[{"$ref":"#/components/schemas/Envelope"},{"properties":{"data":{"properties":{"archived_url":{"description":"§P:普通 OSS 归档地址(无 WORM / ObjectLock)。同 pdf_url 经 objurl 改写为\n`https://oss.idcd.com/\u003ckey\u003e` 对外下载。\n","format":"uri","type":"string"},"blockchain_anchor":{"description":"§P 废弃(D-V3-05);字段保留但不填充","nullable":true,"properties":{"chain":{"enum":["polygon","ethereum","arweave"],"type":"string"},"tx_hash":{"type":"string"}},"type":"object"},"confidence_label":{"enum":["high","medium","low"],"type":"string"},"content_hash":{"description":"SHA-256 of PDF bytes","example":"sha256:abc123...","type":"string"},"created_at":{"format":"date-time","type":"string"},"id":{"example":"vr_xyz","type":"string"},"llm_model":{"nullable":true,"type":"string"},"llm_prompt_version":{"nullable":true,"type":"string"},"llm_used":{"type":"boolean"},"node_consistency_pct":{"description":"多节点一致性百分比","maximum":100,"minimum":0,"type":"number"},"nodes_used":{"description":"报告引用的节点 ID 列表","items":{"type":"string"},"type":"array"},"order_id":{"example":"v_abc123","type":"string"},"pdf_size_bytes":{"type":"integer"},"pdf_url":{"description":"§P:公开下载 URL `https://oss.idcd.com/\u003ckey\u003e`(普通 OSS,长期可下载,\n非预签名无过期)。DB 存内部 `s3://idcd/\u003ckey\u003e`,API 出口经\n`objurl.PublicURL` + config `oss_public_base_url` 改写。\n","format":"uri","type":"string"},"report_type":{"default":"observation_only","description":"D-Concern1 锁定:默认 `observation_only`,明确告知\"一手观测数据 + 第三方背书,\n不构成司法鉴定结论\"。保留枚举供司法鉴定所合作通道升级。\n","enum":["observation_only"],"type":"string"},"self_verify_at":{"description":"§P 字段保留但不填充","format":"date-time","nullable":true,"type":"string"},"self_verify_status":{"description":"§P 废弃(D-V3-06):独立 Self-Verify Worker(`apps/attest-verify`)已删除。\n字段保留但不填充;交付不再以 self_verify 为门(所有 step 成功即 delivered)。\n","enum":["pass","fail","pending"],"type":"string"},"signature_key_id":{"description":"§P:localfile RSA key id","type":"string"},"signature_key_version":{"type":"integer"},"tsa_provider":{"description":"§P 字段保留但不填充(无 RFC3161 TSA,改服务器时间)","enum":["digicert","globalsign","ntsc"],"type":"string"},"tsa_time":{"description":"§P:服务器时间(非 RFC3161)","format":"date-time","type":"string"}},"type":"object"}},"type":"object"}]},"VerdictTemplate":{"description":"Verdict 场景模板(K5 锁定):\n- `sla` ¥299 — SLA 索赔证据(企业用户 vs CDN/云厂商)\n- `incident` ¥199 — 故障取证\n- `compliance` ¥499 — 合规自证(等保/审计)\n- `legal` ¥999 — 争议取证(法务高保真)\n","enum":["sla","incident","compliance","legal"],"type":"string"},"WebhookEndpoint":{"properties":{"active":{"type":"boolean"},"created_at":{"format":"date-time","type":"string"},"events":{"items":{"type":"string"},"type":"array"},"id":{"example":"we_xyz","type":"string"},"url":{"format":"uri","type":"string"}},"type":"object"},"WebhookEndpointListResponse":{"allOf":[{"$ref":"#/components/schemas/Envelope"},{"properties":{"data":{"items":{"$ref":"#/components/schemas/WebhookEndpoint"},"type":"array"}},"type":"object"}]},"WebhookEventPayload":{"properties":{"created_at":{"format":"date-time","type":"string"},"data":{"additionalProperties":true,"type":"object"},"id":{"example":"evt_xyz","type":"string"},"metadata":{"properties":{"api_version":{"example":"v1","type":"string"},"attempt":{"type":"integer"},"delivery_id":{"type":"string"}},"type":"object"},"type":{"description":"事件类型(完整列表详 16-api-spec.md §6):\nmonitor.down / monitor.up / monitor.degraded / monitor.created / monitor.updated /\nmonitor.deleted / monitor.paused /\nalert.triggered / alert.acknowledged / alert.resolved /\nincident.created / incident.updated / incident.resolved /\nmaintenance.scheduled / maintenance.started / maintenance.ended /\nprobe.completed / probe.failed /\nssl.expiring / domain.expiring / icp.changed /\nsubscription.created / subscription.updated / subscription.canceled /\nsubscription.renewed / subscription.payment_failed /\ninvoice.issued /\napi_key.created / api_key.revoked / api_key.leaked_detected /\nteam.member_added / team.member_removed /\nreport.ready / usage.threshold_reached /\nverdict.order_paid / verdict.report_ready / verdict.report_failed /\nverdict.refund_initiated / verdict.refund_failed /\nmcp.token_revoked / mcp.usage_threshold_reached\n","example":"monitor.down","type":"string"}},"required":["id","type","created_at","data"],"type":"object"},"WhoisResponse":{"allOf":[{"$ref":"#/components/schemas/Envelope"},{"properties":{"data":{"properties":{"created_at":{"format":"date-time","type":"string"},"domain":{"type":"string"},"expires_at":{"format":"date-time","type":"string"},"name_servers":{"items":{"type":"string"},"type":"array"},"raw":{"type":"string"},"registrar":{"type":"string"},"status":{"items":{"type":"string"},"type":"array"}},"type":"object"}},"type":"object"}]}},"securitySchemes":{"ApiKeyHeader":{"description":"Core REST API 鉴权 — `X-API-Key: sk_live_xxx`。\n与 BearerAuth 二选一(同一 key)。详 03 §5。\n**MCP token 不能在此使用**:MCP token 走 `mcp.idcd.com` JSON-RPC,详 §MCP Tokens tag。\n","in":"header","name":"X-API-Key","type":"apiKey"},"BearerAuth":{"bearerFormat":"sk_live_xxx","description":"Core REST API 鉴权 — `Authorization: Bearer sk_live_xxx`。\n与 ApiKeyHeader 二选一(同一 key)。\n","scheme":"bearer","type":"http"},"IdcdWebhookSignature":{"description":"idcd → 用户 webhook 出站签名(`t=\u003cunix_ts\u003e,v1=\u003chmac_sha256_hex\u003e`)。\n用户端验签:`hmac_sha256(secret, \"\u003ct\u003e.\u003craw_body\u003e\")`;5 分钟新鲜度窗口。\n详 16-api-spec.md §10。\n","in":"header","name":"X-IDCD-Signature","type":"apiKey"},"PaymentHubWebhookSignature":{"description":"聚合支付 webhook 签名(聚合支付服务商 → idcd 服务端,**反向接收**)。\n校验算法见 packages/payment-go-sdk;本规范不暴露 webhook 接收端 path。\n","in":"header","name":"X-Webhook-Signature","type":"apiKey"}}},"info":{"contact":{"email":"api@idcd.com","name":"idcd.com API support","url":"https://idcd.com/support"},"description":"# idcd.com v2 公共 API 规范\n\n## 三栈架构(v2 K1 锁定)\n\n| 子域 | 协议 | 用途 |\n|---|---|---|\n| `api-prod.idcd.com` | HTTPS REST(本规范主体)| Core 拨测 / 监控 / 告警 / 账户 / 计费 |\n| `attest.idcd.com` | HTTPS REST(本规范 §Verdict/Attest)| Evidence-as-a-Service:Verdict 报告 / 公开验签 / 申诉 |\n| `mcp.idcd.com` | JSON-RPC over stdio + HTTP+SSE(**非 OpenAPI**)| MCP server 给 AI Agent;详 §MCP Protocol 附录 |\n\n三栈独立计量 / 独立 SLA / 独立 PRD 模块(详 OVERVIEW §5.2)。\n\n## 锁定决策反映(v2)\n\n\u003e ⚠️ **DECISIONS §P(2026-06-03)Verdict 轻量化**:Verdict = 免费轻量自签证明。签名改\n\u003e 服务端本地 RSA(`localfile`,无 KMS/Shamir),时间戳改服务器时间(无 RFC3161 TSA),\n\u003e 归档改普通 OSS(无 WORM),删独立 Self-Verify Worker(`apps/attest-verify`),SLA best-effort\n\u003e 无 P0,现阶段免费(收费/退款代码保留)。报告 PDF 经 `oss.idcd.com` 公开下载(#96)。\n\u003e 下方 D5/D6 及 schema 中的 tsa_*/self_verify/blockchain/KMS 字段保留但 §P 下不填充。\n\n- **D21**:所有 MCP token 必有过期日,最长 90 天 auto_renewal,无永久 token;MCP units 是统一套餐配额下的一个计量分项(非独立计费池)\n- **D4**:Verdict 生成走 WAL 状态机;attestation_record UNIQUE(report_id, action)\n- **D5**:Verdict 失败 retry queue + 道歉邮箱 + `refund_failed`(§P 收费重启后才生效;免费下不触发,代码保留)\n- ~~**D6**:Self-verify 独立进程 / VPC subnet / KMS 客户端~~(§P 废弃:`apps/attest-verify` 已删)\n- **D-Concern1**:`/v1/attest/verify` 返回必含 `report_type=observation_only` + `legal_disclaimer`\n\n## 鉴权速查\n\n- **API Key**:`X-API-Key: sk_live_xxx`(详 §components.securitySchemes.ApiKeyHeader)\n- **Bearer**:`Authorization: Bearer sk_live_xxx`(同 API Key,可二选一)\n- **MCP token**:走 `mcp.idcd.com`,**不是** API Key 体系(详 §Auth/MCP Tokens)\n- **Webhook receiver 签名**:`X-IDCD-Signature: t=\u003cts\u003e,v1=\u003chmac\u003e`\n\n## 错误响应统一格式\n\n详 §components.schemas.Error —— 其 `error.code` 字段的 `enum` 即完整错误码清单\n(UPPER_SNAKE_CASE,SSOT = `backend/lib/shared/errcode/codes.go`)。\n\n## SDK 生成\n\n本 yaml 是 SDK 自动生成 source of truth;CI 通过 OpenAPI Generator + 自家模板生成\nJS / Go / Python SDK,人工 review 后发布。\n","license":{"name":"Proprietary","url":"https://idcd.com/legal/terms"},"summary":"idcd.com 网络可观测平台 v2 三栈 API:Core(api-prod.idcd.com)/ Evidence(attest.idcd.com)/\nMCP server(mcp.idcd.com,JSON-RPC,见附录)。本规范是 OpenAPI 3.1 source of truth,\n用于 SDK 自动生成、Mintlify 文档站、契约测试。\n","termsOfService":"https://idcd.com/legal/terms","title":"idcd.com Public API (v2)","version":"2.0.0"},"openapi":"3.1.0","paths":{"/badge/hb/{public_id}.svg":{"get":{"operationId":"heartbeatBadge","responses":{"200":{"content":{"image/svg+xml":{"schema":{"type":"string"}}},"description":"SVG 徽章(up/down/grace/paused/unknown);Cache-Control 短公共缓存"}},"security":[],"summary":"心跳状态徽章(SVG)","tags":["Monitors"]},"parameters":[{"in":"path","name":"public_id","required":true,"schema":{"example":"hbp_V1StGXR8_Z5jdHi6BmyT9","type":"string"}}],"servers":[{"description":"徽章端点在 API 根路径(不含 /v1)","url":"https://api-prod.idcd.com"}]},"/heartbeat/{token}":{"get":{"operationId":"heartbeatPing","responses":{"200":{"content":{"application/json":{"schema":{"properties":{"ok":{"example":true,"type":"boolean"}},"type":"object"}}},"description":"打卡成功(限速丢弃时同样返回,body 恒 {\"ok\":true})"},"404":{"description":"token 不存在或已轮换(body 恒 {\"ok\":false},不区分两者)"}},"security":[],"summary":"心跳打卡(成功)","tags":["Monitors"]},"head":{"operationId":"heartbeatPingHead","responses":{"200":{"description":"打卡成功(无 body)"},"404":{"description":"token 不存在或已轮换"}},"security":[],"summary":"心跳打卡(HEAD — 只刷新 last_ping_at/state,不写打卡流水)","tags":["Monitors"]},"parameters":[{"in":"path","name":"token","required":true,"schema":{"example":"hb_V1StGXR8_Z5jdHi6BmyT9","type":"string"}}],"post":{"operationId":"heartbeatPingPost","responses":{"200":{"description":"同 GET"},"404":{"description":"同 GET"}},"security":[],"summary":"心跳打卡(成功,POST 变体)","tags":["Monitors"]},"servers":[{"description":"打卡端点在 API 根路径(不含 /v1);路径形态保证未来可平迁独立子域","url":"https://api-prod.idcd.com"}]},"/heartbeat/{token}/fail":{"parameters":[{"in":"path","name":"token","required":true,"schema":{"type":"string"}}],"post":{"operationId":"heartbeatFail","responses":{"200":{"content":{"application/json":{"schema":{"properties":{"ok":{"example":true,"type":"boolean"}},"type":"object"}}},"description":"上报成功({\"ok\":true};error=reported_fail 计入打卡流水)"},"404":{"description":"token 不存在或已轮换"}},"security":[],"summary":"心跳主动失败上报(任务自报失败,任意状态直接判 down 并告警)","tags":["Monitors"]},"servers":[{"description":"同上,根路径匿名端点","url":"https://api-prod.idcd.com"}]},"/heartbeat/{token}/start":{"parameters":[{"in":"path","name":"token","required":true,"schema":{"type":"string"}}],"post":{"operationId":"heartbeatStart","responses":{"200":{"content":{"application/json":{"schema":{"properties":{"ok":{"example":true,"type":"boolean"}},"type":"object"}}},"description":"记录成功({\"ok\":true};不写打卡流水、不改状态、不计 ping_count)"},"404":{"description":"token 不存在或已轮换"}},"security":[],"summary":"任务开始打点(v1.1:记录 last_start_at,完成时算运行时长;配了 max_duration_s 则收紧判定截止以便挂死任务提前判 down)","tags":["Monitors"]},"servers":[{"description":"同上,根路径匿名端点","url":"https://api-prod.idcd.com"}]},"/v1/account":{"delete":{"operationId":"deleteAccount","requestBody":{"content":{"application/json":{"schema":{"properties":{"confirm":{"description":"必须字面量 \"DELETE\"","enum":["DELETE"],"type":"string"},"current_password":{"description":"有密码用户必填","format":"password","type":"string"}},"required":["confirm"],"type":"object"}}},"required":true},"responses":{"200":{"$ref":"#/components/responses/MessageOK"},"400":{"$ref":"#/components/responses/BadRequest"}},"summary":"删除账户(30 天软删除)","tags":["Account"]}},"/v1/account/2fa/disable":{"post":{"operationId":"twoFactorDisable","requestBody":{"content":{"application/json":{"schema":{"properties":{"code":{"type":"string"}},"required":["code"],"type":"object"}}},"required":true},"responses":{"200":{"$ref":"#/components/responses/MessageOK"},"401":{"$ref":"#/components/responses/Unauthorized"}},"summary":"禁用 2FA","tags":["Account"]}},"/v1/account/2fa/setup":{"post":{"operationId":"twoFactorSetup","responses":{"200":{"content":{"application/json":{"schema":{"properties":{"data":{"properties":{"otpauth_url":{"type":"string"},"secret":{"type":"string"}},"type":"object"},"request_id":{"type":"string"}},"type":"object"}}},"description":"TOTP secret"}},"summary":"2FA(TOTP)设置 - 返回 secret + otpauth url","tags":["Account"]}},"/v1/account/2fa/status":{"get":{"operationId":"twoFactorStatus","responses":{"200":{"content":{"application/json":{"schema":{"properties":{"data":{"properties":{"enabled":{"type":"boolean"}},"type":"object"},"request_id":{"type":"string"}},"type":"object"}}},"description":"2FA 是否启用"}},"summary":"读取 2FA 状态","tags":["Account"]}},"/v1/account/2fa/verify":{"post":{"operationId":"twoFactorVerify","requestBody":{"content":{"application/json":{"schema":{"properties":{"code":{"description":"6 位 TOTP","type":"string"}},"required":["code"],"type":"object"}}},"required":true},"responses":{"200":{"content":{"application/json":{"schema":{"properties":{"data":{"properties":{"backup_codes":{"items":{"type":"string"},"type":"array"}},"type":"object"},"request_id":{"type":"string"}},"type":"object"}}},"description":"启用成功 + 备份码"},"401":{"$ref":"#/components/responses/Unauthorized"}},"summary":"2FA 验证并启用 - 返回备份码","tags":["Account"]}},"/v1/account/api-keys":{"get":{"operationId":"listApiKeys","parameters":[{"$ref":"#/components/parameters/Page"},{"$ref":"#/components/parameters/PageSize"}],"responses":{"200":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiKeyListResponse"}}},"description":"API Key 列表(secret 不返回,只返回展示前缀)"}},"summary":"列出 API Key","tags":["API Keys"]},"post":{"operationId":"createApiKey","requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/CreateApiKeyRequest"}}},"required":true},"responses":{"201":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/CreateApiKeyResponse"}}},"description":"创建成功(secret 仅返回一次,务必保存)"},"400":{"$ref":"#/components/responses/BadRequest"},"409":{"$ref":"#/components/responses/Conflict"},"429":{"$ref":"#/components/responses/RateLimited"}},"summary":"创建 API Key","tags":["API Keys"]}},"/v1/account/api-keys/{id}":{"delete":{"operationId":"revokeApiKey","responses":{"200":{"$ref":"#/components/responses/MessageOK"},"404":{"$ref":"#/components/responses/NotFound"}},"summary":"撤销 API Key","tags":["API Keys"]},"parameters":[{"$ref":"#/components/parameters/ResourceId"}]},"/v1/account/avatar":{"post":{"operationId":"uploadAvatar","requestBody":{"content":{"multipart/form-data":{"schema":{"properties":{"avatar":{"description":"图片文件 image/{jpeg,png,gif,webp}","format":"binary","type":"string"}},"required":["avatar"],"type":"object"}}},"required":true},"responses":{"200":{"content":{"application/json":{"schema":{"properties":{"data":{"properties":{"avatar_url":{"type":"string"}},"type":"object"},"request_id":{"type":"string"}},"type":"object"}}},"description":"头像已更新"},"400":{"$ref":"#/components/responses/BadRequest"}},"summary":"上传头像","tags":["Account"]}},"/v1/account/email/change-request":{"post":{"operationId":"requestEmailChange","requestBody":{"content":{"application/json":{"schema":{"properties":{"new_email":{"format":"email","type":"string"}},"required":["new_email"],"type":"object"}}},"required":true},"responses":{"200":{"$ref":"#/components/responses/MessageOK"},"400":{"$ref":"#/components/responses/BadRequest"},"429":{"$ref":"#/components/responses/RateLimited"}},"summary":"申请更换邮箱(向新邮箱发验证码)","tags":["Account"]}},"/v1/account/email/verify":{"post":{"operationId":"verifyEmailChange","requestBody":{"content":{"application/json":{"schema":{"properties":{"code":{"type":"string"},"otp_id":{"type":"string"}},"required":["code","otp_id"],"type":"object"}}},"required":true},"responses":{"200":{"$ref":"#/components/responses/MessageOK"},"400":{"$ref":"#/components/responses/BadRequest"}},"summary":"验证新邮箱(确认更换)","tags":["Account"]}},"/v1/account/export":{"get":{"operationId":"exportAccount","responses":{"200":{"content":{"application/json":{"schema":{"properties":{"data":{"properties":{"api_keys":{"items":{"additionalProperties":true,"type":"object"},"type":"array"},"generated_at":{"format":"date-time","type":"string"},"invoices":{"items":{"additionalProperties":true,"type":"object"},"type":"array"},"monitors":{"items":{"additionalProperties":true,"type":"object"},"type":"array"},"schema_version":{"type":"integer"},"sessions":{"items":{"additionalProperties":true,"type":"object"},"type":"array"},"subscription":{"additionalProperties":true,"nullable":true,"type":"object"},"user":{"additionalProperties":true,"type":"object"}},"type":"object"},"request_id":{"type":"string"}},"type":"object"}}},"description":"完整账户数据导出"},"429":{"$ref":"#/components/responses/RateLimited"}},"summary":"导出账户数据(GDPR / 限速 5 次/小时)","tags":["Account"]}},"/v1/account/notification-preferences":{"get":{"operationId":"getNotificationPreferences","responses":{"200":{"content":{"application/json":{"schema":{"properties":{"data":{"additionalProperties":true,"type":"object"},"request_id":{"type":"string"}},"type":"object"}}},"description":"通知偏好(按通知类型分渠道)"},"401":{"$ref":"#/components/responses/Unauthorized"}},"summary":"读取通知偏好","tags":["Account"]},"put":{"operationId":"updateNotificationPreferences","requestBody":{"content":{"application/json":{"schema":{"additionalProperties":true,"type":"object"}}},"required":true},"responses":{"200":{"content":{"application/json":{"schema":{"properties":{"data":{"additionalProperties":true,"type":"object"},"request_id":{"type":"string"}},"type":"object"}}},"description":"更新后的通知偏好"}},"summary":"更新通知偏好","tags":["Account"]}},"/v1/account/passkeys":{"get":{"operationId":"listPasskeys","responses":{"200":{"content":{"application/json":{"schema":{"properties":{"data":{"properties":{"passkeys":{"items":{"properties":{"created_at":{"format":"date-time","type":"string"},"device_name":{"type":"string"},"id":{"type":"string"},"last_used_at":{"format":"date-time","nullable":true,"type":"string"}},"type":"object"},"type":"array"}},"type":"object"},"request_id":{"type":"string"}},"type":"object"}}},"description":"passkey 列表"}},"summary":"列出 passkey","tags":["Account"]}},"/v1/account/passkeys/register/begin":{"post":{"operationId":"passkeyRegisterBegin","responses":{"200":{"content":{"application/json":{"schema":{"properties":{"data":{"properties":{"challenge_id":{"type":"string"},"options":{"additionalProperties":true,"type":"object"}},"type":"object"},"request_id":{"type":"string"}},"type":"object"}}},"description":"WebAuthn 注册 challenge"}},"summary":"passkey 注册 - 开始(返回 WebAuthn options)","tags":["Account"]}},"/v1/account/passkeys/register/complete":{"post":{"operationId":"passkeyRegisterComplete","requestBody":{"content":{"application/json":{"schema":{"properties":{"challenge":{"type":"string"},"device_name":{"type":"string"},"response":{"additionalProperties":true,"type":"object"}},"required":["challenge","response"],"type":"object"}}},"required":true},"responses":{"200":{"content":{"application/json":{"schema":{"properties":{"data":{"properties":{"credential_id":{"type":"string"},"device_name":{"type":"string"}},"type":"object"},"request_id":{"type":"string"}},"type":"object"}}},"description":"注册成功"},"400":{"$ref":"#/components/responses/BadRequest"}},"summary":"passkey 注册 - 完成","tags":["Account"]}},"/v1/account/passkeys/{id}":{"delete":{"operationId":"deletePasskey","responses":{"200":{"$ref":"#/components/responses/MessageOK"},"404":{"$ref":"#/components/responses/NotFound"}},"summary":"删除 passkey","tags":["Account"]},"parameters":[{"$ref":"#/components/parameters/ResourceId"}]},"/v1/account/password":{"patch":{"operationId":"changePassword","requestBody":{"content":{"application/json":{"schema":{"properties":{"current_password":{"format":"password","type":"string"},"new_password":{"format":"password","type":"string"}},"required":["current_password","new_password"],"type":"object"}}},"required":true},"responses":{"200":{"$ref":"#/components/responses/MessageOK"},"400":{"$ref":"#/components/responses/BadRequest"},"401":{"$ref":"#/components/responses/Unauthorized"}},"summary":"修改密码(已有密码用户)","tags":["Account"]}},"/v1/account/password/init":{"post":{"operationId":"initPassword","requestBody":{"content":{"application/json":{"schema":{"properties":{"new_password":{"format":"password","type":"string"}},"required":["new_password"],"type":"object"}}},"required":true},"responses":{"200":{"$ref":"#/components/responses/MessageOK"},"400":{"$ref":"#/components/responses/BadRequest"}},"summary":"设置初始密码(OAuth / Passkey 注册的无密码用户)","tags":["Account"]}},"/v1/account/points":{"get":{"operationId":"getPoints","responses":{"200":{"content":{"application/json":{"schema":{"properties":{"data":{"properties":{"expires_at":{"format":"date-time","nullable":true,"type":"string"},"points":{"type":"integer"}},"type":"object"},"request_id":{"type":"string"}},"type":"object"}}},"description":"积分"}},"summary":"读取积分余额","tags":["Account"]}},"/v1/account/points/redeem":{"post":{"operationId":"redeemPoints","requestBody":{"content":{"application/json":{"schema":{"properties":{"amount":{"type":"integer"}},"required":["amount"],"type":"object"}}},"required":true},"responses":{"200":{"$ref":"#/components/responses/MessageOK"},"400":{"$ref":"#/components/responses/BadRequest"}},"summary":"兑换积分","tags":["Account"]}},"/v1/account/profile":{"get":{"operationId":"getProfile","responses":{"200":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/UserResponse"}}},"description":"当前用户资料(id / email / email_verified / has_password / display_name / avatar_url / bio / locale / timezone / theme / status)"},"401":{"$ref":"#/components/responses/Unauthorized"}},"summary":"当前用户资料","tags":["Account"]},"patch":{"operationId":"updateProfile","requestBody":{"content":{"application/json":{"schema":{"properties":{"bio":{"type":"string"},"display_name":{"type":"string"},"locale":{"example":"zh-CN","type":"string"},"theme":{"enum":["system","light","dark"],"example":"system","type":"string"},"timezone":{"example":"Asia/Shanghai","type":"string"}},"type":"object"}}},"required":true},"responses":{"200":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/UserResponse"}}},"description":"更新后的资料"},"400":{"$ref":"#/components/responses/BadRequest"},"401":{"$ref":"#/components/responses/Unauthorized"}},"summary":"更新用户资料","tags":["Account"]}},"/v1/account/quota":{"get":{"operationId":"getAccountQuota","responses":{"200":{"content":{"application/json":{"schema":{"properties":{"data":{"description":"各资源 used + limit。limit 为三态,与 /v1/plans 目录一致(见后端 wireLimit): -1 = 无限 / 0 = 未解锁(功能锁定,如 free 档状态页) / \u003e0 = 上限。","properties":{"api_calls":{"properties":{"limit":{"description":"三态:-1 无限 / \u003e0 上限(api_daily_reqs 不会为 0)","type":"integer"},"reset_at":{"description":"下次重置 Unix 秒(UTC 次日零点)","format":"int64","type":"integer"},"used":{"type":"integer"}},"type":"object"},"api_calls_trend":{"items":{"properties":{"count":{"type":"integer"},"date":{"format":"date","type":"string"}},"type":"object"},"type":"array"},"channels":{"properties":{"limit":{"description":"三态:-1 无限 / 0 未解锁 / \u003e0 上限","type":"integer"},"used":{"type":"integer"}},"type":"object"},"max_nodes":{"description":"并发节点上限,三态:-1 无限(Business) / \u003e0 上限","type":"integer"},"min_interval_s":{"description":"最小探测间隔(秒","type":"integer","非三态)":null},"monitors":{"properties":{"limit":{"description":"三态:-1 无限 / 0 未解锁 / \u003e0 上限","type":"integer"},"used":{"type":"integer"}},"type":"object"},"plan":{"example":"free","type":"string"},"status_pages":{"properties":{"limit":{"description":"三态:-1 无限 / 0 未解锁(free 档) / \u003e0 上限","type":"integer"},"used":{"type":"integer"}},"type":"object"}},"type":"object"},"request_id":{"type":"string"}},"type":"object"}}},"description":"配额状态(各资源计数 / 上限 / 重置时间)"}},"summary":"读取配额 / 用量状态","tags":["Account"]}},"/v1/account/sessions":{"delete":{"operationId":"revokeAllSessions","responses":{"200":{"content":{"application/json":{"schema":{"properties":{"data":{"properties":{"revoked":{"description":"本次注销的会话数(不含当前会话)","type":"integer"}},"type":"object"},"request_id":{"type":"string"}},"type":"object"}}},"description":"已批量注销"}},"summary":"注销全部其他会话(登出所有其他设备,保留当前会话)","tags":["Account"]},"get":{"operationId":"listSessions","responses":{"200":{"content":{"application/json":{"schema":{"properties":{"data":{"properties":{"sessions":{"items":{"properties":{"created_at":{"format":"date-time","type":"string"},"device":{"nullable":true,"type":"string"},"expires_at":{"format":"date-time","type":"string"},"id":{"type":"string"},"is_current":{"type":"boolean"},"last_seen_at":{"format":"date-time","type":"string"},"user_agent":{"nullable":true,"type":"string"}},"type":"object"},"type":"array"}},"type":"object"},"request_id":{"type":"string"}},"type":"object"}}},"description":"会话列表"}},"summary":"列出登录会话","tags":["Account"]}},"/v1/account/sessions/{session_id}":{"delete":{"operationId":"revokeSession","responses":{"204":{"description":"已注销"},"404":{"$ref":"#/components/responses/NotFound"}},"summary":"注销指定会话(登出其他设备)","tags":["Account"]},"parameters":[{"in":"path","name":"session_id","required":true,"schema":{"type":"string"}}]},"/v1/account/sponsor-profile":{"get":{"operationId":"sponsorProfileMyGet","responses":{"200":{"description":"profile"},"404":{"description":"未设置 sponsor profile"}},"security":[{"BearerAuth":[]}],"summary":"获取当前用户的 sponsor profile(节点提供者展示信息)","tags":["Sponsor"]},"patch":{"operationId":"sponsorProfileMyPatch","requestBody":{"content":{"application/json":{"schema":{"properties":{"description":{"maxLength":80,"type":"string"},"display_name":{"description":"首次创建必填","type":"string"},"link_anchor":{"maxLength":30,"type":"string"},"link_url":{"format":"uri","type":"string"},"logo_url":{"format":"uri","type":"string"}},"type":"object"}}},"required":true},"responses":{"200":{"description":"profile 已保存"},"400":{"description":"校验失败(描述/锚文本超长、首次缺 display_name)"}},"security":[{"BearerAuth":[]}],"summary":"upsert 当前用户的 sponsor profile(首次创建必须含 display_name)","tags":["Sponsor"]}},"/v1/account/tokens":{"get":{"operationId":"listTokens","responses":{"200":{"content":{"application/json":{"schema":{"properties":{"data":{"properties":{"tokens":{"items":{"properties":{"created_at":{"format":"date-time","type":"string"},"expires_at":{"format":"date-time","nullable":true,"type":"string"},"id":{"type":"string"},"last_used_at":{"format":"date-time","nullable":true,"type":"string"},"name":{"type":"string"},"scopes":{"items":{"type":"string"},"type":"array"},"token_prefix":{"type":"string"}},"type":"object"},"type":"array"}},"type":"object"},"request_id":{"type":"string"}},"type":"object"}}},"description":"PAT 列表"}},"summary":"列出个人访问令牌(PAT)","tags":["Account"]},"post":{"operationId":"createToken","requestBody":{"content":{"application/json":{"schema":{"properties":{"expires_days":{"description":"最长 90,超出钳制","type":"integer"},"name":{"type":"string"},"scopes":{"example":["read","write:monitors"],"items":{"type":"string"},"type":"array"}},"required":["name"],"type":"object"}}},"required":true},"responses":{"201":{"content":{"application/json":{"schema":{"properties":{"data":{"properties":{"created_at":{"format":"date-time","type":"string"},"expires_at":{"format":"date-time","nullable":true,"type":"string"},"id":{"type":"string"},"name":{"type":"string"},"scopes":{"items":{"type":"string"},"type":"array"},"token":{"description":"完整 token idcd_pat_*,仅返回一次","type":"string"},"token_prefix":{"type":"string"}},"type":"object"},"request_id":{"type":"string"}},"type":"object"}}},"description":"创建成功(token 仅此一次)"},"400":{"$ref":"#/components/responses/BadRequest"}},"summary":"创建 PAT(secret 仅返回一次,最长 90 天)","tags":["Account"]}},"/v1/account/tokens/{id}":{"delete":{"operationId":"deleteToken","responses":{"204":{"description":"撤销成功(无 body)"},"404":{"$ref":"#/components/responses/NotFound"}},"summary":"撤销 PAT","tags":["Account"]},"parameters":[{"$ref":"#/components/parameters/ResourceId"}]},"/v1/account/usage-records":{"get":{"description":"从 usage_records 读 P3 消费分项视图:窗口内每个资源的累计量 + 成本(分)。\n低频消费(报告/包)逐条写入,高频(API/MCP)异步聚合落表,这里只读。\n","operationId":"accountUsageRecords","parameters":[{"description":"回看天数;\u003c=0 或 \u003e365 回退 30","in":"query","name":"days","schema":{"default":30,"maximum":365,"minimum":1,"type":"integer"}}],"responses":{"200":{"content":{"application/json":{"schema":{"properties":{"items":{"items":{"properties":{"resource_key":{"type":"string"},"total_amount":{"format":"int64","type":"integer"},"total_cost_cents":{"format":"int64","type":"integer"}},"type":"object"},"type":"array"},"window_days":{"type":"integer"}},"type":"object"}}},"description":"分项用量"}},"security":[{"BearerAuth":[]}],"summary":"当前用户分项用量(滚动窗口,按 resource_key 聚合 + 成本)","tags":["Billing"]}},"/v1/affiliate/event":{"post":{"description":"拨测结果页测出\"慢/不可达\"时展示 CDN/主机联盟 CTA,本端点记录其\nimpression / click,作为 M3 go/no-go 的首方数据源。公开匿名 + 无 PII\n(仅 report_id / offer_id / type),per-IP 限流防刷。成功返回 204。\n","operationId":"recordAffiliateEvent","requestBody":{"content":{"application/json":{"schema":{"properties":{"offer_id":{"description":"联盟 offer 注册表中的 offerId","maxLength":64,"type":"string"},"report_id":{"description":"触发 CTA 的拨测报告 id(= subID,可归因)","maxLength":128,"type":"string"},"type":{"enum":["impression","click"],"type":"string"}},"required":["report_id","offer_id","type"],"type":"object"}}},"required":true},"responses":{"204":{"description":"事件已记录(无响应体)"},"400":{"$ref":"#/components/responses/BadRequest"},"429":{"$ref":"#/components/responses/RateLimited"}},"summary":"记录联盟 CTA 曝光/点击事件","tags":["Affiliate"]}},"/v1/alert-channels":{"get":{"operationId":"listAlertChannels","responses":{"200":{"content":{"application/json":{"schema":{"properties":{"data":{"properties":{"items":{"items":{"$ref":"#/components/schemas/AlertChannel"},"type":"array"}},"type":"object"},"request_id":{"type":"string"}},"type":"object"}}},"description":"渠道列表"}},"summary":"列出通知渠道","tags":["Alerting"]},"post":{"operationId":"createAlertChannel","requestBody":{"content":{"application/json":{"schema":{"properties":{"config":{"additionalProperties":true,"type":"object"},"name":{"type":"string"},"type":{"enum":["email","webhook","wecom","dingtalk","feishu","telegram","slack","wechat"],"type":"string"}},"required":["name","type"],"type":"object"}}},"required":true},"responses":{"201":{"content":{"application/json":{"schema":{"properties":{"data":{"$ref":"#/components/schemas/AlertChannel"},"request_id":{"type":"string"}},"type":"object"}}},"description":"已创建"},"400":{"$ref":"#/components/responses/BadRequest"}},"summary":"创建通知渠道","tags":["Alerting"]}},"/v1/alert-channels/{id}":{"delete":{"operationId":"deleteAlertChannel","responses":{"204":{"description":"已删除"},"404":{"$ref":"#/components/responses/NotFound"}},"summary":"删除通知渠道","tags":["Alerting"]},"parameters":[{"$ref":"#/components/parameters/ResourceId"}],"put":{"description":"改名和/或替换投递配置。type 不可变更。修改 config 会把 verified 重置为 false(新地址未验证，绿色「已验证」徽章不得撒谎)；仅改名保留 verified。 微信通道的 config 由系统按绑定的微信自动生成，不支持手动编辑。","operationId":"updateAlertChannel","requestBody":{"content":{"application/json":{"schema":{"properties":{"config":{"additionalProperties":true,"type":"object"},"name":{"type":"string"}},"type":"object"}}},"required":true},"responses":{"200":{"content":{"application/json":{"schema":{"properties":{"data":{"$ref":"#/components/schemas/AlertChannel"},"request_id":{"type":"string"}},"type":"object"}}},"description":"已更新"},"400":{"$ref":"#/components/responses/BadRequest"},"404":{"$ref":"#/components/responses/NotFound"}},"summary":"编辑通知渠道(改名 / 替换配置)","tags":["Alerting"]}},"/v1/alert-channels/{id}/notifications":{"get":{"operationId":"listChannelNotifications","parameters":[{"in":"query","name":"limit","schema":{"default":20,"maximum":100,"type":"integer"}},{"in":"query","name":"offset","schema":{"default":0,"type":"integer"}}],"responses":{"200":{"content":{"application/json":{"schema":{"properties":{"data":{"properties":{"notifications":{"items":{"properties":{"alert_event_id":{"type":"string"},"channel_id":{"type":"string"},"created_at":{"format":"date-time","type":"string"},"error":{"nullable":true,"type":"string"},"id":{"type":"string"},"sent_at":{"format":"date-time","nullable":true,"type":"string"},"status":{"type":"string"}},"type":"object"},"type":"array"},"total":{"type":"integer"}},"type":"object"},"request_id":{"type":"string"}},"type":"object"}}},"description":"通知历史"}},"summary":"渠道通知投递历史","tags":["Alerting"]},"parameters":[{"$ref":"#/components/parameters/ResourceId"}]},"/v1/alert-channels/{id}/test":{"parameters":[{"$ref":"#/components/parameters/ResourceId"}],"post":{"operationId":"testAlertChannel","responses":{"200":{"content":{"application/json":{"schema":{"properties":{"data":{"properties":{"success":{"type":"boolean"}},"type":"object"},"request_id":{"type":"string"}},"type":"object"}}},"description":"测试结果"}},"summary":"测试通知渠道(成功后标记 verified)","tags":["Alerting"]}},"/v1/alert-events":{"get":{"operationId":"listAlertEvents","parameters":[{"$ref":"#/components/parameters/Page"},{"$ref":"#/components/parameters/PageSize"},{"in":"query","name":"state","schema":{"enum":["open","ack","resolved"],"type":"string"}},{"description":"按监控过滤。","in":"query","name":"monitor_id","schema":{"type":"string"}},{"description":"page_size 的向后兼容别名(旧调用方);优先级低于 page_size。","in":"query","name":"limit","schema":{"maximum":200,"minimum":1,"type":"integer"}}],"responses":{"200":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/AlertEventListResponse"}}},"description":"告警事件列表"}},"summary":"列出告警事件","tags":["Alerting"]}},"/v1/alert-events/{id}/ack":{"parameters":[{"$ref":"#/components/parameters/ResourceId"}],"post":{"operationId":"ackAlertEvent","responses":{"200":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/AlertEvent"}}},"description":"Ack 成功"}},"summary":"Ack 告警","tags":["Alerting"]}},"/v1/alert-groups":{"get":{"operationId":"listAlertGroups","responses":{"200":{"content":{"application/json":{"schema":{"properties":{"data":{"properties":{"items":{"items":{"$ref":"#/components/schemas/AlertGroup"},"type":"array"}},"type":"object"},"request_id":{"type":"string"}},"type":"object"}}},"description":"分组列表"}},"summary":"列出告警分组(聚合)规则","tags":["Alerting"]},"post":{"operationId":"createAlertGroup","requestBody":{"content":{"application/json":{"schema":{"properties":{"group_by":{"enum":["monitor_prefix","tag","type"],"type":"string"},"group_value":{"type":"string"},"name":{"type":"string"},"wait_seconds":{"default":60,"type":"integer"}},"required":["name","group_by","group_value"],"type":"object"}}},"required":true},"responses":{"201":{"content":{"application/json":{"schema":{"properties":{"data":{"$ref":"#/components/schemas/AlertGroup"},"request_id":{"type":"string"}},"type":"object"}}},"description":"已创建"},"400":{"$ref":"#/components/responses/BadRequest"}},"summary":"创建告警分组规则","tags":["Alerting"]}},"/v1/alert-groups/{id}":{"delete":{"operationId":"deleteAlertGroup","responses":{"204":{"description":"已删除"}},"summary":"删除告警分组规则","tags":["Alerting"]},"parameters":[{"$ref":"#/components/parameters/ResourceId"}],"put":{"operationId":"updateAlertGroup","requestBody":{"content":{"application/json":{"schema":{"properties":{"group_by":{"enum":["monitor_prefix","tag","type"],"type":"string"},"group_value":{"type":"string"},"name":{"type":"string"},"wait_seconds":{"type":"integer"}},"type":"object"}}},"required":true},"responses":{"200":{"content":{"application/json":{"schema":{"properties":{"data":{"$ref":"#/components/schemas/AlertGroup"},"request_id":{"type":"string"}},"type":"object"}}},"description":"已更新"},"400":{"$ref":"#/components/responses/BadRequest"},"404":{"$ref":"#/components/responses/NotFound"}},"summary":"编辑告警分组规则","tags":["Alerting"]}},"/v1/alert-policies":{"get":{"operationId":"listAlertPolicies","responses":{"200":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/AlertPolicyListResponse"}}},"description":"告警策略列表"}},"summary":"列出告警策略","tags":["Alerting"]},"post":{"operationId":"createAlertPolicy","requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/AlertPolicy"}}},"required":true},"responses":{"201":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/AlertPolicy"}}},"description":"创建成功"}},"summary":"创建告警策略","tags":["Alerting"]}},"/v1/alert-policies/{id}":{"delete":{"operationId":"deleteAlertPolicy","responses":{"204":{"description":"已删除"}},"summary":"删除告警策略","tags":["Alerting"]},"parameters":[{"$ref":"#/components/parameters/ResourceId"}],"patch":{"operationId":"updateAlertPolicy","requestBody":{"content":{"application/json":{"schema":{"properties":{"channel_ids":{"items":{"type":"string"},"type":"array"},"delay_s":{"type":"integer"},"enabled":{"type":"boolean"},"mute_end":{"description":"静音窗口结束(本地时间 HH:MM)","example":"08:00","pattern":"^\\d{2}:\\d{2}$","type":"string"},"mute_start":{"description":"静音窗口起始(本地时间 HH:MM)","example":"22:00","pattern":"^\\d{2}:\\d{2}$","type":"string"},"name":{"type":"string"},"recovery_n":{"maximum":10,"type":"integer"}},"type":"object"}}},"required":true},"responses":{"200":{"content":{"application/json":{"schema":{"properties":{"data":{"$ref":"#/components/schemas/AlertPolicy"},"request_id":{"type":"string"}},"type":"object"}}},"description":"已更新"},"400":{"$ref":"#/components/responses/BadRequest"}},"summary":"更新告警策略","tags":["Alerting"]}},"/v1/alert-silences":{"get":{"operationId":"listAlertSilences","responses":{"200":{"content":{"application/json":{"schema":{"properties":{"data":{"properties":{"items":{"items":{"$ref":"#/components/schemas/AlertSilence"},"type":"array"}},"type":"object"},"request_id":{"type":"string"}},"type":"object"}}},"description":"静默列表"}},"summary":"列出告警静默窗口","tags":["Alerting"]},"post":{"operationId":"createAlertSilence","requestBody":{"content":{"application/json":{"schema":{"properties":{"ends_at":{"format":"date-time","type":"string"},"monitor_id":{"type":"string"},"reason":{"type":"string"},"starts_at":{"format":"date-time","type":"string"}},"required":["reason","starts_at","ends_at"],"type":"object"}}},"required":true},"responses":{"201":{"content":{"application/json":{"schema":{"properties":{"data":{"$ref":"#/components/schemas/AlertSilence"},"request_id":{"type":"string"}},"type":"object"}}},"description":"已创建"},"400":{"$ref":"#/components/responses/BadRequest"}},"summary":"创建静默窗口","tags":["Alerting"]}},"/v1/alert-silences/{id}":{"delete":{"operationId":"deleteAlertSilence","responses":{"204":{"description":"已取消"}},"summary":"取消静默窗口","tags":["Alerting"]},"parameters":[{"$ref":"#/components/parameters/ResourceId"}]},"/v1/attest/ceremony":{"get":{"description":"借鉴 DNSSEC root key ceremony 范式作为信任背书;公开 root key 生成 / 切分 /\nsign key 轮换 / 应急撤销 的完整历史 + 录像 / 公证 PDF 链接。\n","operationId":"listKeyCeremony","parameters":[{"in":"query","name":"action","schema":{"enum":["root_gen","root_split","sign_key_rotate","emergency_revoke"],"type":"string"}}],"responses":{"200":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/KeyCeremonyListResponse"}}},"description":"仪式记录列表"}},"security":[],"summary":"密钥仪式公开记录(transparency)","tags":["Attestation"]},"servers":[{"url":"https://attest.idcd.com"}]},"/v1/attest/key/{key_id}":{"get":{"description":"返回指定 sign key 的 public key + 元数据(版本 / 创建时间 / 撤销状态 / 仪式记录)。\n撤销的 key 仍可查询 public key(只读),用于历史报告验签。\n","operationId":"getAttestKey","responses":{"200":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/AttestKeyResponse"}}},"description":"公钥 + 元数据"},"404":{"$ref":"#/components/responses/NotFound"}},"security":[],"summary":"查询签名公钥 + 元数据","tags":["Attestation"]},"parameters":[{"in":"path","name":"key_id","required":true,"schema":{"type":"string"}}],"servers":[{"url":"https://attest.idcd.com"}]},"/v1/attest/verify":{"post":{"description":"任何第三方可上传由 idcd.com 签发的 Verdict PDF,系统提取嵌入签名 + 服务器时间戳,\n返回验证结果。**不需登录,纯只读,不限频**。\n\n**D-Concern1 响应必含**:`report_type`(默认 `observation_only`)+ `legal_disclaimer`,\n明确告知第三方\"本报告是一手观测数据,不是司法鉴定结论\"。\n\n§P 实施细节:Verdict 用服务端本地 RSA(`localfile`),公钥指纹公开,第三方可下载\n公钥自验;根据报告 metadata 的 `signature_key_id + key_version` 选对应版本 public key\n(撤销 / 过期 key 仍保留 public key 只读),revoke 期间历史报告仍可正常验签。无 KMS。\n","operationId":"verifyAttestation","requestBody":{"content":{"multipart/form-data":{"schema":{"properties":{"pdf":{"description":"待验签的 PDF 文件","format":"binary","type":"string"}},"required":["pdf"],"type":"object"}}},"required":true},"responses":{"200":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/AttestVerifyResponse"}}},"description":"验签结果"},"400":{"$ref":"#/components/responses/BadRequest"},"413":{"$ref":"#/components/responses/PayloadTooLarge"}},"security":[],"servers":[{"url":"https://attest.idcd.com"}],"summary":"公开 PDF 验签","tags":["Attestation"]}},"/v1/auth/2fa-login":{"post":{"operationId":"twoFactorLogin","requestBody":{"content":{"application/json":{"schema":{"properties":{"code":{"type":"string"},"mfa_token":{"type":"string"}},"required":["mfa_token","code"],"type":"object"}}},"required":true},"responses":{"200":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/AuthTokenResponse"}}},"description":"登录成功"},"401":{"$ref":"#/components/responses/Unauthorized"}},"security":[],"summary":"2FA 登录第二步(用 mfa_token + TOTP code 换取登录态)","tags":["Auth"]}},"/v1/auth/dingtalk/callback":{"get":{"operationId":"dingtalkCallback","parameters":[{"in":"query","name":"code","schema":{"type":"string"}},{"in":"query","name":"state","schema":{"type":"string"}}],"responses":{"302":{"description":"重定向到前端 /auth/oauth-callback#code=...\u0026provider=dingtalk"}},"security":[],"summary":"钉钉 OAuth 回调(302 重定向回前端)","tags":["Auth"]}},"/v1/auth/feishu/callback":{"get":{"operationId":"feishuCallback","parameters":[{"in":"query","name":"code","schema":{"type":"string"}},{"in":"query","name":"state","schema":{"type":"string"}}],"responses":{"302":{"description":"重定向到前端 /auth/oauth-callback#code=...\u0026provider=feishu"}},"security":[],"summary":"飞书 OAuth 回调(302 重定向回前端)","tags":["Auth"]}},"/v1/auth/forgot-password":{"post":{"operationId":"forgotPassword","requestBody":{"content":{"application/json":{"schema":{"properties":{"email":{"format":"email","type":"string"}},"required":["email"],"type":"object"}}},"required":true},"responses":{"200":{"$ref":"#/components/responses/MessageOK"}},"security":[],"summary":"申请重置密码(无论邮箱是否存在均返回同一消息)","tags":["Auth"]}},"/v1/auth/login":{"post":{"operationId":"authLogin","requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/LoginRequest"}}},"required":true},"responses":{"200":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/AuthResponse"}}},"description":"登录成功"},"401":{"$ref":"#/components/responses/Unauthorized"},"429":{"$ref":"#/components/responses/RateLimited"}},"security":[],"summary":"登录","tags":["Auth"]}},"/v1/auth/logout":{"post":{"operationId":"logout","responses":{"200":{"$ref":"#/components/responses/MessageOK"}},"summary":"登出(吊销当前会话)","tags":["Auth"]}},"/v1/auth/oauth/begin":{"post":{"operationId":"oauthBegin","requestBody":{"content":{"application/json":{"schema":{"properties":{"provider":{"enum":["dingtalk","feishu"],"type":"string"},"redirect_uri":{"type":"string"}},"required":["provider"],"type":"object"}}},"required":true},"responses":{"200":{"content":{"application/json":{"schema":{"properties":{"data":{"properties":{"auth_url":{"type":"string"}},"type":"object"},"request_id":{"type":"string"}},"type":"object"}}},"description":"授权 URL"}},"security":[],"summary":"OAuth 登录 - 开始(返回授权 URL)","tags":["Auth"]}},"/v1/auth/oauth/exchange":{"post":{"operationId":"oauthExchange","requestBody":{"content":{"application/json":{"schema":{"properties":{"code":{"type":"string"},"provider":{"enum":["dingtalk","feishu"],"type":"string"}},"required":["code","provider"],"type":"object"}}},"required":true},"responses":{"200":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/AuthTokenResponse"}}},"description":"登录成功"},"401":{"$ref":"#/components/responses/Unauthorized"}},"security":[],"summary":"OAuth 登录 - 用回调 code 换取登录态","tags":["Auth"]}},"/v1/auth/passkeys/begin":{"post":{"operationId":"passkeyLoginBegin","responses":{"200":{"content":{"application/json":{"schema":{"properties":{"data":{"properties":{"challenge_id":{"type":"string"},"options":{"additionalProperties":true,"type":"object"}},"type":"object"},"request_id":{"type":"string"}},"type":"object"}}},"description":"WebAuthn 断言 challenge"}},"security":[],"summary":"passkey 登录 - 开始(返回 WebAuthn 断言 options)","tags":["Auth"]}},"/v1/auth/passkeys/complete":{"post":{"operationId":"passkeyLoginComplete","requestBody":{"content":{"application/json":{"schema":{"properties":{"challenge":{"type":"string"},"response":{"additionalProperties":true,"type":"object"}},"required":["challenge","response"],"type":"object"}}},"required":true},"responses":{"200":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/AuthTokenResponse"}}},"description":"登录成功"},"401":{"$ref":"#/components/responses/Unauthorized"}},"security":[],"summary":"passkey 登录 - 完成","tags":["Auth"]}},"/v1/auth/register":{"post":{"operationId":"authRegister","requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/RegisterRequest"}}},"required":true},"responses":{"201":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/AuthResponse"}}},"description":"注册成功(需邮箱验证)"},"400":{"$ref":"#/components/responses/BadRequest"},"409":{"$ref":"#/components/responses/Conflict"},"429":{"$ref":"#/components/responses/RateLimited"}},"security":[],"summary":"邮箱注册","tags":["Auth"]}},"/v1/auth/resend-verify":{"post":{"operationId":"resendVerify","responses":{"200":{"$ref":"#/components/responses/MessageOK"}},"summary":"重发邮箱验证码(需登录)","tags":["Auth"]}},"/v1/auth/reset-password":{"post":{"operationId":"resetPassword","requestBody":{"content":{"application/json":{"schema":{"properties":{"code":{"type":"string"},"email":{"format":"email","type":"string"},"new_password":{"format":"password","type":"string"},"otp_id":{"type":"string"}},"required":["email","otp_id","code","new_password"],"type":"object"}}},"required":true},"responses":{"200":{"$ref":"#/components/responses/MessageOK"},"400":{"$ref":"#/components/responses/BadRequest"}},"security":[],"summary":"重置密码","tags":["Auth"]}},"/v1/auth/verify-email":{"post":{"operationId":"verifyEmail","requestBody":{"content":{"application/json":{"schema":{"properties":{"code":{"type":"string"},"email":{"format":"email","type":"string"},"otp_id":{"type":"string"}},"required":["email","code","otp_id"],"type":"object"}}},"required":true},"responses":{"200":{"$ref":"#/components/responses/MessageOK"},"400":{"$ref":"#/components/responses/BadRequest"}},"security":[],"summary":"验证邮箱(注册后)","tags":["Auth"]}},"/v1/auth/wechat/qr-begin":{"post":{"operationId":"wechatQrBegin","responses":{"200":{"content":{"application/json":{"schema":{"properties":{"data":{"properties":{"qr_code":{"type":"string"},"qr_expires_at":{"type":"integer"},"session_id":{"type":"string"}},"type":"object"},"request_id":{"type":"string"}},"type":"object"}}},"description":"二维码会话"}},"security":[],"summary":"微信扫码登录 - 申请二维码","tags":["Auth"]}},"/v1/auth/wechat/qr-exchange":{"post":{"operationId":"wechatQrExchange","requestBody":{"content":{"application/json":{"schema":{"properties":{"exchange_code":{"type":"string"}},"required":["exchange_code"],"type":"object"}}},"required":true},"responses":{"200":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/AuthTokenResponse"}}},"description":"登录成功"}},"security":[],"summary":"微信扫码登录 - 用 exchange_code 换取登录态","tags":["Auth"]}},"/v1/auth/wechat/qr-status":{"get":{"operationId":"wechatQrStatus","parameters":[{"in":"query","name":"session_id","required":true,"schema":{"type":"string"}}],"responses":{"200":{"content":{"application/json":{"schema":{"properties":{"data":{"properties":{"exchange_code":{"type":"string"},"status":{"enum":["pending","scanned","confirmed","consumed","expired","error"],"type":"string"}},"type":"object"},"request_id":{"type":"string"}},"type":"object"}}},"description":"扫码状态(confirmed 时含 exchange_code)"}},"security":[],"summary":"微信扫码登录 - 轮询状态","tags":["Auth"]}},"/v1/beta/redeem":{"post":{"operationId":"redeemBetaInvitation","requestBody":{"content":{"application/json":{"schema":{"properties":{"code":{"type":"string"}},"required":["code"],"type":"object"}}},"required":true},"responses":{"200":{"$ref":"#/components/responses/MessageOK"},"400":{"$ref":"#/components/responses/BadRequest"}},"summary":"兑换 beta 邀请码","tags":["Account"]}},"/v1/beta/request":{"post":{"operationId":"requestBetaAccess","requestBody":{"content":{"application/json":{"schema":{"additionalProperties":true,"type":"object"}}}},"responses":{"200":{"$ref":"#/components/responses/MessageOK"}},"summary":"申请 beta 资格","tags":["Account"]}},"/v1/beta/status":{"get":{"operationId":"getBetaStatus","responses":{"200":{"content":{"application/json":{"schema":{"properties":{"data":{"additionalProperties":true,"type":"object"},"request_id":{"type":"string"}},"type":"object"}}},"description":"beta 状态"}},"summary":"读取当前用户 beta 资格状态","tags":["Account"]}},"/v1/billing/cancel":{"post":{"operationId":"billingCancel","responses":{"200":{"$ref":"#/components/responses/MessageOK"}},"summary":"取消订阅","tags":["Billing"]}},"/v1/billing/invoices":{"get":{"operationId":"listInvoices","parameters":[{"$ref":"#/components/parameters/Page"},{"in":"query","name":"page_size","schema":{"default":20,"maximum":100,"type":"integer"}}],"responses":{"200":{"content":{"application/json":{"schema":{"properties":{"data":{"properties":{"invoices":{"items":{"properties":{"amount_cents":{"type":"integer"},"created_at":{"format":"date-time","type":"string"},"currency":{"type":"string"},"id":{"type":"string"},"paid_at":{"format":"date-time","nullable":true,"type":"string"},"provider":{"type":"string"},"status":{"type":"string"},"subscription_id":{"type":"string"}},"type":"object"},"type":"array"},"page":{"type":"integer"},"page_size":{"type":"integer"},"total":{"type":"integer"}},"type":"object"},"request_id":{"type":"string"}},"type":"object"}}},"description":"发票列表"}},"summary":"列出发票","tags":["Billing"]}},"/v1/billing/packs/{item_key}":{"post":{"description":"stub provider 即时下发(ProvisionPack)+ 写支付记录;真实 provider 发起一次性\n收款,metadata 带 pack_item_key + order_ref,支付成功 webhook 再按 order_ref\n幂等下发。包价取 pricing_items,必须 \u003e 0(防 admin 误配 ¥0 白送)。\n","operationId":"billingBuyPack","parameters":[{"in":"path","name":"item_key","required":true,"schema":{"type":"string"}}],"responses":{"200":{"content":{"application/json":{"schema":{"properties":{"order_ref":{"type":"string"},"pay_url":{"description":"真实 provider 的支付链接","type":"string"},"provisioned":{"description":"stub 即时下发为 true","type":"boolean"}},"type":"object"}}},"description":"下单结果"},"400":{"description":"未知 item_key / 不可购买 / 未配置价格"}},"security":[{"BearerAuth":[]}],"summary":"购买加量包 / 按次包(api_pack / report_pack)","tags":["Billing"]}},"/v1/billing/subscribe":{"post":{"operationId":"billingSubscribe","requestBody":{"content":{"application/json":{"schema":{"properties":{"channel":{"enum":["alipay","wechat_pay"],"type":"string"},"coupon":{"type":"string"},"plan":{"type":"string"}},"required":["plan"],"type":"object"}}},"required":true},"responses":{"200":{"content":{"application/json":{"schema":{"properties":{"data":{"properties":{"expires_at":{"format":"date-time","type":"string"},"pay_url":{"type":"string"},"subscription_id":{"type":"string"}},"type":"object"},"request_id":{"type":"string"}},"type":"object"}}},"description":"待支付"},"400":{"$ref":"#/components/responses/BadRequest"}},"summary":"订阅付费计划(返回支付 URL)","tags":["Billing"]}},"/v1/billing/subscription":{"get":{"operationId":"getSubscription","responses":{"200":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/SubscriptionResponse"}}},"description":"当前订阅档位 + 用量"}},"summary":"当前订阅","tags":["Billing"]}},"/v1/cert/certs":{"get":{"operationId":"certListCerts","parameters":[{"in":"query","name":"status","schema":{"enum":["issued","revoked","expired"],"type":"string"}},{"in":"query","name":"limit","schema":{"default":20,"maximum":100,"type":"integer"}},{"in":"query","name":"offset","schema":{"default":0,"type":"integer"}}],"responses":{"200":{"content":{"application/json":{"schema":{"properties":{"certs":{"items":{"$ref":"#/components/schemas/CertResponse"},"type":"array"},"limit":{"type":"integer"},"offset":{"type":"integer"},"total":{"type":"integer"}},"type":"object"}}},"description":"证书列表"}},"summary":"列出本账号已签发证书","tags":["Cert"]}},"/v1/cert/certs/{id}":{"get":{"operationId":"certGetCert","parameters":[{"in":"path","name":"id","required":true,"schema":{"format":"int64","type":"integer"}}],"responses":{"200":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/CertResponse"}}},"description":"证书详情"},"404":{"$ref":"#/components/responses/NotFound"}},"summary":"查询单张证书元数据(不含私钥)","tags":["Cert"]}},"/v1/cert/certs/{id}/download":{"post":{"description":"生成 HMAC-SHA256 签名的一次性 token,5 分钟过期。返回的 download_url\n指向 /v1/cert/dl/{token},该子路径无需鉴权(token 本身即凭证)。\n","operationId":"certIssueDownloadLink","parameters":[{"in":"path","name":"id","required":true,"schema":{"format":"int64","type":"integer"}}],"responses":{"200":{"content":{"application/json":{"schema":{"properties":{"download_url":{"format":"uri","type":"string"},"expires_at":{"format":"date-time","type":"string"}},"type":"object"}}},"description":"下载链接"},"503":{"description":"CERT_DOWNLOAD_SECRET 未配置 — 下载关闭"}},"summary":"申请一次性签名下载链接(包含私钥)","tags":["Cert"]}},"/v1/cert/certs/{id}/revoke":{"post":{"operationId":"certRevokeCert","parameters":[{"in":"path","name":"id","required":true,"schema":{"format":"int64","type":"integer"}}],"requestBody":{"content":{"application/json":{"schema":{"properties":{"reason":{"enum":["unspecified","keyCompromise","superseded","cessationOfOperation"],"type":"string"}},"type":"object"}}}},"responses":{"202":{"description":"撤销已入队(WAL 写入 revoke_started)"}},"summary":"撤销已签发证书","tags":["Cert"]}},"/v1/cert/dl/{token}":{"get":{"operationId":"certDownloadByToken","parameters":[{"in":"path","name":"token","required":true,"schema":{"type":"string"}}],"responses":{"200":{"content":{"application/zip":{"schema":{"format":"binary","type":"string"}}},"description":"证书 ZIP / PEM 包"},"404":{"description":"token 不存在 / 已使用"},"410":{"description":"token 已过期"}},"security":[],"summary":"一次性 token 兑换 — 下载证书包","tags":["Cert"]}},"/v1/cert/dns-credentials":{"get":{"operationId":"certListDNSCredentials","responses":{"200":{"content":{"application/json":{"schema":{"properties":{"dns_credentials":{"items":{"$ref":"#/components/schemas/DNSCredentialResponse"},"type":"array"}},"type":"object"}}},"description":"凭据列表"}},"summary":"列出本账号 DNS 凭据","tags":["Cert"]},"post":{"operationId":"certCreateDNSCredential","requestBody":{"content":{"application/json":{"schema":{"properties":{"display_name":{"type":"string"},"provider":{"enum":["cloudflare","aliyun","dnspod","route53","gcloud","manual"],"type":"string"},"secrets":{"additionalProperties":{"type":"string"},"type":"object"}},"required":["provider","display_name","secrets"],"type":"object"}}},"required":true},"responses":{"201":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/DNSCredentialResponse"}}},"description":"凭据已创建"}},"summary":"新建 DNS Provider 凭据(字段级 KMS 加密)","tags":["Cert"]}},"/v1/cert/dns-credentials/{id}":{"delete":{"operationId":"certDeleteDNSCredential","parameters":[{"in":"path","name":"id","required":true,"schema":{"format":"int64","type":"integer"}}],"responses":{"204":{"description":"已撤销"}},"summary":"撤销 DNS 凭据","tags":["Cert"]}},"/v1/cert/dns-credentials/{id}/health-check":{"post":{"operationId":"certHealthCheckDNSCredential","parameters":[{"in":"path","name":"id","required":true,"schema":{"format":"int64","type":"integer"}}],"responses":{"200":{"content":{"application/json":{"schema":{"properties":{"health_status":{"enum":["valid","invalid","unknown"],"type":"string"}},"type":"object"}}},"description":"健康检查结果"}},"summary":"触发 DNS 凭据健康检查","tags":["Cert"]}},"/v1/cert/orders":{"get":{"operationId":"certListOrders","parameters":[{"in":"query","name":"status","schema":{"type":"string"}},{"in":"query","name":"limit","schema":{"default":20,"maximum":100,"type":"integer"}},{"in":"query","name":"offset","schema":{"default":0,"type":"integer"}}],"responses":{"200":{"content":{"application/json":{"schema":{"properties":{"limit":{"type":"integer"},"offset":{"type":"integer"},"orders":{"items":{"$ref":"#/components/schemas/CertOrderResponse"},"type":"array"},"total":{"type":"integer"}},"type":"object"}}},"description":"订单列表"}},"summary":"列出本账号证书订单","tags":["Cert"]},"post":{"description":"提交一笔免费证书签发请求。sans 必填;challenge 可选(仅支持 dns-01,留空默认\ndns-01);auto 模式需带 dns_credential_id,manual 模式留空。返回订单 id 与\n初始 status。未注册的 CA(如未配置 EAB 的 zerossl/buypass)返回 422。\n","operationId":"certCreateOrder","requestBody":{"content":{"application/json":{"schema":{"properties":{"ca":{"enum":["lets-encrypt","zerossl","buypass"],"type":"string"},"challenge":{"default":"dns-01","enum":["dns-01"],"type":"string"},"dns_credential_id":{"format":"int64","type":"integer"},"idempotency_key":{"type":"string"},"sans":{"items":{"type":"string"},"type":"array"}},"required":["sans"],"type":"object"}}},"required":true},"responses":{"201":{"content":{"application/json":{"schema":{"properties":{"order_id":{"format":"int64","type":"integer"},"status":{"type":"string"}},"type":"object"}}},"description":"订单已创建(返回订单 id 与初始 status,非完整 order)"},"400":{"$ref":"#/components/responses/BadRequest"},"409":{"$ref":"#/components/responses/Conflict"},"422":{"$ref":"#/components/responses/Unprocessable"},"429":{"$ref":"#/components/responses/RateLimited"}},"summary":"创建证书签发订单","tags":["Cert"]}},"/v1/cert/orders/{id}":{"get":{"operationId":"certGetOrder","parameters":[{"in":"path","name":"id","required":true,"schema":{"format":"int64","type":"integer"}}],"responses":{"200":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/CertOrderResponse"}}},"description":"订单详情(含 WAL 进度摘要)"},"404":{"$ref":"#/components/responses/NotFound"}},"summary":"查询单条订单详情","tags":["Cert"]}},"/v1/cert/orders/{id}/manual-ready":{"post":{"operationId":"certManualReady","parameters":[{"in":"path","name":"id","required":true,"schema":{"format":"int64","type":"integer"}}],"requestBody":{"content":{"application/json":{"schema":{"properties":{"fqdn":{"type":"string"},"value":{"type":"string"}},"required":["fqdn","value"],"type":"object"}}},"required":true},"responses":{"202":{"description":"已注入 Coordinator","worker 将继续 challenge":null},"404":{"description":"无活跃 manual coordinator(worker 重启)"}},"summary":"手动 DNS 模式 — 通知平台 TXT 记录已生效","tags":["Cert"]}},"/v1/cert/orders/{id}/retry":{"post":{"description":"仅对 status=failed 的订单生效;复用既有 WAL 步骤。","operationId":"certRetryOrder","parameters":[{"in":"path","name":"id","required":true,"schema":{"format":"int64","type":"integer"}}],"responses":{"202":{"description":"已重新入队"},"409":{"description":"订单状态非 failed"}},"summary":"显式重试 failed 订单","tags":["Cert"]}},"/v1/cert/quota":{"get":{"description":"证书配额仪表盘卡片数据源,由 cert-svc(handler/quota.go)实现,经 apps/api 反代。\n响应为扁平 JSON(无 data 信封),字段与前端 CertQuota 契约一致。\n","operationId":"getCertQuota","responses":{"200":{"content":{"application/json":{"schema":{"properties":{"expiring_soon":{"description":"30 天内到期的有效证书数(status=issued)","type":"integer"},"limit":{"description":"月配额上限(三态:-1 无限 / 0 禁用 / \u003e0 上限)","type":"integer"},"monthly_success_rate":{"description":"本月签发成功率(0-100 整数百分比;无终态订单时为 0)","maximum":100,"minimum":0,"type":"integer"},"used":{"description":"本月已签发证书数(issued/revoking/revoked)","type":"integer"}},"required":["used","limit","expiring_soon","monthly_success_rate"],"type":"object"}}},"description":"证书配额"}},"summary":"读取免费证书配额","tags":["Cert"]}},"/v1/dashboard/pins":{"get":{"operationId":"getDashboardPins","responses":{"200":{"content":{"application/json":{"schema":{"properties":{"data":{"properties":{"monitor_ids":{"items":{"type":"string"},"type":"array"}},"type":"object"},"request_id":{"type":"string"}},"type":"object"}}},"description":"固定监控 id 列表"}},"summary":"读取首页固定的监控卡片","tags":["Reports"]},"put":{"operationId":"updateDashboardPins","requestBody":{"content":{"application/json":{"schema":{"properties":{"monitor_ids":{"items":{"type":"string"},"maxItems":6,"type":"array"}},"required":["monitor_ids"],"type":"object"}}},"required":true},"responses":{"200":{"content":{"application/json":{"schema":{"properties":{"data":{"properties":{"monitor_ids":{"items":{"type":"string"},"type":"array"}},"type":"object"},"request_id":{"type":"string"}},"type":"object"}}},"description":"更新后的固定列表"}},"summary":"更新首页固定卡片(最多 6 个)","tags":["Reports"]}},"/v1/dashboard/summary":{"get":{"operationId":"getDashboardSummary","responses":{"200":{"content":{"application/json":{"schema":{"properties":{"data":{"properties":{"alerts_fired_7d":{"type":"integer"},"avg_uptime_7d":{"type":"number"},"checks_today":{"type":"integer"},"incidents_open":{"type":"integer"},"monitors":{"properties":{"down":{"type":"integer"},"paused":{"type":"integer"},"total":{"type":"integer"},"up":{"type":"integer"}},"type":"object"},"status_pages":{"type":"integer"}},"type":"object"},"request_id":{"type":"string"}},"type":"object"}}},"description":"概览"}},"summary":"首页概览(监控统计 / 今日检测 / 7d 可用率 / 开放故障 / 告警)","tags":["Reports"]}},"/v1/diagnose":{"post":{"description":"权重 20。包含多协议拨测 + 多地节点 + 综合分析。","operationId":"createDiagnose","requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/DiagnoseRequest"}}},"required":true},"responses":{"202":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ProbeTaskAccepted"}}},"description":"诊断已入队(async)"}},"summary":"一键全面诊断","tags":["Diagnose"]}},"/v1/diagnose/reports":{"get":{"description":"列出当前登录用户保存的分享报告(#462),按创建时间倒序。owner-scoped:user_id\n取自会话,不接受 owner 查询参数 → 只能看到自己的报告。需登录(Bearer)。\n","operationId":"listDiagnoseReports","parameters":[{"in":"query","name":"limit","required":false,"schema":{"default":20,"maximum":100,"minimum":1,"type":"integer"}},{"in":"query","name":"offset","required":false,"schema":{"default":0,"minimum":0,"type":"integer"}}],"responses":{"200":{"content":{"application/json":{"schema":{"properties":{"data":{"properties":{"reports":{"items":{"properties":{"created_at":{"format":"date-time","type":"string"},"domain":{"type":"string"},"id":{"type":"string"},"target":{"type":"string"},"tool":{"type":"string"},"type":{"description":"single | multi | combo","type":"string"}},"type":"object"},"type":"array"}},"type":"object"},"request_id":{"type":"string"}},"type":"object"}}},"description":"报告列表"},"401":{"$ref":"#/components/responses/Unauthorized"}},"summary":"我的分享报告列表","tags":["Diagnose"]},"post":{"description":"保存一份诊断/拨测报告并返回可分享的报告 id。**服务端拥有该 id(#464)**:\n请求体里的任何 `id` 字段都会被忽略,服务端生成一个不可猜测的 id 并在 201\n响应的 `data.id` 里回传 —— 客户端必须用这个返回的 id 跳转 `/r/{id}`。\n(信任 client 提供的 id 会让任何调用方覆写他人已分享报告的服务副本。)\n请求体须为 JSON 对象,封顶 64 KiB。\n","operationId":"saveDiagnoseReport","requestBody":{"content":{"application/json":{"schema":{"additionalProperties":true,"description":"报告快照(整份存储)。客户端可带 id,但服务端忽略并改写为自生成 id。","type":"object"}}},"required":true},"responses":{"201":{"content":{"application/json":{"schema":{"properties":{"data":{"properties":{"id":{"description":"服务端生成的报告 id,分享链接用它","type":"string"}},"type":"object"},"request_id":{"type":"string"}},"type":"object"}}},"description":"已保存"},"400":{"$ref":"#/components/responses/BadRequest"}},"summary":"保存诊断报告","tags":["Diagnose"]}},"/v1/diagnose/reports/{id}":{"delete":{"description":"删除当前登录用户保存的一份分享报告(#462)。owner-scoped:仅能删除自己的报告,\n删除后同时清除 Redis 副本,公开分享链接 /r/{id} 立即失效。需登录(Bearer)。\n","operationId":"deleteDiagnoseReport","responses":{"200":{"content":{"application/json":{"schema":{"properties":{"data":{"properties":{"id":{"type":"string"}},"type":"object"},"request_id":{"type":"string"}},"type":"object"}}},"description":"已删除"},"401":{"$ref":"#/components/responses/Unauthorized"},"404":{"$ref":"#/components/responses/NotFound"}},"summary":"删除自己保存的分享报告","tags":["Diagnose"]},"get":{"operationId":"getDiagnoseReport","responses":{"200":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/DiagnoseResponse"}}},"description":"诊断详情"}},"summary":"诊断报告详情","tags":["Diagnose"]},"parameters":[{"$ref":"#/components/parameters/ResourceId"}]},"/v1/domain-combo/preview":{"post":{"description":"给定 slot 规则 + TLD 列表,返回将生成的组合总数 / 是否封顶 / 实际生成数 +\n前几个示例域名。计数与 /domain-combo/stream 共享同一引擎,Effective ==\nstream 实际发出的 result 事件数。校验失败 400。\n","operationId":"domainComboPreview","requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/DomainComboSpec"}}},"required":true},"responses":{"200":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/DomainComboPreview"}}},"description":"组合预览"},"400":{"$ref":"#/components/responses/BadRequest"}},"security":[],"summary":"域名组合数预览(便宜计数,不查可注册性)","tags":["DomainCombo"]}},"/v1/domain-combo/stream":{"get":{"description":"流式生成候选域名并逐个分类(available / registered / failed),走两阶段\nDNS→RDAP/WHOIS 管线 + 有界 worker pool + Redis 非对称缓存。spec 经 query\n参数传入(base64url 编码的 JSON,或字面 JSON)。开流前做 quota 前置\n(已登录账号)+ spec 校验,失败返回 4xx JSON(非 SSE)。开流后推送\n`event: result` / `event: progress` / `event: done`(并在生成异常时\n`event: error`)。客户端断连即 cancel,停止 worker。\n","operationId":"domainComboStream","parameters":[{"description":"base64url 编码的 JSON spec(DomainComboSpec),或字面 JSON。","in":"query","name":"spec","required":true,"schema":{"type":"string"}}],"responses":{"200":{"content":{"text/event-stream":{"schema":{"type":"string"}}},"description":"SSE 事件流(result / progress / done / error)"},"400":{"$ref":"#/components/responses/BadRequest"},"429":{"$ref":"#/components/responses/RateLimited"}},"security":[],"summary":"域名组合流式可注册性查询(SSE)","tags":["DomainCombo"]}},"/v1/geo/cities":{"get":{"description":"地理数据固定字典(总览 #568)Phase 3 城市查询。给声明式城市录入(申请表 /\nadmin 声明城市的 CitySelect)提供 typeahead:选国/省后按 country(或 subdivision)\n+ q 子串搜索,分页返回。数据源 countries-states-cities-database,入 geo_cities\n参考表(选项 B 全量入库)。任何人可访问,无 auth,60/min/IP 限流。\n口径边界:仅服务声明式录入;GeoIP/probe 的 measured city 仍是自由文本,不走本表。\n","operationId":"searchGeoCities","parameters":[{"description":"ISO 3166-1 alpha-2(如 CN)。country 或 subdivision 至少给一个;给 subdivision 时可省略(由前两位推出)","in":"query","name":"country","schema":{"pattern":"^[A-Za-z]{2}$","type":"string"}},{"description":"ISO 3166-2(如 CN-GD),可选,进一步收窄到某省/州","in":"query","name":"subdivision","schema":{"pattern":"^[A-Za-z]{2}-[A-Za-z0-9]{1,3}$","type":"string"}},{"description":"大小写不敏感子串,匹配 name / name_zh / native","in":"query","name":"q","schema":{"type":"string"}},{"in":"query","name":"page","schema":{"default":1,"type":"integer"}},{"in":"query","name":"limit","schema":{"default":20,"maximum":100,"type":"integer"}}],"responses":{"200":{"content":{"application/json":{"schema":{"properties":{"data":{"properties":{"cities":{"items":{"properties":{"country_code":{"type":"string"},"id":{"description":"geo_cities.id(CSC 稳定数字 id),业务表以此引用","type":"integer"},"name":{"description":"英文名","type":"string"},"name_zh":{"description":"简体中文名(CN 取可靠的 native)","type":"string"},"native":{"description":"原生名","type":"string"},"subdivision_code":{"description":"ISO 3166-2 父省/州,空串=无对应白名单项","type":"string"},"type":{"description":"CSC 行政层级(prefecture/county/...)","type":"string"}},"type":"object"},"type":"array"}},"type":"object"}},"type":"object"}}},"description":"城市列表"},"400":{"description":"未提供 country 或 subdivision"}},"summary":"城市固定字典搜索(#566)","tags":["Meta"]}},"/v1/incidents":{"get":{"operationId":"listIncidents","parameters":[{"in":"query","name":"limit","schema":{"default":20,"maximum":200,"type":"integer"}},{"in":"query","name":"page","schema":{"default":1,"minimum":1,"type":"integer"}},{"description":"resolved=仅已恢复;unresolved=仅进行中(firing/acknowledged);缺省=全部。","in":"query","name":"status","schema":{"enum":["resolved","unresolved"],"type":"string"}}],"responses":{"200":{"content":{"application/json":{"schema":{"properties":{"data":{"properties":{"incidents":{"items":{"additionalProperties":true,"type":"object"},"type":"array"},"limit":{"type":"integer"},"page":{"type":"integer"},"total":{"type":"integer"}},"type":"object"},"request_id":{"type":"string"}},"type":"object"}}},"description":"故障列表"}},"summary":"列出故障事件","tags":["Incidents"]}},"/v1/incidents/{event_id}/draft":{"parameters":[{"in":"path","name":"event_id","required":true,"schema":{"type":"string"}}],"post":{"operationId":"createIncidentDraft","responses":{"201":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Postmortem"}}},"description":"草稿已创建"}},"summary":"从告警事件创建复盘草稿","tags":["Incidents"]}},"/v1/incidents/{event_id}/postmortem":{"get":{"operationId":"getPostmortem","responses":{"200":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Postmortem"}}},"description":"复盘报告"},"404":{"$ref":"#/components/responses/NotFound"}},"summary":"读取复盘报告","tags":["Incidents"]},"parameters":[{"in":"path","name":"event_id","required":true,"schema":{"type":"string"}}],"patch":{"operationId":"updatePostmortem","requestBody":{"content":{"application/json":{"schema":{"properties":{"impact":{"type":"string"},"resolution":{"type":"string"},"root_cause":{"type":"string"},"severity":{"type":"string"},"status":{"type":"string"},"title":{"type":"string"}},"type":"object"}}},"required":true},"responses":{"200":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Postmortem"}}},"description":"已更新"},"400":{"$ref":"#/components/responses/BadRequest"}},"summary":"更新复盘报告","tags":["Incidents"]}},"/v1/info/asn":{"get":{"operationId":"getInfoAsn","parameters":[{"description":"IP 或 AS 号","example":"AS13335","in":"query","name":"q","required":true,"schema":{"type":"string"}}],"responses":{"200":{"content":{"application/json":{"schema":{"properties":{"data":{"properties":{"asn":{"type":"string"},"country":{"type":"string"},"name":{"type":"string"},"prefixes_count":{"type":"integer"}},"type":"object"},"request_id":{"type":"string"}},"type":"object"}}},"description":"ASN 信息"},"400":{"$ref":"#/components/responses/BadRequest"}},"summary":"ASN 信息查询","tags":["Network Info"]}},"/v1/info/bgp":{"get":{"operationId":"getInfoBgp","parameters":[{"description":"IP 或 CIDR","in":"query","name":"q","required":true,"schema":{"type":"string"}}],"responses":{"200":{"content":{"application/json":{"schema":{"properties":{"data":{"properties":{"announcements":{"items":{"properties":{"asn":{"type":"string"},"prefix":{"type":"string"}},"type":"object"},"type":"array"},"query":{"type":"string"}},"type":"object"},"request_id":{"type":"string"}},"type":"object"}}},"description":"BGP 通告"},"400":{"$ref":"#/components/responses/BadRequest"}},"summary":"BGP 路由通告查询","tags":["Network Info"]}},"/v1/info/blacklist":{"get":{"operationId":"getInfoBlacklist","parameters":[{"description":"目标 IP","in":"query","name":"q","required":true,"schema":{"type":"string"}}],"responses":{"200":{"content":{"application/json":{"schema":{"properties":{"data":{"properties":{"checked":{"type":"integer"},"ip":{"type":"string"},"listed_in":{"items":{"type":"string"},"type":"array"}},"type":"object"},"request_id":{"type":"string"}},"type":"object"}}},"description":"黑名单命中列表"},"400":{"$ref":"#/components/responses/BadRequest"}},"summary":"IP 黑名单(DNSBL)检查","tags":["Network Info"]}},"/v1/info/cdn-waf":{"get":{"description":"抓目标 HTTP 响应头后,按指纹判定前置的 CDN 与 WAF 厂商。evidence 列出命中的 头(name: value)作为判定证据。cdn / waf 为空字符串表示未检测到。逐跳 SSRF 校验 + 锁 IP dial,拒绝私网 / 云 metadata 目标。q 不含 scheme 时默认按 http:// 起跳。\n","operationId":"getInfoCdnWaf","parameters":[{"description":"目标 URL 或裸域名(裸域名按 http:// 起跳)","example":"example.com","in":"query","name":"q","required":true,"schema":{"type":"string"}}],"responses":{"200":{"content":{"application/json":{"schema":{"properties":{"data":{"properties":{"cdn":{"description":"命中的 CDN 厂商标识(未检测到为空串)","type":"string"},"evidence":{"description":"命中的证据头列表(name: value),永远非 nil(空时为 [])","items":{"type":"string"},"type":"array"},"url":{"description":"用户原始请求(可能补了 http:// 前缀)","type":"string"},"waf":{"description":"命中的 WAF/安全代理厂商标识(未检测到为空串)","type":"string"}},"type":"object"},"request_id":{"type":"string"}},"type":"object"}}},"description":"CDN / WAF 指纹结果"},"400":{"$ref":"#/components/responses/BadRequest"},"403":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}},"description":"目标落私网 / 云 metadata,被 SSRF 校验拒绝"},"503":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}},"description":"目标不可达 / 抓取失败"}},"summary":"CDN / WAF 指纹识别(基于响应头)","tags":["Network Info"]}},"/v1/info/dkim":{"get":{"operationId":"getInfoDkim","parameters":[{"description":"域名","in":"query","name":"q","required":true,"schema":{"type":"string"}},{"description":"DKIM selector","example":"default","in":"query","name":"selector","required":true,"schema":{"type":"string"}}],"responses":{"200":{"content":{"application/json":{"schema":{"properties":{"data":{"properties":{"domain":{"type":"string"},"record":{"type":"string"},"selector":{"type":"string"}},"type":"object"},"request_id":{"type":"string"}},"type":"object"}}},"description":"DKIM 记录"},"400":{"$ref":"#/components/responses/BadRequest"}},"summary":"DKIM 记录查询(需 selector)","tags":["Network Info"]}},"/v1/info/dmarc":{"get":{"operationId":"getInfoDmarc","parameters":[{"in":"query","name":"q","required":true,"schema":{"type":"string"}}],"responses":{"200":{"content":{"application/json":{"schema":{"properties":{"data":{"properties":{"domain":{"type":"string"},"policy":{"type":"string"},"record":{"type":"string"},"tags":{"additionalProperties":true,"type":"object"},"warnings":{"items":{"type":"string"},"type":"array"}},"type":"object"},"request_id":{"type":"string"}},"type":"object"}}},"description":"DMARC 记录 + 解析标签"},"400":{"$ref":"#/components/responses/BadRequest"}},"summary":"DMARC 记录查询 + 解析","tags":["Network Info"]}},"/v1/info/dns":{"get":{"operationId":"getInfoDns","parameters":[{"description":"域名","in":"query","name":"q","required":true,"schema":{"type":"string"}},{"description":"记录类型(默认 A)","in":"query","name":"type","schema":{"default":"A","enum":["A","AAAA","CNAME","MX","NS","TXT","SOA","CAA"],"type":"string"}}],"responses":{"200":{"content":{"application/json":{"schema":{"properties":{"data":{"properties":{"query":{"type":"string"},"records":{"items":{"properties":{"name":{"type":"string"},"ttl":{"type":"integer"},"type":{"type":"string"},"value":{"type":"string"}},"type":"object"},"type":"array"},"type":{"type":"string"}},"type":"object"},"request_id":{"type":"string"}},"type":"object"}}},"description":"DNS 记录"},"400":{"$ref":"#/components/responses/BadRequest"}},"summary":"DNS 记录查询","tags":["Network Info"]}},"/v1/info/dnssec":{"get":{"operationId":"getInfoDnssec","parameters":[{"in":"query","name":"q","required":true,"schema":{"type":"string"}}],"responses":{"200":{"content":{"application/json":{"schema":{"properties":{"data":{"properties":{"chain_valid":{"type":"boolean"},"dnssec_enabled":{"type":"boolean"},"domain":{"type":"string"},"warnings":{"items":{"type":"string"},"type":"array"}},"type":"object"},"request_id":{"type":"string"}},"type":"object"}}},"description":"DNSSEC 验证结果"},"400":{"$ref":"#/components/responses/BadRequest"}},"summary":"DNSSEC 验证","tags":["Network Info"]}},"/v1/info/http-headers":{"get":{"description":"抓取目标 URL 的 HTTP 响应头与完整重定向链,抽取安全/优化相关头(HSTS / CSP / Content-Encoding 等),并给出机器可读的强信号判定(no_https_redirect / no_hsts / no_compression / no_cdn)。逐跳做 SSRF 校验 + 锁 IP dial,拒绝私网 / 云 metadata 目标,且不跟转进内网。q 不含 scheme 时默认按 http:// 起跳。\n","operationId":"getHttpHeaders","parameters":[{"description":"目标 URL 或裸域名(裸域名按 http:// 起跳)","example":"example.com","in":"query","name":"q","required":true,"schema":{"type":"string"}}],"responses":{"200":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/HttpHeadersResponse"}}},"description":"响应头 + 重定向链 + 分析"},"400":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}},"description":"缺少 q / URL 非 http(s) / 端口非 80/443"},"403":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}},"description":"目标(或重定向目标)落私网 / 云 metadata,被 SSRF 校验拒绝"},"503":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}},"description":"目标不可达 / 抓取失败"}},"summary":"HTTP 响应头 + 重定向链 + 安全/优化信号","tags":["Network Info"]}},"/v1/info/http-protocols":{"get":{"description":"一次性给出目标支持的 HTTP 版本:HTTP/1.1(拿到任意响应即为基线 true)、 HTTP/2(:443 TLS ALPN 协商出 h2)、HTTP/3(响应头 Alt-Svc 广告 h3/h3-29, 注意是\"广告\"非实测 QUIC 握手)。逐跳 SSRF 校验 + 锁 IP dial,拒绝私网 / 云 metadata 目标。q 不含 scheme 时默认按 http:// 起跳。\n","operationId":"getInfoHttpProtocols","parameters":[{"description":"目标 URL 或裸域名(裸域名按 http:// 起跳)","example":"example.com","in":"query","name":"q","required":true,"schema":{"type":"string"}}],"responses":{"200":{"content":{"application/json":{"schema":{"properties":{"data":{"properties":{"alpn":{"description":":443 TLS 握手协商出的协议(h2 / http/1.1 / 空)","type":"string"},"alt_svc":{"description":"最终响应的 Alt-Svc 头原文","type":"string"},"http11":{"description":"拿到任意响应即 true(基线)","type":"boolean"},"http2":{"description":"ALPN 协商出 h2","type":"boolean"},"http3_advertised":{"description":"Alt-Svc 广告了 h3(非实测握手)","type":"boolean"},"url":{"description":"用户原始请求(可能补了 http:// 前缀)","type":"string"}},"type":"object"},"request_id":{"type":"string"}},"type":"object"}}},"description":"HTTP 协议支持结果"},"400":{"$ref":"#/components/responses/BadRequest"},"403":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}},"description":"目标落私网 / 云 metadata,被 SSRF 校验拒绝"},"503":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}},"description":"目标不可达 / 检测失败"}},"summary":"HTTP 协议支持检测(HTTP/1.1 · HTTP/2 · HTTP/3)","tags":["Network Info"]}},"/v1/info/icp":{"get":{"operationId":"getInfoIcp","parameters":[{"description":"域名","example":"example.cn","in":"query","name":"q","required":true,"schema":{"type":"string"}}],"responses":{"200":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/IcpResponse"}}},"description":"ICP 备案信息"},"400":{"$ref":"#/components/responses/BadRequest"}},"summary":"ICP 备案查询(中国大陆)","tags":["Network Info"]}},"/v1/info/ip":{"get":{"operationId":"getInfoIp","parameters":[{"description":"目标 IPv4/IPv6","example":"1.1.1.1","in":"query","name":"q","required":true,"schema":{"type":"string"}}],"responses":{"200":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/IpInfoResponse"}}},"description":"IP info"},"400":{"$ref":"#/components/responses/BadRequest"}},"summary":"IP 归属信息(地理 / ASN / ISP / 数据中心 / 代理判定)","tags":["Network Info"]}},"/v1/info/ip-whois":{"get":{"description":"对一个 IP(v4/v6 字面量)跑 WHOIS 查询,从 RIR(ARIN/RIPE/APNIC/LACNIC/ AFRINIC)原始文本抽取网络归属字段。仅接受 IP 字面量,域名会被拒绝(域名请走 /info/whois)。私网 / 保留 / metadata IP 无公共 RIR 记录,直接 400。\n","operationId":"getInfoIpWhois","parameters":[{"description":"IPv4 或 IPv6 字面量","example":"8.8.8.8","in":"query","name":"q","required":true,"schema":{"type":"string"}}],"responses":{"200":{"content":{"application/json":{"schema":{"properties":{"data":{"properties":{"abuse_email":{"type":"string"},"cidr":{"type":"string"},"country":{"type":"string"},"ip":{"type":"string"},"net_range":{"description":"inetnum / NetRange","type":"string"},"netname":{"type":"string"},"note":{"description":"查询不可达 / 超时时的说明","type":"string"},"organization":{"type":"string"},"raw":{"description":"截断后的原始 WHOIS 文本(供折叠透明查看)","type":"string"}},"type":"object"},"request_id":{"type":"string"}},"type":"object"}}},"description":"IP WHOIS 结果(字段按 RIR 输出,可能缺省)"},"400":{"$ref":"#/components/responses/BadRequest"}},"summary":"IP WHOIS(RIR 网络归属字段)","tags":["Network Info"]}},"/v1/info/mx":{"get":{"operationId":"getInfoMx","parameters":[{"in":"query","name":"q","required":true,"schema":{"type":"string"}}],"responses":{"200":{"content":{"application/json":{"schema":{"properties":{"data":{"properties":{"domain":{"type":"string"},"records":{"items":{"properties":{"host":{"type":"string"},"priority":{"type":"integer"}},"type":"object"},"type":"array"}},"type":"object"},"request_id":{"type":"string"}},"type":"object"}}},"description":"MX 记录"},"400":{"$ref":"#/components/responses/BadRequest"}},"summary":"MX 记录查询","tags":["Network Info"]}},"/v1/info/rdns":{"get":{"operationId":"getInfoRdns","parameters":[{"description":"目标 IP","in":"query","name":"q","required":true,"schema":{"type":"string"}}],"responses":{"200":{"content":{"application/json":{"schema":{"properties":{"data":{"properties":{"ip":{"type":"string"},"ptr":{"items":{"type":"string"},"type":"array"}},"type":"object"},"request_id":{"type":"string"}},"type":"object"}}},"description":"PTR 记录"},"400":{"$ref":"#/components/responses/BadRequest"}},"summary":"反向 DNS(PTR)查询","tags":["Network Info"]}},"/v1/info/spf":{"get":{"operationId":"getInfoSpf","parameters":[{"in":"query","name":"q","required":true,"schema":{"type":"string"}}],"responses":{"200":{"content":{"application/json":{"schema":{"properties":{"data":{"properties":{"all_qualifier":{"type":"string"},"domain":{"type":"string"},"lookup_count":{"type":"integer"},"mechanisms":{"items":{"type":"string"},"type":"array"},"record":{"type":"string"},"warnings":{"items":{"type":"string"},"type":"array"}},"type":"object"},"request_id":{"type":"string"}},"type":"object"}}},"description":"SPF 记录 + 审计(mechanisms / lookup_count / warnings)"},"400":{"$ref":"#/components/responses/BadRequest"}},"summary":"SPF 记录查询 + 审计","tags":["Network Info"]}},"/v1/info/ssl":{"get":{"operationId":"getInfoSsl","parameters":[{"description":"域名,可带端口 host:port(默认 443)","example":"example.com","in":"query","name":"q","required":true,"schema":{"type":"string"}}],"responses":{"200":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/SslResponse"}}},"description":"SSL 证书 + 评分"},"400":{"$ref":"#/components/responses/BadRequest"}},"summary":"SSL/TLS 证书查询(链 / 版本 / OCSP / 评分)","tags":["Network Info"]}},"/v1/info/whois":{"get":{"operationId":"getInfoWhois","parameters":[{"description":"域名","example":"example.com","in":"query","name":"q","required":true,"schema":{"type":"string"}}],"responses":{"200":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/WhoisResponse"}}},"description":"WHOIS 数据"},"400":{"$ref":"#/components/responses/BadRequest"}},"summary":"WHOIS 查询","tags":["Network Info"]}},"/v1/ip/reputation":{"get":{"operationId":"getIpReputation","parameters":[{"description":"目标 IPv4/IPv6 或域名","example":"1.1.1.1","in":"query","name":"q","required":true,"schema":{"type":"string"}}],"responses":{"200":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/IpReputationResponse"}}},"description":"IP reputation verdict"},"400":{"$ref":"#/components/responses/BadRequest"},"429":{"$ref":"#/components/responses/RateLimited"}},"summary":"IP 信誉 / 风险查询(风险分 + 类型标签 + 证据)","tags":["Network Info"]}},"/v1/leaderboard/contributors":{"get":{"description":"按 (points_30d DESC, active_node_count DESC, display_name ASC) 排序;\nPremium tier 通过 ★ Badge 视觉区分, 不影响排序. 显式排除 idcd_system.\n仅返回 approved + (verified | premium) + hidden_at IS NULL.\n","operationId":"leaderboardContributors","responses":{"200":{"content":{"application/json":{"schema":{"properties":{"contributors":{"items":{"properties":{"active_node_count":{"type":"integer"},"display_name":{"type":"string"},"link_url":{"nullable":true,"type":"string"},"logo_url":{"nullable":true,"type":"string"},"points_30d":{"type":"integer"},"rank":{"type":"integer"},"tier":{"enum":["verified","premium"],"type":"string"},"user_id":{"type":"string"}},"type":"object"},"type":"array"},"window_days":{"description":"默认 30","type":"integer"}},"type":"object"}}},"description":"排行榜"}},"summary":"公开节点贡献者排行榜 (N3-2)","tags":["Sponsor"]}},"/v1/leaderboard/weekly":{"get":{"description":"已发布 (status=published) 的周报周期列表, 按 period_start 倒序。供周报索引页\n与 sitemap 收录。草稿不在此暴露 (admin API 管理)。\n","operationId":"leaderboardWeeklyList","responses":{"200":{"content":{"application/json":{"schema":{"properties":{"data":{"properties":{"reports":{"items":{"properties":{"generated_at":{"format":"date-time","type":"string"},"period":{"description":"ISO 周编号 YYYY-Www","type":"string"},"period_end":{"format":"date","type":"string"},"period_start":{"format":"date","type":"string"},"published_at":{"format":"date-time","nullable":true,"type":"string"},"sample_total":{"format":"int64","type":"integer"}},"type":"object"},"type":"array"},"total":{"type":"integer"}},"type":"object"}},"type":"object"}}},"description":"已发布周报列表"}},"summary":"公开数据周报列表 (#498)","tags":["Meta"]}},"/v1/leaderboard/weekly/{period}":{"get":{"description":"单个已发布周期的完整聚合 (各省×运营商 可用性/延迟 + CDN/云 延迟 + 环比)。\n未发布或不存在的周期返回 404。\n","operationId":"leaderboardWeeklyGet","parameters":[{"description":"ISO 周编号, 如 2026-W26","in":"path","name":"period","required":true,"schema":{"type":"string"}}],"responses":{"200":{"content":{"application/json":{"schema":{"properties":{"data":{"properties":{"published_at":{"format":"date-time","nullable":true,"type":"string"},"report":{"description":"weeklyreport.Summary 聚合载荷","type":"object"}},"type":"object"}},"type":"object"}}},"description":"周报聚合数据"},"404":{"description":"周报不存在或未发布"}},"summary":"公开数据周报详情 (#498)","tags":["Meta"]}},"/v1/mcp/tokens":{"get":{"operationId":"listMcpTokens","responses":{"200":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/McpTokenListResponse"}}},"description":"MCP token 列表(secret 不返回,只返回展示前缀)"}},"summary":"列出 MCP token","tags":["MCP Tokens"]},"post":{"operationId":"createMcpToken","requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/CreateMcpTokenRequest"}}},"required":true},"responses":{"201":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/CreateMcpTokenResponse"}}},"description":"创建成功(token 明文仅此一次返回,务必保存)"},"422":{"$ref":"#/components/responses/Unprocessable"}},"summary":"创建 MCP token(secret 仅返回一次,最长 90 天)","tags":["MCP Tokens"]}},"/v1/mcp/tokens/{id}":{"delete":{"operationId":"revokeMcpToken","responses":{"204":{"description":"撤销成功(无 body)"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"}},"summary":"撤销 MCP token","tags":["MCP Tokens"]},"parameters":[{"$ref":"#/components/parameters/ResourceId"}]},"/v1/monitors":{"get":{"operationId":"listMonitors","parameters":[{"$ref":"#/components/parameters/Page"},{"$ref":"#/components/parameters/PageSize"},{"in":"query","name":"type","schema":{"enum":["http","ping","tcping","dns","ssl","domain","icp","keyword","json","heartbeat","browser"],"type":"string"}},{"in":"query","name":"status","schema":{"enum":["up","down","degraded","paused"],"type":"string"}}],"responses":{"200":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/MonitorListResponse"}}},"description":"监控项列表"}},"summary":"列出监控项","tags":["Monitors"]},"post":{"operationId":"createMonitor","requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/CreateMonitorRequest"}}},"required":true},"responses":{"201":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/MonitorResponse"}}},"description":"创建成功"},"400":{"$ref":"#/components/responses/BadRequest"}},"summary":"创建监控项","tags":["Monitors"]}},"/v1/monitors/bulk":{"post":{"operationId":"bulkMonitors","requestBody":{"content":{"application/json":{"schema":{"properties":{"action":{"enum":["pause","resume","delete","tag"],"type":"string"},"ids":{"items":{"type":"string"},"type":"array"},"mode":{"enum":["add","remove","replace"],"type":"string"},"tags":{"items":{"type":"string"},"type":"array"}},"required":["ids","action"],"type":"object"}}},"required":true},"responses":{"200":{"content":{"application/json":{"schema":{"properties":{"data":{"properties":{"failed":{"items":{"type":"string"},"type":"array"},"succeeded":{"items":{"type":"string"},"type":"array"},"total":{"type":"integer"}},"type":"object"},"request_id":{"type":"string"}},"type":"object"}}},"description":"批量结果"},"400":{"$ref":"#/components/responses/BadRequest"}},"summary":"批量操作监控(暂停 / 恢复 / 删除 / 打标签)","tags":["Monitors"]}},"/v1/monitors/export":{"get":{"description":"把调用者全部非归档监控作为可移植配置包下载(PRD §4.3)。format=json 全保真(含 config/assertions、分组名、标签),用于备份/迁移;format=csv 仅基础字段(name/type/target/interval_s/node_count/group/tags),无法表达 assertions。分组按名称携带,导入时按名解析或创建。响应附 Content-Disposition 触发浏览器下载。","operationId":"exportMonitors","parameters":[{"in":"query","name":"format","schema":{"default":"json","enum":["json","csv"],"type":"string"}}],"responses":{"200":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/MonitorExportEnvelope"}},"text/csv":{"schema":{"type":"string"}}},"description":"监控配置包(JSON 信封或 CSV 文本)"},"400":{"$ref":"#/components/responses/BadRequest"}},"summary":"批量导出监控项(JSON 全保真 / CSV 基础字段)","tags":["Monitors"]}},"/v1/monitors/groups":{"get":{"description":"当前用户的监控分组,按 sort_order、name 排序(后续期 C,§7.1)。","operationId":"listMonitorGroups","responses":{"200":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/MonitorGroupListResponse"}}},"description":"分组列表"}},"summary":"列出监控分组","tags":["Monitors"]},"post":{"operationId":"createMonitorGroup","requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/CreateMonitorGroupRequest"}}},"required":true},"responses":{"201":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/MonitorGroupResponse"}}},"description":"创建成功"},"400":{"$ref":"#/components/responses/BadRequest"},"409":{"description":"同名分组已存在"}},"summary":"创建监控分组","tags":["Monitors"]}},"/v1/monitors/groups/{gid}":{"delete":{"description":"删除分组;成员监控的 group_id 由同库 FK ON DELETE SET NULL 自动置空 (D-A),不删除监控本身。","operationId":"deleteMonitorGroup","responses":{"204":{"description":"删除成功"},"404":{"description":"分组不存在"}},"summary":"删除监控分组","tags":["Monitors"]},"parameters":[{"in":"path","name":"gid","required":true,"schema":{"type":"string"}}],"patch":{"operationId":"updateMonitorGroup","requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/UpdateMonitorGroupRequest"}}},"required":true},"responses":{"200":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/MonitorGroupResponse"}}},"description":"更新成功"},"400":{"$ref":"#/components/responses/BadRequest"},"404":{"description":"分组不存在"},"409":{"description":"同名分组已存在"}},"summary":"更新监控分组(名称 / 排序)","tags":["Monitors"]}},"/v1/monitors/import":{"post":{"description":"两阶段批量导入(PRD §4.3)。dry_run=true 仅返回逐行计划(create/skip/error) 与汇总,不写入;用户确认后以 dry_run=false 实际创建。skip 以 (name,type,target) 精确匹配现有非归档监控 + 本文件已规划的创建,使重复导入 与中途失败重跑都幂等。分组按名称 get-or-create。content 为文件原文,format 指明 json|csv。","operationId":"importMonitors","requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/MonitorImportRequest"}}},"required":true},"responses":{"200":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/MonitorImportResponse"}}},"description":"导入计划(dry-run)或导入结果(commit)"},"400":{"$ref":"#/components/responses/BadRequest"}},"summary":"批量导入监控项(两阶段:dry-run 预览 + 确认写入)","tags":["Monitors"]}},"/v1/monitors/maintenance":{"get":{"description":"当前用户的维护窗口,按 starts_at 倒序(后续期 B,§7.3 / A8)。","operationId":"listMaintenanceWindows","responses":{"200":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/MaintenanceWindowListResponse"}}},"description":"维护窗口列表"}},"summary":"列出维护窗口","tags":["Monitors"]},"post":{"description":"一次性维护窗口,scope = monitor/group/tag/all。窗口内仍拨测仍记录,但冻结 状态机不开事件、两路不告警、可用率分母排除(A8)、状态页显「维护中」。","operationId":"createMaintenanceWindow","requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/CreateMaintenanceWindowRequest"}}},"required":true},"responses":{"201":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/MaintenanceWindowResponse"}}},"description":"创建成功"},"400":{"$ref":"#/components/responses/BadRequest"}},"summary":"创建维护窗口","tags":["Monitors"]}},"/v1/monitors/maintenance/{wid}":{"delete":{"operationId":"deleteMaintenanceWindow","responses":{"204":{"description":"删除成功"},"404":{"description":"维护窗口不存在"}},"summary":"删除维护窗口","tags":["Monitors"]},"parameters":[{"in":"path","name":"wid","required":true,"schema":{"type":"string"}}],"patch":{"description":"局部更新;省略的字段保持不变。","operationId":"updateMaintenanceWindow","requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/UpdateMaintenanceWindowRequest"}}},"required":true},"responses":{"200":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/MaintenanceWindowResponse"}}},"description":"更新成功"},"400":{"$ref":"#/components/responses/BadRequest"},"404":{"description":"维护窗口不存在"}},"summary":"更新维护窗口","tags":["Monitors"]}},"/v1/monitors/sparklines":{"get":{"description":"卡片视图的 24h sparkline 批量数据源。一次请求服务整页卡片(避免每张卡片 各拉一次 /checks 的 N+1)。返回的 id 已与调用方自己的监控项求交集 —— 传入 他人 id 不会泄漏数据(未授权 id 不出现在结果里)。分桶/过滤口径与 uptime% 一致:仅 datacenter 节点(#19 P1-4)+ 维护窗口排除(A8,维护期桶 缺省为断点)。","operationId":"getMonitorSparklines","parameters":[{"description":"逗号分隔的监控项 id 列表(去重、上限 50)。","in":"query","name":"ids","required":true,"schema":{"example":"mon_abc","mon_def":null,"type":"string"}}],"responses":{"200":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/MonitorSparklinesResponse"}}},"description":"按监控项 id 索引的 24h 分桶序列(1h 桶,≤24 点)"}},"summary":"批量获取监控项 24h 迷你趋势图数据","tags":["Monitors"]}},"/v1/monitors/tags":{"delete":{"description":"把指定标签从调用方全部活跃监控上摘除(§8 ③)。标签经查询参数传入(非路径段), 因为标签为自由文本、可能含 '/' 或空格。","operationId":"deleteMonitorTag","parameters":[{"description":"要删除的标签(大小写不敏感,服务端规范化为小写)。","in":"query","name":"tag","required":true,"schema":{"maxLength":50,"type":"string"}}],"responses":{"200":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/TagMutationResponse"}}},"description":"已更新的监控数量"},"400":{"$ref":"#/components/responses/BadRequest"}},"summary":"从全部监控移除一个标签","tags":["Monitors"]},"get":{"description":"当前用户全部活跃监控(status != archived)的去重标签 + 使用计数,按计数降序、 名称升序(后续期 §8 ③)。供标签管理器与全局标签建议使用 —— 不再受列表分页 页内聚合的限制。","operationId":"listMonitorTags","responses":{"200":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/MonitorTagListResponse"}}},"description":"标签计数列表"}},"summary":"列出标签及使用计数","tags":["Monitors"]}},"/v1/monitors/tags/rename":{"post":{"description":"把 from 标签在调用方全部活跃监控上替换为 to(§8 ③)。仅触碰确实带 from 的 监控;若某监控已带 to,两者合并去重。from/to 大小写不敏感,规范化后不得相同。","operationId":"renameMonitorTag","requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/RenameTagRequest"}}},"required":true},"responses":{"200":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/TagMutationResponse"}}},"description":"已更新的监控数量"},"400":{"$ref":"#/components/responses/BadRequest"}},"summary":"跨全部监控重命名标签","tags":["Monitors"]}},"/v1/monitors/{id}":{"delete":{"operationId":"deleteMonitor","responses":{"204":{"description":"删除成功"}},"summary":"删除监控项","tags":["Monitors"]},"get":{"operationId":"getMonitor","responses":{"200":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/MonitorResponse"}}},"description":"监控项详情"}},"summary":"监控项详情","tags":["Monitors"]},"parameters":[{"$ref":"#/components/parameters/ResourceId"}],"patch":{"operationId":"updateMonitor","requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/UpdateMonitorRequest"}}},"required":true},"responses":{"200":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/MonitorResponse"}}},"description":"更新成功"},"400":{"$ref":"#/components/responses/BadRequest"}},"summary":"更新监控项","tags":["Monitors"]}},"/v1/monitors/{id}/agent-obs":{"delete":{"operationId":"deleteAgentObsConfig","responses":{"204":{"description":"已删除"}},"summary":"删除 agent-obs 配置","tags":["Agent Observability"]},"get":{"operationId":"getAgentObsConfig","responses":{"200":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/AgentObsConfigResponse"}}},"description":"配置"},"404":{"$ref":"#/components/responses/NotFound"}},"summary":"读取监控的 agent-obs(LLM/工具可观测)配置","tags":["Agent Observability"]},"parameters":[{"$ref":"#/components/parameters/ResourceId"}],"patch":{"operationId":"updateAgentObsConfig","requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/AgentObsConfigRequest"}}},"required":true},"responses":{"200":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/AgentObsConfigResponse"}}},"description":"已更新"}},"summary":"更新 agent-obs 配置","tags":["Agent Observability"]},"post":{"operationId":"createAgentObsConfig","requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/AgentObsConfigRequest"}}},"required":true},"responses":{"201":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/AgentObsConfigResponse"}}},"description":"已创建"},"400":{"$ref":"#/components/responses/BadRequest"}},"summary":"创建/启用 agent-obs 配置","tags":["Agent Observability"]}},"/v1/monitors/{id}/agent-obs/checks":{"get":{"description":"列出某监控的 agent 观测检查记录(monitor_agent_obs_checks),按 checked_at 倒序。 支持两种分页:cursor(keyset,推荐)与 offset(向后兼容)。cursor 模式下响应携带 next_cursor 供翻下一页,翻到末页时 next_cursor 为空。","operationId":"listAgentObsChecks","responses":{"200":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/AgentObsChecksListResponse"}}},"description":"Agent 观测检查列表"}},"summary":"Agent 观测检查历史","tags":["Monitors"]},"parameters":[{"$ref":"#/components/parameters/ResourceId"},{"in":"query","name":"limit","schema":{"default":20,"maximum":100,"minimum":1,"type":"integer"}},{"description":"Keyset(游标)分页 token —— 上一页响应里的 next_cursor。给定时优先于 offset, 按稳定复合键 (checked_at, id) 倒序翻页,深翻不随页深退化(O(pageSize)),命中 (monitor_id, checked_at DESC) 索引。这是 monitor_agent_obs_checks(TimescaleDB hypertable,只增的时序表)推荐的翻页方式。token 不透明,客户端只回传不解析; 无效/过期 token 静默回落第一页。","in":"query","name":"cursor","schema":{"type":"string"}},{"description":"传统 OFFSET 分页(向后兼容保留)。仅当不传 cursor 时生效。深翻会让 Postgres 扫描并丢弃整个前缀,基数高时退化;深翻请改用 cursor。","in":"query","name":"offset","schema":{"default":0,"minimum":0,"type":"integer"}}]},"/v1/monitors/{id}/baseline":{"get":{"operationId":"getMonitorBaseline","responses":{"200":{"content":{"application/json":{"schema":{"properties":{"data":{"additionalProperties":true,"type":"object"},"request_id":{"type":"string"}},"type":"object"}}},"description":"基线数据"}},"summary":"监控基线(正常区间)","tags":["Monitors"]},"parameters":[{"$ref":"#/components/parameters/ResourceId"}]},"/v1/monitors/{id}/checks":{"get":{"operationId":"getMonitorChecks","responses":{"200":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/MonitorChecksResponse"}}},"description":"检查历史(时序数据)"}},"summary":"监控项历史检查","tags":["Monitors"]},"parameters":[{"$ref":"#/components/parameters/ResourceId"},{"$ref":"#/components/parameters/FromTime"},{"$ref":"#/components/parameters/ToTime"},{"description":"多日时序窗口。给定时优先于 hours/resolution,自动选桶宽: 7d→1h 桶(168 点) / 30d→6h 桶(120 点) / 90d→1d 桶(90 点)。 缺省或未知值时回落到 hours/resolution(默认 24h / 30min 桶)。","in":"query","name":"range","schema":{"enum":["7d","30d","90d"],"type":"string"}},{"description":"回看小时数(range 缺省时生效,默认 24,上限 168)。","in":"query","name":"hours","schema":{"default":24,"maximum":168,"minimum":1,"type":"integer"}},{"description":"桶宽(range 缺省时生效)。","in":"query","name":"resolution","schema":{"default":"30m","enum":["30m","60m"],"type":"string"}},{"in":"query","name":"limit","schema":{"default":100,"maximum":1000,"type":"integer"}}]},"/v1/monitors/{id}/checks/recent":{"get":{"operationId":"getRecentChecks","parameters":[{"in":"query","name":"limit","schema":{"default":10,"maximum":100,"type":"integer"}}],"responses":{"200":{"content":{"application/json":{"schema":{"properties":{"data":{"properties":{"checks":{"items":{"properties":{"check_at":{"format":"date-time","type":"string"},"country":{"nullable":true,"type":"string"},"error":{"nullable":true,"type":"string"},"latency_ms":{"nullable":true,"type":"integer"},"node_id":{"type":"string"},"node_name":{"nullable":true,"type":"string"},"status":{"type":"string"}},"type":"object"},"type":"array"},"limit":{"type":"integer"},"monitor_id":{"type":"string"}},"type":"object"},"request_id":{"type":"string"}},"type":"object"}}},"description":"最近检测"}},"summary":"最近检测结果(各节点最新)","tags":["Monitors"]},"parameters":[{"$ref":"#/components/parameters/ResourceId"}]},"/v1/monitors/{id}/deviations":{"get":{"operationId":"getMonitorDeviations","responses":{"200":{"content":{"application/json":{"schema":{"properties":{"data":{"additionalProperties":true,"type":"object"},"request_id":{"type":"string"}},"type":"object"}}},"description":"偏离记录"}},"summary":"监控偏离记录(异常检测)","tags":["Monitors"]},"parameters":[{"$ref":"#/components/parameters/ResourceId"}]},"/v1/monitors/{id}/events":{"get":{"description":"列出监控的故障事件(monitor_event)。事件是状态机的一等产物 —— 未配告警策略的 监控 down 了同样产生事件。按 started_at 倒序返回。","operationId":"listMonitorEvents","responses":{"200":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/MonitorEventListResponse"}}},"description":"监控事件列表"}},"summary":"监控事件时间线","tags":["Monitors"]},"parameters":[{"$ref":"#/components/parameters/ResourceId"},{"description":"open=仅进行中(ended_at IS NULL),closed=仅已恢复,缺省=全部","in":"query","name":"status","schema":{"enum":["open","closed"],"type":"string"}},{"in":"query","name":"limit","schema":{"default":50,"maximum":200,"type":"integer"}},{"in":"query","name":"page","schema":{"default":1,"minimum":1,"type":"integer"}}]},"/v1/monitors/{id}/events/{eid}":{"parameters":[{"$ref":"#/components/parameters/ResourceId"},{"in":"path","name":"eid","required":true,"schema":{"type":"string"}}],"patch":{"operationId":"updateMonitorEventNotes","requestBody":{"content":{"application/json":{"schema":{"properties":{"notes":{"description":"空字符串清除备注","type":"string"}},"type":"object"}}},"required":true},"responses":{"200":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/MonitorEventResponse"}}},"description":"更新成功,返回更新后的事件"}},"summary":"更新监控事件备注","tags":["Monitors"]}},"/v1/monitors/{id}/events/{eid}/ack":{"parameters":[{"$ref":"#/components/parameters/ResourceId"},{"in":"path","name":"eid","required":true,"schema":{"type":"string"}}],"post":{"operationId":"ackMonitorEvent","responses":{"200":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/MonitorEventResponse"}}},"description":"确认成功,返回更新后的事件"}},"summary":"确认监控事件","tags":["Monitors"]}},"/v1/monitors/{id}/events/{eid}/false-positive":{"parameters":[{"$ref":"#/components/parameters/ResourceId"},{"in":"path","name":"eid","required":true,"schema":{"type":"string"}}],"post":{"description":"反误报反馈闭环(§13)。仅翻转 is_false_positive 标志,不关闭事件、不设 resolved_by;进行中的事件仍由状态机在监控恢复时关闭。","operationId":"markMonitorEventFalsePositive","responses":{"200":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/MonitorEventResponse"}}},"description":"标记成功,返回更新后的事件"}},"summary":"标记监控事件为误报","tags":["Monitors"]}},"/v1/monitors/{id}/heartbeat/rotate":{"parameters":[{"$ref":"#/components/parameters/ResourceId"}],"post":{"description":"仅 type=heartbeat。事务内删除旧 token、签发新 token(state / 打卡流水 计数保留),旧打卡 URL 立即 404(Redis 映射同步失效)——token 泄露 (脚本进 git / 日志)的一键止血手段(PRD 26 §10)。","operationId":"rotateHeartbeatToken","responses":{"200":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/HeartbeatRotateResponse"}}},"description":"新 token 与完整打卡 URL"},"400":{"$ref":"#/components/responses/BadRequest"}},"summary":"轮换心跳打卡 token(M10)","tags":["Monitors"]}},"/v1/monitors/{id}/pause":{"parameters":[{"$ref":"#/components/parameters/ResourceId"}],"post":{"operationId":"pauseMonitor","responses":{"200":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/MonitorResponse"}}},"description":"已暂停"},"404":{"$ref":"#/components/responses/NotFound"}},"summary":"暂停监控","tags":["Monitors"]}},"/v1/monitors/{id}/resume":{"parameters":[{"$ref":"#/components/parameters/ResourceId"}],"post":{"operationId":"resumeMonitor","responses":{"200":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/MonitorResponse"}}},"description":"已恢复"},"404":{"$ref":"#/components/responses/NotFound"}},"summary":"恢复监控","tags":["Monitors"]}},"/v1/monitors/{id}/stream":{"get":{"operationId":"streamMonitorChecks","responses":{"200":{"content":{"text/event-stream":{"schema":{"type":"string"}}},"description":"text/event-stream;每条 event data 为 {monitor_id, node_id, status, latency_ms?, checked_at, error}"}},"summary":"实时检测事件流(SSE)","tags":["Monitors"]},"parameters":[{"$ref":"#/components/parameters/ResourceId"}]},"/v1/monitors/{id}/test":{"parameters":[{"$ref":"#/components/parameters/ResourceId"}],"post":{"description":"按监控当前 config + target 向若干在线节点派发一次性探测,异步执行。返回 test_id;用 GET .../test/{tid} 轮询结果。结果不计入历史可用率、不进状态机、 不触发告警(测试 Tab,§6.2)。每监控限频(≤6/min)。","operationId":"testMonitor","responses":{"202":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/MonitorTestRunResponse"}}},"description":"测试已派发,返回 test_id 供轮询"},"429":{"description":"该监控测试过于频繁"},"503":{"description":"当前无可用探测节点"}},"summary":"立即测试监控项(一次性拨测)","tags":["Monitors"]}},"/v1/monitors/{id}/test/{tid}":{"get":{"description":"轮询一次性测试的进度与结果。status=pending 表示仍有节点未返回;done 表示全部 节点已返回。verdict 为各节点的聚合判定。","operationId":"getMonitorTestResult","responses":{"200":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/MonitorTestResultResponse"}}},"description":"测试进度/结果"},"404":{"description":"测试不存在或已过期"}},"summary":"轮询立即测试结果","tags":["Monitors"]},"parameters":[{"$ref":"#/components/parameters/ResourceId"},{"in":"path","name":"tid","required":true,"schema":{"type":"string"}}]},"/v1/nodes":{"get":{"operationId":"listNodes","responses":{"200":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/NodeListResponse"}}},"description":"节点目录"}},"security":[],"summary":"列出公开节点目录","tags":["Nodes"]}},"/v1/nodes/apply":{"post":{"operationId":"applyNode","requestBody":{"content":{"application/json":{"schema":{"additionalProperties":true,"type":"object"}}},"required":true},"responses":{"201":{"content":{"application/json":{"schema":{"properties":{"data":{"additionalProperties":true,"type":"object"},"request_id":{"type":"string"}},"type":"object"}}},"description":"申请已提交"},"400":{"$ref":"#/components/responses/BadRequest"}},"summary":"申请接入自建节点","tags":["Nodes"]}},"/v1/nodes/enrollment-tokens":{"get":{"operationId":"listSelfServeEnrollmentTokens","responses":{"200":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/EnrollmentTokenList"}}},"description":"Token 列表"},"401":{"$ref":"#/components/responses/Unauthorized"}},"summary":"列出我的 enrollment token","tags":["Nodes"]},"post":{"description":"登录用户申请一次性 enrollment token，用于将服务器加入众包节点网络。单用户最多 5 个待用 token，TTL 24h。","operationId":"createSelfServeEnrollmentToken","requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/CreateEnrollmentTokenRequest"}}},"required":false},"responses":{"201":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/EnrollmentTokenCreated"}}},"description":"Token 生成成功"},"400":{"$ref":"#/components/responses/BadRequest"},"401":{"$ref":"#/components/responses/Unauthorized"},"429":{"$ref":"#/components/responses/RateLimited"}},"summary":"自助生成 enrollment token","tags":["Nodes"]}},"/v1/nodes/enrollment-tokens/{id}":{"delete":{"operationId":"revokeSelfServeEnrollmentToken","responses":{"200":{"content":{"application/json":{"schema":{"properties":{"data":{"properties":{"status":{"enum":["revoked"],"type":"string"}},"required":["status"],"type":"object"},"request_id":{"type":"string"}},"required":["data","request_id"],"type":"object"}}},"description":"撤销成功"},"401":{"$ref":"#/components/responses/Unauthorized"},"404":{"$ref":"#/components/responses/NotFound"},"409":{"$ref":"#/components/responses/Conflict"}},"summary":"撤销 enrollment token","tags":["Nodes"]},"parameters":[{"$ref":"#/components/parameters/ResourceId"}]},"/v1/nodes/my-applications":{"get":{"operationId":"listMyNodeApplications","responses":{"200":{"content":{"application/json":{"schema":{"properties":{"data":{"additionalProperties":true,"type":"object"},"request_id":{"type":"string"}},"type":"object"}}},"description":"申请列表"}},"summary":"列出我的节点接入申请","tags":["Nodes"]}},"/v1/nodes/my-nodes":{"get":{"operationId":"listMyNodes","responses":{"200":{"content":{"application/json":{"schema":{"properties":{"data":{"properties":{"nodes":{"items":{"properties":{"declared_region":{"deprecated":true,"description":"Legacy free-form region (metadata.region). Deprecated per #564 — no new writes; subdivision is now declared as an ISO 3166-2 code (e.g. CN-GD) validated server-side. Existing values are echoed as-is.","type":"string"},"id":{"type":"string"},"last_seen_at":{"format":"date-time","nullable":true,"type":"string"},"name":{"nullable":true,"type":"string"},"node_id":{"type":"string"},"status":{"type":"string"}},"type":"object"},"type":"array"}},"type":"object"},"request_id":{"type":"string"}},"type":"object"}}},"description":"我的节点"}},"summary":"列出我的自建节点","tags":["Nodes"]}},"/v1/nodes/{id}":{"delete":{"operationId":"retireNode","responses":{"200":{"content":{"application/json":{"schema":{"properties":{"data":{"properties":{"status":{"example":"retired","type":"string"}},"type":"object"},"request_id":{"type":"string"}},"type":"object"}}},"description":"已退役"},"404":{"$ref":"#/components/responses/NotFound"}},"summary":"退役自建节点","tags":["Nodes"]},"parameters":[{"$ref":"#/components/parameters/ResourceId"}]},"/v1/nodes/{id}/diagnostics":{"get":{"operationId":"getNodeDiagnostics","responses":{"200":{"content":{"application/json":{"schema":{"properties":{"data":{"properties":{"latency_distribution":{"properties":{"max":{"type":"number"},"min":{"type":"number"},"p50":{"type":"number"},"p90":{"type":"number"},"p95":{"type":"number"},"p99":{"type":"number"}},"type":"object"},"location":{"properties":{"asn":{"type":"string"},"city":{"type":"string"},"country":{"type":"string"},"isp":{"type":"string"}},"type":"object"},"name":{"type":"string"},"node_id":{"type":"string"},"status":{"type":"string"},"uptime_24h":{"type":"number"}},"type":"object"},"request_id":{"type":"string"}},"type":"object"}}},"description":"节点诊断数据"}},"security":[],"summary":"节点诊断(公开:延迟分布 / 健康趋势)","tags":["Nodes"]},"parameters":[{"$ref":"#/components/parameters/ResourceId"}]},"/v1/nodes/{id}/pause":{"parameters":[{"$ref":"#/components/parameters/ResourceId"}],"post":{"operationId":"pauseNode","responses":{"200":{"content":{"application/json":{"schema":{"properties":{"data":{"properties":{"status":{"example":"paused","type":"string"}},"type":"object"},"request_id":{"type":"string"}},"type":"object"}}},"description":"已暂停"},"422":{"$ref":"#/components/responses/Unprocessable"}},"summary":"暂停自建节点","tags":["Nodes"]}},"/v1/nodes/{id}/resume":{"parameters":[{"$ref":"#/components/parameters/ResourceId"}],"post":{"operationId":"resumeNode","responses":{"200":{"content":{"application/json":{"schema":{"properties":{"data":{"properties":{"status":{"example":"active","type":"string"}},"type":"object"},"request_id":{"type":"string"}},"type":"object"}}},"description":"已恢复"},"422":{"$ref":"#/components/responses/Unprocessable"}},"summary":"恢复自建节点","tags":["Nodes"]}},"/v1/oncall/schedules":{"get":{"operationId":"listOncallSchedules","responses":{"200":{"content":{"application/json":{"schema":{"properties":{"data":{"properties":{"items":{"items":{"$ref":"#/components/schemas/OncallSchedule"},"type":"array"}},"type":"object"},"request_id":{"type":"string"}},"type":"object"}}},"description":"排班列表"}},"summary":"列出值班排班","tags":["On-Call"]},"post":{"operationId":"createOncallSchedule","requestBody":{"content":{"application/json":{"schema":{"properties":{"handoff_hour":{"maximum":23,"minimum":0,"type":"integer"},"name":{"type":"string"},"rotation_type":{"enum":["daily","weekly"],"type":"string"},"team_id":{"type":"string"}},"required":["team_id","name","rotation_type"],"type":"object"}}},"required":true},"responses":{"201":{"content":{"application/json":{"schema":{"properties":{"data":{"$ref":"#/components/schemas/OncallSchedule"},"request_id":{"type":"string"}},"type":"object"}}},"description":"已创建"},"400":{"$ref":"#/components/responses/BadRequest"},"403":{"$ref":"#/components/responses/Forbidden"}},"summary":"创建值班排班","tags":["On-Call"]}},"/v1/oncall/schedules/{id}":{"delete":{"description":"团队 owner/admin 限定。参与者与 override 无 FK 级联，服务端在事务内显式删除。","operationId":"deleteOncallSchedule","responses":{"204":{"description":"已删除"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"}},"summary":"删除排班(级联成员 / override)","tags":["On-Call"]},"get":{"operationId":"getOncallSchedule","responses":{"200":{"content":{"application/json":{"schema":{"properties":{"data":{"allOf":[{"$ref":"#/components/schemas/OncallSchedule"},{"properties":{"current_on_call":{"nullable":true,"type":"string"},"participants":{"items":{"additionalProperties":true,"type":"object"},"type":"array"},"preview":{"items":{"additionalProperties":true,"type":"object"},"type":"array"}},"type":"object"}]},"request_id":{"type":"string"}},"type":"object"}}},"description":"排班详情"},"404":{"$ref":"#/components/responses/NotFound"}},"summary":"排班详情(含当前值班 / 预览 / 成员)","tags":["On-Call"]},"parameters":[{"$ref":"#/components/parameters/ResourceId"}],"put":{"description":"团队 owner/admin 限定。所有字段可选，仅更新提交的字段。","operationId":"updateOncallSchedule","requestBody":{"content":{"application/json":{"schema":{"properties":{"handoff_hour":{"maximum":23,"minimum":0,"type":"integer"},"name":{"type":"string"},"rotation_type":{"enum":["daily","weekly"],"type":"string"}},"type":"object"}}},"required":true},"responses":{"200":{"content":{"application/json":{"schema":{"properties":{"data":{"$ref":"#/components/schemas/OncallSchedule"},"request_id":{"type":"string"}},"type":"object"}}},"description":"已更新"},"400":{"$ref":"#/components/responses/BadRequest"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"}},"summary":"编辑排班(改名 / rotation / handoff_hour)","tags":["On-Call"]}},"/v1/oncall/schedules/{id}/current":{"get":{"operationId":"getCurrentOnCall","responses":{"200":{"content":{"application/json":{"schema":{"properties":{"data":{"properties":{"user_id":{"nullable":true,"type":"string"}},"type":"object"},"request_id":{"type":"string"}},"type":"object"}}},"description":"当前值班 user"}},"summary":"当前值班人","tags":["On-Call"]},"parameters":[{"$ref":"#/components/parameters/ResourceId"}]},"/v1/oncall/schedules/{id}/overrides":{"get":{"operationId":"listOncallOverrides","parameters":[{"in":"query","name":"active","schema":{"type":"boolean"}}],"responses":{"200":{"content":{"application/json":{"schema":{"properties":{"data":{"properties":{"overrides":{"items":{"additionalProperties":true,"type":"object"},"type":"array"}},"type":"object"},"request_id":{"type":"string"}},"type":"object"}}},"description":"代班列表"}},"summary":"列出值班代班(override)","tags":["On-Call"]},"parameters":[{"$ref":"#/components/parameters/ResourceId"}],"post":{"operationId":"createOncallOverride","requestBody":{"content":{"application/json":{"schema":{"properties":{"end_at":{"format":"date-time","type":"string"},"start_at":{"format":"date-time","type":"string"},"user_id":{"type":"string"}},"required":["user_id","start_at","end_at"],"type":"object"}}},"required":true},"responses":{"201":{"content":{"application/json":{"schema":{"properties":{"data":{"additionalProperties":true,"type":"object"},"request_id":{"type":"string"}},"type":"object"}}},"description":"已创建"},"400":{"$ref":"#/components/responses/BadRequest"}},"summary":"创建值班代班","tags":["On-Call"]}},"/v1/oncall/schedules/{id}/overrides/{override_id}":{"delete":{"operationId":"deleteOncallOverride","responses":{"204":{"description":"已删除"}},"summary":"删除值班代班","tags":["On-Call"]},"parameters":[{"$ref":"#/components/parameters/ResourceId"},{"in":"path","name":"override_id","required":true,"schema":{"type":"string"}}]},"/v1/oncall/schedules/{id}/participants":{"parameters":[{"$ref":"#/components/parameters/ResourceId"}],"post":{"operationId":"addOncallParticipant","requestBody":{"content":{"application/json":{"schema":{"properties":{"order_index":{"type":"integer"},"user_id":{"type":"string"}},"required":["user_id"],"type":"object"}}},"required":true},"responses":{"201":{"content":{"application/json":{"schema":{"properties":{"data":{"additionalProperties":true,"type":"object"},"request_id":{"type":"string"}},"type":"object"}}},"description":"已添加"},"400":{"$ref":"#/components/responses/BadRequest"}},"summary":"添加值班成员","tags":["On-Call"]}},"/v1/oncall/schedules/{id}/participants/{user_id}":{"delete":{"operationId":"removeOncallParticipant","responses":{"204":{"description":"已移除"}},"summary":"移除值班成员","tags":["On-Call"]},"parameters":[{"$ref":"#/components/parameters/ResourceId"},{"in":"path","name":"user_id","required":true,"schema":{"type":"string"}}]},"/v1/plans":{"get":{"operationId":"listPlans","responses":{"200":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/PlanListResponse"}}},"description":"价格档位列表(Core + Compliance)"}},"security":[],"summary":"公开价格档位","tags":["Plans"]}},"/v1/probe/dns":{"post":{"operationId":"probeDns","requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/DnsProbeRequest"}}},"required":true},"responses":{"200":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/DnsProbeResponse"}}},"description":"DNS 解析结果"}},"summary":"多地 DNS 解析","tags":["Probe"]}},"/v1/probe/http":{"post":{"description":"从指定节点池或指定节点 ID 发起 HTTP 拨测;支持 sync(默认,等待结果)/ async(callback_url)。\n权重 3。\n","operationId":"probeHttp","requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/HttpProbeRequest"}}},"required":true},"responses":{"200":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/HttpProbeResponse"}}},"description":"拨测结果(sync)"},"202":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ProbeTaskAccepted"}}},"description":"拨测已入队(async)"},"400":{"$ref":"#/components/responses/BadRequest"},"422":{"$ref":"#/components/responses/Unprocessable"},"429":{"$ref":"#/components/responses/RateLimited"}},"summary":"多地 HTTP/HTTPS 拨测","tags":["Probe"]}},"/v1/probe/mtr":{"post":{"operationId":"probeMtr","requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/GenericProbeRequest"}}},"required":true},"responses":{"200":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ProbeTaskAccepted"}}},"description":"结果"},"202":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ProbeTaskAccepted"}}},"description":"已入队"},"400":{"$ref":"#/components/responses/BadRequest"}},"summary":"多地 MTR(路由质量)拨测","tags":["Probe"]}},"/v1/probe/ntp":{"post":{"operationId":"probeNtp","requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/GenericProbeRequest"}}},"required":true},"responses":{"200":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ProbeTaskAccepted"}}},"description":"结果"},"202":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ProbeTaskAccepted"}}},"description":"已入队"},"400":{"$ref":"#/components/responses/BadRequest"}},"summary":"多地 NTP 拨测","tags":["Probe"]}},"/v1/probe/ping":{"post":{"operationId":"probePing","requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/PingProbeRequest"}}},"required":true},"responses":{"200":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/PingProbeResponse"}}},"description":"Ping 结果"},"400":{"$ref":"#/components/responses/BadRequest"},"429":{"$ref":"#/components/responses/RateLimited"}},"summary":"多地 Ping","tags":["Probe"]}},"/v1/probe/smtp":{"post":{"operationId":"probeSmtp","requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/GenericProbeRequest"}}},"required":true},"responses":{"200":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ProbeTaskAccepted"}}},"description":"结果"},"202":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ProbeTaskAccepted"}}},"description":"已入队"},"400":{"$ref":"#/components/responses/BadRequest"}},"summary":"多地 SMTP 拨测","tags":["Probe"]}},"/v1/probe/speedtest":{"post":{"operationId":"probeSpeedtest","requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/GenericProbeRequest"}}},"required":true},"responses":{"200":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ProbeTaskAccepted"}}},"description":"结果"},"202":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ProbeTaskAccepted"}}},"description":"已入队"},"400":{"$ref":"#/components/responses/BadRequest"}},"summary":"多地测速拨测","tags":["Probe"]}},"/v1/probe/tasks/{taskId}":{"get":{"operationId":"getProbeTask","responses":{"200":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/HttpProbeResponse"}}},"description":"任务状态 + 结果(若已完成)"}},"summary":"查询拨测任务状态(async)","tags":["Probe"]},"parameters":[{"description":"拨测任务 ID","in":"path","name":"taskId","required":true,"schema":{"type":"string"}}]},"/v1/probe/tcp":{"post":{"operationId":"probeTcp","requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/GenericProbeRequest"}}},"required":true},"responses":{"200":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ProbeTaskAccepted"}}},"description":"拨测结果(sync)"},"202":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ProbeTaskAccepted"}}},"description":"拨测已入队(async)"},"400":{"$ref":"#/components/responses/BadRequest"},"422":{"$ref":"#/components/responses/Unprocessable"}},"summary":"多地 TCP 连接拨测","tags":["Probe"]}},"/v1/probe/tcping":{"post":{"operationId":"probeTcping","requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/TcpingProbeRequest"}}},"required":true},"responses":{"200":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/PingProbeResponse"}}},"description":"TCP Ping 结果"}},"summary":"多地 TCP Ping","tags":["Probe"]}},"/v1/probe/traceroute":{"post":{"operationId":"probeTraceroute","requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/TracerouteRequest"}}},"required":true},"responses":{"200":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/TracerouteResponse"}}},"description":"Traceroute 结果"}},"summary":"多地路由追踪","tags":["Probe"]}},"/v1/probe/udp":{"post":{"operationId":"probeUdp","requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/GenericProbeRequest"}}},"required":true},"responses":{"200":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ProbeTaskAccepted"}}},"description":"结果"},"202":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ProbeTaskAccepted"}}},"description":"已入队"},"400":{"$ref":"#/components/responses/BadRequest"}},"summary":"多地 UDP 可达性拨测","tags":["Probe"]}},"/v1/probe/websocket":{"post":{"operationId":"probeWebsocket","requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/GenericProbeRequest"}}},"required":true},"responses":{"200":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ProbeTaskAccepted"}}},"description":"结果"},"202":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ProbeTaskAccepted"}}},"description":"已入队"},"400":{"$ref":"#/components/responses/BadRequest"}},"summary":"多地 WebSocket 握手拨测","tags":["Probe"]}},"/v1/referral/code":{"get":{"operationId":"getReferralCode","responses":{"200":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ReferralCodeResponse"}}},"description":"推荐码"}},"summary":"读取我的推荐码","tags":["Account"]},"post":{"operationId":"createReferralCode","responses":{"201":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ReferralCodeResponse"}}},"description":"推荐码"}},"summary":"获取或生成推荐码","tags":["Account"]}},"/v1/referral/rewards":{"get":{"operationId":"listReferralRewards","responses":{"200":{"content":{"application/json":{"schema":{"properties":{"data":{"properties":{"account_balance":{"example":"10.00","type":"string"},"rewards":{"items":{"additionalProperties":true,"type":"object"},"type":"array"},"total_credited":{"example":"10.00","type":"string"},"total_pending":{"example":"20.00","type":"string"}},"type":"object"},"request_id":{"type":"string"}},"type":"object"}}},"description":"推荐奖励"}},"summary":"读取推荐奖励","tags":["Account"]}},"/v1/reports/alert-noise":{"get":{"operationId":"getAlertNoiseReport","parameters":[{"in":"query","name":"days","schema":{"default":30,"maximum":365,"type":"integer"}}],"responses":{"200":{"content":{"application/json":{"schema":{"properties":{"data":{"properties":{"daily_trend":{"items":{"properties":{"date":{"type":"string"},"firings":{"type":"integer"},"flaps":{"type":"integer"}},"type":"object"},"type":"array"},"noisiest_monitors":{"items":{"properties":{"firings":{"type":"integer"},"flaps":{"type":"integer"},"monitor_id":{"type":"string"}},"type":"object"},"type":"array"},"period":{"properties":{"from":{"format":"date-time","type":"string"},"to":{"format":"date-time","type":"string"}},"type":"object"},"total_firings":{"type":"integer"},"total_flaps":{"type":"integer"}},"type":"object"},"request_id":{"type":"string"}},"type":"object"}}},"description":"噪音报表"}},"summary":"告警噪音报表(firings / flaps / 最吵监控 / 日趋势)","tags":["Reports"]}},"/v1/reports/sla":{"get":{"operationId":"getSlaReport","parameters":[{"example":"2026-04","in":"query","name":"period","required":true,"schema":{"pattern":"^\\d{4}-\\d{2}$","type":"string"}}],"responses":{"200":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/SlaReport"}}},"description":"SLA 报告"}},"summary":"SLA 报告","tags":["Reports"]}},"/v1/sponsors/{user_id}":{"get":{"description":"节点详情页、拨测/工具结果 footer 用于\"由 X 节点(提供者: Y)\"透出。\n未审核 / free 档 / 已拒绝的 sponsor 一律返回 404(避免泄露审批状态)。\n响应不含 approved_by / rejected_at / reject_reason 审核字段。\n","operationId":"sponsorProfilePublicGet","parameters":[{"in":"path","name":"user_id","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"公开 sponsor 信息"},"404":{"description":"未找到或不公开"}},"summary":"公开查询 sponsor profile(仅 approved + tier∈verified|premium)","tags":["Sponsor"]}},"/v1/status-pages":{"get":{"operationId":"listStatusPages","responses":{"200":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/StatusPageListResponse"}}},"description":"状态页列表"}},"summary":"列出状态页","tags":["Status Pages"]},"post":{"operationId":"createStatusPage","requestBody":{"content":{"application/json":{"schema":{"properties":{"description":{"type":"string"},"is_public":{"type":"boolean"},"name":{"type":"string"},"slug":{"type":"string"}},"required":["name","slug"],"type":"object"}}},"required":true},"responses":{"201":{"content":{"application/json":{"schema":{"properties":{"data":{"properties":{"status_page":{"$ref":"#/components/schemas/StatusPageItem"}},"type":"object"},"request_id":{"type":"string"}},"type":"object"}}},"description":"已创建"},"400":{"$ref":"#/components/responses/BadRequest"},"409":{"$ref":"#/components/responses/Conflict"}},"summary":"创建状态页","tags":["Status Pages"]}},"/v1/status-pages/{id}":{"delete":{"operationId":"deleteStatusPage","responses":{"204":{"description":"已删除"}},"summary":"删除状态页","tags":["Status Pages"]},"get":{"operationId":"getStatusPage","responses":{"200":{"content":{"application/json":{"schema":{"properties":{"data":{"properties":{"status_page":{"$ref":"#/components/schemas/StatusPageItem"}},"type":"object"},"request_id":{"type":"string"}},"type":"object"}}},"description":"状态页"},"404":{"$ref":"#/components/responses/NotFound"}},"summary":"状态页详情","tags":["Status Pages"]},"parameters":[{"$ref":"#/components/parameters/ResourceId"}],"patch":{"operationId":"updateStatusPage","requestBody":{"content":{"application/json":{"schema":{"properties":{"description":{"description":"状态页描述(handler 读取 req.Description，此前 spec 漏列)","type":"string"},"is_public":{"type":"boolean"},"name":{"type":"string"},"slug":{"type":"string"}},"required":["name","slug"],"type":"object"}}},"required":true},"responses":{"200":{"$ref":"#/components/responses/OkTrue"},"400":{"$ref":"#/components/responses/BadRequest"}},"summary":"更新状态页","tags":["Status Pages"]}},"/v1/status-pages/{id}/domain":{"parameters":[{"$ref":"#/components/parameters/ResourceId"}],"patch":{"operationId":"setStatusPageDomain","requestBody":{"content":{"application/json":{"schema":{"properties":{"custom_domain":{"description":"空字符串清除","type":"string"}},"type":"object"}}},"required":true},"responses":{"200":{"content":{"application/json":{"schema":{"properties":{"data":{"properties":{"custom_domain":{"type":"string"},"instructions":{"type":"string"},"verified":{"type":"boolean"}},"type":"object"},"request_id":{"type":"string"}},"type":"object"}}},"description":"域名设置结果"}},"summary":"设置/清除自定义域名","tags":["Status Pages"]}},"/v1/status-pages/{id}/domain/verify":{"get":{"operationId":"verifyStatusPageDomain","responses":{"200":{"content":{"application/json":{"schema":{"properties":{"data":{"properties":{"error":{"type":"string"},"transient":{"description":"true=DNS 瞬时不可用，可稍后重试（非配置错误）","type":"boolean"},"verified":{"type":"boolean"}},"type":"object"},"request_id":{"type":"string"}},"type":"object"}}},"description":"校验结果"}},"summary":"校验自定义域名 DNS 配置","tags":["Status Pages"]},"parameters":[{"$ref":"#/components/parameters/ResourceId"}]},"/v1/status-pages/{id}/incidents":{"get":{"operationId":"listStatusPageIncidents","parameters":[{"in":"query","name":"page","schema":{"default":1,"minimum":1,"type":"integer"}},{"in":"query","name":"limit","schema":{"default":20,"maximum":100,"minimum":1,"type":"integer"}}],"responses":{"200":{"content":{"application/json":{"schema":{"properties":{"data":{"properties":{"incidents":{"items":{"$ref":"#/components/schemas/StatusPageIncident"},"type":"array"},"limit":{"type":"integer"},"page":{"type":"integer"},"total":{"type":"integer"}},"type":"object"},"request_id":{"type":"string"}},"type":"object"}}},"description":"事件列表"}},"summary":"列出状态页事件（含更新时间线）","tags":["Status Pages"]},"parameters":[{"$ref":"#/components/parameters/ResourceId"}],"post":{"operationId":"createStatusPageIncident","requestBody":{"content":{"application/json":{"schema":{"properties":{"affected_monitor_ids":{"items":{"type":"string"},"type":"array"},"body":{"description":"首条更新正文","type":"string"},"impact":{"default":"minor","enum":["minor","major","critical"],"type":"string"},"status":{"default":"investigating","enum":["investigating","identified","monitoring","resolved"],"type":"string"},"title":{"type":"string"}},"required":["title","body"],"type":"object"}}},"required":true},"responses":{"201":{"content":{"application/json":{"schema":{"properties":{"data":{"properties":{"id":{"type":"string"}},"type":"object"},"request_id":{"type":"string"}},"type":"object"}}},"description":"已创建"},"400":{"$ref":"#/components/responses/BadRequest"}},"summary":"创建状态页事件（含首条更新）","tags":["Status Pages"]}},"/v1/status-pages/{id}/incidents/{incidentId}":{"delete":{"operationId":"deleteStatusPageIncident","responses":{"204":{"description":"已删除"},"404":{"$ref":"#/components/responses/NotFound"}},"summary":"删除状态页事件","tags":["Status Pages"]},"parameters":[{"$ref":"#/components/parameters/ResourceId"},{"in":"path","name":"incidentId","required":true,"schema":{"type":"string"}}]},"/v1/status-pages/{id}/incidents/{incidentId}/updates":{"parameters":[{"$ref":"#/components/parameters/ResourceId"},{"in":"path","name":"incidentId","required":true,"schema":{"type":"string"}}],"post":{"operationId":"addStatusPageIncidentUpdate","requestBody":{"content":{"application/json":{"schema":{"properties":{"body":{"type":"string"},"status":{"enum":["investigating","identified","monitoring","resolved"],"type":"string"}},"required":["status","body"],"type":"object"}}},"required":true},"responses":{"201":{"content":{"application/json":{"schema":{"properties":{"data":{"properties":{"id":{"type":"string"}},"type":"object"},"request_id":{"type":"string"}},"type":"object"}}},"description":"已追加"},"400":{"$ref":"#/components/responses/BadRequest"},"404":{"$ref":"#/components/responses/NotFound"}},"summary":"追加事件更新并推进事件状态","tags":["Status Pages"]}},"/v1/status-pages/{id}/monitors":{"get":{"operationId":"listStatusPageMonitors","responses":{"200":{"content":{"application/json":{"schema":{"properties":{"data":{"properties":{"monitors":{"items":{"properties":{"monitor_id":{"type":"string"},"name":{"type":"string"},"status":{"type":"string"},"target":{"type":"string"},"type":{"type":"string"}},"type":"object"},"type":"array"}},"type":"object"},"request_id":{"type":"string"}},"type":"object"}}},"description":"关联监控"}},"summary":"列出状态页关联的监控","tags":["Status Pages"]},"parameters":[{"$ref":"#/components/parameters/ResourceId"}],"post":{"operationId":"addStatusPageMonitor","requestBody":{"content":{"application/json":{"schema":{"properties":{"monitor_id":{"type":"string"}},"required":["monitor_id"],"type":"object"}}},"required":true},"responses":{"201":{"$ref":"#/components/responses/OkTrue"},"400":{"$ref":"#/components/responses/BadRequest"}},"summary":"关联监控到状态页","tags":["Status Pages"]}},"/v1/status-pages/{id}/monitors/reorder":{"parameters":[{"$ref":"#/components/parameters/ResourceId"}],"patch":{"description":"body 传完整有序 monitor_id 列表；display_order 重写为列表位置（1 起）。列表须为该状态页关联监控的完整集合（非空、无重复、不含未关联 id），校验与更新同一语句原子执行，不满足则整体 400、零行变更。","operationId":"reorderStatusPageMonitors","requestBody":{"content":{"application/json":{"schema":{"properties":{"monitor_ids":{"items":{"type":"string"},"minItems":1,"type":"array"}},"required":["monitor_ids"],"type":"object"}}},"required":true},"responses":{"200":{"$ref":"#/components/responses/OkTrue"},"400":{"$ref":"#/components/responses/BadRequest"}},"summary":"调整状态页监控显示顺序","tags":["Status Pages"]}},"/v1/status-pages/{id}/monitors/{monitorId}":{"delete":{"operationId":"removeStatusPageMonitor","responses":{"204":{"description":"已移除"}},"summary":"从状态页移除监控","tags":["Status Pages"]},"parameters":[{"$ref":"#/components/parameters/ResourceId"},{"in":"path","name":"monitorId","required":true,"schema":{"type":"string"}}]},"/v1/status-pages/{slug}/public":{"get":{"description":"公开状态页数据,按 slug 或自定义域名访问。响应为**手动拼装并缓存**的裸 JSON\n信封(非通用 `{data,request_id}` 包裹),支持 `If-None-Match` → `304`。\n","operationId":"getStatusPagePublic","responses":{"200":{"content":{"application/json":{"schema":{"properties":{"branding":{"additionalProperties":true,"nullable":true,"type":"object"},"description":{"nullable":true,"type":"string"},"events":{"items":{"additionalProperties":true,"type":"object"},"type":"array"},"groups":{"items":{"properties":{"id":{"type":"string"},"monitors":{"items":{"properties":{"id":{"type":"string"},"name":{"type":"string"},"status":{"type":"string"}},"type":"object"},"type":"array"},"name":{"type":"string"},"status":{"type":"string"}},"type":"object"},"type":"array"},"overall_status":{"enum":["operational","degraded","partial_outage","major_outage","maintenance"],"type":"string"},"slug":{"type":"string"},"title":{"type":"string"}},"type":"object"}}},"description":"公开状态页(裸 JSON,含 ETag 头)"},"304":{"description":"未修改(ETag 命中)"},"404":{"$ref":"#/components/responses/NotFound"}},"security":[],"summary":"状态页公开视图(无需鉴权;支持 ETag 协商缓存)","tags":["Status Pages"]},"parameters":[{"in":"path","name":"slug","required":true,"schema":{"type":"string"}}]},"/v1/status-pages/{slug}/subscribe":{"parameters":[{"in":"path","name":"slug","required":true,"schema":{"type":"string"}}],"post":{"operationId":"subscribeStatusPage","requestBody":{"content":{"application/json":{"schema":{"properties":{"channel_type":{"enum":["email","webhook","wecom","dingtalk"],"type":"string"},"endpoint":{"type":"string"},"events":{"items":{"type":"string"},"type":"array"},"locale":{"type":"string"}},"required":["channel_type","endpoint"],"type":"object"}}},"required":true},"responses":{"201":{"content":{"application/json":{"schema":{"properties":{"data":{"properties":{"channel_type":{"type":"string"},"created_at":{"format":"date-time","type":"string"},"endpoint":{"type":"string"},"events":{"items":{"type":"string"},"type":"array"},"id":{"type":"string"},"verified":{"type":"boolean"}},"type":"object"},"request_id":{"type":"string"}},"type":"object"}}},"description":"订阅创建(待验证)"},"400":{"$ref":"#/components/responses/BadRequest"}},"security":[],"summary":"订阅状态页变更通知(公开)","tags":["Status Pages"]}},"/v1/status-pages/{slug}/subscriptions":{"get":{"operationId":"listStatusPageSubscriptions","responses":{"200":{"content":{"application/json":{"schema":{"properties":{"data":{"items":{"properties":{"channel_type":{"type":"string"},"created_at":{"format":"date-time","type":"string"},"endpoint":{"type":"string"},"events":{"items":{"type":"string"},"type":"array"},"id":{"type":"string"},"verified":{"type":"boolean"}},"type":"object"},"type":"array"},"request_id":{"type":"string"}},"type":"object"}}},"description":"订阅列表"}},"summary":"列出状态页订阅(Bearer,页主)","tags":["Status Pages"]},"parameters":[{"in":"path","name":"slug","required":true,"schema":{"type":"string"}}]},"/v1/status-pages/{slug}/subscriptions/{id}":{"delete":{"operationId":"deleteStatusPageSubscription","responses":{"204":{"description":"已删除"}},"summary":"删除订阅(Bearer,页主)","tags":["Status Pages"]},"parameters":[{"in":"path","name":"slug","required":true,"schema":{"type":"string"}},{"$ref":"#/components/parameters/ResourceId"}]},"/v1/status-pages/{slug}/unsubscribe":{"delete":{"operationId":"unsubscribeStatusPageApi","responses":{"200":{"content":{"application/json":{"schema":{"properties":{"data":{"properties":{"status":{"example":"unsubscribed","type":"string"}},"type":"object"},"request_id":{"type":"string"}},"type":"object"}}},"description":"已退订"}},"security":[],"summary":"退订(公开,API 形式)","tags":["Status Pages"]},"get":{"operationId":"unsubscribeStatusPagePrompt","responses":{"200":{"content":{"text/html":{"schema":{"type":"string"}}},"description":"HTML 确认页"}},"security":[],"summary":"退订确认页(公开,返回 HTML 表单 — RFC 8058)","tags":["Status Pages"]},"parameters":[{"in":"path","name":"slug","required":true,"schema":{"type":"string"}},{"in":"query","name":"token","required":true,"schema":{"type":"string"}}],"post":{"operationId":"unsubscribeStatusPageConfirm","responses":{"200":{"content":{"text/html":{"schema":{"type":"string"}}},"description":"HTML 完成页"}},"security":[],"summary":"退订(公开,one-click,返回 HTML 完成页)","tags":["Status Pages"]}},"/v1/status-pages/{slug}/verify":{"get":{"operationId":"verifyStatusPageSubscription","parameters":[{"in":"query","name":"token","required":true,"schema":{"type":"string"}}],"responses":{"200":{"content":{"application/json":{"schema":{"properties":{"data":{"properties":{"verified":{"example":true,"type":"boolean"}},"type":"object"},"request_id":{"type":"string"}},"type":"object"}}},"description":"已验证"}},"security":[],"summary":"验证状态页订阅邮箱(公开)","tags":["Status Pages"]},"parameters":[{"in":"path","name":"slug","required":true,"schema":{"type":"string"}}]},"/v1/teams":{"get":{"operationId":"listTeams","responses":{"200":{"content":{"application/json":{"schema":{"properties":{"data":{"properties":{"teams":{"items":{"$ref":"#/components/schemas/Team"},"type":"array"}},"type":"object"},"request_id":{"type":"string"}},"type":"object"}}},"description":"团队列表"}},"summary":"列出我的团队","tags":["Teams"]},"post":{"operationId":"createTeam","requestBody":{"content":{"application/json":{"schema":{"properties":{"name":{"type":"string"},"slug":{"type":"string"}},"required":["name","slug"],"type":"object"}}},"required":true},"responses":{"201":{"content":{"application/json":{"schema":{"properties":{"data":{"properties":{"team":{"$ref":"#/components/schemas/Team"}},"type":"object"},"request_id":{"type":"string"}},"type":"object"}}},"description":"已创建"},"400":{"$ref":"#/components/responses/BadRequest"},"409":{"$ref":"#/components/responses/Conflict"}},"summary":"创建团队","tags":["Teams"]}},"/v1/teams/accept-invitation":{"post":{"operationId":"acceptTeamInvitation","requestBody":{"content":{"application/json":{"schema":{"properties":{"token":{"type":"string"}},"required":["token"],"type":"object"}}},"required":true},"responses":{"200":{"content":{"application/json":{"schema":{"properties":{"data":{"$ref":"#/components/schemas/Team"},"request_id":{"type":"string"}},"type":"object"}}},"description":"已加入"},"400":{"$ref":"#/components/responses/BadRequest"}},"summary":"接受团队邀请","tags":["Teams"]}},"/v1/teams/{id}":{"delete":{"operationId":"deleteTeam","responses":{"200":{"$ref":"#/components/responses/MessageOK"}},"summary":"删除团队","tags":["Teams"]},"get":{"operationId":"getTeam","responses":{"200":{"content":{"application/json":{"schema":{"properties":{"data":{"properties":{"members":{"items":{"additionalProperties":true,"type":"object"},"type":"array"},"team":{"$ref":"#/components/schemas/Team"}},"type":"object"},"request_id":{"type":"string"}},"type":"object"}}},"description":"团队详情"},"404":{"$ref":"#/components/responses/NotFound"}},"summary":"团队详情(含成员)","tags":["Teams"]},"parameters":[{"$ref":"#/components/parameters/ResourceId"}],"patch":{"operationId":"updateTeam","requestBody":{"content":{"application/json":{"schema":{"properties":{"name":{"type":"string"}},"type":"object"}}},"required":true},"responses":{"200":{"content":{"application/json":{"schema":{"properties":{"data":{"properties":{"team":{"$ref":"#/components/schemas/Team"}},"type":"object"},"request_id":{"type":"string"}},"type":"object"}}},"description":"已更新"}},"summary":"更新团队","tags":["Teams"]}},"/v1/teams/{id}/api-keys":{"get":{"operationId":"listTeamApiKeys","responses":{"200":{"content":{"application/json":{"schema":{"properties":{"data":{"properties":{"api_keys":{"items":{"additionalProperties":true,"type":"object"},"type":"array"}},"type":"object"},"request_id":{"type":"string"}},"type":"object"}}},"description":"API Key 列表"}},"summary":"列出团队 API Key","tags":["Teams"]},"parameters":[{"$ref":"#/components/parameters/ResourceId"}],"post":{"operationId":"createTeamApiKey","requestBody":{"content":{"application/json":{"schema":{"properties":{"key_type":{"enum":["test","production"],"type":"string"},"name":{"type":"string"}},"required":["name","key_type"],"type":"object"}}},"required":true},"responses":{"201":{"content":{"application/json":{"schema":{"properties":{"data":{"properties":{"api_key":{"additionalProperties":true,"type":"object"}},"type":"object"},"request_id":{"type":"string"}},"type":"object"}}},"description":"已创建"},"400":{"$ref":"#/components/responses/BadRequest"}},"summary":"创建团队 API Key(secret 仅返回一次)","tags":["Teams"]}},"/v1/teams/{id}/api-keys/{key_id}":{"delete":{"operationId":"deleteTeamApiKey","responses":{"200":{"$ref":"#/components/responses/MessageOK"}},"summary":"删除团队 API Key","tags":["Teams"]},"parameters":[{"$ref":"#/components/parameters/ResourceId"},{"in":"path","name":"key_id","required":true,"schema":{"type":"string"}}]},"/v1/teams/{id}/billing/subscribe":{"parameters":[{"$ref":"#/components/parameters/ResourceId"}],"post":{"operationId":"teamBillingSubscribe","requestBody":{"content":{"application/json":{"schema":{"properties":{"coupon":{"type":"string"},"plan":{"type":"string"}},"required":["plan"],"type":"object"}}},"required":true},"responses":{"200":{"content":{"application/json":{"schema":{"properties":{"data":{"properties":{"expires_at":{"format":"date-time","type":"string"},"pay_url":{"type":"string"},"subscription_id":{"type":"string"}},"type":"object"},"request_id":{"type":"string"}},"type":"object"}}},"description":"待支付"}},"summary":"团队订阅付费计划","tags":["Teams"]}},"/v1/teams/{id}/billing/subscription":{"get":{"operationId":"getTeamBillingSubscription","responses":{"200":{"content":{"application/json":{"schema":{"properties":{"data":{"additionalProperties":true,"nullable":true,"type":"object"},"request_id":{"type":"string"}},"type":"object"}}},"description":"团队订阅"}},"summary":"读取团队订阅","tags":["Teams"]},"parameters":[{"$ref":"#/components/parameters/ResourceId"}]},"/v1/teams/{id}/invitations":{"get":{"operationId":"listTeamInvitations","responses":{"200":{"content":{"application/json":{"schema":{"properties":{"data":{"properties":{"invitations":{"items":{"additionalProperties":true,"type":"object"},"type":"array"}},"type":"object"},"request_id":{"type":"string"}},"type":"object"}}},"description":"邀请列表"}},"summary":"列出团队邀请","tags":["Teams"]},"parameters":[{"$ref":"#/components/parameters/ResourceId"}],"post":{"operationId":"createTeamInvitation","requestBody":{"content":{"application/json":{"schema":{"properties":{"email":{"format":"email","type":"string"},"role":{"enum":["admin","member"],"type":"string"}},"required":["email"],"type":"object"}}},"required":true},"responses":{"201":{"content":{"application/json":{"schema":{"properties":{"data":{"properties":{"invitation":{"additionalProperties":true,"type":"object"}},"type":"object"},"request_id":{"type":"string"}},"type":"object"}}},"description":"已发送(含 token / invite_url)"},"400":{"$ref":"#/components/responses/BadRequest"}},"summary":"发送团队邀请","tags":["Teams"]}},"/v1/teams/{id}/invitations/{inv_id}":{"delete":{"operationId":"revokeTeamInvitation","responses":{"200":{"$ref":"#/components/responses/MessageOK"}},"summary":"撤销团队邀请","tags":["Teams"]},"parameters":[{"$ref":"#/components/parameters/ResourceId"},{"in":"path","name":"inv_id","required":true,"schema":{"type":"string"}}]},"/v1/teams/{id}/members":{"get":{"operationId":"listTeamMembers","responses":{"200":{"content":{"application/json":{"schema":{"properties":{"data":{"properties":{"members":{"items":{"additionalProperties":true,"type":"object"},"type":"array"}},"type":"object"},"request_id":{"type":"string"}},"type":"object"}}},"description":"成员列表"}},"summary":"列出团队成员","tags":["Teams"]},"parameters":[{"$ref":"#/components/parameters/ResourceId"}]},"/v1/teams/{id}/members/{user_id}":{"delete":{"operationId":"removeTeamMember","responses":{"200":{"$ref":"#/components/responses/MessageOK"}},"summary":"移除团队成员","tags":["Teams"]},"parameters":[{"$ref":"#/components/parameters/ResourceId"},{"in":"path","name":"user_id","required":true,"schema":{"type":"string"}}],"patch":{"operationId":"updateTeamMemberRole","requestBody":{"content":{"application/json":{"schema":{"properties":{"role":{"enum":["owner","admin","member"],"type":"string"}},"required":["role"],"type":"object"}}},"required":true},"responses":{"200":{"$ref":"#/components/responses/MessageOK"}},"summary":"修改成员角色","tags":["Teams"]}},"/v1/transparency":{"get":{"description":"公开运行状态仪表盘:平台可用率 / 节点覆盖 / 近期事故 / 申诉统计。\n任何人可访问, 无 auth。\noverall_status 由真实 30 天可用率派生(\u003e=99% → operational, 否则 degraded);\n无可用率样本时为 null。platform_uptime 各窗口在无样本时为 null(区分「无数据」\n与真实 0%),nodes.total / nodes.active 在无数据源(DB 不可用或查询失败)时为\nnull,nodes.regions(覆盖地区 = 活跃节点 country_code 去重计数)在无地理\n元数据时为 null;均不编造占位数字。recent_incidents / appeal_stats\n在 S2 真实数据源就绪前返回 null(前端渲染「数据准备中」占位,不编造数据)。\n(kms / tsa 已按 DECISIONS §P / D-V3-03 从本接口移除:Verdict 降级本地 RSA 自签,\n去商业 KMS + TSA。)\n","operationId":"getTransparency","responses":{"200":{"content":{"application/json":{"schema":{"properties":{"data":{"properties":{"appeal_stats":{"description":"S2 前为 null","nullable":true,"properties":{"avg_resolution_h":{"type":"number"},"pending":{"type":"integer"},"resolved":{"type":"integer"},"total":{"type":"integer"}},"type":"object"},"last_updated":{"format":"date-time","type":"string"},"nodes":{"properties":{"active":{"description":"无数据源(DB 不可用/查询失败)时为 null,不编造占位数字","nullable":true,"type":"integer"},"regions":{"description":"活跃节点 country_code 去重计数;无地理元数据时为 null","nullable":true,"type":"integer"},"total":{"description":"无数据源(DB 不可用/查询失败)时为 null,不编造占位数字","nullable":true,"type":"integer"}},"type":"object"},"overall_status":{"description":"无可用率样本时为 null","enum":["operational","degraded"],"nullable":true,"type":"string"},"platform_uptime":{"description":"各窗口在无样本时为 null(区分无数据与真实 0%)","properties":{"30d":{"nullable":true,"type":"number"},"365d":{"nullable":true,"type":"number"},"90d":{"nullable":true,"type":"number"}},"type":"object"},"recent_incidents":{"description":"S2 前为 null","items":{"properties":{"date":{"type":"string"},"duration_min":{"type":"integer"},"resolved":{"type":"boolean"},"severity":{"type":"string"},"title":{"type":"string"}},"type":"object"},"nullable":true,"type":"array"}},"type":"object"},"request_id":{"type":"string"}},"type":"object"}}},"description":"透明度仪表盘数据"}},"summary":"平台透明度公开仪表盘","tags":["Meta"]}},"/v1/uploads/init":{"post":{"description":"服务端选 key + 校验 size/content_type/限流 → 登记 pending storage_object → 返回短时 presigned PUT URL 及浏览器需回传的 header(x-oss-forbid-overwrite: true 已签名做写一次,Content-Type 未签名但应回传)。AK 不出后端。仅 presigned_put 策略(§0.2)。\n","operationId":"uploadsInit","requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/UploadInitRequest"}}},"required":true},"responses":{"201":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/UploadInitResponse"}}},"description":"已登记 pending 并签发凭证"},"400":{"$ref":"#/components/responses/BadRequest"},"401":{"$ref":"#/components/responses/Unauthorized"},"409":{"$ref":"#/components/responses/Conflict"},"429":{"$ref":"#/components/responses/RateLimited"},"503":{"$ref":"#/components/responses/ServiceUnavailable"}},"summary":"初始化直传(签发 presigned PUT)","tags":["Uploads"]}},"/v1/uploads/{id}/commit":{"post":{"description":"服务端 HeadObject 实测 size/type(绝不信前端上报)→ 与 init pin 的约束比对 越界拒绝 → 守卫式 pending→committed(二次 commit = 409,天然一次性)。\n","operationId":"uploadsCommit","parameters":[{"description":"init 返回的 object_id","in":"path","name":"id","required":true,"schema":{"type":"string"}}],"responses":{"200":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/UploadCommitResponse"}}},"description":"已确认"},"400":{"$ref":"#/components/responses/BadRequest"},"401":{"$ref":"#/components/responses/Unauthorized"},"404":{"$ref":"#/components/responses/NotFound"},"409":{"$ref":"#/components/responses/Conflict"},"503":{"$ref":"#/components/responses/ServiceUnavailable"}},"summary":"确认直传(HeadObject 实测 → committed)","tags":["Uploads"]}},"/v1/verdict/orders":{"get":{"description":"返回当前登录用户自己创建的 Verdict 订单,按 `created_at` 倒序、分页。\nOwner 过滤在 SQL 层(`WHERE owner_id = \u003ccaller\u003e`),不会返回他人订单。\n`total` 为该用户订单总数的独立 COUNT(不受 `offset` 越界影响)。\n","operationId":"listVerdictOrders","parameters":[{"in":"query","name":"limit","required":false,"schema":{"default":20,"maximum":100,"minimum":1,"type":"integer"}},{"in":"query","name":"offset","required":false,"schema":{"default":0,"minimum":0,"type":"integer"}}],"responses":{"200":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ListVerdictOrdersResponse"}}},"description":"分页的存证订单列表"}},"servers":[{"url":"https://attest.idcd.com"}],"summary":"我的存证列表(当前用户自己的 Verdict 订单)","tags":["Verdict"]},"post":{"description":"创建订单 → 返回 聚合支付 checkout URL(用户跳转支付)。\n支付完成由 聚合支付 webhook → `verdict_order(status=paid)` → 进入 generation queue。\n状态机:`pending → paid → generating → delivered`(成功)或\n`pending → paid → generating → failed → refunded`(D5 兑底)或\n`... → refund_failed`(D5 兑底失败,P0 告警 + admin dashboard)。\n","operationId":"createVerdictOrder","requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/CreateVerdictOrderRequest"}}},"required":true},"responses":{"201":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/CreateVerdictOrderResponse"}}},"description":"订单创建成功 + 聚合支付 checkout URL"},"400":{"$ref":"#/components/responses/BadRequest"},"422":{"$ref":"#/components/responses/Unprocessable"}},"servers":[{"url":"https://attest.idcd.com"}],"summary":"创建 Verdict 订单","tags":["Verdict"]}},"/v1/verdict/orders/{id}":{"get":{"description":"返回完整状态机字段。SLA 承诺:90% 报告 60s 内生成,99% 5min 内。\n失败 → `status=failed → refunded`;refund 兑底失败 → `status=refund_failed`(D5)。\n","operationId":"getVerdictOrder","responses":{"200":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/VerdictOrder"}}},"description":"订单详情"},"404":{"$ref":"#/components/responses/NotFound"}},"summary":"订单状态查询","tags":["Verdict"]},"parameters":[{"$ref":"#/components/parameters/ResourceId"}],"servers":[{"url":"https://attest.idcd.com"}]},"/v1/verdict/reports/{id}":{"get":{"description":"返回报告详情(localfile RSA 签名 / 节点列表 / `report_type=observation_only`)。\n§P 轻量化:`pdf_url` / `archived_url` 由 DB 内部地址 `s3://idcd/\u003ckey\u003e` 经 API 出口\n(`lib/shared/objurl.PublicURL` + config `oss_public_base_url`)改写为公开下载 URL\n`https://oss.idcd.com/\u003ckey\u003e`(普通 OSS,非 WORM,长期可下载;非预签名,无过期)。\n`tsa_*` / `self_verify_status` / `blockchain_anchor` 字段保留但 §P 下不填充。\n","operationId":"getVerdictReport","responses":{"200":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/VerdictReport"}}},"description":"报告详情"},"404":{"$ref":"#/components/responses/NotFound"}},"summary":"报告详情 + PDF 下载链接","tags":["Verdict"]},"parameters":[{"$ref":"#/components/parameters/ResourceId"}],"servers":[{"url":"https://attest.idcd.com"}]},"/v1/version":{"get":{"operationId":"getVersion","responses":{"200":{"content":{"application/json":{"schema":{"properties":{"data":{"additionalProperties":true,"type":"object"},"request_id":{"type":"string"}},"type":"object"}}},"description":"版本"}},"security":[],"summary":"API 版本信息(公开)","tags":["Meta"]}},"/v1/wechat/bind/begin":{"post":{"operationId":"wechatBindBegin","responses":{"200":{"content":{"application/json":{"schema":{"properties":{"data":{"properties":{"expires_in":{"type":"integer"},"qr_image_url":{"type":"string"},"session_id":{"type":"string"}},"type":"object"},"request_id":{"type":"string"}},"type":"object"}}},"description":"绑定二维码"}},"summary":"微信绑定 - 申请二维码","tags":["Auth"]}},"/v1/wechat/bind/status":{"get":{"operationId":"wechatBindStatus","parameters":[{"in":"query","name":"session_id","required":true,"schema":{"type":"string"}}],"responses":{"200":{"content":{"application/json":{"schema":{"properties":{"data":{"properties":{"reason":{"type":"string"},"status":{"type":"string"}},"type":"object"},"request_id":{"type":"string"}},"type":"object"}}},"description":"绑定状态"}},"summary":"微信绑定 - 轮询状态","tags":["Auth"]}},"/v1/wechat/binding":{"delete":{"operationId":"deleteWechatBinding","responses":{"200":{"content":{"application/json":{"schema":{"properties":{"data":{"properties":{"bound":{"example":false,"type":"boolean"}},"type":"object"},"request_id":{"type":"string"}},"type":"object"}}},"description":"已解绑"}},"summary":"解绑微信","tags":["Auth"]},"get":{"operationId":"getWechatBinding","responses":{"200":{"content":{"application/json":{"schema":{"properties":{"data":{"properties":{"avatar":{"nullable":true,"type":"string"},"bound":{"type":"boolean"},"nickname":{"nullable":true,"type":"string"}},"type":"object"},"request_id":{"type":"string"}},"type":"object"}}},"description":"绑定信息"}},"summary":"读取当前微信绑定状态","tags":["Auth"]}},"/v1/wechat/jssdk-signature":{"get":{"description":"公开端点(#461):分享报告页 /r/{id} 用它获取 wx.config 所需的签名,以启用微信内\n「分享给好友 / 朋友圈」自定义卡片。公众号未配置 / 签名失败时优雅降级返回\nenabled=false(前端隐藏原生分享卡),绝不 5xx 破坏页面。无需登录。\n","operationId":"wechatJssdkSignature","parameters":[{"description":"当前页面完整 URL(用于签名)","in":"query","name":"url","required":true,"schema":{"type":"string"}}],"responses":{"200":{"content":{"application/json":{"schema":{"properties":{"data":{"properties":{"app_id":{"type":"string"},"enabled":{"type":"boolean"},"nonce_str":{"type":"string"},"signature":{"type":"string"},"timestamp":{"type":"string"}},"type":"object"},"request_id":{"type":"string"}},"type":"object"}}},"description":"签名结果(或 enabled=false 表示未启用)"},"400":{"$ref":"#/components/responses/BadRequest"}},"security":[],"summary":"微信 JS-SDK 签名(分享页 wx.config)","tags":["Auth"]}}},"security":[{"ApiKeyHeader":[]},{"BearerAuth":[]}],"servers":[{"description":"生产环境 — Core REST API(idcd.com 正式域)。server URL 不含 `/v1`;每条\npath 自带完整 `/v1/...` 前缀,故完整 URL 形如 `https://api.idcd.com/v1/auth/register`。\n","url":"https://api.idcd.com"},{"description":"当前线上生产环境 — Core REST API(唯一在用;品牌域 `api.idcd.com` 上线前对外即此域)","url":"https://api-prod.idcd.com"}],"tags":[{"description":"认证(注册 / 登录 / 2FA / session)","name":"Auth"},{"description":"API Key 签发与管理(Core REST API 凭证)","name":"API Keys"},{"description":"MCP token 签发与管理(D21)。token 走 `mcp.idcd.com` JSON-RPC,\n不是 Core REST API Key 体系。所有 token 必有 expires_at,最长 90 天;\n验证器接受的明文前缀为 `idcd_mcp_*`(行 ID 前缀为 `mcpt_*`)。\n","name":"MCP Tokens"},{"description":"账户资料 / 密码 / 2FA / passkey / session / PAT / 通知偏好 / 积分 / 推荐 / beta","name":"Account"},{"description":"团队 / 组织 / 成员","name":"Teams"},{"description":"一次性拨测(http / ping / tcping / dns / traceroute / mtr / udp / speedtest / websocket)","name":"Probe"},{"description":"一键全面诊断","name":"Diagnose"},{"description":"IP / ASN / WHOIS / DNS / SSL / ICP / Headers 网络信息查询","name":"Network Info"},{"description":"监控项(M01-M23,含 Agent obs 的 M21-M23)","name":"Monitors"},{"description":"告警策略 / 事件 / 通道","name":"Alerting"},{"description":"状态页(私有管理 + 公开访问)","name":"Status Pages"},{"description":"SLA 报告 / 告警噪音 / Dashboard 概览","name":"Reports"},{"description":"值班排班(rotation / participants / overrides / 当前值班)","name":"On-Call"},{"description":"故障复盘(从告警事件创建 postmortem 草稿 / 编辑)","name":"Incidents"},{"description":"元信息(版本等公开只读端点)","name":"Meta"},{"description":"节点目录(公开;Verdict 报告引用的节点必在此可查)","name":"Nodes"},{"description":"订阅 / 订单 / 发票 / 余额 / 用量(Core + Compliance)","name":"Billing"},{"description":"公开价格档位","name":"Plans"},{"description":"Evidence-as-a-Service:Verdict 件价报告订单 + 生成 + 分享。\n位于 `attest.idcd.com` 子域(K1)。状态机走 D4 WAL + D5 refund retry。\n","name":"Verdict"},{"description":"Evidence-as-a-Service:公开验签 + 密钥仪式 transparency。\n`POST /v1/attest/verify` 不需登录(纯只读);其他 attestation 接口走 API Key。\n**D-Concern1**:验签响应必含 `report_type=observation_only` + `legal_disclaimer`。\n","name":"Attestation"},{"description":"AI Agent 工作流可观测(M21 LLM endpoint / M22 Tool/API / M23 RAG/Vector store)。\n事件流走 SSE long-lived(D13);LB sticky session by token_id;单实例 10k 并发。\n","name":"Agent Observability"},{"description":"节点赞助商透出(sponsor profile / 公开 sponsor 信息 / 贡献者排行)","name":"Sponsor"},{"description":"前端直传(presigned_put):服务端选 key + 签发短时 presigned PUT,AK 不出后端;\ncommit 走 HeadObject 实测核对。详 24-object-storage-and-uploads §6。\n","name":"Uploads"}],"x-mcp-protocol":{"auth":{"constraints":["所有 token 必有 expires_at,最长 90 天(D21)","personal 24h auto-refresh","workspace 90d auto_renewal","service 90d auto_renewal + IP 白名单强制","撤销立即生效:active SSE 连接通过 Redis pub-sub broadcast 断开"],"description":"Header `Authorization: Bearer idcd_mcp_xxx`(`idcd_mcp_` 为明文 secret 前缀;\n行 ID 前缀 `mcpt_` 不用于鉴权);\ntoken 通过 `POST /v1/mcp/tokens`(在 `api-prod.idcd.com`)签发,\n详 §components.schemas.McpToken + §MCP Tokens tag。\n","method":"bearer_mcp_token"},"clients_supported":[{"name":"Claude Code","status":"S3 alpha","transport":["stdio","http+sse"]},{"name":"Cursor","status":"S3 alpha","transport":["stdio"]},{"name":"Codex CLI","status":"S3 GA","transport":["stdio"]},{"name":"Anthropic Console MCP Gallery","status":"S3 GA","transport":["http+sse"]},{"name":"idcd-mcp-py (自家 SDK)","status":"S3 GA","transport":["stdio","http+sse"]},{"name":"idcd-mcp-ts (自家 SDK)","status":"S3 GA","transport":["stdio","http+sse"]}],"description":"`mcp.idcd.com` 走 **Anthropic MCP protocol**(JSON-RPC over stdio + HTTP+SSE),\n与 OpenAPI 3.1 不直接兼容,因此**不在本规范的 paths 中暴露**。\n本节作为描述性附录,供 SDK / 文档生成器参考。\n\n完整规范见 `docs.mcp.idcd.com`(独立子域,D3)。`mcp.idcd.com/docs` 走 302 redirect。\n","links":{"docs":"https://docs.mcp.idcd.com","quickstart":"https://docs.mcp.idcd.com/quickstart","tool_reference":"https://docs.mcp.idcd.com/tools"},"pricing":{"notes":"MCP units 与 API calls 是统一套餐配额下的两个独立计量分项(同属一套套餐权益,非独立计费池)。\nFree 100/day, Pro 5k/day, Team 30k/day, Business 200k/day。\n","unit_cny":0.002},"protocol":"anthropic-mcp","protocol_version":"2024-11-05","tools":[{"description":"多地 Ping(指定/默认节点选择)","name":"ping","units":1},{"description":"多地 HTTP/HTTPS 拨测","name":"http","units":2},{"description":"多地 DNS 解析 + 污染检测","name":"dns","units":2},{"description":"多地路由追踪","name":"traceroute","units":3},{"description":"SSL 证书查询 + 安全评分","name":"ssl","units":1},{"description":"一键全面诊断","name":"diagnose","units":10},{"description":"IP 归属 / ASN / ISP 查询","name":"ip","units":1},{"description":"WHOIS 查询","name":"whois","units":1}],"transports":[{"description":"主流;用于 Cursor / Claude Code / Codex / 自家 SDK 本地客户端","name":"stdio"},{"description":"长连 SSE(D13 stateful);LB sticky session 必要;\n单实例 10k 并发;多实例横向扩展跨实例事件通过 Redis Streams 广播。\n","name":"http+sse"}]}}