{ "openapi": "3.1.0", "info": { "title": "Flashduty Open API", "description": "Public HTTP API for the Flashduty incident management platform — incidents, notification templates, channels, schedules, monitors, RUM, and platform administration. Every operation is authenticated with an `app_key` query parameter issued from the Flashduty console under Account → APP Keys. Responses follow a uniform envelope: `{ request_id, data }` on success, `{ request_id, error }` on failure.", "version": "1.0.0" }, "servers": [ { "url": "https://api.flashcat.cloud", "description": "Flashduty Open API" } ], "security": [ { "AppKeyAuth": [] } ], "tags": [ { "name": "Platform/Members", "description": "" }, { "name": "Platform/Teams", "description": "" }, { "name": "Platform/Roles & permissions", "description": "" }, { "name": "Platform/Audit logs", "description": "Search and retrieve account operation audit logs." }, { "name": "Platform/Account", "description": "Account profile and settings" } ], "paths": { "/team/list": { "post": { "operationId": "team-read-list", "summary": "List teams", "description": "Return a paginated list of teams in the current account.", "tags": [ "Platform/Teams" ], "x-mint": { "content": "## Restrictions\n\n| Aspect | Value |\n| ------ | ----- |\n| Rate limits | **1,000 requests/minute**; **50 requests/second** per account |\n| Permissions | None — any valid `app_key` can call this operation |\n\n## Usage\n\n- Filter by `person_id` to return teams that a specific person belongs to.\n- Defaults: p=1, limit=20.", "href": "/en/api-reference/platform/teams/team-read-list", "metadata": { "sidebarTitle": "List teams" } }, "responses": { "200": { "description": "Success", "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": "Backend 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": "Batch get teams", "description": "Return basic info for multiple teams by their IDs in a single request.", "tags": [ "Platform/Teams" ], "x-mint": { "content": "## Restrictions\n\n| Aspect | Value |\n| ------ | ----- |\n| Rate limits | **1,000 requests/minute**; **50 requests/second** per account |\n| Permissions | None — any valid `app_key` can call this operation |\n\n## Usage\n\n- Up to 100 team IDs per request.", "href": "/en/api-reference/platform/teams/team-read-infos", "metadata": { "sidebarTitle": "Batch get teams" } }, "responses": { "200": { "description": "Success", "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": "Backend SRE", "person_ids": [ 80011, 80012 ] }, { "team_id": 1002, "team_name": "Frontend", "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": "Disable a role", "description": "Disable a custom role to prevent it from granting permissions.", "tags": [ "Platform/Roles & permissions" ], "x-mint": { "content": "## Restrictions\n\n| Aspect | Value |\n| ------ | ----- |\n| Rate limits | **1,000 requests/minute**; **50 requests/second** per account |\n| Permissions | **Roles Manage** (`organization`) |\n\n## Usage\n\n- Members who held this role lose its permissions immediately.\n- Only custom roles can be disabled.\n- Every call is recorded in the account audit log. Don't put secrets in request fields.", "href": "/en/api-reference/platform/roles-permissions/role-write-disable", "metadata": { "sidebarTitle": "Disable a role" } }, "responses": { "200": { "description": "Success", "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": "Delete a role", "description": "Permanently delete a custom role and revoke it from all members.", "tags": [ "Platform/Roles & permissions" ], "x-mint": { "content": "## Restrictions\n\n| Aspect | Value |\n| ------ | ----- |\n| Rate limits | **1,000 requests/minute**; **50 requests/second** per account |\n| Permissions | **Roles Manage** (`organization`) |\n\n## Usage\n\n- Built-in roles cannot be deleted.\n- All members who held this role lose its permissions immediately.\n- Every call is recorded in the account audit log. Don't put secrets in request fields.", "href": "/en/api-reference/platform/roles-permissions/role-write-delete", "metadata": { "sidebarTitle": "Delete a role" } }, "responses": { "200": { "description": "Success", "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": "Batch get persons", "description": "Return profile information for a batch of person IDs (members or accounts).", "tags": [ "Platform/Members" ], "x-mint": { "content": "## Restrictions\n\n| Aspect | Value |\n| ------ | ----- |\n| Rate limits | **1,000 requests/minute**; **50 requests/second** per account |\n| Permissions | None — any valid `app_key` can call this operation |", "href": "/en/api-reference/platform/members/person-infos", "metadata": { "sidebarTitle": "Batch get persons" } }, "responses": { "200": { "description": "Success", "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": "Get current member info", "description": "Return the current session member's full profile.", "tags": [ "Platform/Members" ], "x-mint": { "content": "## Restrictions\n\n| Aspect | Value |\n| ------ | ----- |\n| Rate limits | **1,000 requests/minute**; **50 requests/second** per account |\n| Permissions | None — any valid `app_key` can call this operation |", "href": "/en/api-reference/platform/members/member-info", "metadata": { "sidebarTitle": "Get current member info" } }, "responses": { "200": { "description": "Success", "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": "List permissions", "description": "Return all available permissions, optionally filtered to those granted to specific roles.", "tags": [ "Platform/Roles & permissions" ], "x-mint": { "content": "## Restrictions\n\n| Aspect | Value |\n| ------ | ----- |\n| Rate limits | **1,000 requests/minute**; **50 requests/second** per account |\n| Permissions | None — any valid `app_key` can call this operation |\n\n## Usage\n\n- Pass `role_ids` to filter permissions to those granted to those roles.\n- Pass `with_all: true` to include all permissions regardless of role filter, with `is_granted` set to indicate which are granted to the specified roles.", "href": "/en/api-reference/platform/roles-permissions/role-read-list-permission", "metadata": { "sidebarTitle": "List permissions" } }, "responses": { "200": { "description": "Success", "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": "Templates Read", "permission_type": "read", "description": "View notification templates", "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": "Get team detail", "description": "Return a single team by ID, name, or external reference ID.", "tags": [ "Platform/Teams" ], "x-mint": { "content": "## Restrictions\n\n| Aspect | Value |\n| ------ | ----- |\n| Rate limits | **1,000 requests/minute**; **50 requests/second** per account |\n| Permissions | None — any valid `app_key` can call this operation |\n\n## Usage\n\n- At least one of `team_id`, `team_name`, or `ref_id` must be provided.", "href": "/en/api-reference/platform/teams/team-read-info", "metadata": { "sidebarTitle": "Get team detail" } }, "responses": { "200": { "description": "Success", "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": "Backend SRE", "description": "Backend reliability engineering team", "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": "Delete a team", "description": "Permanently delete a team by ID, name, or external reference ID.", "tags": [ "Platform/Teams" ], "x-mint": { "content": "## Restrictions\n\n| Aspect | Value |\n| ------ | ----- |\n| Rate limits | **1,000 requests/minute**; **50 requests/second** per account |\n| Permissions | **Teams Manage** (`organization`) |\n\n## Usage\n\n- At least one of `team_id`, `team_name`, or `ref_id` must be provided.\n- Fails with `400 ReferenceExist` if the team is still referenced by schedules, escalation rules, or other resources.\n- Every call is recorded in the account audit log. Don't put secrets in request fields.", "href": "/en/api-reference/platform/teams/team-write-delete", "metadata": { "sidebarTitle": "Delete a team" } }, "responses": { "200": { "description": "Success", "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": "Get role detail", "description": "Return the detail of a single role by its ID.", "tags": [ "Platform/Roles & permissions" ], "x-mint": { "content": "## Restrictions\n\n| Aspect | Value |\n| ------ | ----- |\n| Rate limits | **1,000 requests/minute**; **50 requests/second** per account |\n| Permissions | None — any valid `app_key` can call this operation |", "href": "/en/api-reference/platform/roles-permissions/role-read-info", "metadata": { "sidebarTitle": "Get role detail" } }, "responses": { "200": { "description": "Success", "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": "Account Admin", "description": "Account admin with all permissions.", "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": "Invite members", "description": "Batch invite new members to the organization by email or phone.", "tags": [ "Platform/Members" ], "x-mint": { "content": "## Restrictions\n\n| Aspect | Value |\n| ------ | ----- |\n| Rate limits | **1,000 requests/minute**; **50 requests/second** per account |\n| Permissions | **Members Manage** (`organization`) |", "href": "/en/api-reference/platform/members/member-invite", "metadata": { "sidebarTitle": "Invite members" } }, "responses": { "200": { "description": "Success", "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": "Enable a role", "description": "Re-enable a previously disabled custom role.", "tags": [ "Platform/Roles & permissions" ], "x-mint": { "content": "## Restrictions\n\n| Aspect | Value |\n| ------ | ----- |\n| Rate limits | **1,000 requests/minute**; **50 requests/second** per account |\n| Permissions | **Roles Manage** (`organization`) |\n\n## Usage\n\n- Only custom roles can be enabled/disabled. Built-in roles always remain enabled.\n- Every call is recorded in the account audit log. Don't put secrets in request fields.", "href": "/en/api-reference/platform/roles-permissions/role-write-enable", "metadata": { "sidebarTitle": "Enable a role" } }, "responses": { "200": { "description": "Success", "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": "List roles", "description": "Return all custom and built-in roles for the current account.", "tags": [ "Platform/Roles & permissions" ], "x-mint": { "content": "## Restrictions\n\n| Aspect | Value |\n| ------ | ----- |\n| Rate limits | **1,000 requests/minute**; **50 requests/second** per account |\n| Permissions | None — any valid `app_key` can call this operation |\n\n## Usage\n\n- Built-in roles (`editable: false`) cannot be modified or deleted.", "href": "/en/api-reference/platform/roles-permissions/role-read-list", "metadata": { "sidebarTitle": "List roles" } }, "responses": { "200": { "description": "Success", "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": "Account Admin", "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": "Reset member info", "description": "Batch-update multiple profile fields of the current member.", "tags": [ "Platform/Members" ], "x-mint": { "content": "## Restrictions\n\n| Aspect | Value |\n| ------ | ----- |\n| Rate limits | **1,000 requests/minute**; **50 requests/second** per account |\n| Permissions | None — any valid `app_key` can call this operation |", "href": "/en/api-reference/platform/members/member-reset-info", "metadata": { "sidebarTitle": "Reset member info" } }, "responses": { "200": { "description": "Success", "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": "Search audit logs", "description": "Return a cursor-paginated list of audit log entries within a time range.", "tags": [ "Platform/Audit logs" ], "x-mint": { "content": "## Restrictions\n\n| Aspect | Value |\n| ------ | ----- |\n| Rate limits | **1,000 requests/minute**; **50 requests/second** per account |\n| Permissions | **Audit Read** (`organization`) |\n\n## Usage\n\n- Time range is required. Maximum span is 90 days. Both `start_time` and `end_time` are Unix epoch **seconds**.\n- Use `search_after_ctx` from the previous response to fetch the next page. The token is opaque — do not construct it manually.\n- The retention window depends on the account's license. Queries beyond the retention boundary silently return an empty result rather than an error.\n- Default page size is 20 rows; maximum is 99.", "href": "/en/api-reference/platform/audit-logs/audit-read-search", "metadata": { "sidebarTitle": "Search audit logs" } }, "responses": { "200": { "description": "Success", "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\":\"Prod default\"}", "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": "Grant role to members", "description": "Assign a role to one or more members, giving them its permissions.", "tags": [ "Platform/Roles & permissions" ], "x-mint": { "content": "## Restrictions\n\n| Aspect | Value |\n| ------ | ----- |\n| Rate limits | **1,000 requests/minute**; **50 requests/second** per account |\n| Permissions | **Roles Manage** (`organization`) |\n\n## Usage\n\n- Up to 100 member IDs per request.\n- Members who already have the role are silently skipped.\n- Every call is recorded in the account audit log. Don't put secrets in request fields.", "href": "/en/api-reference/platform/roles-permissions/role-write-grant-role", "metadata": { "sidebarTitle": "Grant role to members" } }, "responses": { "200": { "description": "Success", "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": "Update member roles", "description": "Replace all role assignments for a member at once.", "tags": [ "Platform/Members" ], "x-mint": { "content": "## Restrictions\n\n| Aspect | Value |\n| ------ | ----- |\n| Rate limits | **1,000 requests/minute**; **50 requests/second** per account |\n| Permissions | **Members Manage** (`organization`) |", "href": "/en/api-reference/platform/members/member-update-role", "metadata": { "sidebarTitle": "Update member roles" } }, "responses": { "200": { "description": "Success", "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": "Create or update a role", "description": "Create a new custom role or update an existing one. Pass `role_id` to update.", "tags": [ "Platform/Roles & permissions" ], "x-mint": { "content": "## Restrictions\n\n| Aspect | Value |\n| ------ | ----- |\n| Rate limits | **1,000 requests/minute**; **50 requests/second** per account |\n| Permissions | **Roles Manage** (`organization`) |\n\n## Usage\n\n- Omit `role_id` (or set to 0) to create; pass an existing ID to update.\n- `role_name` must be 1–39 characters and unique within the account.\n- `permission_ids` sets the full permission set for the role, replacing any previous assignment.\n- Every call is recorded in the account audit log. Don't put secrets in request fields.", "href": "/en/api-reference/platform/roles-permissions/role-write-upsert", "metadata": { "sidebarTitle": "Create or update a role" } }, "responses": { "200": { "description": "Success", "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": "On-call Manager" } } } } }, "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": "On-call Manager", "description": "Manage on-call rotations and incidents.", "permission_ids": [ 501, 502 ] } } } } } }, "/role/permission/factor/list": { "post": { "operationId": "role-read-list-permission-factor", "summary": "List permission factors", "description": "Return all permission factors (API, button, menu, URL, visit) optionally filtered by type.", "tags": [ "Platform/Roles & permissions" ], "x-mint": { "content": "## Restrictions\n\n| Aspect | Value |\n| ------ | ----- |\n| Rate limits | **1,000 requests/minute**; **50 requests/second** per account |\n| Permissions | None — any valid `app_key` can call this operation |\n\n## Usage\n\n- Permission factors are the fine-grained controls that make up each permission.\n- `factor_types` accepts: `api`, `button`, `visit`, `menu`, `url`.", "href": "/en/api-reference/platform/roles-permissions/role-read-list-permission-factor", "metadata": { "sidebarTitle": "List permission factors" } }, "responses": { "200": { "description": "Success", "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": "Revoke role from members", "description": "Remove a role from one or more members, revoking the permissions it granted.", "tags": [ "Platform/Roles & permissions" ], "x-mint": { "content": "## Restrictions\n\n| Aspect | Value |\n| ------ | ----- |\n| Rate limits | **1,000 requests/minute**; **50 requests/second** per account |\n| Permissions | **Roles Manage** (`organization`) |\n\n## Usage\n\n- Members who don't have the role are silently skipped.\n- Every call is recorded in the account audit log. Don't put secrets in request fields.", "href": "/en/api-reference/platform/roles-permissions/role-write-revoke-role", "metadata": { "sidebarTitle": "Revoke role from members" } }, "responses": { "200": { "description": "Success", "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": "List auditable operation types", "description": "Return all operation names that are recorded in the audit log, for use as `operations` filter values.", "tags": [ "Platform/Audit logs" ], "x-mint": { "content": "## Restrictions\n\n| Aspect | Value |\n| ------ | ----- |\n| Rate limits | **1,000 requests/minute**; **50 requests/second** per account |\n| Permissions | **Audit Read** (`organization`) |\n\n## Usage\n\n- Use the `name` values from this response as `operations` filter values in `POST /audit/search`.\n- `name_cn` is the human-readable Chinese label shown in the console; `name` is the stable wire value to filter on.", "href": "/en/api-reference/platform/audit-logs/audit-read-operation-list", "metadata": { "sidebarTitle": "List auditable operation types" } }, "responses": { "200": { "description": "Success", "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": "Create or update a team", "description": "Create a new team or update an existing one. Pass `team_id` to update.", "tags": [ "Platform/Teams" ], "x-mint": { "content": "## Restrictions\n\n| Aspect | Value |\n| ------ | ----- |\n| Rate limits | **1,000 requests/minute**; **50 requests/second** per account |\n| Permissions | **Teams Manage** (`organization`) |\n\n## Usage\n\n- Omit `team_id` (or set to 0) to create a new team; pass an existing ID to update.\n- `team_name` must be 1–39 characters and unique within the account.\n- Pass `person_ids` to set team membership; this replaces the entire member list.\n- Pass `emails` or `phones` to invite members who don't yet have accounts.\n- `ref_id` is an external identifier for integration with third-party HR systems.\n- Every call is recorded in the account audit log. Don't put secrets in request fields.", "href": "/en/api-reference/platform/teams/team-write-upsert", "metadata": { "sidebarTitle": "Create or update a team" } }, "responses": { "200": { "description": "Success", "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": "Backend 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": "Backend SRE", "description": "Backend reliability engineering team", "person_ids": [ 80011, 80012 ] } } } } } }, "/member/role/grant": { "post": { "operationId": "memberGrantRole", "summary": "Grant role to member", "description": "Add a role assignment to a member.", "tags": [ "Platform/Members" ], "x-mint": { "content": "## Restrictions\n\n| Aspect | Value |\n| ------ | ----- |\n| Rate limits | **1,000 requests/minute**; **50 requests/second** per account |\n| Permissions | **Members Manage** (`organization`) |", "href": "/en/api-reference/platform/members/member-grant-role", "metadata": { "sidebarTitle": "Grant role to member" } }, "responses": { "200": { "description": "Success", "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": "Revoke role from member", "description": "Remove a role assignment from a member.", "tags": [ "Platform/Members" ], "x-mint": { "content": "## Restrictions\n\n| Aspect | Value |\n| ------ | ----- |\n| Rate limits | **1,000 requests/minute**; **50 requests/second** per account |\n| Permissions | **Members Manage** (`organization`) |", "href": "/en/api-reference/platform/members/member-revoke-role", "metadata": { "sidebarTitle": "Revoke role from member" } }, "responses": { "200": { "description": "Success", "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": "Delete member", "description": "Remove a member from the organization by ID, email, phone, or name.", "tags": [ "Platform/Members" ], "x-mint": { "content": "## Restrictions\n\n| Aspect | Value |\n| ------ | ----- |\n| Rate limits | **1,000 requests/minute**; **50 requests/second** per account |\n| Permissions | **Members Manage** (`organization`) |\n\n## Usage\n\n- By default (`is_force=false`), the system checks whether the member is referenced by other resources (e.g., escalation rules, schedules). If references exist, the API returns error code `ReferenceExist` with the reference list in `data.refs`. Set `is_force=true` to skip the reference check and force delete.\n- Members provisioned via SSO with `sso_user_non_editable=true` cannot be deleted through this API. Disable that SSO restriction first.\n- This operation is recorded in the audit log.", "href": "/en/api-reference/platform/members/member-delete", "metadata": { "sidebarTitle": "Delete member" } }, "responses": { "200": { "description": "Success", "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": "List members", "description": "Return a paginated list of organization members.", "tags": [ "Platform/Members" ], "x-mint": { "content": "## Restrictions\n\n| Aspect | Value |\n| ------ | ----- |\n| Rate limits | **1,000 requests/minute**; **50 requests/second** per account |\n| Permissions | None — any valid `app_key` can call this operation |", "href": "/en/api-reference/platform/members/member-list", "metadata": { "sidebarTitle": "List members" } }, "responses": { "200": { "description": "Success", "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": "Get account detail", "description": "Return the current account's profile and settings.", "operationId": "account-read-info", "tags": [ "Platform/Account" ], "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": "Get account detail" }, "content": "| Permission | Description |\n| --- | --- |\n| None | None — any valid app_key can call this operation. |\n\nFind this operation in the [Platform API reference](/en/api-reference/platform/account/account-read-info).", "href": "/en/api-reference/platform/account/account-read-info" } } } }, "components": { "securitySchemes": { "AppKeyAuth": { "type": "apiKey", "in": "query", "name": "app_key", "description": "App key issued from the Flashduty console under Account → APP Keys. Required on every public API call. Keep it secret — it grants the same access as the owning account." } }, "responses": { "BadRequest": { "description": "Invalid request — usually a missing or malformed parameter.", "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": "Missing or invalid 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": "The app_key is valid but lacks permission for this operation.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "examples": { "noEditPermission": { "value": { "request_id": "01HK8XQE3Z7JM2NTFQ5YJ8P9R4", "error": { "code": "AccessDenied", "message": "Access Denied." } } } } } } }, "NotFound": { "description": "The referenced resource does not exist or has been deleted. Note: Flashduty historically returns HTTP 400 with code `ResourceNotFound` for missing domain entities; a true 404 is reserved for unknown routes.", "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": "Rate limit hit. Either the global API limit, a per-account limit, or a per-integration limit.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "examples": { "rateLimited": { "value": { "request_id": "01HK8XQE3Z7JM2NTFQ5YJ8P9R4", "error": { "code": "RequestTooFrequently", "message": "Request too frequently." } } } } } } }, "ServerError": { "description": "Unexpected server-side error. Include the request_id when reporting.", "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": "A single audit log entry.", "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": "Timestamp of the operation in Unix epoch milliseconds." }, "account_id": { "type": "integer", "format": "uint64", "description": "ID of the account." }, "member_id": { "type": "integer", "format": "uint64", "description": "ID of the member who performed the action." }, "member_name": { "type": "string", "description": "Display name of the member." }, "request_id": { "type": "string", "description": "Unique request ID for correlation." }, "ip": { "type": "string", "description": "Client IP address of the caller." }, "operation": { "type": "string", "description": "Stable machine-readable operation name, e.g. `template:write:create`." }, "operation_name": { "type": "string", "description": "Human-readable operation label in the account's locale." }, "body": { "type": "string", "description": "JSON-encoded request body (may be truncated at 10 KB)." }, "params": { "type": "array", "items": { "type": "object", "properties": { "Key": { "type": "string" }, "Value": { "type": "string" } } }, "description": "URL path parameters as an array of key-value pairs, or an empty array when none." }, "is_dangerous": { "type": "boolean", "description": "True if this is flagged as a high-risk operation." }, "is_write": { "type": "boolean", "description": "True for mutating operations; false for read-only ones." } } }, "AuditOperationListRequest": { "type": "object", "description": "No parameters required.", "additionalProperties": false }, "AuditOperationListResponse": { "type": "object", "description": "List of auditable operation types.", "required": [ "items" ], "properties": { "items": { "type": "array", "items": { "$ref": "#/components/schemas/AuditOperationTypeItem" } } } }, "AuditOperationTypeItem": { "type": "object", "description": "An auditable operation type.", "required": [ "name", "name_cn" ], "properties": { "name": { "type": "string", "description": "Stable machine-readable operation name for use as a filter.", "example": "template:write:create" }, "name_cn": { "type": "string", "description": "Human-readable Chinese label shown in the console.", "example": "创建模板" } } }, "AuditSearchRequest": { "type": "object", "description": "Filter criteria for audit log search. Time range is required.", "required": [ "start_time", "end_time" ], "properties": { "start_time": { "type": "integer", "format": "int64", "description": "Start of the search window, Unix epoch seconds.", "example": 1712620800 }, "end_time": { "type": "integer", "format": "int64", "description": "End of the search window, Unix epoch seconds. Must be after `start_time`. Maximum span 90 days.", "example": 1712707200 }, "limit": { "type": "integer", "description": "Page size. Minimum 0, maximum 99.", "minimum": 0, "maximum": 99, "example": 20 }, "request_id": { "type": "string", "description": "Filter to a single request by its unique request ID." }, "search_after_ctx": { "type": "string", "description": "Opaque pagination cursor returned by the previous response. Leave empty for the first page." }, "operations": { "type": "array", "items": { "type": "string" }, "description": "Filter to specific operation names. Use `POST /audit/operation/list` to get the valid set." }, "person_id": { "type": "integer", "format": "uint64", "description": "Filter by the member who performed the action." }, "is_dangerous": { "type": [ "boolean", "null" ], "description": "When true, return only high-risk (dangerous) operations." }, "is_write": { "type": [ "boolean", "null" ], "description": "When true, return only write operations; when false, return only read operations." } } }, "AuditSearchResponse": { "type": "object", "description": "Cursor-paginated audit log search result.", "required": [ "total", "search_after_ctx" ], "properties": { "total": { "type": "integer", "format": "int64", "description": "Total matching entries in the search window.", "example": 2 }, "search_after_ctx": { "type": "string", "description": "Opaque cursor for the next page. Empty string when there are no more results." }, "docs": { "type": "array", "items": { "$ref": "#/components/schemas/AuditLog" }, "description": "Audit log entries for this page." } } }, "DutyError": { "type": "object", "description": "Error payload inside the response envelope. Present only on non-2xx responses.", "properties": { "code": { "$ref": "#/components/schemas/ErrorCode" }, "message": { "type": "string", "description": "Human-readable error message, localized by the caller's Accept-Language. May contain field names, IDs, or other context from the failing request.", "example": "The specified parameter template_id is not valid." } }, "required": [ "code", "message" ] }, "EmptyObject": { "type": "object", "description": "An empty object. Returned as the `data` payload by operations whose success signal is simply the absence of an error.", "additionalProperties": false }, "EmptyRequest": { "type": "object", "description": "No parameters required.", "additionalProperties": false }, "EmptyResponse": { "type": "object", "description": "Empty response body. The server returns `data: null` on success.", "properties": {} }, "ErrorCode": { "type": "string", "description": "Flashduty error code enum. Every failed API response sets `error.code` to one of these stable wire strings. HTTP status is informational — the authoritative signal is the enum value.\n\n| Code | HTTP | Meaning |\n|---|---|---|\n| `OK` | 200 | Reserved — not returned on real errors. |\n| `InvalidParameter` | 400 | A required parameter is missing or failed validation. |\n| `BadRequest` | 400 | Generic 400 used when no more specific code fits. |\n| `InvalidContentType` | 400 | The `Content-Type` header is not `application/json`. |\n| `ResourceNotFound` | 400 | The referenced resource does not exist. Note: returned as HTTP 400, not 404 (historical choice). |\n| `NoLicense` | 400 | The feature is license-gated and no active license was found. |\n| `ReferenceExist` | 400 | Deletion blocked — other entities still reference this resource. |\n| `Unauthorized` | 401 | `app_key` is missing, invalid, or expired. |\n| `BalanceNotEnough` | 402 | Billing-gated operation with insufficient account balance. |\n| `AccessDenied` | 403 | Authenticated but lacking the permission required for this operation. |\n| `RouteNotFound` | 404 | The request URL path is not a known route. |\n| `MethodNotAllowed` | 405 | The HTTP method is not allowed on this otherwise-known path. |\n| `UndonedOrderExist` | 409 | An outstanding billing order blocks this new one. Wait and retry. |\n| `RequestLocked` | 423 | Operation temporarily locked due to repeated failures. |\n| `EntityTooLarge` | 413 | Request body exceeds the configured max size. |\n| `RequestTooFrequently` | 429 | Rate limit hit — API-global, per-account, or per-integration. |\n| `RequestVerifyRequired` | 428 | Second-factor verification required but not supplied. |\n| `DangerousOperation` | 428 | High-risk operation requires MFA verification. |\n| `InternalError` | 500 | Unhandled server-side error. Include `request_id` in the bug report. |\n| `ServiceUnavailable` | 503 | A backend dependency is unavailable. Try again later. |", "enum": [ "OK", "InvalidParameter", "BadRequest", "InvalidContentType", "ResourceNotFound", "NoLicense", "ReferenceExist", "Unauthorized", "BalanceNotEnough", "AccessDenied", "RouteNotFound", "MethodNotAllowed", "UndonedOrderExist", "RequestLocked", "EntityTooLarge", "RequestTooFrequently", "RequestVerifyRequired", "DangerousOperation", "InternalError", "ServiceUnavailable" ], "x-enumDescriptions": { "OK": "Reserved — not returned on real errors.", "InvalidParameter": "A required parameter is missing or failed validation.", "BadRequest": "Generic 400 used when no more specific code fits.", "InvalidContentType": "The `Content-Type` header is not `application/json`.", "ResourceNotFound": "The referenced resource does not exist. Note: returned as HTTP 400, not 404 (historical choice).", "NoLicense": "The feature is license-gated and no active license was found.", "ReferenceExist": "Deletion blocked — other entities still reference this resource.", "Unauthorized": "`app_key` is missing, invalid, or expired.", "BalanceNotEnough": "Billing-gated operation with insufficient account balance.", "AccessDenied": "Authenticated but lacking the permission required for this operation.", "RouteNotFound": "The request URL path is not a known route.", "MethodNotAllowed": "The HTTP method is not allowed on this otherwise-known path.", "UndonedOrderExist": "An outstanding billing order blocks this new one. Wait and retry.", "RequestLocked": "Operation temporarily locked due to repeated failures.", "EntityTooLarge": "Request body exceeds the configured max size.", "RequestTooFrequently": "Rate limit hit — API-global, per-account, or per-integration.", "RequestVerifyRequired": "Second-factor verification required but not supplied.", "DangerousOperation": "High-risk operation requires MFA verification.", "InternalError": "Unhandled server-side error. Include `request_id` in the bug report.", "ServiceUnavailable": "A backend dependency is unavailable. Try again later." }, "example": "InvalidParameter" }, "ErrorResponse": { "type": "object", "description": "Response envelope for errors. `error` is required; `data` is absent.", "properties": { "request_id": { "type": "string", "example": "01HK8XQE3Z7JM2NTFQ5YJ8P9R4" }, "error": { "$ref": "#/components/schemas/DutyError" } }, "required": [ "request_id", "error" ] }, "InviteMemberItem": { "type": "object", "description": "Member to invite", "properties": { "member_name": { "type": "string", "minLength": 2, "maxLength": 39, "description": "Display name" }, "email": { "type": "string", "description": "Email address" }, "phone": { "type": "string", "description": "Phone number" }, "country_code": { "type": "string", "description": "Country code" }, "role_ids": { "type": "array", "items": { "type": "integer" }, "description": "Role IDs to assign" }, "locale": { "type": "string", "enum": [ "zh-CN", "en-US" ], "description": "Locale" }, "time_zone": { "type": "string", "description": "Time zone" }, "ref_id": { "type": "string", "description": "External reference ID" } } }, "MemberDeleteRequest": { "type": "object", "description": "Delete member request (provide one of the lookup fields)", "properties": { "member_id": { "type": "integer", "format": "uint64", "description": "Member ID" }, "member_name": { "type": "string", "description": "Member name" }, "email": { "type": "string", "description": "Email address" }, "phone": { "type": "string", "description": "Phone number" }, "country_code": { "type": "string", "description": "Phone country code, used with phone" }, "ref_id": { "type": "string", "description": "External reference ID" }, "is_force": { "type": "boolean", "description": "Force delete. Defaults to false, which checks for references from escalation rules, schedules, etc. Set to true to skip the reference check and delete immediately", "default": false } } }, "MemberEmptyObject": { "type": "object", "description": "Empty response", "properties": {} }, "MemberInfoRequest": { "type": "object", "description": "Get member info request", "properties": {} }, "MemberInfoResponse": { "type": "object", "description": "Current member profile", "properties": { "account_id": { "type": "integer", "format": "uint64", "description": "Account ID" }, "account_name": { "type": "string", "description": "Account name" }, "account_avatar": { "type": "string", "description": "Account avatar URL" }, "account_email": { "type": "string", "description": "Account email" }, "account_role_ids": { "type": "array", "items": { "type": "integer", "format": "uint64" }, "description": "Assigned role IDs" }, "account_locale": { "type": "string", "description": "Account-level locale preference (e.g. zh-CN or en-US)" }, "account_time_zone": { "type": "string", "description": "Account-level time zone (e.g. Asia/Shanghai)" }, "domain": { "type": "string", "description": "Account domain" }, "member_id": { "type": "integer", "format": "uint64", "description": "Member ID" }, "member_name": { "type": "string", "description": "Member display name" }, "phone": { "type": "string", "description": "Masked phone number" }, "phone_verified": { "type": "boolean", "description": "Whether phone is verified" }, "email": { "type": "string", "description": "Email address" }, "email_verified": { "type": "boolean", "description": "Whether email is verified" }, "country_code": { "type": "string", "description": "Phone country code" }, "avatar": { "type": "string", "description": "Member avatar URL" }, "locale": { "type": "string", "description": "Locale preference" }, "time_zone": { "type": "string", "description": "Time zone" }, "is_external": { "type": "boolean", "description": "Whether provisioned via SSO" }, "status": { "type": "string", "enum": [ "enabled", "pending", "deleted" ], "description": "Member status. `enabled` — active member; `pending` — invited but not yet accepted; `deleted` — removed from the organization." } } }, "MemberInviteRequest": { "type": "object", "description": "Invite members request", "required": [ "members" ], "properties": { "members": { "type": "array", "items": { "$ref": "#/components/schemas/InviteMemberItem" }, "description": "Members to invite (max 20)" }, "from": { "type": "string", "description": "Invite source context" } } }, "MemberInviteResponse": { "type": "object", "description": "Invite members response", "properties": { "items": { "type": "array", "items": { "$ref": "#/components/schemas/NewMemberItem" }, "description": "Newly created members" } } }, "MemberItem": { "type": "object", "description": "Member item", "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": "Account ID" }, "member_id": { "type": "integer", "format": "uint64", "description": "Member ID" }, "member_name": { "type": "string", "description": "Display name" }, "country_code": { "type": "string", "description": "Phone country code" }, "phone": { "type": "string", "description": "Masked phone number" }, "email": { "type": "string", "description": "Email address" }, "locale": { "type": "string", "description": "Locale" }, "time_zone": { "type": "string", "description": "Time zone" }, "phone_verified": { "type": "boolean", "description": "Phone verified" }, "email_verified": { "type": "boolean", "description": "Email verified" }, "avatar": { "type": "string", "description": "Avatar URL" }, "status": { "type": "string", "enum": [ "enabled", "pending", "deleted" ], "description": "Member status. `enabled` — active member; `pending` — invited but not yet accepted; `deleted` — removed from the organization." }, "account_role_ids": { "type": "array", "items": { "type": "integer", "format": "uint64" }, "description": "Role IDs" }, "is_external": { "type": "boolean", "description": "Provisioned via SSO" }, "ref_id": { "type": "string", "description": "External reference ID" }, "created_at": { "type": "integer", "format": "int64", "description": "Creation timestamp (Unix seconds)" }, "updated_at": { "type": "integer", "format": "int64", "description": "Update timestamp (Unix seconds)" } } }, "MemberListRequest": { "type": "object", "description": "List members request", "properties": { "role_id": { "type": "integer", "format": "uint64", "description": "Filter by role ID" }, "p": { "type": "integer", "minimum": 1, "description": "Page number" }, "limit": { "type": "integer", "minimum": 1, "maximum": 100, "description": "Page size" }, "orderby": { "type": "string", "enum": [ "created_at", "updated_at" ], "description": "Sort field" }, "asc": { "type": "boolean", "description": "Ascending order" }, "query": { "type": "string", "description": "Search keyword" } } }, "MemberListResponse": { "type": "object", "description": "Member list response", "properties": { "p": { "type": "integer", "description": "Current page" }, "limit": { "type": "integer", "description": "Page size" }, "total": { "type": "integer", "description": "Total count" }, "items": { "type": "array", "items": { "$ref": "#/components/schemas/MemberItem" }, "description": "Member items" } } }, "MemberResetInfoRequest": { "type": "object", "description": "Reset member info request", "required": [ "member_id" ], "properties": { "member_id": { "type": "integer", "format": "uint64", "description": "Member ID of the member to update" }, "member_name": { "type": [ "string", "null" ], "minLength": 2, "maxLength": 39, "description": "Display name" }, "email": { "type": [ "string", "null" ], "description": "Email address" }, "phone": { "type": [ "string", "null" ], "description": "Phone number" }, "country_code": { "type": [ "string", "null" ], "description": "Country code" }, "avatar": { "type": [ "string", "null" ], "description": "Avatar URL" }, "locale": { "type": [ "string", "null" ], "enum": [ "zh-CN", "en-US" ], "description": "Locale" }, "time_zone": { "type": [ "string", "null" ], "description": "Time zone" } } }, "MemberRoleGrantRequest": { "type": "object", "description": "Grant role to member request", "required": [ "member_id", "role_ids" ], "properties": { "member_id": { "type": "integer", "format": "uint64", "description": "Member ID" }, "role_ids": { "type": "array", "items": { "type": "integer", "format": "uint64" }, "description": "Role IDs to grant; appended to the member's current roles (duplicates are deduplicated)." } } }, "MemberRoleRevokeRequest": { "type": "object", "description": "Revoke role from member request", "required": [ "member_id", "role_ids" ], "properties": { "member_id": { "type": "integer", "format": "uint64", "description": "Member ID" }, "role_ids": { "type": "array", "items": { "type": "integer", "format": "uint64" }, "description": "Role IDs to remove from the member." } } }, "MemberRoleUpdateRequest": { "type": "object", "description": "Update member roles request", "required": [ "member_id", "role_ids" ], "properties": { "member_id": { "type": "integer", "format": "uint64", "description": "Member ID" }, "role_ids": { "type": "array", "items": { "type": "integer", "format": "uint64" }, "description": "New set of role IDs" } } }, "NewMemberItem": { "type": "object", "description": "Newly created member", "properties": { "member_id": { "type": "integer", "format": "uint64", "description": "Member ID" }, "member_name": { "type": "string", "description": "Member display name" } } }, "PermissionFactorItem": { "type": "object", "description": "A permission factor.", "required": [ "factor_name", "factor_type" ], "properties": { "factor_name": { "type": "string", "description": "Factor identifier (e.g., 'template:read:info')." }, "factor_type": { "type": "string", "enum": [ "api", "button", "visit", "menu", "url" ], "description": "Factor type." } } }, "PermissionFactorListRequest": { "type": "object", "description": "Filters for listing permission factors.", "properties": { "factor_types": { "type": "array", "items": { "type": "string", "enum": [ "api", "button", "visit", "menu", "url" ] }, "description": "Filter by factor type." } } }, "PermissionFactorListResponse": { "type": "array", "description": "List of permission factors.", "items": { "$ref": "#/components/schemas/PermissionFactorItem" } }, "PermissionItem": { "type": "object", "description": "A permission entry.", "required": [ "id", "permission_name", "permission_type", "description", "class", "scope", "status" ], "properties": { "id": { "type": "integer", "format": "uint64", "description": "Unique permission ID." }, "permission_name": { "type": "string", "description": "Permission display name." }, "permission_type": { "type": "string", "enum": [ "read", "manage" ], "description": "Whether this is a read or manage permission." }, "description": { "type": "string", "description": "Human-readable permission description." }, "class": { "type": "string", "description": "Permission class (e.g., 'On-call', 'Organization')." }, "scope": { "type": "string", "description": "Permission scope (e.g., 'on-call', 'organization')." }, "status": { "type": "string", "enum": [ "enabled", "disabled" ], "description": "Permission status." }, "is_granted": { "type": "boolean", "description": "Present when with_all is true. Indicates whether this permission is granted to the requested roles." } } }, "PersonInfosRequest": { "type": "object", "description": "Get person info by IDs request", "required": [ "person_ids" ], "properties": { "person_ids": { "type": "array", "items": { "type": "integer", "format": "uint64" }, "description": "List of person IDs" } } }, "PersonInfosResponse": { "type": "object", "description": "Person info by IDs response", "properties": { "items": { "type": "array", "items": { "$ref": "#/components/schemas/PersonItem" }, "description": "Person profiles" } } }, "PersonItem": { "type": "object", "description": "Person profile", "required": [ "account_id", "person_id", "phone_verified", "email_verified" ], "properties": { "account_id": { "type": "integer", "format": "uint64", "description": "Account ID" }, "person_id": { "type": "integer", "format": "uint64", "description": "Person ID" }, "person_name": { "type": "string", "description": "Display name" }, "avatar": { "type": "string", "description": "Avatar URL" }, "locale": { "type": "string", "description": "Locale" }, "time_zone": { "type": "string", "description": "Time zone" }, "email": { "type": "string", "description": "Email address" }, "phone": { "type": "string", "description": "Phone number" }, "phone_verified": { "type": "boolean", "description": "Phone verified" }, "email_verified": { "type": "boolean", "description": "Email verified" }, "as": { "type": "string", "description": "Login role (account/member)" }, "status": { "type": "string", "enum": [ "enabled", "pending", "deleted" ], "description": "Person status. `enabled` — active; `pending` — invited but not yet accepted; `deleted` — removed." } } }, "PlatformEmptyObject": { "type": "object", "description": "Empty object returned on success for operations with no meaningful payload.", "additionalProperties": false }, "RoleGrantRequest": { "type": "object", "required": [ "member_ids", "role_id" ], "description": "Request to grant or revoke a role from members.", "properties": { "member_ids": { "type": "array", "items": { "type": "integer", "format": "uint64" }, "description": "Member IDs to grant/revoke the role. Max 100." }, "role_id": { "type": "integer", "format": "uint64", "description": "Role ID to grant or revoke." } } }, "RoleIDRequest": { "type": "object", "required": [ "role_id" ], "properties": { "role_id": { "type": "integer", "format": "uint64", "description": "Role ID." } } }, "RoleInfoRequest": { "type": "object", "required": [ "role_id" ], "properties": { "role_id": { "type": "integer", "format": "uint64", "description": "Role ID." } } }, "RoleItem": { "type": "object", "description": "A role and its permission set.", "required": [ "role_id", "role_name", "description", "status", "permission_ids", "editable", "created_at", "updated_at" ], "properties": { "role_id": { "type": "integer", "format": "uint64", "description": "Unique role ID." }, "role_name": { "type": "string", "description": "Role display name." }, "description": { "type": "string", "description": "Role description." }, "status": { "type": "string", "enum": [ "enabled", "disabled" ], "description": "Role status." }, "permission_ids": { "type": "array", "items": { "type": "integer", "format": "uint64" }, "description": "IDs of permissions granted by this role." }, "editable": { "type": "boolean", "description": "False for built-in roles which cannot be modified." }, "created_at": { "type": "integer", "format": "int64", "description": "Unix epoch seconds the role was created." }, "updated_at": { "type": "integer", "format": "int64", "description": "Unix epoch seconds the role was last updated." } } }, "RoleListRequest": { "type": "object", "description": "Filters for listing roles.", "properties": { "orderby": { "type": "string", "enum": [ "created_at", "updated_at" ], "description": "Sort field." }, "asc": { "type": "boolean", "description": "Ascending sort order." } } }, "RoleListResponse": { "type": "object", "description": "Role list result.", "required": [ "total", "items" ], "properties": { "total": { "type": "integer", "description": "Total role count." }, "items": { "type": "array", "items": { "$ref": "#/components/schemas/RoleItem" } } } }, "RolePermissionListRequest": { "type": "object", "description": "Filters for listing permissions.", "properties": { "role_ids": { "type": "array", "items": { "type": "integer", "format": "uint64" }, "description": "Filter to permissions granted to these roles." }, "with_all": { "type": "boolean", "description": "If true, return all permissions with is_granted set to indicate which are granted." } } }, "RolePermissionListResponse": { "type": "object", "description": "Permission list result.", "required": [ "items" ], "properties": { "items": { "type": "array", "items": { "$ref": "#/components/schemas/PermissionItem" } } } }, "RoleUpsertRequest": { "type": "object", "required": [ "role_name" ], "description": "Parameters for creating or updating a custom role.", "properties": { "role_id": { "type": "integer", "format": "uint64", "description": "Role ID. Omit or set to 0 to create." }, "role_name": { "type": "string", "minLength": 1, "maxLength": 39, "description": "Role display name. 1–39 characters." }, "description": { "type": "string", "maxLength": 499, "description": "Role description." }, "permission_ids": { "type": "array", "items": { "type": "integer", "format": "uint64" }, "description": "Permission IDs to grant. Replaces the existing set." } } }, "RoleUpsertResponse": { "type": "object", "description": "Role create/update result.", "required": [ "role_id", "role_name" ], "properties": { "role_id": { "type": "integer", "format": "uint64", "description": "Created or updated role ID." }, "role_name": { "type": "string", "description": "Role name echoed from the request." } } }, "SuccessEnvelope": { "type": "object", "description": "Success response envelope. On every 2xx response, `request_id` identifies the call (also mirrored in the `Flashcat-Request-Id` header) and `data` holds the endpoint-specific payload. Failure responses use a different shape — see `ErrorResponse`.", "properties": { "request_id": { "type": "string", "description": "Unique ID for this request. Mirrored in the Flashcat-Request-Id response header. Include it when reporting issues.", "example": "01HK8XQE3Z7JM2NTFQ5YJ8P9R4" }, "data": { "description": "Endpoint-specific payload. See each operation's 200 response schema." } }, "required": [ "request_id", "data" ] }, "TeamBriefItem": { "type": "object", "description": "Brief team info for batch responses.", "properties": { "team_id": { "type": "integer", "format": "uint64" }, "team_name": { "type": "string" }, "person_ids": { "type": "array", "items": { "type": "integer", "format": "uint64" } } } }, "TeamDeleteRequest": { "type": "object", "description": "Request identifying a team to delete.", "properties": { "team_id": { "type": "integer", "format": "uint64", "description": "Team ID." }, "team_name": { "type": "string", "description": "Team name." }, "ref_id": { "type": "string", "description": "External reference ID." } } }, "TeamInfoRequest": { "type": "object", "description": "Request identifying a team by one of ID, name, or external ref.", "properties": { "team_id": { "type": "integer", "format": "uint64", "description": "Team ID." }, "team_name": { "type": "string", "description": "Team name." }, "ref_id": { "type": "string", "description": "External reference ID." } } }, "TeamInfosRequest": { "type": "object", "required": [ "team_ids" ], "description": "Request for batch team lookup by IDs.", "properties": { "team_ids": { "type": "array", "items": { "type": "integer", "format": "uint64" }, "description": "List of team IDs to look up. Max 100." } } }, "TeamInfosResponse": { "type": "object", "description": "Batch team info result.", "required": [ "items" ], "properties": { "items": { "type": "array", "items": { "$ref": "#/components/schemas/TeamBriefItem" } } } }, "TeamItem": { "type": "object", "description": "A team and its membership.", "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": "Owning account ID." }, "team_id": { "type": "integer", "format": "uint64", "description": "Unique team ID." }, "team_name": { "type": "string", "description": "Team display name. 1–39 characters, unique per account." }, "description": { "type": "string", "description": "Free-form description." }, "status": { "type": "string", "enum": [ "enabled", "disabled" ], "description": "Team status." }, "updated_by_name": { "type": "string", "description": "Display name of the last editor." }, "updated_by": { "type": "integer", "format": "uint64", "description": "Member ID of the last editor." }, "creator_id": { "type": "integer", "format": "uint64", "description": "Member ID of the creator." }, "creator_name": { "type": "string", "description": "Display name of the creator." }, "created_at": { "type": "integer", "format": "int64", "description": "Unix epoch seconds the team was created." }, "updated_at": { "type": "integer", "format": "int64", "description": "Unix epoch seconds the team was last updated." }, "person_ids": { "type": "array", "items": { "type": "integer", "format": "uint64" }, "description": "Member IDs of team members." }, "ref_id": { "type": "string", "description": "External reference ID for third-party HR system integration." } } }, "TeamListRequest": { "type": "object", "description": "Filters for listing teams.", "properties": { "p": { "type": "integer", "description": "Page number. Default: 1.", "minimum": 1, "default": 1 }, "limit": { "type": "integer", "description": "Page size. Max: 100. Default: 20.", "minimum": 1, "maximum": 100, "default": 20 }, "orderby": { "type": "string", "description": "Sort field.", "enum": [ "created_at", "updated_at", "team_name" ] }, "asc": { "type": "boolean", "description": "Ascending sort order." }, "person_id": { "type": "integer", "format": "uint64", "description": "Filter by member ID — return only teams this person belongs to." }, "query": { "type": "string", "description": "Substring match on team name." } } }, "TeamListResponse": { "type": "object", "description": "Paginated team list.", "required": [ "p", "limit", "total", "items" ], "properties": { "p": { "type": "integer", "description": "Current page number." }, "limit": { "type": "integer", "description": "Page size used." }, "total": { "type": "integer", "description": "Total number of teams matching the filter." }, "items": { "type": "array", "items": { "$ref": "#/components/schemas/TeamItem" } } } }, "TeamUpsertRequest": { "type": "object", "required": [ "team_name" ], "description": "Parameters for creating or updating a team.", "properties": { "team_id": { "type": "integer", "format": "uint64", "description": "Team ID. Omit or set to 0 to create a new team." }, "team_name": { "type": "string", "minLength": 1, "maxLength": 39, "description": "Team display name. 1–39 characters." }, "description": { "type": "string", "maxLength": 500, "description": "Free-form description." }, "person_ids": { "type": "array", "items": { "type": "integer", "format": "uint64" }, "description": "Member IDs to set as team members. Replaces the existing member list." }, "emails": { "type": "array", "items": { "type": "string", "format": "email" }, "description": "Email addresses to invite as members." }, "phones": { "type": "array", "items": { "type": "string" }, "description": "Phone numbers to invite as members." }, "countryCode": { "type": "string", "description": "Default country code applied to any `phones` entries that are not in E.164 format." }, "ref_id": { "type": "string", "description": "External reference ID for HR system integration." }, "reset_if_name_exist": { "type": "boolean", "description": "If true and a team with the same name already exists, reset its membership to the provided person_ids." } } }, "TeamUpsertResponse": { "type": "object", "description": "Team create/update result.", "required": [ "team_id", "team_name" ], "properties": { "team_id": { "type": "integer", "format": "uint64", "description": "Created or updated team ID." }, "team_name": { "type": "string", "description": "Team name echoed from the request." } } }, "AccountInfo": { "type": "object", "properties": { "account_id": { "type": "integer", "description": "Account identifier." }, "account_name": { "type": "string", "description": "Account name." }, "domain": { "type": "string", "description": "Primary account domain (login subdomain)." }, "extra_domains": { "type": "array", "items": { "type": "string" }, "description": "Additional account domains." }, "phone": { "type": "string", "description": "Account contact phone, masked for privacy." }, "country_code": { "type": "string", "description": "Calling country code for the contact phone." }, "email": { "type": "string", "description": "Account contact email." }, "avatar": { "type": "string", "description": "Account avatar URL." }, "locale": { "type": "string", "description": "Account language preference (e.g. zh-CN, en-US)." }, "time_zone": { "type": "string", "description": "Account default timezone (IANA name, e.g. Asia/Shanghai)." }, "created_at": { "type": "integer", "format": "int64", "description": "Account creation time, Unix timestamp in seconds." }, "restrictions": { "type": "object", "description": "Account access restrictions (present only when configured).", "properties": { "ips": { "type": "array", "items": { "type": "string" }, "description": "Allowed source IP/CIDR whitelist." }, "email_domains": { "type": "array", "items": { "type": "string" }, "description": "Allowed login email domains." }, "allow_subdomain": { "type": "boolean", "description": "Whether subdomains of the allowed email domains are also accepted." } } }, "mp_plat": { "type": "string", "description": "Cloud marketplace platform the account was provisioned from (present only for marketplace accounts)." }, "mp_account_id": { "type": "string", "description": "Account identifier on the cloud marketplace platform (present only for marketplace accounts)." } } } } } }