{ "openapi": "3.1.0", "info": { "title": "Flashduty 开放 API", "description": "Flashduty 事件管理平台的公开 HTTP API —— 覆盖故障、通知模板、协作空间、值班排班、监控、RUM、以及平台管理。每次调用都需在 query 中携带 `app_key`，该 key 在 Flashduty 控制台账户 → APP Key 中签发。所有响应使用统一结构：成功时为 `{ request_id, data }`，失败时为 `{ request_id, error }`。", "version": "1.0.0" }, "servers": [ { "url": "https://api.flashcat.cloud", "description": "Flashduty Open API" } ], "security": [ { "AppKeyAuth": [] } ], "tags": [ { "name": "平台/成员管理", "description": "" }, { "name": "平台/团队管理", "description": "" }, { "name": "平台/角色与权限", "description": "" }, { "name": "平台/审计日志", "description": "检索和读取账户操作审计日志。" }, { "name": "平台/账户设置", "description": "账户（主体）信息与设置" } ], "paths": { "/team/list": { "post": { "operationId": "team-read-list", "summary": "查看团队列表", "description": "分页返回当前账户下的团队列表。", "tags": [ "平台/团队管理" ], "x-mint": { "content": "## 限制说明\n\n| 项目 | 说明 |\n| ---- | ---- |\n| 速率限制 | 每个账户 **1,000 次/分钟**；**50 次/秒** |\n| 权限要求 | 无 —— 持有有效的 `app_key` 即可调用 |\n\n## 使用说明\n\n- 传入 `person_id` 可过滤返回指定人员所属的团队。\n- 默认 p=1、limit=20。", "href": "/zh/api-reference/platform/teams/team-read-list", "metadata": { "sidebarTitle": "查看团队列表" } }, "responses": { "200": { "description": "成功", "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/SuccessEnvelope" }, { "type": "object", "properties": { "data": { "$ref": "#/components/schemas/TeamListResponse" } } } ] }, "example": { "request_id": "01HK8XQE3Z7JM2NTFQ5YJ8P9R4", "data": { "p": 1, "limit": 20, "total": 5, "items": [ { "account_id": 10023, "team_id": 1001, "team_name": "后端 SRE", "status": "enabled", "creator_id": 80011, "created_at": 1710000000, "updated_at": 1712000000, "person_ids": [ 80011 ], "description": "", "updated_by_name": "", "updated_by": 0, "creator_name": "alice", "ref_id": "" } ] } } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "429": { "$ref": "#/components/responses/TooManyRequests" }, "500": { "$ref": "#/components/responses/ServerError" } }, "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/TeamListRequest" }, "example": { "p": 1, "limit": 20, "orderby": "created_at", "asc": false } } } } } }, "/team/infos": { "post": { "operationId": "team-read-infos", "summary": "批量查看团队信息", "description": "一次请求按 ID 列表批量返回多个团队的基本信息。", "tags": [ "平台/团队管理" ], "x-mint": { "content": "## 限制说明\n\n| 项目 | 说明 |\n| ---- | ---- |\n| 速率限制 | 每个账户 **1,000 次/分钟**；**50 次/秒** |\n| 权限要求 | 无 —— 持有有效的 `app_key` 即可调用 |\n\n## 使用说明\n\n- 每次最多传入 100 个团队 ID。", "href": "/zh/api-reference/platform/teams/team-read-infos", "metadata": { "sidebarTitle": "批量查看团队信息" } }, "responses": { "200": { "description": "成功", "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/SuccessEnvelope" }, { "type": "object", "properties": { "data": { "$ref": "#/components/schemas/TeamInfosResponse" } } } ] }, "example": { "request_id": "01HK8XQE3Z7JM2NTFQ5YJ8P9R4", "data": { "items": [ { "team_id": 1001, "team_name": "后端 SRE", "person_ids": [ 80011, 80012 ] }, { "team_id": 1002, "team_name": "前端", "person_ids": [ 80013 ] } ] } } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "429": { "$ref": "#/components/responses/TooManyRequests" }, "500": { "$ref": "#/components/responses/ServerError" } }, "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/TeamInfosRequest" }, "example": { "team_ids": [ 1001, 1002 ] } } } } } }, "/role/disable": { "post": { "operationId": "role-write-disable", "summary": "禁用角色", "description": "禁用自定义角色，使其停止授予权限。", "tags": [ "平台/角色与权限" ], "x-mint": { "content": "## 限制说明\n\n| 项目 | 说明 |\n| ---- | ---- |\n| 速率限制 | 每个账户 **1,000 次/分钟**；**50 次/秒** |\n| 权限要求 | **角色管理**（`organization`） |\n\n## 使用说明\n\n- 持有该角色的成员将立即失去其权限。\n- 只有自定义角色可被禁用。\n- 每次调用都会记录到账户审计日志，请不要把敏感信息放在请求字段中。", "href": "/zh/api-reference/platform/roles-permissions/role-write-disable", "metadata": { "sidebarTitle": "禁用角色" } }, "responses": { "200": { "description": "成功", "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/SuccessEnvelope" }, { "type": "object", "properties": { "data": { "$ref": "#/components/schemas/PlatformEmptyObject" } } } ] }, "example": { "request_id": "01HK8XQE3Z7JM2NTFQ5YJ8P9R4", "data": {} } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "429": { "$ref": "#/components/responses/TooManyRequests" }, "500": { "$ref": "#/components/responses/ServerError" } }, "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RoleIDRequest" }, "example": { "role_id": 150 } } } } } }, "/role/delete": { "post": { "operationId": "role-write-delete", "summary": "删除角色", "description": "永久删除自定义角色并从所有成员处撤销授权。", "tags": [ "平台/角色与权限" ], "x-mint": { "content": "## 限制说明\n\n| 项目 | 说明 |\n| ---- | ---- |\n| 速率限制 | 每个账户 **1,000 次/分钟**；**50 次/秒** |\n| 权限要求 | **角色管理**（`organization`） |\n\n## 使用说明\n\n- 内置角色无法删除。\n- 持有该角色的所有成员将立即失去其权限。\n- 每次调用都会记录到账户审计日志，请不要把敏感信息放在请求字段中。", "href": "/zh/api-reference/platform/roles-permissions/role-write-delete", "metadata": { "sidebarTitle": "删除角色" } }, "responses": { "200": { "description": "成功", "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/SuccessEnvelope" }, { "type": "object", "properties": { "data": { "$ref": "#/components/schemas/PlatformEmptyObject" } } } ] }, "example": { "request_id": "01HK8XQE3Z7JM2NTFQ5YJ8P9R4", "data": {} } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "429": { "$ref": "#/components/responses/TooManyRequests" }, "500": { "$ref": "#/components/responses/ServerError" } }, "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RoleIDRequest" }, "example": { "role_id": 150 } } } } } }, "/person/infos": { "post": { "operationId": "personInfos", "summary": "批量获取人员信息", "description": "根据 ID 批量返回成员或账户的资料信息。", "tags": [ "平台/成员管理" ], "x-mint": { "content": "## 限制说明\n\n| 项目 | 说明 |\n| ---- | ---- |\n| 速率限制 | 每个账户 **1,000 次/分钟**；**50 次/秒** |\n| 权限要求 | 无 —— 持有有效的 `app_key` 即可调用 |", "href": "/zh/api-reference/platform/members/person-infos", "metadata": { "sidebarTitle": "批量获取人员信息" } }, "responses": { "200": { "description": "成功", "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/SuccessEnvelope" }, { "type": "object", "properties": { "data": { "$ref": "#/components/schemas/PersonInfosResponse" } } } ] }, "example": { "request_id": "01HK8XQE3Z7JM2NTFQ5YJ8P9R4", "data": { "items": [ { "account_id": 2451002751131, "person_id": 2476444212131, "person_name": "Alice", "avatar": "/image/avatar1.png", "locale": "zh-CN", "time_zone": "Asia/Shanghai", "email": "alice@example.com", "phone_verified": false, "email_verified": true, "as": "member", "status": "enabled" }, { "account_id": 2451002751131, "person_id": 3790925372131, "person_name": "Bob", "email": "bob@example.com", "phone_verified": false, "email_verified": true, "as": "member", "status": "enabled" } ] } } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "429": { "$ref": "#/components/responses/TooManyRequests" }, "500": { "$ref": "#/components/responses/ServerError" } }, "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PersonInfosRequest" }, "example": { "person_ids": [ 2476444212131, 3790925372131 ] } } } } } }, "/member/info": { "post": { "operationId": "memberInfo", "summary": "获取当前成员信息", "description": "返回当前会话成员的完整资料。", "tags": [ "平台/成员管理" ], "x-mint": { "content": "## 限制说明\n\n| 项目 | 说明 |\n| ---- | ---- |\n| 速率限制 | 每个账户 **1,000 次/分钟**；**50 次/秒** |\n| 权限要求 | 无 —— 持有有效的 `app_key` 即可调用 |", "href": "/zh/api-reference/platform/members/member-info", "metadata": { "sidebarTitle": "获取当前成员信息" } }, "responses": { "200": { "description": "成功", "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/SuccessEnvelope" }, { "type": "object", "properties": { "data": { "$ref": "#/components/schemas/MemberInfoResponse" } } } ] }, "example": { "request_id": "01HK8XQE3Z7JM2NTFQ5YJ8P9R4", "data": { "account_avatar": "", "account_email": "alice@example.com", "account_id": 2451002751131, "account_locale": "en-US", "account_name": "Acme Corp", "account_role_ids": [ 6 ], "account_time_zone": "Asia/Shanghai", "avatar": "/image/avatar1.png", "country_code": "CN", "created_at": 1701399971, "domain": "acme", "email": "alice@example.com", "email_verified": true, "is_external": false, "locale": "zh-CN", "member_id": 2476444212131, "member_name": "Alice", "phone": "+86185****0300", "phone_verified": true, "time_zone": "Asia/Shanghai" } } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "429": { "$ref": "#/components/responses/TooManyRequests" }, "500": { "$ref": "#/components/responses/ServerError" } }, "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/MemberInfoRequest" }, "example": {} } } } } }, "/role/permission/list": { "post": { "operationId": "role-read-list-permission", "summary": "查看角色权限集合", "description": "返回所有可用权限，可按角色 ID 过滤仅返回指定角色已授予的权限。", "tags": [ "平台/角色与权限" ], "x-mint": { "content": "## 限制说明\n\n| 项目 | 说明 |\n| ---- | ---- |\n| 速率限制 | 每个账户 **1,000 次/分钟**；**50 次/秒** |\n| 权限要求 | 无 —— 持有有效的 `app_key` 即可调用 |\n\n## 使用说明\n\n- 传入 `role_ids` 可过滤只返回指定角色已授予的权限。\n- 传入 `with_all: true` 可返回全部权限，并在每项中通过 `is_granted` 标记是否已授予。", "href": "/zh/api-reference/platform/roles-permissions/role-read-list-permission", "metadata": { "sidebarTitle": "查看角色权限集合" } }, "responses": { "200": { "description": "成功", "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/SuccessEnvelope" }, { "type": "object", "properties": { "data": { "$ref": "#/components/schemas/RolePermissionListResponse" } } } ] }, "example": { "request_id": "01HK8XQE3Z7JM2NTFQ5YJ8P9R4", "data": { "items": [ { "id": 501, "permission_name": "模板查看", "permission_type": "read", "description": "查看通知模板", "class": "On-call", "scope": "on-call", "status": "enabled", "is_granted": true } ] } } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "429": { "$ref": "#/components/responses/TooManyRequests" }, "500": { "$ref": "#/components/responses/ServerError" } }, "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RolePermissionListRequest" }, "example": { "role_ids": [ 150 ], "with_all": true } } } } } }, "/team/info": { "post": { "operationId": "team-read-info", "summary": "查看团队详情", "description": "按 ID、名称或外部引用 ID 返回单个团队的详细信息。", "tags": [ "平台/团队管理" ], "x-mint": { "content": "## 限制说明\n\n| 项目 | 说明 |\n| ---- | ---- |\n| 速率限制 | 每个账户 **1,000 次/分钟**；**50 次/秒** |\n| 权限要求 | 无 —— 持有有效的 `app_key` 即可调用 |\n\n## 使用说明\n\n- `team_id`、`team_name`、`ref_id` 三者至少提供一个。", "href": "/zh/api-reference/platform/teams/team-read-info", "metadata": { "sidebarTitle": "查看团队详情" } }, "responses": { "200": { "description": "成功", "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/SuccessEnvelope" }, { "type": "object", "properties": { "data": { "$ref": "#/components/schemas/TeamItem" } } } ] }, "example": { "request_id": "01HK8XQE3Z7JM2NTFQ5YJ8P9R4", "data": { "account_id": 10023, "team_id": 1001, "team_name": "后端 SRE", "description": "后端可靠性工程团队", "status": "enabled", "updated_by_name": "alice", "updated_by": 80011, "creator_id": 80011, "creator_name": "alice", "created_at": 1710000000, "updated_at": 1712000000, "person_ids": [ 80011, 80012 ], "ref_id": "" } } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "429": { "$ref": "#/components/responses/TooManyRequests" }, "500": { "$ref": "#/components/responses/ServerError" } }, "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/TeamInfoRequest" }, "example": { "team_id": 1001 } } } } } }, "/team/delete": { "post": { "operationId": "team-write-delete", "summary": "删除团队", "description": "按 ID、名称或外部引用 ID 永久删除一个团队。", "tags": [ "平台/团队管理" ], "x-mint": { "content": "## 限制说明\n\n| 项目 | 说明 |\n| ---- | ---- |\n| 速率限制 | 每个账户 **1,000 次/分钟**；**50 次/秒** |\n| 权限要求 | **团队管理**（`organization`） |\n\n## 使用说明\n\n- `team_id`、`team_name`、`ref_id` 三者至少提供一个。\n- 若团队仍被排班、分派策略等资源引用，会返回 `400 ReferenceExist`。\n- 每次调用都会记录到账户审计日志，请不要把敏感信息放在请求字段中。", "href": "/zh/api-reference/platform/teams/team-write-delete", "metadata": { "sidebarTitle": "删除团队" } }, "responses": { "200": { "description": "成功", "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/SuccessEnvelope" }, { "type": "object", "properties": { "data": { "$ref": "#/components/schemas/PlatformEmptyObject" } } } ] }, "example": { "request_id": "01HK8XQE3Z7JM2NTFQ5YJ8P9R4", "data": {} } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "429": { "$ref": "#/components/responses/TooManyRequests" }, "500": { "$ref": "#/components/responses/ServerError" } }, "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/TeamDeleteRequest" }, "example": { "team_id": 1001 } } } } } }, "/role/info": { "post": { "operationId": "role-read-info", "summary": "查看角色详情", "description": "按角色 ID 返回单个角色的详细信息。", "tags": [ "平台/角色与权限" ], "x-mint": { "content": "## 限制说明\n\n| 项目 | 说明 |\n| ---- | ---- |\n| 速率限制 | 每个账户 **1,000 次/分钟**；**50 次/秒** |\n| 权限要求 | 无 —— 持有有效的 `app_key` 即可调用 |", "href": "/zh/api-reference/platform/roles-permissions/role-read-info", "metadata": { "sidebarTitle": "查看角色详情" } }, "responses": { "200": { "description": "成功", "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/SuccessEnvelope" }, { "type": "object", "properties": { "data": { "$ref": "#/components/schemas/RoleItem" } } } ] }, "example": { "request_id": "01HK8XQE3Z7JM2NTFQ5YJ8P9R4", "data": { "role_id": 2, "role_name": "账户管理员", "description": "拥有所有权限的账户管理员。", "status": "enabled", "permission_ids": [ 101, 102, 201 ], "editable": false, "created_at": 1700000000, "updated_at": 1700000000 } } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "429": { "$ref": "#/components/responses/TooManyRequests" }, "500": { "$ref": "#/components/responses/ServerError" } }, "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RoleInfoRequest" }, "example": { "role_id": 2 } } } } } }, "/member/invite": { "post": { "operationId": "memberInvite", "summary": "邀请成员", "description": "通过邮箱或手机号批量邀请新成员加入组织。", "tags": [ "平台/成员管理" ], "x-mint": { "content": "## 限制说明\n\n| 项目 | 说明 |\n| ---- | ---- |\n| 速率限制 | 每个账户 **1,000 次/分钟**；**50 次/秒** |\n| 权限要求 | **成员管理**（`organization`） |", "href": "/zh/api-reference/platform/members/member-invite", "metadata": { "sidebarTitle": "邀请成员" } }, "responses": { "200": { "description": "成功", "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/SuccessEnvelope" }, { "type": "object", "properties": { "data": { "$ref": "#/components/schemas/MemberInviteResponse" } } } ] }, "example": { "request_id": "01HK8XQE3Z7JM2NTFQ5YJ8P9R4", "data": { "items": [ { "member_id": 5068740052131, "member_name": "Charlie" } ] } } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "429": { "$ref": "#/components/responses/TooManyRequests" }, "500": { "$ref": "#/components/responses/ServerError" } }, "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/MemberInviteRequest" }, "example": { "members": [ { "member_name": "Charlie", "email": "charlie@example.com", "locale": "en-US", "time_zone": "Asia/Shanghai", "role_ids": [ 6 ] } ] } } } } } }, "/role/enable": { "post": { "operationId": "role-write-enable", "summary": "启用角色", "description": "重新启用已被禁用的自定义角色。", "tags": [ "平台/角色与权限" ], "x-mint": { "content": "## 限制说明\n\n| 项目 | 说明 |\n| ---- | ---- |\n| 速率限制 | 每个账户 **1,000 次/分钟**；**50 次/秒** |\n| 权限要求 | **角色管理**（`organization`） |\n\n## 使用说明\n\n- 只有自定义角色可以被启用/禁用，内置角色始终保持启用状态。\n- 每次调用都会记录到账户审计日志，请不要把敏感信息放在请求字段中。", "href": "/zh/api-reference/platform/roles-permissions/role-write-enable", "metadata": { "sidebarTitle": "启用角色" } }, "responses": { "200": { "description": "成功", "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/SuccessEnvelope" }, { "type": "object", "properties": { "data": { "$ref": "#/components/schemas/PlatformEmptyObject" } } } ] }, "example": { "request_id": "01HK8XQE3Z7JM2NTFQ5YJ8P9R4", "data": {} } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "429": { "$ref": "#/components/responses/TooManyRequests" }, "500": { "$ref": "#/components/responses/ServerError" } }, "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RoleIDRequest" }, "example": { "role_id": 150 } } } } } }, "/role/list": { "post": { "operationId": "role-read-list", "summary": "查看角色列表", "description": "返回当前账户下所有自定义及内置角色。", "tags": [ "平台/角色与权限" ], "x-mint": { "content": "## 限制说明\n\n| 项目 | 说明 |\n| ---- | ---- |\n| 速率限制 | 每个账户 **1,000 次/分钟**；**50 次/秒** |\n| 权限要求 | 无 —— 持有有效的 `app_key` 即可调用 |\n\n## 使用说明\n\n- 内置角色（`editable: false`）不可修改或删除。", "href": "/zh/api-reference/platform/roles-permissions/role-read-list", "metadata": { "sidebarTitle": "查看角色列表" } }, "responses": { "200": { "description": "成功", "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/SuccessEnvelope" }, { "type": "object", "properties": { "data": { "$ref": "#/components/schemas/RoleListResponse" } } } ] }, "example": { "request_id": "01HK8XQE3Z7JM2NTFQ5YJ8P9R4", "data": { "total": 3, "items": [ { "role_id": 2, "role_name": "账户管理员", "description": "", "status": "enabled", "permission_ids": [], "editable": false, "created_at": 1700000000, "updated_at": 1700000000 } ] } } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "429": { "$ref": "#/components/responses/TooManyRequests" }, "500": { "$ref": "#/components/responses/ServerError" } }, "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RoleListRequest" }, "example": { "orderby": "created_at", "asc": false } } } } } }, "/member/info/reset": { "post": { "operationId": "memberResetInfo", "summary": "重置成员信息", "description": "批量更新当前成员的多个资料字段。", "tags": [ "平台/成员管理" ], "x-mint": { "content": "## 限制说明\n\n| 项目 | 说明 |\n| ---- | ---- |\n| 速率限制 | 每个账户 **1,000 次/分钟**；**50 次/秒** |\n| 权限要求 | 无 —— 持有有效的 `app_key` 即可调用 |", "href": "/zh/api-reference/platform/members/member-reset-info", "metadata": { "sidebarTitle": "重置成员信息" } }, "responses": { "200": { "description": "成功", "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/SuccessEnvelope" }, { "type": "object", "properties": { "data": { "$ref": "#/components/schemas/MemberEmptyObject" } } } ] }, "example": { "request_id": "01HK8XQE3Z7JM2NTFQ5YJ8P9R4", "data": {} } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "429": { "$ref": "#/components/responses/TooManyRequests" }, "500": { "$ref": "#/components/responses/ServerError" } }, "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/MemberResetInfoRequest" }, "example": { "member_id": 2476444212131, "member_name": "Alice", "locale": "zh-CN", "time_zone": "Asia/Shanghai" } } } } } }, "/audit/search": { "post": { "operationId": "audit-read-search", "summary": "检索审计日志", "description": "按时间范围返回游标分页的操作审计日志列表。", "tags": [ "平台/审计日志" ], "x-mint": { "content": "## 限制说明\n\n| 项目 | 说明 |\n| ---- | ---- |\n| 速率限制 | 每个账户 **1,000 次/分钟**；**50 次/秒** |\n| 权限要求 | **审计查看**（`organization`） |\n\n## 使用说明\n\n- 时间范围必填。最大跨度 90 天，`start_time` 和 `end_time` 均为 Unix 时间戳（**秒**）。\n- 使用上次响应中的 `search_after_ctx` 获取下一页。该 token 是不透明的，请勿手动构造。\n- 可查询的时间窗口受账户许可证限制，超出保留期的查询会静默返回空结果，而不是报错。\n- 默认每页 20 条，最大 99 条。", "href": "/zh/api-reference/platform/audit-logs/audit-read-search", "metadata": { "sidebarTitle": "检索审计日志" } }, "responses": { "200": { "description": "成功", "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/SuccessEnvelope" }, { "type": "object", "properties": { "data": { "$ref": "#/components/schemas/AuditSearchResponse" } } } ] }, "example": { "request_id": "01HK8XQE3Z7JM2NTFQ5YJ8P9R4", "data": { "total": 2, "search_after_ctx": "", "docs": [ { "created_at": 1712700123456, "account_id": 10023, "member_id": 80011, "member_name": "Alice", "request_id": "01HK8XQE3Z7JM2NTFQ5YJ8P9R4", "ip": "203.0.113.42", "operation": "template:write:create", "operation_name": "创建模板", "body": "{\"template_name\":\"生产默认模板\"}", "params": [], "is_dangerous": false, "is_write": true } ] } } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "429": { "$ref": "#/components/responses/TooManyRequests" }, "500": { "$ref": "#/components/responses/ServerError" } }, "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AuditSearchRequest" }, "example": { "start_time": 1712620800, "end_time": 1712707200, "limit": 20, "operations": [ "template:write:create", "template:write:delete" ] } } } } } }, "/role/member/grant": { "post": { "operationId": "role-write-grant-role", "summary": "授予成员账户权限", "description": "将角色授予一个或多个成员，赋予其该角色包含的权限。", "tags": [ "平台/角色与权限" ], "x-mint": { "content": "## 限制说明\n\n| 项目 | 说明 |\n| ---- | ---- |\n| 速率限制 | 每个账户 **1,000 次/分钟**；**50 次/秒** |\n| 权限要求 | **角色管理**（`organization`） |\n\n## 使用说明\n\n- 每次最多传入 100 个成员 ID。\n- 已持有该角色的成员会被静默跳过。\n- 每次调用都会记录到账户审计日志，请不要把敏感信息放在请求字段中。", "href": "/zh/api-reference/platform/roles-permissions/role-write-grant-role", "metadata": { "sidebarTitle": "授予成员账户权限" } }, "responses": { "200": { "description": "成功", "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/SuccessEnvelope" }, { "type": "object", "properties": { "data": { "$ref": "#/components/schemas/PlatformEmptyObject" } } } ] }, "example": { "request_id": "01HK8XQE3Z7JM2NTFQ5YJ8P9R4", "data": {} } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "429": { "$ref": "#/components/responses/TooManyRequests" }, "500": { "$ref": "#/components/responses/ServerError" } }, "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RoleGrantRequest" }, "example": { "member_ids": [ 80011, 80012 ], "role_id": 150 } } } } } }, "/member/role/update": { "post": { "operationId": "memberUpdateRole", "summary": "更新成员角色", "description": "一次性替换成员的全部角色授权。", "tags": [ "平台/成员管理" ], "x-mint": { "content": "## 限制说明\n\n| 项目 | 说明 |\n| ---- | ---- |\n| 速率限制 | 每个账户 **1,000 次/分钟**；**50 次/秒** |\n| 权限要求 | **成员管理**（`organization`） |", "href": "/zh/api-reference/platform/members/member-update-role", "metadata": { "sidebarTitle": "更新成员角色" } }, "responses": { "200": { "description": "成功", "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/SuccessEnvelope" }, { "type": "object", "properties": { "data": { "$ref": "#/components/schemas/MemberEmptyObject" } } } ] }, "example": { "request_id": "01HK8XQE3Z7JM2NTFQ5YJ8P9R4", "data": {} } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "429": { "$ref": "#/components/responses/TooManyRequests" }, "500": { "$ref": "#/components/responses/ServerError" } }, "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/MemberRoleUpdateRequest" }, "example": { "member_id": 5068740052131, "role_ids": [ 2, 6 ] } } } } } }, "/role/upsert": { "post": { "operationId": "role-write-upsert", "summary": "创建或更新角色", "description": "创建新的自定义角色或更新已有角色，更新时传入 `role_id`。", "tags": [ "平台/角色与权限" ], "x-mint": { "content": "## 限制说明\n\n| 项目 | 说明 |\n| ---- | ---- |\n| 速率限制 | 每个账户 **1,000 次/分钟**；**50 次/秒** |\n| 权限要求 | **角色管理**（`organization`） |\n\n## 使用说明\n\n- 省略 `role_id`（或置为 0）表示创建；传入已有 ID 表示更新。\n- `role_name` 须为 1–39 个字符且在账户内唯一。\n- `permission_ids` 会完整替换角色的权限集合。\n- 每次调用都会记录到账户审计日志，请不要把敏感信息放在请求字段中。", "href": "/zh/api-reference/platform/roles-permissions/role-write-upsert", "metadata": { "sidebarTitle": "创建或更新角色" } }, "responses": { "200": { "description": "成功", "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/SuccessEnvelope" }, { "type": "object", "properties": { "data": { "$ref": "#/components/schemas/RoleUpsertResponse" } } } ] }, "example": { "request_id": "01HK8XQE3Z7JM2NTFQ5YJ8P9R4", "data": { "role_id": 150, "role_name": "值班管理员" } } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "429": { "$ref": "#/components/responses/TooManyRequests" }, "500": { "$ref": "#/components/responses/ServerError" } }, "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RoleUpsertRequest" }, "example": { "role_name": "值班管理员", "description": "管理值班排班和故障处理。", "permission_ids": [ 501, 502 ] } } } } } }, "/role/permission/factor/list": { "post": { "operationId": "role-read-list-permission-factor", "summary": "查看权限因子集合", "description": "返回所有权限因子（API、按钮、菜单、URL、访问），可按类型过滤。", "tags": [ "平台/角色与权限" ], "x-mint": { "content": "## 限制说明\n\n| 项目 | 说明 |\n| ---- | ---- |\n| 速率限制 | 每个账户 **1,000 次/分钟**；**50 次/秒** |\n| 权限要求 | 无 —— 持有有效的 `app_key` 即可调用 |\n\n## 使用说明\n\n- 权限因子是每个权限的细粒度控制项。\n- `factor_types` 可选值：`api`、`button`、`visit`、`menu`、`url`。", "href": "/zh/api-reference/platform/roles-permissions/role-read-list-permission-factor", "metadata": { "sidebarTitle": "查看权限因子集合" } }, "responses": { "200": { "description": "成功", "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/SuccessEnvelope" }, { "type": "object", "properties": { "data": { "$ref": "#/components/schemas/PermissionFactorListResponse" } } } ] }, "example": { "request_id": "01HK8XQE3Z7JM2NTFQ5YJ8P9R4", "data": [ { "factor_name": "template:read:info", "factor_type": "api" } ] } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "429": { "$ref": "#/components/responses/TooManyRequests" }, "500": { "$ref": "#/components/responses/ServerError" } }, "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PermissionFactorListRequest" }, "example": { "factor_types": [ "api" ] } } } } } }, "/role/member/revoke": { "post": { "operationId": "role-write-revoke-role", "summary": "解除成员账户权限", "description": "从一个或多个成员处撤销角色授权。", "tags": [ "平台/角色与权限" ], "x-mint": { "content": "## 限制说明\n\n| 项目 | 说明 |\n| ---- | ---- |\n| 速率限制 | 每个账户 **1,000 次/分钟**；**50 次/秒** |\n| 权限要求 | **角色管理**（`organization`） |\n\n## 使用说明\n\n- 未持有该角色的成员会被静默跳过。\n- 每次调用都会记录到账户审计日志，请不要把敏感信息放在请求字段中。", "href": "/zh/api-reference/platform/roles-permissions/role-write-revoke-role", "metadata": { "sidebarTitle": "解除成员账户权限" } }, "responses": { "200": { "description": "成功", "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/SuccessEnvelope" }, { "type": "object", "properties": { "data": { "$ref": "#/components/schemas/PlatformEmptyObject" } } } ] }, "example": { "request_id": "01HK8XQE3Z7JM2NTFQ5YJ8P9R4", "data": {} } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "429": { "$ref": "#/components/responses/TooManyRequests" }, "500": { "$ref": "#/components/responses/ServerError" } }, "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RoleGrantRequest" }, "example": { "member_ids": [ 80011 ], "role_id": 150 } } } } } }, "/audit/operation/list": { "post": { "operationId": "audit-read-operation-list", "summary": "查看事件类型列表", "description": "返回所有会记录到审计日志中的操作名称，可用于 `operations` 过滤参数。", "tags": [ "平台/审计日志" ], "x-mint": { "content": "## 限制说明\n\n| 项目 | 说明 |\n| ---- | ---- |\n| 速率限制 | 每个账户 **1,000 次/分钟**；**50 次/秒** |\n| 权限要求 | **审计查看**（`organization`） |\n\n## 使用说明\n\n- 将本接口返回的 `name` 值作为 `POST /audit/search` 的 `operations` 过滤参数使用。\n- `name_cn` 是控制台展示的中文标签；`name` 是用于过滤的稳定字段值。", "href": "/zh/api-reference/platform/audit-logs/audit-read-operation-list", "metadata": { "sidebarTitle": "查看事件类型列表" } }, "responses": { "200": { "description": "成功", "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/SuccessEnvelope" }, { "type": "object", "properties": { "data": { "$ref": "#/components/schemas/AuditOperationListResponse" } } } ] }, "example": { "request_id": "01HK8XQE3Z7JM2NTFQ5YJ8P9R4", "data": { "items": [ { "name": "template:write:create", "name_cn": "创建模板" }, { "name": "template:write:delete", "name_cn": "删除模板" }, { "name": "incident:write:acknowledge", "name_cn": "认领故障" } ] } } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "429": { "$ref": "#/components/responses/TooManyRequests" }, "500": { "$ref": "#/components/responses/ServerError" } }, "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AuditOperationListRequest" }, "example": {} } } } } }, "/team/upsert": { "post": { "operationId": "team-write-upsert", "summary": "变更团队信息", "description": "创建新团队或更新已有团队，更新时传入 `team_id`。", "tags": [ "平台/团队管理" ], "x-mint": { "content": "## 限制说明\n\n| 项目 | 说明 |\n| ---- | ---- |\n| 速率限制 | 每个账户 **1,000 次/分钟**；**50 次/秒** |\n| 权限要求 | **团队管理**（`organization`） |\n\n## 使用说明\n\n- 省略 `team_id`（或置为 0）表示创建新团队；传入已有 ID 表示更新。\n- `team_name` 须为 1–39 个字符且在账户内唯一。\n- 传入 `person_ids` 可设置团队成员，会替换整个成员列表。\n- 传入 `emails` 或 `phones` 可邀请尚未注册的成员。\n- `ref_id` 是供第三方 HR 系统集成使用的外部标识。\n- 每次调用都会记录到账户审计日志，请不要把敏感信息放在请求字段中。", "href": "/zh/api-reference/platform/teams/team-write-upsert", "metadata": { "sidebarTitle": "变更团队信息" } }, "responses": { "200": { "description": "成功", "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/SuccessEnvelope" }, { "type": "object", "properties": { "data": { "$ref": "#/components/schemas/TeamUpsertResponse" } } } ] }, "example": { "request_id": "01HK8XQE3Z7JM2NTFQ5YJ8P9R4", "data": { "team_id": 1001, "team_name": "后端 SRE" } } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "429": { "$ref": "#/components/responses/TooManyRequests" }, "500": { "$ref": "#/components/responses/ServerError" } }, "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/TeamUpsertRequest" }, "example": { "team_name": "后端 SRE", "description": "后端可靠性工程团队", "person_ids": [ 80011, 80012 ] } } } } } }, "/member/role/grant": { "post": { "operationId": "memberGrantRole", "summary": "授予成员角色", "description": "为成员添加角色授权。", "tags": [ "平台/成员管理" ], "x-mint": { "content": "## 限制说明\n\n| 项目 | 说明 |\n| ---- | ---- |\n| 速率限制 | 每个账户 **1,000 次/分钟**；**50 次/秒** |\n| 权限要求 | **成员管理**（`organization`） |", "href": "/zh/api-reference/platform/members/member-grant-role", "metadata": { "sidebarTitle": "授予成员角色" } }, "responses": { "200": { "description": "成功", "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/SuccessEnvelope" }, { "type": "object", "properties": { "data": { "$ref": "#/components/schemas/MemberEmptyObject" } } } ] }, "example": { "request_id": "01HK8XQE3Z7JM2NTFQ5YJ8P9R4", "data": {} } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "429": { "$ref": "#/components/responses/TooManyRequests" }, "500": { "$ref": "#/components/responses/ServerError" } }, "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/MemberRoleGrantRequest" }, "example": { "member_id": 5068740052131, "role_ids": [ 6 ] } } } } } }, "/member/role/revoke": { "post": { "operationId": "memberRevokeRole", "summary": "解除成员角色", "description": "移除成员的角色授权。", "tags": [ "平台/成员管理" ], "x-mint": { "content": "## 限制说明\n\n| 项目 | 说明 |\n| ---- | ---- |\n| 速率限制 | 每个账户 **1,000 次/分钟**；**50 次/秒** |\n| 权限要求 | **成员管理**（`organization`） |", "href": "/zh/api-reference/platform/members/member-revoke-role", "metadata": { "sidebarTitle": "解除成员角色" } }, "responses": { "200": { "description": "成功", "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/SuccessEnvelope" }, { "type": "object", "properties": { "data": { "$ref": "#/components/schemas/MemberEmptyObject" } } } ] }, "example": { "request_id": "01HK8XQE3Z7JM2NTFQ5YJ8P9R4", "data": {} } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "429": { "$ref": "#/components/responses/TooManyRequests" }, "500": { "$ref": "#/components/responses/ServerError" } }, "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/MemberRoleRevokeRequest" }, "example": { "member_id": 5068740052131, "role_ids": [ 6 ] } } } } } }, "/member/delete": { "post": { "operationId": "memberDelete", "summary": "删除成员", "description": "通过 ID、邮箱、手机号或名称从组织中移除成员。", "tags": [ "平台/成员管理" ], "x-mint": { "content": "## 限制说明\n\n| 项目 | 说明 |\n| ---- | ---- |\n| 速率限制 | 每个账户 **1,000 次/分钟**；**50 次/秒** |\n| 权限要求 | **成员管理**（`organization`） |\n\n## 使用说明\n\n- 默认情况下（`is_force=false`），系统会检查该成员是否被其他资源引用（如分派策略、值班表等）。如果存在引用，接口将返回错误码 `ReferenceExist` 并在 `data.refs` 中返回引用列表。设置 `is_force=true` 可跳过引用检查，直接强制删除。\n- 通过 SSO 同步且 SSO 配置了成员不可编辑（`sso_user_non_editable=true`）的成员，无法通过此接口删除。需要先在 SSO 配置中关闭该限制。\n- 此操作会记录审计日志。", "href": "/zh/api-reference/platform/members/member-delete", "metadata": { "sidebarTitle": "删除成员" } }, "responses": { "200": { "description": "成功", "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/SuccessEnvelope" }, { "type": "object", "properties": { "data": { "$ref": "#/components/schemas/MemberEmptyObject" } } } ] }, "example": { "request_id": "01HK8XQE3Z7JM2NTFQ5YJ8P9R4", "data": {} } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "429": { "$ref": "#/components/responses/TooManyRequests" }, "500": { "$ref": "#/components/responses/ServerError" } }, "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/MemberDeleteRequest" }, "example": { "member_id": 5068740052131 } } } } } }, "/member/list": { "post": { "operationId": "memberList", "summary": "查询成员列表", "description": "返回组织成员的分页列表。", "tags": [ "平台/成员管理" ], "x-mint": { "content": "## 限制说明\n\n| 项目 | 说明 |\n| ---- | ---- |\n| 速率限制 | 每个账户 **1,000 次/分钟**；**50 次/秒** |\n| 权限要求 | 无 —— 持有有效的 `app_key` 即可调用 |", "href": "/zh/api-reference/platform/members/member-list", "metadata": { "sidebarTitle": "查询成员列表" } }, "responses": { "200": { "description": "成功", "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/SuccessEnvelope" }, { "type": "object", "properties": { "data": { "$ref": "#/components/schemas/MemberListResponse" } } } ] }, "example": { "request_id": "01HK8XQE3Z7JM2NTFQ5YJ8P9R4", "data": { "p": 1, "limit": 5, "total": 148, "items": [ { "account_id": 2451002751131, "member_id": 5068740052131, "member_name": "Bob", "country_code": "", "phone": "+86151****6519", "email": "bob@example.com", "phone_verified": true, "email_verified": true, "avatar": "", "status": "enabled", "account_role_ids": [ 2, 6 ], "created_at": 1752030749, "updated_at": 1775962064, "ref_id": "", "is_external": false }, { "account_id": 2451002751131, "member_id": 2476444212131, "member_name": "Alice", "country_code": "CN", "phone": "+86185****0300", "email": "alice@example.com", "phone_verified": true, "email_verified": true, "avatar": "/image/avatar1.png", "status": "enabled", "account_role_ids": [ 6 ], "created_at": 1701399971, "updated_at": 1775809507, "ref_id": "", "is_external": false } ] } } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "429": { "$ref": "#/components/responses/TooManyRequests" }, "500": { "$ref": "#/components/responses/ServerError" } }, "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/MemberListRequest" }, "example": { "p": 1, "limit": 5 } } } } } }, "/account/info": { "post": { "summary": "查看主体信息", "description": "返回当前主体（账户）的基本信息与设置。", "operationId": "account-read-info", "tags": [ "平台/账户设置" ], "security": [ { "AppKeyAuth": [] } ], "requestBody": { "content": { "application/json": { "schema": { "type": "object" }, "example": {} } } }, "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/SuccessEnvelope" }, { "type": "object", "properties": { "data": { "$ref": "#/components/schemas/AccountInfo" } } } ] }, "example": { "error_code": 0, "data": { "account_id": 1001, "account_name": "acme", "domain": "acme", "extra_domains": [ "acme-corp" ], "phone": "138****8000", "country_code": "86", "email": "ops@acme.example", "avatar": "https://cdn.flashcat.cloud/avatar/acme.png", "locale": "zh-CN", "time_zone": "Asia/Shanghai", "created_at": 1716960000, "restrictions": { "ips": [ "203.0.113.0/24" ], "email_domains": [ "acme.example" ], "allow_subdomain": true } } } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "429": { "$ref": "#/components/responses/TooManyRequests" }, "500": { "$ref": "#/components/responses/ServerError" } }, "x-mint": { "metadata": { "sidebarTitle": "查看主体信息" }, "content": "| 权限 | 描述 |\n| --- | --- |\n| 无 | 无 — 任意有效的 app_key 均可调用此操作。 |\n\n在 [平台 API 参考](/zh/api-reference/platform/account/account-read-info) 中查看此操作。", "href": "/zh/api-reference/platform/account/account-read-info" } } } }, "components": { "securitySchemes": { "AppKeyAuth": { "type": "apiKey", "in": "query", "name": "app_key", "description": "在 Flashduty 控制台账户 → APP Key 中签发的 app_key。调用任何公开 API 时都必须携带。它等同于所属账户的身份凭证，请妥善保管。" } }, "responses": { "BadRequest": { "description": "请求非法 — 通常是参数缺失或格式不正确。", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "examples": { "missingParameter": { "value": { "request_id": "01HK8XQE3Z7JM2NTFQ5YJ8P9R4", "error": { "code": "InvalidParameter", "message": "The specified parameter is not valid." } } } } } } }, "Unauthorized": { "description": "app_key 缺失或无效。", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "examples": { "missingAppKey": { "value": { "request_id": "01HK8XQE3Z7JM2NTFQ5YJ8P9R4", "error": { "code": "Unauthorized", "message": "You are unauthorized." } } } } } } }, "Forbidden": { "description": "app_key 有效但没有执行该操作的权限。", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "examples": { "noEditPermission": { "value": { "request_id": "01HK8XQE3Z7JM2NTFQ5YJ8P9R4", "error": { "code": "AccessDenied", "message": "Access Denied." } } } } } } }, "NotFound": { "description": "目标资源不存在或已被删除。注意：Flashduty 对业务实体的缺失通常返回 HTTP 400 + code=`ResourceNotFound`，真正的 404 只用于未知路由。", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "examples": { "resourceMissing": { "value": { "request_id": "01HK8XQE3Z7JM2NTFQ5YJ8P9R4", "error": { "code": "ResourceNotFound", "message": "The resource you request is not found" } } } } } } }, "TooManyRequests": { "description": "命中限流。可能是全局 API 限流、账户级限流或集成级限流。限流按账户聚合。", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "examples": { "rateLimited": { "value": { "request_id": "01HK8XQE3Z7JM2NTFQ5YJ8P9R4", "error": { "code": "RequestTooFrequently", "message": "Request too frequently." } } } } } } }, "ServerError": { "description": "服务端未预期错误。反馈问题时请携带 request_id。", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "examples": { "internal": { "value": { "request_id": "01HK8XQE3Z7JM2NTFQ5YJ8P9R4", "error": { "code": "InternalError", "message": "We encountered an internal error, and it has been reported. Please try again later." } } } } } } } }, "schemas": { "AuditLog": { "type": "object", "description": "单条审计日志。", "required": [ "created_at", "account_id", "member_id", "member_name", "request_id", "ip", "operation", "operation_name", "body", "params", "is_dangerous", "is_write" ], "properties": { "created_at": { "type": "integer", "format": "int64", "description": "操作时间，Unix 毫秒时间戳。" }, "account_id": { "type": "integer", "format": "uint64", "description": "账户 ID。" }, "member_id": { "type": "integer", "format": "uint64", "description": "操作人的成员 ID。" }, "member_name": { "type": "string", "description": "操作人的显示名称。" }, "request_id": { "type": "string", "description": "用于关联的唯一请求 ID。" }, "ip": { "type": "string", "description": "调用者的客户端 IP 地址。" }, "operation": { "type": "string", "description": "稳定的机器可读操作名称，如 `template:write:create`。" }, "operation_name": { "type": "string", "description": "按账户语种显示的人类可读操作标签。" }, "body": { "type": "string", "description": "JSON 编码的请求体（可能截断至 10 KB）。" }, "params": { "type": "array", "items": { "type": "object", "properties": { "Key": { "type": "string" }, "Value": { "type": "string" } } }, "description": "URL 路径参数的键值对数组，无参数时为空数组。" }, "is_dangerous": { "type": "boolean", "description": "是否被标记为高危操作。" }, "is_write": { "type": "boolean", "description": "是否为写操作；false 表示只读操作。" } } }, "AuditOperationListRequest": { "type": "object", "description": "不需要任何参数。", "additionalProperties": false }, "AuditOperationListResponse": { "type": "object", "description": "可审计操作类型列表。", "required": [ "items" ], "properties": { "items": { "type": "array", "items": { "$ref": "#/components/schemas/AuditOperationTypeItem" } } } }, "AuditOperationTypeItem": { "type": "object", "description": "一条可审计的操作类型。", "required": [ "name", "name_cn" ], "properties": { "name": { "type": "string", "description": "用于过滤的稳定机器可读操作名称。", "example": "template:write:create" }, "name_cn": { "type": "string", "description": "控制台显示的中文标签。", "example": "创建模板" } } }, "AuditSearchRequest": { "type": "object", "description": "审计日志检索的过滤条件，时间范围必填。", "required": [ "start_time", "end_time" ], "properties": { "start_time": { "type": "integer", "format": "int64", "description": "检索窗口开始时间，Unix 时间戳（秒）。", "example": 1712620800 }, "end_time": { "type": "integer", "format": "int64", "description": "检索窗口结束时间，Unix 时间戳（秒）。必须晚于 `start_time`，最大跨度 90 天。", "example": 1712707200 }, "limit": { "type": "integer", "description": "每页条数。最小 0，最大 99。", "minimum": 0, "maximum": 99, "example": 20 }, "request_id": { "type": "string", "description": "按唯一请求 ID 过滤到单条记录。" }, "search_after_ctx": { "type": "string", "description": "上次响应返回的不透明分页游标。首页留空。" }, "operations": { "type": "array", "items": { "type": "string" }, "description": "按操作名称过滤。合法值可通过 `POST /audit/operation/list` 获取。" }, "person_id": { "type": "integer", "format": "uint64", "description": "按操作人成员 ID 过滤。" }, "is_dangerous": { "type": [ "boolean", "null" ], "description": "为 true 时只返回高危操作。" }, "is_write": { "type": [ "boolean", "null" ], "description": "为 true 时只返回写操作；为 false 时只返回读操作。" } } }, "AuditSearchResponse": { "type": "object", "description": "游标分页的审计日志检索结果。", "required": [ "total", "search_after_ctx" ], "properties": { "total": { "type": "integer", "format": "int64", "description": "检索窗口内符合条件的总条数。", "example": 2 }, "search_after_ctx": { "type": "string", "description": "用于获取下一页的不透明游标。没有更多结果时为空字符串。" }, "docs": { "type": "array", "items": { "$ref": "#/components/schemas/AuditLog" }, "description": "当前页的审计日志条目。" } } }, "DutyError": { "type": "object", "description": "响应结构中的错误 payload，仅在非 2xx 响应时出现。", "properties": { "code": { "$ref": "#/components/schemas/ErrorCode" }, "message": { "type": "string", "description": "用户可读的错误描述，语言会跟随调用方的 Accept-Language。可能包含字段名、ID 等请求上下文。", "example": "The specified parameter template_id is not valid." } }, "required": [ "code", "message" ] }, "EmptyObject": { "type": "object", "description": "空对象。当操作的成功信号就是不报错时，作为 `data` 返回。", "additionalProperties": false }, "EmptyRequest": { "type": "object", "description": "无参数。", "additionalProperties": false }, "EmptyResponse": { "type": "object", "description": "空响应体。成功时服务端返回 `data: null`。", "properties": {} }, "ErrorCode": { "type": "string", "description": "Flashduty 错误码枚举。每个失败响应的 `error.code` 都是下列稳定值之一，HTTP 状态码仅作参考。\n\n| 错误码 | HTTP | 含义 |\n|---|---|---|\n| `OK` | 200 | 保留值，正常错误响应不会返回。 |\n| `InvalidParameter` | 400 | 必填参数缺失或未通过校验。 |\n| `BadRequest` | 400 | 通用的 400 错误，通常是请求本身不合法。 |\n| `InvalidContentType` | 400 | 请求头 `Content-Type` 不是 `application/json`。 |\n| `ResourceNotFound` | 400 | 目标资源不存在。注意 HTTP 状态码是 400 而非 404（历史设计）。 |\n| `NoLicense` | 400 | 功能需要有效授权，但未找到可用的 license。 |\n| `ReferenceExist` | 400 | 该资源仍被其他实体引用，无法删除。 |\n| `Unauthorized` | 401 | `app_key` 缺失、无效或已过期。 |\n| `BalanceNotEnough` | 402 | 账户余额不足，无法执行需要计费的操作。 |\n| `AccessDenied` | 403 | 身份认证通过，但 RBAC 权限不足以执行该操作。 |\n| `RouteNotFound` | 404 | 请求的 URL 路径不是已知路由。 |\n| `MethodNotAllowed` | 405 | 当前路径不接受所使用的 HTTP 方法。 |\n| `UndonedOrderExist` | 409 | 账户存在未完成的订单，请稍后重试。 |\n| `RequestLocked` | 423 | 因连续失败被临时锁定。 |\n| `EntityTooLarge` | 413 | 请求体超过允许的最大长度。 |\n| `RequestTooFrequently` | 429 | 命中限流（全局、账户级或集成级）。 |\n| `RequestVerifyRequired` | 428 | 操作需要二次验证码，但未提供。 |\n| `DangerousOperation` | 428 | 危险操作，需要进行 MFA 验证。 |\n| `InternalError` | 500 | 服务端未预期错误。反馈问题请附上 `request_id`。 |\n| `ServiceUnavailable` | 503 | 后端依赖不可用，请稍后重试。 |", "enum": [ "OK", "InvalidParameter", "BadRequest", "InvalidContentType", "ResourceNotFound", "NoLicense", "ReferenceExist", "Unauthorized", "BalanceNotEnough", "AccessDenied", "RouteNotFound", "MethodNotAllowed", "UndonedOrderExist", "RequestLocked", "EntityTooLarge", "RequestTooFrequently", "RequestVerifyRequired", "DangerousOperation", "InternalError", "ServiceUnavailable" ], "x-enumDescriptions": { "OK": "保留值，正常错误响应不会返回。", "InvalidParameter": "必填参数缺失或未通过校验。", "BadRequest": "通用的 400 错误，通常是请求本身不合法。", "InvalidContentType": "请求头 `Content-Type` 不是 `application/json`。", "ResourceNotFound": "目标资源不存在。注意 HTTP 状态码是 400 而非 404（历史设计）。", "NoLicense": "功能需要有效授权，但未找到可用的 license。", "ReferenceExist": "该资源仍被其他实体引用，无法删除。", "Unauthorized": "`app_key` 缺失、无效或已过期。", "BalanceNotEnough": "账户余额不足，无法执行需要计费的操作。", "AccessDenied": "身份认证通过，但 RBAC 权限不足以执行该操作。", "RouteNotFound": "请求的 URL 路径不是已知路由。", "MethodNotAllowed": "当前路径不接受所使用的 HTTP 方法。", "UndonedOrderExist": "账户存在未完成的订单，请稍后重试。", "RequestLocked": "因连续失败被临时锁定。", "EntityTooLarge": "请求体超过允许的最大长度。", "RequestTooFrequently": "命中限流（全局、账户级或集成级）。", "RequestVerifyRequired": "操作需要二次验证码，但未提供。", "DangerousOperation": "危险操作，需要进行 MFA 验证。", "InternalError": "服务端未预期错误。反馈问题请附上 `request_id`。", "ServiceUnavailable": "后端依赖不可用，请稍后重试。" }, "example": "InvalidParameter" }, "ErrorResponse": { "type": "object", "description": "错误响应结构。`error` 必填，`data` 不存在。", "properties": { "request_id": { "type": "string", "example": "01HK8XQE3Z7JM2NTFQ5YJ8P9R4" }, "error": { "$ref": "#/components/schemas/DutyError" } }, "required": [ "request_id", "error" ] }, "InviteMemberItem": { "type": "object", "description": "待邀请成员", "properties": { "member_name": { "type": "string", "minLength": 2, "maxLength": 39, "description": "显示名称" }, "email": { "type": "string", "description": "邮箱地址" }, "phone": { "type": "string", "description": "手机号" }, "country_code": { "type": "string", "description": "国家区号" }, "role_ids": { "type": "array", "items": { "type": "integer" }, "description": "授予的角色 ID 列表" }, "locale": { "type": "string", "enum": [ "zh-CN", "en-US" ], "description": "语言" }, "time_zone": { "type": "string", "description": "时区" }, "ref_id": { "type": "string", "description": "外部引用 ID" } } }, "MemberDeleteRequest": { "type": "object", "description": "删除成员请求（提供其中一个查找字段）", "properties": { "member_id": { "type": "integer", "format": "uint64", "description": "成员 ID" }, "member_name": { "type": "string", "description": "成员名称" }, "email": { "type": "string", "description": "邮箱地址" }, "phone": { "type": "string", "description": "手机号" }, "country_code": { "type": "string", "description": "国家区号，配合 phone 使用" }, "ref_id": { "type": "string", "description": "外部引用 ID" }, "is_force": { "type": "boolean", "description": "是否强制删除。默认 false，会检查成员是否被分派策略、值班表等资源引用；设为 true 则跳过引用检查直接删除", "default": false } } }, "MemberEmptyObject": { "type": "object", "description": "空响应", "properties": {} }, "MemberInfoRequest": { "type": "object", "description": "获取成员信息请求", "properties": {} }, "MemberInfoResponse": { "type": "object", "description": "当前成员资料", "properties": { "account_id": { "type": "integer", "format": "uint64", "description": "账户 ID" }, "account_name": { "type": "string", "description": "账户名称" }, "account_avatar": { "type": "string", "description": "账户头像 URL" }, "account_email": { "type": "string", "description": "账户邮箱" }, "account_role_ids": { "type": "array", "items": { "type": "integer", "format": "uint64" }, "description": "授予的角色 ID 列表" }, "account_locale": { "type": "string", "description": "账户级语言偏好（如 zh-CN 或 en-US）" }, "account_time_zone": { "type": "string", "description": "账户级时区（如 Asia/Shanghai）" }, "domain": { "type": "string", "description": "账户域名" }, "member_id": { "type": "integer", "format": "uint64", "description": "成员 ID" }, "member_name": { "type": "string", "description": "成员显示名称" }, "phone": { "type": "string", "description": "脱敏手机号" }, "phone_verified": { "type": "boolean", "description": "手机号是否已验证" }, "email": { "type": "string", "description": "邮箱地址" }, "email_verified": { "type": "boolean", "description": "邮箱是否已验证" }, "country_code": { "type": "string", "description": "手机国家区号" }, "avatar": { "type": "string", "description": "成员头像 URL" }, "locale": { "type": "string", "description": "语言偏好" }, "time_zone": { "type": "string", "description": "时区" }, "is_external": { "type": "boolean", "description": "是否通过 SSO 创建" }, "status": { "type": "string", "enum": [ "enabled", "pending", "deleted" ], "description": "成员状态。`enabled` — 已激活成员；`pending` — 已邀请但尚未接受；`deleted` — 已从组织移除。" } } }, "MemberInviteRequest": { "type": "object", "description": "邀请成员请求", "required": [ "members" ], "properties": { "members": { "type": "array", "items": { "$ref": "#/components/schemas/InviteMemberItem" }, "description": "待邀请成员列表（最多 20 个）" }, "from": { "type": "string", "description": "邀请来源上下文" } } }, "MemberInviteResponse": { "type": "object", "description": "邀请成员响应", "properties": { "items": { "type": "array", "items": { "$ref": "#/components/schemas/NewMemberItem" }, "description": "新建的成员列表" } } }, "MemberItem": { "type": "object", "description": "成员条目", "required": [ "account_id", "member_id", "member_name", "country_code", "phone", "email", "phone_verified", "email_verified", "avatar", "status", "account_role_ids", "created_at", "updated_at", "ref_id", "is_external" ], "properties": { "account_id": { "type": "integer", "format": "uint64", "description": "账户 ID" }, "member_id": { "type": "integer", "format": "uint64", "description": "成员 ID" }, "member_name": { "type": "string", "description": "显示名称" }, "country_code": { "type": "string", "description": "手机国家区号" }, "phone": { "type": "string", "description": "脱敏手机号" }, "email": { "type": "string", "description": "邮箱地址" }, "locale": { "type": "string", "description": "语言" }, "time_zone": { "type": "string", "description": "时区" }, "phone_verified": { "type": "boolean", "description": "手机已验证" }, "email_verified": { "type": "boolean", "description": "邮箱已验证" }, "avatar": { "type": "string", "description": "头像 URL" }, "status": { "type": "string", "enum": [ "enabled", "pending", "deleted" ], "description": "成员状态。`enabled` — 已激活成员；`pending` — 已邀请但尚未接受；`deleted` — 已从组织移除。" }, "account_role_ids": { "type": "array", "items": { "type": "integer", "format": "uint64" }, "description": "角色 ID 列表" }, "is_external": { "type": "boolean", "description": "是否通过 SSO 创建" }, "ref_id": { "type": "string", "description": "外部引用 ID" }, "created_at": { "type": "integer", "format": "int64", "description": "创建时间（Unix 秒）" }, "updated_at": { "type": "integer", "format": "int64", "description": "更新时间（Unix 秒）" } } }, "MemberListRequest": { "type": "object", "description": "查询成员列表请求", "properties": { "role_id": { "type": "integer", "format": "uint64", "description": "按角色 ID 过滤" }, "p": { "type": "integer", "minimum": 1, "description": "页码" }, "limit": { "type": "integer", "minimum": 1, "maximum": 100, "description": "每页条数" }, "orderby": { "type": "string", "enum": [ "created_at", "updated_at" ], "description": "排序字段" }, "asc": { "type": "boolean", "description": "是否升序" }, "query": { "type": "string", "description": "搜索关键词" } } }, "MemberListResponse": { "type": "object", "description": "成员列表响应", "properties": { "p": { "type": "integer", "description": "当前页码" }, "limit": { "type": "integer", "description": "每页条数" }, "total": { "type": "integer", "description": "总数" }, "items": { "type": "array", "items": { "$ref": "#/components/schemas/MemberItem" }, "description": "成员列表" } } }, "MemberResetInfoRequest": { "type": "object", "description": "重置成员信息请求", "required": [ "member_id" ], "properties": { "member_id": { "type": "integer", "format": "uint64", "description": "要更新的成员 ID" }, "member_name": { "type": [ "string", "null" ], "minLength": 2, "maxLength": 39, "description": "显示名称" }, "email": { "type": [ "string", "null" ], "description": "邮箱地址" }, "phone": { "type": [ "string", "null" ], "description": "手机号" }, "country_code": { "type": [ "string", "null" ], "description": "国家区号" }, "avatar": { "type": [ "string", "null" ], "description": "头像 URL" }, "locale": { "type": [ "string", "null" ], "enum": [ "zh-CN", "en-US" ], "description": "语言" }, "time_zone": { "type": [ "string", "null" ], "description": "时区" } } }, "MemberRoleGrantRequest": { "type": "object", "description": "授予成员角色请求", "required": [ "member_id", "role_ids" ], "properties": { "member_id": { "type": "integer", "format": "uint64", "description": "成员 ID" }, "role_ids": { "type": "array", "items": { "type": "integer", "format": "uint64" }, "description": "要授予的角色 ID 列表，将追加到成员现有角色集合（自动去重）。" } } }, "MemberRoleRevokeRequest": { "type": "object", "description": "解除成员角色请求", "required": [ "member_id", "role_ids" ], "properties": { "member_id": { "type": "integer", "format": "uint64", "description": "成员 ID" }, "role_ids": { "type": "array", "items": { "type": "integer", "format": "uint64" }, "description": "要从成员处撤销的角色 ID 列表。" } } }, "MemberRoleUpdateRequest": { "type": "object", "description": "更新成员角色请求", "required": [ "member_id", "role_ids" ], "properties": { "member_id": { "type": "integer", "format": "uint64", "description": "成员 ID" }, "role_ids": { "type": "array", "items": { "type": "integer", "format": "uint64" }, "description": "新的角色 ID 集合" } } }, "NewMemberItem": { "type": "object", "description": "新建成员信息", "properties": { "member_id": { "type": "integer", "format": "uint64", "description": "成员 ID" }, "member_name": { "type": "string", "description": "成员显示名称" } } }, "PermissionFactorItem": { "type": "object", "description": "一个权限因子。", "required": [ "factor_name", "factor_type" ], "properties": { "factor_name": { "type": "string", "description": "因子标识符（如 'template:read:info'）。" }, "factor_type": { "type": "string", "enum": [ "api", "button", "visit", "menu", "url" ], "description": "因子类型。" } } }, "PermissionFactorListRequest": { "type": "object", "description": "查询权限因子列表的过滤参数。", "properties": { "factor_types": { "type": "array", "items": { "type": "string", "enum": [ "api", "button", "visit", "menu", "url" ] }, "description": "按因子类型过滤。" } } }, "PermissionFactorListResponse": { "type": "array", "description": "权限因子列表。", "items": { "$ref": "#/components/schemas/PermissionFactorItem" } }, "PermissionItem": { "type": "object", "description": "一个权限条目。", "required": [ "id", "permission_name", "permission_type", "description", "class", "scope", "status" ], "properties": { "id": { "type": "integer", "format": "uint64", "description": "唯一权限 ID。" }, "permission_name": { "type": "string", "description": "权限显示名称。" }, "permission_type": { "type": "string", "enum": [ "read", "manage" ], "description": "查看权限或管理权限。" }, "description": { "type": "string", "description": "权限的用户可读描述。" }, "class": { "type": "string", "description": "权限分类（如 'On-call'、'Organization'）。" }, "scope": { "type": "string", "description": "权限范围（如 'on-call'、'organization'）。" }, "status": { "type": "string", "enum": [ "enabled", "disabled" ], "description": "权限状态。" }, "is_granted": { "type": "boolean", "description": "当 with_all 为 true 时存在，表示该权限是否已授予所请求的角色。" } } }, "PersonInfosRequest": { "type": "object", "description": "批量获取人员信息请求", "required": [ "person_ids" ], "properties": { "person_ids": { "type": "array", "items": { "type": "integer", "format": "uint64" }, "description": "人员 ID 列表" } } }, "PersonInfosResponse": { "type": "object", "description": "批量人员信息响应", "properties": { "items": { "type": "array", "items": { "$ref": "#/components/schemas/PersonItem" }, "description": "人员资料列表" } } }, "PersonItem": { "type": "object", "description": "人员资料", "required": [ "account_id", "person_id", "phone_verified", "email_verified" ], "properties": { "account_id": { "type": "integer", "format": "uint64", "description": "账户 ID" }, "person_id": { "type": "integer", "format": "uint64", "description": "人员 ID" }, "person_name": { "type": "string", "description": "显示名称" }, "avatar": { "type": "string", "description": "头像 URL" }, "locale": { "type": "string", "description": "语言" }, "time_zone": { "type": "string", "description": "时区" }, "email": { "type": "string", "description": "邮箱地址" }, "phone": { "type": "string", "description": "手机号" }, "phone_verified": { "type": "boolean", "description": "手机已验证" }, "email_verified": { "type": "boolean", "description": "邮箱已验证" }, "as": { "type": "string", "description": "登录角色（account/member）" }, "status": { "type": "string", "enum": [ "enabled", "pending", "deleted" ], "description": "人员状态。`enabled` — 已激活；`pending` — 已邀请但尚未接受；`deleted` — 已移除。" } } }, "PlatformEmptyObject": { "type": "object", "description": "成功时返回的空对象，适用于无实质 payload 的操作。", "additionalProperties": false }, "RoleGrantRequest": { "type": "object", "required": [ "member_ids", "role_id" ], "description": "向成员授予或撤销角色的请求。", "properties": { "member_ids": { "type": "array", "items": { "type": "integer", "format": "uint64" }, "description": "要授予/撤销角色的成员 ID 列表，最多 100 个。" }, "role_id": { "type": "integer", "format": "uint64", "description": "要授予或撤销的角色 ID。" } } }, "RoleIDRequest": { "type": "object", "required": [ "role_id" ], "properties": { "role_id": { "type": "integer", "format": "uint64", "description": "角色 ID。" } } }, "RoleInfoRequest": { "type": "object", "required": [ "role_id" ], "properties": { "role_id": { "type": "integer", "format": "uint64", "description": "角色 ID。" } } }, "RoleItem": { "type": "object", "description": "角色及其权限集合。", "required": [ "role_id", "role_name", "description", "status", "permission_ids", "editable", "created_at", "updated_at" ], "properties": { "role_id": { "type": "integer", "format": "uint64", "description": "唯一角色 ID。" }, "role_name": { "type": "string", "description": "角色显示名称。" }, "description": { "type": "string", "description": "角色描述。" }, "status": { "type": "string", "enum": [ "enabled", "disabled" ], "description": "角色状态。" }, "permission_ids": { "type": "array", "items": { "type": "integer", "format": "uint64" }, "description": "该角色授予的权限 ID 列表。" }, "editable": { "type": "boolean", "description": "内置角色为 false，不可修改。" }, "created_at": { "type": "integer", "format": "int64", "description": "创建时间（Unix 秒）。" }, "updated_at": { "type": "integer", "format": "int64", "description": "最近更新时间（Unix 秒）。" } } }, "RoleListRequest": { "type": "object", "description": "查询角色列表的过滤参数。", "properties": { "orderby": { "type": "string", "enum": [ "created_at", "updated_at" ], "description": "排序字段。" }, "asc": { "type": "boolean", "description": "升序排序。" } } }, "RoleListResponse": { "type": "object", "description": "角色列表结果。", "required": [ "total", "items" ], "properties": { "total": { "type": "integer", "description": "角色总数。" }, "items": { "type": "array", "items": { "$ref": "#/components/schemas/RoleItem" } } } }, "RolePermissionListRequest": { "type": "object", "description": "查询权限列表的过滤参数。", "properties": { "role_ids": { "type": "array", "items": { "type": "integer", "format": "uint64" }, "description": "按角色 ID 过滤，只返回这些角色已授予的权限。" }, "with_all": { "type": "boolean", "description": "若为 true，返回所有权限并用 is_granted 标记哪些已授予。" } } }, "RolePermissionListResponse": { "type": "object", "description": "权限列表结果。", "required": [ "items" ], "properties": { "items": { "type": "array", "items": { "$ref": "#/components/schemas/PermissionItem" } } } }, "RoleUpsertRequest": { "type": "object", "required": [ "role_name" ], "description": "创建或更新自定义角色的参数。", "properties": { "role_id": { "type": "integer", "format": "uint64", "description": "角色 ID，省略或置为 0 表示创建。" }, "role_name": { "type": "string", "minLength": 1, "maxLength": 39, "description": "角色显示名称，1–39 个字符。" }, "description": { "type": "string", "maxLength": 499, "description": "角色描述。" }, "permission_ids": { "type": "array", "items": { "type": "integer", "format": "uint64" }, "description": "要授予的权限 ID 列表，会替换现有权限集合。" } } }, "RoleUpsertResponse": { "type": "object", "description": "角色创建/更新结果。", "required": [ "role_id", "role_name" ], "properties": { "role_id": { "type": "integer", "format": "uint64", "description": "创建或更新的角色 ID。" }, "role_name": { "type": "string", "description": "从请求中回显的角色名称。" } } }, "SuccessEnvelope": { "type": "object", "description": "成功响应结构。2xx 响应中 `request_id` 标识本次调用（同时出现在 `Flashcat-Request-Id` 响应头中），`data` 为接口业务 payload。失败响应使用不同结构，参见 `ErrorResponse`。", "properties": { "request_id": { "type": "string", "description": "本次请求的唯一 ID，也会在 Flashcat-Request-Id 响应头中返回。反馈问题时请一并附上。", "example": "01HK8XQE3Z7JM2NTFQ5YJ8P9R4" }, "data": { "description": "每个接口自己的业务 payload，详见各接口的 200 响应 schema。" } }, "required": [ "request_id", "data" ] }, "TeamBriefItem": { "type": "object", "description": "批量响应中的团队简要信息。", "properties": { "team_id": { "type": "integer", "format": "uint64" }, "team_name": { "type": "string" }, "person_ids": { "type": "array", "items": { "type": "integer", "format": "uint64" } } } }, "TeamDeleteRequest": { "type": "object", "description": "标识要删除的团队的请求。", "properties": { "team_id": { "type": "integer", "format": "uint64", "description": "团队 ID。" }, "team_name": { "type": "string", "description": "团队名称。" }, "ref_id": { "type": "string", "description": "外部引用 ID。" } } }, "TeamInfoRequest": { "type": "object", "description": "通过 ID、名称或外部引用标识团队的请求。", "properties": { "team_id": { "type": "integer", "format": "uint64", "description": "团队 ID。" }, "team_name": { "type": "string", "description": "团队名称。" }, "ref_id": { "type": "string", "description": "外部引用 ID。" } } }, "TeamInfosRequest": { "type": "object", "required": [ "team_ids" ], "description": "按 ID 列表批量查询团队的请求。", "properties": { "team_ids": { "type": "array", "items": { "type": "integer", "format": "uint64" }, "description": "要查询的团队 ID 列表，最多 100 个。" } } }, "TeamInfosResponse": { "type": "object", "description": "批量团队查询结果。", "required": [ "items" ], "properties": { "items": { "type": "array", "items": { "$ref": "#/components/schemas/TeamBriefItem" } } } }, "TeamItem": { "type": "object", "description": "团队及其成员信息。", "required": [ "account_id", "team_id", "team_name", "description", "status", "updated_by_name", "updated_by", "creator_id", "creator_name", "created_at", "updated_at", "person_ids", "ref_id" ], "properties": { "account_id": { "type": "integer", "format": "uint64", "description": "所属账户 ID。" }, "team_id": { "type": "integer", "format": "uint64", "description": "唯一团队 ID。" }, "team_name": { "type": "string", "description": "团队显示名称，1–39 个字符，账户内唯一。" }, "description": { "type": "string", "description": "自定义描述。" }, "status": { "type": "string", "enum": [ "enabled", "disabled" ], "description": "团队状态。" }, "updated_by_name": { "type": "string", "description": "最后修改人显示名称。" }, "updated_by": { "type": "integer", "format": "uint64", "description": "最后修改人成员 ID。" }, "creator_id": { "type": "integer", "format": "uint64", "description": "创建人成员 ID。" }, "creator_name": { "type": "string", "description": "创建人显示名称。" }, "created_at": { "type": "integer", "format": "int64", "description": "创建时间（Unix 秒）。" }, "updated_at": { "type": "integer", "format": "int64", "description": "最近更新时间（Unix 秒）。" }, "person_ids": { "type": "array", "items": { "type": "integer", "format": "uint64" }, "description": "团队成员的成员 ID 列表。" }, "ref_id": { "type": "string", "description": "外部引用 ID，用于与第三方 HR 系统集成。" } } }, "TeamListRequest": { "type": "object", "description": "查询团队列表的过滤参数。", "properties": { "p": { "type": "integer", "description": "页码，从 1 开始，默认 1。", "minimum": 1, "default": 1 }, "limit": { "type": "integer", "description": "分页大小，最大 100，默认 20。", "minimum": 1, "maximum": 100, "default": 20 }, "orderby": { "type": "string", "description": "排序字段。", "enum": [ "created_at", "updated_at", "team_name" ] }, "asc": { "type": "boolean", "description": "升序排序。" }, "person_id": { "type": "integer", "format": "uint64", "description": "按成员 ID 过滤，只返回该成员所属的团队。" }, "query": { "type": "string", "description": "按团队名称做子串匹配。" } } }, "TeamListResponse": { "type": "object", "description": "分页团队列表。", "required": [ "p", "limit", "total", "items" ], "properties": { "p": { "type": "integer", "description": "当前页码。" }, "limit": { "type": "integer", "description": "本次使用的分页大小。" }, "total": { "type": "integer", "description": "符合过滤条件的团队总数。" }, "items": { "type": "array", "items": { "$ref": "#/components/schemas/TeamItem" } } } }, "TeamUpsertRequest": { "type": "object", "required": [ "team_name" ], "description": "创建或更新团队的参数。", "properties": { "team_id": { "type": "integer", "format": "uint64", "description": "团队 ID，省略或置为 0 表示创建新团队。" }, "team_name": { "type": "string", "minLength": 1, "maxLength": 39, "description": "团队显示名称，1–39 个字符。" }, "description": { "type": "string", "maxLength": 500, "description": "自定义描述。" }, "person_ids": { "type": "array", "items": { "type": "integer", "format": "uint64" }, "description": "设置为团队成员的成员 ID 列表，会替换现有成员列表。" }, "emails": { "type": "array", "items": { "type": "string", "format": "email" }, "description": "要邀请为成员的邮箱地址。" }, "phones": { "type": "array", "items": { "type": "string" }, "description": "要邀请为成员的手机号码。" }, "countryCode": { "type": "string", "description": "默认国家区号，用于 `phones` 中未采用 E.164 格式的手机号。" }, "ref_id": { "type": "string", "description": "供 HR 系统集成使用的外部引用 ID。" }, "reset_if_name_exist": { "type": "boolean", "description": "若为 true，当同名团队已存在时重置其成员列表为传入的 person_ids。" } } }, "TeamUpsertResponse": { "type": "object", "description": "创建或更新团队的结果。", "required": [ "team_id", "team_name" ], "properties": { "team_id": { "type": "integer", "format": "uint64", "description": "创建或更新的团队 ID。" }, "team_name": { "type": "string", "description": "从请求中回显的团队名称。" } } }, "AccountInfo": { "type": "object", "properties": { "account_id": { "type": "integer", "description": "主体（账户）标识。" }, "account_name": { "type": "string", "description": "主体名称。" }, "domain": { "type": "string", "description": "主体主域名（登录子域名）。" }, "extra_domains": { "type": "array", "items": { "type": "string" }, "description": "主体的附加域名。" }, "phone": { "type": "string", "description": "主体联系电话，已做隐私脱敏处理。" }, "country_code": { "type": "string", "description": "联系电话的国家区号。" }, "email": { "type": "string", "description": "主体联系邮箱。" }, "avatar": { "type": "string", "description": "主体头像 URL。" }, "locale": { "type": "string", "description": "主体语言偏好（例如 zh-CN、en-US）。" }, "time_zone": { "type": "string", "description": "主体默认时区（IANA 名称，例如 Asia/Shanghai）。" }, "created_at": { "type": "integer", "format": "int64", "description": "主体创建时间，Unix 时间戳（秒）。" }, "restrictions": { "type": "object", "description": "主体访问限制（仅在已配置时返回）。", "properties": { "ips": { "type": "array", "items": { "type": "string" }, "description": "允许的来源 IP/CIDR 白名单。" }, "email_domains": { "type": "array", "items": { "type": "string" }, "description": "允许的登录邮箱域名。" }, "allow_subdomain": { "type": "boolean", "description": "是否同时接受允许邮箱域名的子域名。" } } }, "mp_plat": { "type": "string", "description": "主体所属的云市场平台（仅云市场来源的主体返回）。" }, "mp_account_id": { "type": "string", "description": "主体在云市场平台上的账户标识（仅云市场来源的主体返回）。" } } } } } }